This page is now obsolete, please see Using Papyrus 2020-06 for Modeling !

Introduction

The Open Source UML tool Papyrus is a plug-in for the Open Source integrated development environment (IDE) Eclipse.

...

The Gendoc plugin is used in conjunction with a document template. The template contains instructions that enable generation of a Microsoft Word document. The document can include extracts from the model such as diagrams, class definitions, attribute definitions along with their stereotypes etc as well as figures and text directly entered into the template.

Installation

Note that it's possible to install more than one version of Eclipse on the same machine. Each can then have its own version of Papyrus and GenDoc.

Current ONAP modelling tool versions

• Eclipse: version 4.8 "Photon"
• Note that Eclipse Photon requires a 1.8 compatible JVM
• Papyrus: version 4.0.0
• GenDoc: version 0.6.0

...

      Testing of this version still results in an error with gendoc - it will not generate documents where the path to the Papyrus files have a space in it.

Checking

...

the version of Eclipse

...

• To

...

• verify you have the correct version

...

• of Eclipse, go to "Help" → "About Eclipse".
• A popup window should appear that looks something like this: 
  Image Added

Checking the version of Papyrus

• To verify you have the correct version of Papyrus, open the version information for Eclipse (see above).
• Click on "Installation Details" to see something like these:
  Image Added

Checking the version of GenDoc

• To verify you have the correct version of Papyrus, open the version information for Eclipse (see above).
• Click on "Installation Details" to see something like these:
  Image Added

Checking compatibility between Eclipse and Papyrus versions

Each version of Eclipse has a corresponding Papyrus version that it supports.

To see the version mapping go to: https://www.eclipse.org/papyrus/download.html

Image Added

Image Added

Installing Eclipse Modelling Tools

• Eclipse “Photon” Modeling Tools package version 4.8 can be downloaded from here:
  https://www.eclipse.org/downloads/packages/release/photon/r/eclipse-modeling-tools
• Select the download link that is appropriate for the machine on which you will be making the install, ex. "Windows 64-bit".
• This results in the download of a zip file.
• Extract the contents of the zip file to a directory from which you will start Eclipse. On a PC, "Program Files" is always a good option.
• The content of the extracted files should look something like this:

Image Added

• To launch eclipse, double-click on the "eclipse.exe" file.
  • For convenience, you may want to create a shortcut to eclipse.exe on your desktop or (for PC) pin it to your start menu
• When Eclipse starts coming up, it will prompt you for a "Workspace", providing a default that you can override. The workspace is where the Eclipse projects, with associated models, will be stored. 
• When Eclipse fully comes up, you can close the Welcome tab.

Installing Papyrus within Eclipse

• Papyrus Photon version 4.0.0 can be downloaded from here: https://www.eclipse.org/papyrus/download.html
• Scroll down the page, click on "Previous Releases Update Sites", and copy the URL of the update site for "Papyrus Photon 4.0.0". Should be something like: https://archive.eclipse.org/modeling/mdt/papyrus/updates/releases/photon
• Now go back into Eclipse and select "Help"→"Install

Image Removed

Image Removed

Installing Eclipse

• Eclipse “Photon” Modeling Tools package version 4.8 can be downloaded from here:
  https://www.eclipse.org/downloads/packages/release/photon/r/eclipse-modeling-tools
• Select the download link that is appropriate for the machine on which you will be making the install, i.e. "Windows 64-bit".
• This results in the download of a zip file.
• Extract the contents of the zip file to wherever you would like to install Eclipse. On a PC, "Program Files" is always a good option.
• The content of the extracted files should look something like this:

Image Removed

• To launch eclipse, double-click on the "eclipse.exe" file.
• When Eclipse starts coming up, it will prompt you for a "Workspace", providing a default that you can override. The workspace is where the Eclipse projects, with associated models, will be stored. 
• When Eclipse fully comes up, you can close the Welcome tab.

Checking the version of Eclipse

• To verify you have the correct version of Eclipse, go to "Help" → "About Eclipse".
• You should see something that looks like this: 
  Image Removed

Installing Papyrus within Eclipse

• Papyrus Photon version 4.0.0 can be downloaded from here: https://www.eclipse.org/papyrus/download.html
• Scroll down on the right side of the page and select: "Papyrus Photon 4.0.0 " and select "Download Page". This takes you to "Papyrus Update Site for Photon"
• Copy the URL of the update site to which it takes you. Should be something like: https://download.eclipse.org/modeling/mdt/papyrus/updates/releases/photon/
• Now go back into Eclipse and select "Help"→ "Install new software". An "Available Software" screen comes up.
• Paste the URL of the update site into the "Work with:" box and hit enter.
• There should be multiple "Papyrus" related packages available to install. Select only the box: "Papyrus" and make sure the others are not selected.:
  Image Modified
  
  
• Click "Next". The installation will check for dependencies and requirements. You will get a screen indicating what will be installed:
  
  • Papyrus for UML
  • Papyrus for UML Developer Resources
• Click "Next". The install will then prompt you to "Accept" the license agreement.
• Once accepted, you can select "Finish" and the installation process continues.
• Note: The installation might take a while, and perhaps even appear to hang for a while. You can see install progress in the lower right hand corner of Eclipse the progress on the install .
  Image Modified
  
  
• When the installation is finished, restart Eclipse to begin to use Papyrus. You may get a popup asking if you want to restart.
• Go to "Go to "Window"→"Perspective"→"Open Perspective"→"Other" and select Papyrus. You will now be in the Papyrus Perspective perspective where you can begin to use Papyrus.

...

• To verify you have the correct version of Papyrus, first go to "Help" → "About Eclipse".
You should see something that looks like this:
Image Removed

• Click on INSTALLATION DETAILS to see something like these:
  Image Removed
  Image Removed

Installing GenDoc within Eclipse

• In Eclipse, go to "Help" → "Install new software". An "Available Software" screen comes up.
• Paste the GenDoc update site http://download.eclipse.org/gendoc/updates/releases/0.6.0/ in the "Work with" section and hit enter. The "gendoc" package should show:
  Image Added
  
  
• Select the Gendoc . Select this package and hit "Next".
  Image Removed
• Follow the instructions to complete the installation. Note: You may get a warning message about installing software that contains unsigned content - select "Install anyway".
• When the installation is finished, restart Eclipse to begin to use GenDoc

Using the ONAP Model with Gerrit

First-time Setup

This process must be followed if you have never used the Eclipse/Git function with Gerrit.

Setup of RSA Keys in Eclipse

• You must first generate an SSH key within Eclipse/Papyrus.
• Go to "Window→ Preferences→ General→ Network Connection→ SSH2"
• Select the tab "Key Management" and choose "Generate RSA Key"

          Image Removed

...

Uploading an RSA key from Eclipse into ONAP Gerrit

• Login to Gerrit (https://gerrit.onap.org/)
• Click your name at the top right.
• Go to Settings → SSH Public Keys
• Click Add Key.
• Go back to Eclipse and go to "Window→ Preferences→ General→ Network Connection→ SSH2" → LOAD EXISTING KEY
• Paste the text of your public key into the text box.

• Click Add.

ONAP Gerrit user setup in Eclipse

To be able to push model changes to Gerrit, your "committer" user information in Eclipse/Git must correspond to the user name and email you have associated with your Gerrit account. 

• To see these settings in Gerrit (https://gerrit.onap.org/), click on the drop down next to your name and choose "settings". You will see your user name and email.
• To check the committer information being filled in by Git in Eclipse, go to Eclipse and go to: Window → Preferences → Team → Git-Configuration → User Settings
  Image Removed
• If User Settings is empty or the information doesn't match your settings in Gerrit, you will need to update your User Settings. Sometimes on an initial setup, your settings may not be writable.
  • First check that the Location field points at a valid Git config file. If you're unsure, click on "Open". This should open the .gitconfig file in the background in Eclipse.
    • Note: if you want to switch to the opened file and see its contents, you'll need to close the settings window and reopen it.
  • If the specified .gitconfig file isn't valid and writable, you may be able to fix this by exiting Eclipse, specifying your home directory in Windows, and reopening Eclipse. Follow the instructions here: http://wiki.eclipse.org/EGit/User_Guide#Setting_up_the_Home_Directory_on_Windows
• Once your User Settings are editable:
  
  • Select "add entry". Type in as a key "user.name" and provide your user name from Gerrit.
  • Then select "add entry" again, type in "user.email" as a key and provide your email from Gerrit.

Cloning the Model

The ONAP model currently resides in Gerrit in the modeling/modelspec repository. In order to download the model to your machine, to either visualize it or make updates, you will need to clone it in Eclipse/Git.

• Bring up your Eclipse/Papyrus that you installed in the previous steps, if you haven't done so already.
  • Note: you may have to CLOSE THE ECLIPSE WELCOME PAGE.
• Note: If you were previously using Papyrus ONAP model when it was in a "Private" GitHub, you will have to select that repository, right click, and select "Delete Repository". Make sure you delete all files.
• Go to the Git Perspective by selecting "Window→Perspective→Open Perspective→Other" on the top of your screen and then select "Git".
  • Note: Another quick way to get to this perspective exists on the top right side of your screen. You will see "Quick Access". Select the "Git" perspective.
    Image Removed
• Once in the Git perspective, your screen should have the following on top:

           Image Removed

• On the bottom of the picture above, you see a  "cloud" with a repository and a green arrow. That is your "clone repository" function in Git. Select that.
  • It looks like this: Image Removed
• You will need to fill-in the screen, Source Git Repository that appears with a URI. The format of that URI is:
  • ssh://{LF Userid}@gerrit.onap.org:29418/modeling/modelspec
  • Ex. ssh://bencheung@gerrit.onap.org:29418/modeling/modelspec
• Based upon what you have just entered, the rest of the screen gets populated with the correct info. It should look something like this:

Image Removed

• Make sure to fill in User and Password with your LF Userid and password. Once the screen is filled in, select "Next".
• It will then prompt you for the branches to select. Choose: "master" (DESELECT everything else) and  Click "Next". The popup should looks like this:
  Image Removed
• You will then be prompted to select a local directory on your machine into which the model should be loaded. It can be any location you want, and not necessarily the workspace you are using for Eclipse/Papyrus projects.  As an "initial branch", select "master". Select the option "Import all existing Eclipse projects...".  Your screen at this point should look like this:
  Image Removed

• Also remember to check the box to import all existing Eclipse projects.
  • If you forget to do so, you will not see the project in the Papyrus perspective.
  • Alternatively, if you forget to select the checkbox,
    • In the Git perspective, select the Working Tree, then right click and select  import projects
• Note: In order for the above process to work, you may have to exit your corporate VPN.
  • Alternatively,  go to windows →preferences →general → network connection, and set up a proxy access gerrit, including:
    • set to manual
    • fill out http and https
      Image Removed
• Select "finish".
• For a first-time setup, you may get the following message. Select "Yes".
  Image Removed
• The cloning process should complete, and the repository should be created on your local machine. If you encounter errors, contact the ONAP model administrator to get help.
• The view below shows an example of the newly created repository which has been opened up down to the level of the "Local" folder. Note: You should  have the "master" branch only showing up as your "Local".

          Image Removed

Viewing the Model in Papyrus

• Once you have successfully cloned the ONAP model, you can now view it in Papyrus. Go to the Papyrus perspective by selecting  "Window->Perspective→Open Perspective→ Other" on the top of your screen and then select "Papyrus". Or, again you can go to "Quick Access" and select the icon that looks like a bird:
  Image Removed
• This perspective should show a "Project Explorer" on the left side of the screen.
• You should see a screen that looks like this:
  • Image Removed
• You should see your newly created Eclipse/Papyrus project in the "Project Explorer" on the left side of the screen. (ignore the question mark, it shouldn't be there)
  Image Removed
• The text in light brown is telling you that your project is in the modelspec repository you just created, in the branch "master".  We are no longer using the R3working branch.  All work is being performed in the master branch.
• If you open up the ONAP Information Model folder (click on the ">" to open explore the Model), you will see:
  Image Removed

• Here is a description of what you have in the ONAP Information Model. Each of the "green birds" represent a Papyrus model. Aside from the Profiles, you have the overall "model" that is composed of "sub-models". Each of the "sub-models" has a model editor that is responsible for editing the model and uploading the changes into Gerrit/Git. Note: two people can not be editing a "sub-model" without clearly communicated coordination, otherwise "model conflicts" arise. 
  • GenDoc  - This is where the GenDoc templates reside for creating an output of the model in Word                     
  • StyleSheets - These are CSS stylesheets to use when formatting the model                                                              
  • Common - The common submodel of the model (where artifacts used by multiple sub-models are stored)           
  • Infrastructure -  The infrastructure submodel where the multi-cloud artifacts are stored                                          
  • model - This is the "umbrella" ONAP model that contains all the submodels                                                            
  • Nf - Network Function submodel                                                                                                                                
  • Ns - Network Service submodel                                                                                                                                  
  • OpenModel_Profile.profile - Contains IISOMI stereotypes                                                                                                                                     
  • Party - The party submodel for party related artifacts                                                                                                 
  • Pnf - The Pnf submodel where PNFD resides                                                                                                               
  • Resource - The resource submodel for resource related artifacts                                                                                
  • Service - The service submodel for service related artifacts                                                                                         
  • Vnf - The Vnf submodel for Vnf specific artifacts
• To see the entire model, double-click on "model". The model will open up in the model explorer which is on the left side of the screen in the center:

            Image Removed

• The icon with the triangle saying "model" represents the entire ONAP model. The icons with a little arrow coming out of a circle represent the sub-models.
• Open up any sub-model like you would a folder, and you will see something like the following (in this example it is the Vnf sub-model)
  Image Removed
• Each sub-model has the following types of packages
  • Associations - Contains all associations used in diagrams.
  • Diagrams - Contains UML diagrams
  • Interfaces - Contains Component, Interface, and Operation artifacts (usually empty for now)
  • ObjectClasses - Contains all class definitions
  • TypeDefinitions - Contains all DataTypes and Enumerations.
• Start viewing the model by selecting any diagram, i.e. in the Vnf → Diagrams package.
• Here's a little trick for seeing the associated artifacts in the diagram. In the model explorer bar you will see two arrows opposing each other. Select that double-arrow option:

       Image Removed

• What this means, is when you select any artifact on a diagram, i.e. a "Class", the model explorer takes you directly to that artifact in the model explorer tree.
• Now, explore the model yourself by taking a look at all the class diagrams in the sub-models! Note, some of the sub-models are currently empty.

Updating the Model in Gerrit

...

• Current model editors for each submodel are specified here.

...

• .

Tips and Tricks in Eclipse

Workspaces

A workspace is a directory where Eclipse projects, with associated models and files, are stored. It's possible to have several workspaces, but only one is active at a time. Preferences for Eclipse and its plugins are also local to a workspace.

Important: if you open a workspace in a different version of Eclipse than previously used, Eclipse will update the workspace to match that version.

• When Eclipse starts, a popup window normally asks you to select a Workspace, with many different options for selection:
  Image Added
  
  • You can also create a new workspace by writing in a new directory name in the Workspace field.
• Within Eclipse, you can switch between workspaces by going to go to "File"→"Switch Workspace". 
  • Clicking "Other..." brings up a popup window similar to the one shown on startup, but that also allows you to copy workspace settings from the current workspace to a new one.
• Note: It's possible to delete a workspace by simply deleting its directory when it is not active in Eclipse. This will delete all content that is stored locally there!!!

Perspectives

A perspective is a view in Eclipse that contains a series of selection and content editor areas. The perspective has an initial layout that you can change by collapsing, expanding or moving around the different areas.

• Eclipse has a number of pre-defined perspectives associated with different tasks and plugins. In ONAP we mainly use the perspectives for Papyrus and for Git.
• To change perspective, go to "Window→Perspective→Open Perspective→Other" on the top of your screen and then select the perspective that you want to use:
  Image Added
• Another quick way to change perspective exists on the top right side of your screen. Next to the "Quick Access" bar, you will see a number of small icons:
  Image Added
  • Select the icon for the perspective that you want to use. The storage/cylinder icon marked "GIT" is for Git, and the bird icon is for Papyrus.
  • If you don't see the icon for the perspective that you want to use, clicking the icon with the "+" to the left of the predefined perspectives brings you to the same popup window as going to "Window"→"Perspective"→"Open Perspective"→Other".
• If you have moved around or minimized some of the view areas and can't find something you're looking for, you can reset the perspective to its default by first selecting "Window"→"Perspective"→"Reset Perspective..." and then clicking "Reset Perspective" in the popup window.

EGit (Eclipse/Git)

If you encounter unanticipated problems when following the procedures below for working with Eclipse/Git, check http://wiki.eclipse.org/EGit/User_Guide for possible solutions.

Using the ONAP Model with Gerrit

First-time Setup

This process must be followed if you have never used the Eclipse/Git function with Gerrit.

Setup of RSA Keys in Eclipse and Gerrit

• You must first generate an SSH key within Eclipse/Papyrus.
• Go to "Window"→ "Preferences", then "General"→ "Network Connection"→ "SSH2".
• Select the"Key Management" tab and click "Generate RSA Key...".

          Image Added

• The system will generate a key for you and place the key in the same window.
• Select "Save private key", which will save your key as an id_rsa file.
  • Note: You may be asked if you want to save this private key without passphrase protection - select OK.
    
    Image Added
    
    
• A window will pop up with a location and a name for the key file - just click Save.
  Image Added
  
  
• Don't click "Apply and Close" yet.
• Login to Gerrit (https://gerrit.onap.org/).
• Click your name at the top right and click "Settings".
• Click or scroll to "SSH Keys".
• Switch to the open "SSH2" window in Eclipse and copy the text of your public key.
• Switch back to Gerrit, paste the text of your public key into the "New SSH key" text box and click "Add New SSH Key".
• Now you can go back to Eclipse and click "Apply and Close".

Gerrit user contributor agreement

To be able to push model changes to Gerrit, you need to have a CCLA (Corporate Contributor License Agreement) associated with your account in Gerrit.

• Login to Gerrit (https://gerrit.onap.org/).
• Click your name at the top right and click "Settings".
• Click or scroll to "Agreements".
• If you do not see a CCLA clickable link, click on "New Contributor Agreement" and follow the instructions:
  Image Added

ONAP Gerrit user setup in Eclipse

To be able to push model changes to Gerrit, your "committer" user information in Eclipse/Git must correspond to the user name and email you have associated with your Gerrit account. 

• To see these settings in Gerrit (https://gerrit.onap.org/), click on the drop down next to your name and choose "settings". You will see your user name and email.
• To check the committer information being used by EGit (a.k.a. Git in Eclipse), in Eclipse go to: "Window"→"Preferences", then "Team"→"Git"→"Configuration", and select the "User Settings" tab:
  Image Added
  
  
• The table should contain a "user" category with an "email" and a "name" entry.
• The value for the "email" key should be your email from Gerrit.
• The value for the "name" key should be your user name from Gerrit.
• If "User Settings" is empty or the information doesn't match your settings in Gerrit, you will add or update entries in the key-value table.
• Sometimes on an initial setup, your settings may not be writable.
  • First check that the Location field points at a valid Git config file. If you're unsure, click on "Open". This should open the .gitconfig file in the background in Eclipse.
    • Note: if you want to switch to the opened file and see its contents, you'll need to close the settings window and reopen it.
  • If the specified .gitconfig file isn't valid and writable, you may be able to fix this by exiting Eclipse, specifying your home directory in Windows, and reopening Eclipse. Follow the instructions here: http://wiki.eclipse.org/EGit/User_Guide#Setting_up_the_Home_Directory_on_Windows
• Once your User Settings are editable:
  • If the "email" key exists but has the wrong value, select the value field in the table and provide your email from Gerrit.
  • If the table is empty or missing the "email" key, select "Add Entry...", type in the key "user.email", and provide your email from Gerrit as the value.
  • If the "name" key exists but has the wrong value, select the value field in the table and provide your user name from Gerrit.
  • If the table is empty or missing the "name" key, select "Add Entry...", type in the key "user.name", and provide your user name from Gerrit as the value.

Cloning the Model

The ONAP model currently resides in Gerrit in the modeling/modelspec repository. In order to download the model to your machine, to either visualize it or make updates, you will need to clone it in Eclipse/Git.

• Bring up the Eclipse/Papyrus that you installed in the previous steps, if you haven't done so already.
  • Note: you may have to close the Eclipse Welcome page.
  • Note: If you were previously using Papyrus ONAP model when it was in a "Private" GitHub, you will have to select that repository, right click, and select "Delete Repository". Make sure you delete all files.
• Go to the Git Perspective by selecting "Window"→"Perspective"→"Open Perspective"→"Other..." on the top of your screen and then select "Git".
• Once in the Git perspective, your screen should have the following on top:

           Image Added

• Select the "cloud" icon with a repository and a green arrow. This is your "clone repository" function in Git:
  Image Added
• In the popup window, you need to supply the URI for the Source Git Repository. The format of that URI is ssh://{LF Userid}@gerrit.onap.org:29418/modeling/modelspec
  • Ex. ssh://bencheung@gerrit.onap.org:29418/modeling/modelspec
  • Based upon what you have just entered, the rest of the screen gets populated with the correct info. It should look something like this:
    Image Added

• Make sure to fill in User and Password with your LF Userid and password. Once the screen is filled in, select "Next".
• It will then prompt you for the branches to select. Choose: "master" (DESELECT everything else) and click "Next". The popup should looks like this:
  Image Added
• You will then be prompted to select a local directory on your machine into which the model should be loaded by Git. It can be any location you want, and not necessarily the workspace you are using for Eclipse/Papyrus projects. Check the box "Import all existing Eclipse projects...".  Your screen at this point should look like this:
  Image Added

• Select "Finish".
  • For a first-time setup, you may get the following message. Select "Yes".
    Image Added
• The cloning process should complete, and the repository should be created on your local machine.
• The view below shows an example of the newly created repository which has been opened up down to the level of the "Local" folder. Only the "master" branch should show up as your "Local".

          Image Added

What if Eclipse/Git won't connect to ONAP Gerrit?

• If it looks like Eclipse is not able to connect to Gerrit, you can try working with the model outside your corporate VPN.
• However, the preferred way to solve this problem is to set up a proxy access to Gerrit:
  
  • Go to "Window"→"Preferences"→"General"→"Network Connections"
  • Edit the entries for HTTP and HTTPS that have "Provider" preset to Manual. For both, set the URL for your proxy under "Host" and its port under "Port".
  • For "Active Provider" at the top of the window, select "Manual".
  • The resulting configuration should look something like this:
    Image Added

Viewing the Model in Papyrus

Once you have successfully cloned the ONAP model, you can now view it in Papyrus.

• Go to the Papyrus perspective by selecting  "Window"→"Perspective"→"Open Perspective"→ "Other..." on the top of your screen and then select "Papyrus".
• This perspective should show a "Project Explorer" on the left side of the screen that looks something like this:
  Image Added
  
  
• You should see your newly created Eclipse/Papyrus project in the "Project Explorer" on the left side of the screen. (ignore the question mark, it shouldn't be there)
  Image Added
  
  
• The text in light brown is telling you that your project is in the modelspec repository you just created, in the branch "master". Note that all model work is being performed in the "master" branch.
  • If you do not see the project in the "Project Explorer", probably you forget to check the box to import all existing Eclipse projects when cloning the model. To fix this, switch to the Git perspective, select the repository name or the Working Tree, then right-click and select "Import projects...".
• If you click on the ">" to open/explore the ONAP Information Model folder, you will see something like:
  Image Added

• Each of the "green birds" represent a Papyrus model. Double-clicking on any of these models will open it in a new Model Explorer panel, which is usually on the left side of the screen in the center.
  
  • The icon with the triangle saying "model" represents the top-level of the ONAP model. Double-click on "model" like you would a folder, and you should see something like this: 
    Image Added
  •  The icons with a little arrow coming out of a circle represent the sub-models. Open up any sub-model like you would a folder, and you should see something like this (in this example it is the Vnf sub-model):
    Image Added

• Start viewing the model by selecting any diagram, i.e. in the Vnf → Diagrams package.
  • Here's a little trick for seeing the associated artifacts in the diagram. In the model explorer bar you will see two arrows opposing each other. Select that double-arrow option:
    Image Added
  • What this means, is when you select any artifact on a diagram, i.e. a "Class", the model explorer takes you directly to that artifact in the model explorer tree.

• Now, explore the model yourself by taking a look at all the class diagrams in the sub-models! Note, some of the sub-models are currently empty.

Contents of the ONAP Information Model

Here is a description of what you have in the ONAP Information Model.

• The overall ONAP "model" is composed of "sub-models".
• Each of the "sub-models" has a model editor that is responsible for editing the model and uploading the changes into Gerrit/Git.
  • Note: two people should never edit a "sub-model" at the same time without clearly communicated coordination, otherwise "model conflicts" may arise.
• You should see the following in the ONAP Information Model folder:
  
  • GenDoc  - This is where the GenDoc templates reside for creating an output of the model in Word
  • StyleSheets - These are CSS stylesheets to use when formatting the model                                                              
  • Common - The common submodel of the model (where artifacts used by multiple sub-models are stored)           
  • Infrastructure -  The infrastructure submodel where the multi-cloud artifacts are stored                                          
  • model - This is the "umbrella" ONAP model that contains all the submodels                                                            
  • Nf - Network Function submodel                                                                                                                                
  • Ns - Network Service submodel                                                                                                                                  
  • OpenModel_Profile.profile - Contains IISOMI stereotypes                                                                                                                                     
  • Party - The party submodel for party related artifacts                                                                                                 
  • Pnf - The Pnf submodel where PNFD resides                                                                                                               
  • Resource - The resource submodel for resource related artifacts                                                                                
  • Service - The service submodel for service related artifacts                                                                                         
  • Vnf - The Vnf submodel for Vnf specific artifacts

• Each sub-model has the following types of packages
  • Associations - Contains all associations used in diagrams.
  • Diagrams - Contains UML diagrams
  • Interfaces - Contains Component, Interface, and Operation artifacts (usually empty for now)
  • ObjectClasses - Contains all class definitions
  • TypeDefinitions - Contains all DataTypes and Enumerations.

Updating the Model in Gerrit

Only approved model editors can update the working branch in Gerrit. To be a model editor you must undergo Papyrus training. Current model editors for each submodel are specified here.

• Before making changes, always ensure that you have the latest version of the model from the ONAP Gerrit repository.
  • If you have not yet cloned the model, the clone process will provide you with the latest version.
  • If you have already cloned the model into your workspace, make sure to "Fetch" the latest updates from Gerrit before making any changes.
• Once you have finished making your model changes, select "File"→ "Save" or click the Save icon.

Staging changes

Only changes that have been staged will be included in the Push to Gerrit.

• If this is a first-time that you're updating the model, make sure that you first have set up the user information for Gerrit properly. See these instructions: ONAP Gerrit user setup in Eclipse
• Next, go to the Git perspective by selecting "Window"→"Perspective"→"Open Perspective"→"Other..." on the top of your screen and then select "Git".
• Once in the Git Perspective, select the repository where you have changed the files:
  Image Added
• Select the "Git Staging" tab in the lower right hand portion of your screen (it might also be on the right-hand side of your screen based on your layout)
  It looks like this: Image Added with a little green down-arrow
• The Git Staging window looks like this:
  Image Added
• You will see all of the files that you have changed in the "Unstaged changes".
  • Note: If there is a file in the list that you did not intend to change, you can revert the unwanted changes by right-clicking on that file and selecting "Replace with HEAD revision".
• For each changed file that you want to stage, right-click and select "Add to index". Once they have been added, the files will move to "Staged Changes".
  
  • As a shortcut, you can select the little green "++" sign that will add all the files for you:
    Image Added
  • After you hit the green "++" it should look something like this:
    Image Added

Writing the commit message

Next you will need to prepare to "Commit and Push" your changes.

• Position your cursor in the "Commit Message" window.
• Add a commit message indicating the change you have done, i.e. "Added new diagram to service model".
• Then press carriage return twice so that you have a blank line after your message.
  • You can then optionally add a more detailed message about the change.
• Next, you will have to associate the change to a JIRA ticket. Add on the line after the blank line:  Issue-ID: MODELING-xxx
  • The JIRA ticket should be from the Modeling project. List of tickets here: https://jira.onap.org/projects/MODELING/issues/
  • Note that there needs to be a blank between ":" and "M".
• Git should generate a "Change-Id" for you, so you don't need to manually add one.
  • If there is no "Change-Id" line in the "Commit Message" window, click the "Add Change-ID" icon to the right on the same line as the "Commit Message" title.
• Then "Sign-off" on the change by clicking the "Add Signed-off-by" icon that looks like a pen and is on the same line as the "Commit Message" title:

                   Image Added

Commit to local repository and push to remote Gerrit

• Now you are ready to select "Commit and Push". This commits your local changes and pushes them to the remote Gerrit repository (which should be the working branch).
  Image Added
  
  
  • Note that the "Committer" must correspond to the user name and email you have associated to your Gerrit account. If they don't, follow the instructions here: ONAP Gerrit user setup in Eclipse
• After you press "Commit and Push...", you will see this popup:
  Image Added
• Click "Finish".

Asking for approval in Gerrit

• Once your changes have been successfully pushed to Gerrit, you should see push result messages from Gerrit in a new window in Eclipse:

                Image Added

• This window display the Gerrit identifier (in this case 59893) associated with the change. Make a note of the identifier.
• Now open a browser and login to Gerrit (https://gerrit.onap.org/).
• You should then see the change you have just made. Select that change.
• Click "Add..." and specify the name of the person to approve that change. Approvers are Deng Hui as well as the model owner, if you are updating a model for which you are not the owner.
  Image Added
• Once the change has been committed, you will receive an email confirmation of the commit.

Recovering from a failed push to Gerrit

• If your commit and push fails for any reason, once you have fixed the problem, you can try to resend the request by selecting the "Amend (Edit previous commit)" icon in the Commit Message bar:
  Image Added
• If you want to roll back your failed commits:
  • Go to the Git Perspective by selecting "Window"→"Perspective"→"Open Perspective"→"Other..." on the top of your screen and then select "Git".
  • Right-click on the "modelspec" repository and select "Reset...".
  • Image Added
  • Select "Remote Tracking"→"origin"→"master", then "Mixed", and then click "Reset".
    Image Added
  • This operation will let your local back to keep aligned with the remote merged changes, then you can do a new commit.

...

                     Image Removed

• • The Git Staging window looks like this:
    Image Removed
  • after you hit the green "++" it looks like this:
    Image Removed
  • Once they have been added, they will show up in the "Staged Changes" 
  • COMMIT MESSAGE: Next you will need to prepare to "Commit and Push" your changes. Position your cursor in the "Commit Message" window
  • Add a commit message indicating the change you have done, i.e. "Added new diagram to service model" then carriage return twice so that you will have a blank line after your message.
  • You can then optionally add a more detailed message about the change.
  • JIRA TICKET: Next, you will have to associate the change to a JIRA ticket. Add on the line after the blank line:  Issue-ID: MODELING-104
  • Note that there is a blank between ":" and "M".  The JIRA ticket MODELING-104 is a general ticket for changes to the working branch.
  • Note that Git will generate a "Change id" for you, so you don't need to manually add one.
  • SIGNOFF (PENCIL) ICON: Then you will need to "Sign-off" on the change by selecting the "Sign-off" button. This is the "Pen" icon next to the "Commit Message". Select that icon

                   Image Removed

• • Now you are ready to select "Commit and Push". This commits your local changes and pushes them to the remote Gerrit repository (which should be the working branch)
    Image Removed
  • Note that the "committer" above must correspond to the user name and email you have associated to your Gerrit account. If they don't, follow the instructions here: ONAP Gerrit user setup in Eclipse
  • After you hit the commit and push you will see this popup:
    Image Removed
  • Once your changes have been successfully committed and pushed to Gerrit, you will see the results:

                Image Removed

• This window display the Gerrit identifier (in this case 59893) associated to the change.
• Next you will have to go to Gerrit at: gerrit.onap.org and login to Gerrit
• You can then see the change you have made. Select that change. You will then need to "add" the name of the person to approve that change.
• Approvers are Deng Hui together with the model owner, if you are updating a model for which you are not the owner.
  Image Removed
• Once the change has been committed, you will receive an email confirmation of the commit.
Note: If your commit and push fails for any reason, once you have fixed the problem, you can resend the request by selecting the "Amend (Edit previous commit)" icon in the Commit Message bar.
Image Removed

Export the ONAP Model

Export to a Word Document

GenDoc is a tool plugin to Eclipse/Papyrus that enables you to output the model to a Word document. (See installation instructions on how to install for the GenDoc plug-in above.)

Updating the GenDoc Template

• A generic template is provided in the ONAP model Generic GenDoc templates are provided in the GenDoc folder of the ONAP model you cloned from Gerrit.The . Each template is a Word document itself that contains GenDoc instructions.
  • The template commonly used for model output is called
  ONAP GenDoc Template. 
• You can either open it in Eclipse by selecting the template, or you can open it up directly in Word by finding it in the folder where your model is stored.
• • "ONAP GenDoc Template.docx". 
• You can open the template directly in Eclipse by right-clicking the template and choosing "Open With", and then the editor you want to use.
  • To open the template in Word outside of the Eclipse environment, select "System Editor".
• There are two There are 3 things in this template that you need to update

1. 1. Output file - This will be a Word document where GenDoc will store the output. 
            Image Removed
   
   1. Diagram file - This is the model file where GenDoc will find the diagrams. Its' format is ".notation". The example below is going to output the diagrams in the Common sub-model
      Image Removed
   2. Uml file - This is the model file where GenDoc will find the uml model artifacts. Its' format is ".uml". The example below is going to output all the Uml artifacts in the Common sub-mode

                   Image Removed

• before exporting the model:
  • Find the key "model_name" and fill in the name of the model that you want to export. This needs to be changed whenever you export a different sub-model.
    
    • Ex.<param key='model_name' value='Pnf'/><drop/>
  • Find the key "user_path" and fill in the name of the directory of your workspace. This only needs to be changed when opening the model in a new workspace.
    • Ex. <param key='user_path' value='D:\eclipse-workspace\ONAP_IM'/><drop/>
  • Note: Don't "push" the updated GenDoc template which contains your specific information, unless you are also changing something in the body of the template itself

Running the GenDoc template

• Once you have updated the GenDoc template, right-click on the ONAP GenDoc Template template file and select  the option select "Generate documentation using Gendoc"
• The GenDoc utility is invoked and the template is run. Once it has completed, you can find your output in the Output file you specified in the template.
• Note: You do not want to "commit" to Gerrit the updated GenDoc template which contains your specific information.
• By default, the template creates a directory "GenDoc_output" in your workspace, if it doesn't already exist.
• It then creates a Word doc that contains the model name and the current date-time in its name.

• To see the newly directory and file, select "File"→"Refresh".

• As an alternative:
  • Create
  As an alternative, you can create
  • your own private folder for the Gendoc template by
  selecting the option
  • selecting  "File
  ->New→Folder
  • "→"New"→"Folder". Give the folder a name.
  • Then
  you can
  • select "File
  ->Import→
  • "→"Import"→"File System" and import the Gendoc template from your "ONAP Information
  Model → Gendoc directory When you update this file you imported, it
  • Model"/Gendoc directory .
  • This imported file is now your own
  "
  • private
  "
  • copy. You can run the template using the same procedure described above.

Export to an Excel File

...

Papyrus provides the capability to export fragments of the model to tables.

Creating a table

• In the Model Explorer, rightRight-click on the folder containing the Uml UML artifacts you want to output , (for example , Common → ObjectClasses "Common"→"Root"→"RootObjectClasses") and select the an option under "New Table".
  Papryus
  • Papyrus proposes different formats for
  you
  • your table
  :
  • , such as Class Tree Table, Generic Tree Table,
  or even
  • as well as a configuration utility to create your own table format.
  • For the purposes of this example,
  we are going to create a
  • select "Class Tree Table". 
  • The table artifact will be stored in your ObjectClasses folder the folder you selected above, using the name you provided when you created the table.
  • The "Class Tree Table" will be automatically opened up when it is created and will look like this:
    
  • Now, in the model explorerModel Explorer, select all the classes you which to put in the table and "drag/drop" them into the table. 
    • Note: Another option to create a table is to first select the
    Uml
    • UML artifacts you wish to output, then right-click and select New Table.
  • Select the table contents and right-click and select  "Expand all for selection"Now, for Common object classes, the . The table will look something like this:

            

  Putting a table into Excel

  • You can then "copy/paste" your table to an Excel spreadsheet, or just keep the table in Papyrus for future reference.