...

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

...

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, ex. "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 for UML
• Papyrus for UML Developer Resources

...

• 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 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 Added
  
  
• 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 .
  Image Added
  
  
• 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 "Window"→"Perspective"→"Open Perspective"→"Other" and select Papyrus. You will now be in the Papyrus perspective where you can begin to use Papyrus.

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 package and hit "Next".
• 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.

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".

Checking the version of Papyrus

...

Installing GenDoc within Eclipse

...

Checking the version of GenDoc

• To verify you have the correct version of GenDoc, 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

Using the ONAP Model with Gerrit

...

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 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" "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:

• On the bottom of the picture above, you see a  Select the "cloud" icon with a repository and a green arrow. That This is your "clone repository" function in Git. Select that.
  • It looks like this: Image Removed
  :
  Image Added
• In the popup window, you need to supply the URI for the Source Git RepositoryYou 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 Modified

• 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 and click "Next". The popup should looks like this:
  
• 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 Check the option box "Import all existing Eclipse projects...".  Your screen at this point should look like this:
  

• Also remember If you forget 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 To fix this, go to the Git perspective, select the repository name or the Working Tree, then right-click and select  import projects"Import projects...".
• Note: In order for the above process to If some step in this process doesn't work, you may have to exit your corporate VPN .Alternatively,  go to windows →preferences →general → network connection, and or, alternatively, set up a proxy access 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"., including:
  • set to manual
  fill out http and https
  Image Modified
• Select "finishFinish".
  • For a first-time setup, you may get the following message. Select "Yes".
    Image Modified
• 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 Only the "master" branch only showing should show up as your "Local".

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"→"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 Removedselect "Papyrus".
• This perspective should show a "Project Explorer" on the left side of the screen.You should see a screen that looks like this:
  Image Modified
  
  
• 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)
  
  
  
• 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 Note that all model 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:
  

...

• 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.
• Once you have finished making your model changes, make sure you "save" them in Papyrus, by selecting "File→ Save", or select the Save icon.
• 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: ONAP Gerrit user setup in Eclipse
• Next, you will need to go to the "Git" perspective to select the files you have changed and prepare them for uploading to Gerrit.
  • Go to the Git perspective by selecting  "Window->Perspective→Open Perspective→ Other → Git" like this:
    Image Removed 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.
    
  • 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: with a little green down-arrow
  • You will see the files that you have changed in the "Unstaged changes". Note: If there is a file there that you did not intend to change, right-click on that file and select "Replace with HEAD revision". That will revert any unwanted changes you may have made.
  • STAGE CHANGES: Select the files that you did change, right-click and select "Add to index", Or, as a shortcut, you can select the little green "plus" sign that will add the files for you:

...

• • 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.
    
  
  
  • 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.
    
    
    

Recovering from a Failed Push to Gerrit

Export the ONAP Model

Export to a Word Document

...

• Once you have updated the GenDoc template, right click on the ONAP GenDoc Template file and select  the option "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.
• As an alternative, you can create your own private folder for Gendoc template by selecting the option "File->New→FolderFile→New→Folder". Give the folder a name.
• Then you can select "File->Import→ File System" and import the Gendoc template from your ONAP Information Model → Gendoc directory 
• When you update this file you imported, it is now your own "private" copy. You can run the template using the same procedure described above.

...