Versions Compared

Old Version 1

changes.mady.by.user Jacqueline Beaulac

Saved on

compared with

New Version Current

changes.mady.by.user Jacqueline Beaulac

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Current ONAP modelling tool versions

Installation

For current versions of Papyrus, both Eclipse and the Papyrus plugin are bundled together in a single installation package. Note that it's possible to install more than one version of Eclipse/Papyrus on the same machine.

Installing Papyrus

  • Papyrus installation packages can be downloaded from here: https://www.eclipse.org/papyrus/download.html
    • 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 Papyrus. On a PC, "Program Files" is always a good option.
    • The content of the extracted files should look something like this:

Image Removed

Installation

For current versions of Papyrus, both Eclipse and the Papyrus plugin are bundled together in a single installation package. Note that it's possible to install more than one version of Eclipse/Papyrus on the same machine.

Checking the status of the Eclipse Foundation servers

Before installing any Eclipse software, always check the status of the Eclipse Foundation servers! Installations can fail or act unpredictably if their servers are not fully operational.

The status is reported here: https://www.eclipsestatus.io/

Installing Papyrus

  • Papyrus installation packages can be downloaded from here: https://www.eclipse.org/papyrus/download.html
    • 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 Papyrus. 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 Papyrus, double-click on the "papyrus.exe" file.
    • For convenience,
    To launch Papyrus, double-click on the "papyrus.exe" file.
    • For convenience, you may want to create a shortcut to papyrus.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 your Eclipse projects will be stored. 
  • When Eclipse fully comes up, you can close the Welcome tab.

...

  • GenDoc releases are available here: https://www.eclipse.org/gendoc/downloads/download.php
  • The easiest way to install GenDoc is to copy the URL to the update site from that page and use that it directly in Papyrus.
    • In Papyrus, go to the menu item "Help" → →"Install new software...". An "Available Software" popup window should appear.
    • In the "Work with:" section, paste in the GenDoc update site for the appropriate release (for example http://download.eclipse.org/gendoc/updates/releases/0.7.2/2019-09) and hit enter.
    • Select the Gendoc package. You should see something like this:
    • Click the "Next >" button and 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 Eclipse will prompt for a restart. Accept the restart to begin to use GenDoc.

Checking the versions of the tools

...

  • To verify you have the correct version of Papyrus, go to the menu item "Help" → →"About Papyrus".
  • A popup window should appear that shows the Eclipse version (NOTE: not the Papyrus version) and looks something like this: 

...

  • To verify you have the correct version of Papyrus, open GenDoc, first follow the instructions above for checking the version information for Eclipse (see above).
  • Click on In the "Papyrus Installation Details" to popup, when GenDoc is properly installed, you should see something like these:
    Image RemovedImage Added

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.

...

  • You can also create a new workspace by writing in a new directory name in the Workspace field.

...

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

/Papyrus

EGit (Eclipse/Git)

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

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.

Note that local GIT repositories are not stored in the workspace itself, but there is a link from the workspace to the GIT repository being used in that 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.

Important

...

: 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, so be sure before deleting!!!

Choosing workspace at startup

  • When Papyrus starts, a popup window normally asks you to select a Workspace, with many different options for selection. You can also create a new workspace by writing in a new directory name in the Workspace field.
    Image Added

Switching workspaces

  • Within Papyrus, you can switch between workspaces by going to the menu item "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.

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.

Papyrus has a number of pre-defined perspectives associated with different tasks and plugins. In ONAP we mainly use the perspectives for Papyrus and Git.

Resetting a perspective to default layout

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 current perspective to its default layout.

  • Select the menu item "Window"→"Perspective"→"Reset Perspective..." and then click "Reset Perspective" in the popup window.

Switching perspective

There are several ways to switch perspectives:

  • To change perspective, go to the menu item

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 Removed
  • 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 Removed
  • 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"and then select the perspective that you want to use.
    Image Added
  • If you don't see the perspective you want, continue to menu item "Other" to open a popup with further options that looks like this:
    Image Added
  • To switch back and forth in the list of currently active perspectives, select the menu item 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"→"PerspectiveNavigation"→"Reset Next 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

...

  • "/"Previous Perspective" or use the corresponding hotkeys:
    Image Added
  • There is also a toolbar for changing perspectives, normally on the top right side of your screen. You will see a number of small icons that represent perspectives:
    Image Added
    • 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 the menu item "Window"→"Perspective"→"Open Perspective"→Other".

Using the ONAP Model from Gerrit in Papyrus

First-time Setup of Papyrus for ONAP Gerrit

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

Setup of RSA Keys in

...

Papyrus and ONAP Gerrit

You must first generate an SSH key within

...

Papyrus

...

:

  • Go to the menu item "Window"→"Preferences", then "General"→"Network ConnectionConnections"→"SSH2".
  • Select the "Key Management" tab and click "Generate RSA Key...".

...

  • The system will generate a key for you and place the key in the same windowyou and place the key in the same window, in the box labelled "You can paste this public key into the remote authorized_keys file:".
  • Copy the public key. You will need to paste this into ONAP Gerrit.
  • 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.



  • A window will pop up with a location and a name for the key file - just click Save.


  • Don't click "Apply and Close" yet.

Add the key from Papyrus into ONAP Gerrit:

  • Login to ONAP Gerrit (https://gerrit.onap.org/).
  • Click your name at the top right and click "Settings".
  • Click or scroll to "SSH Keys". :
    Image Added
  • If you didn't copy the text of your public key before, you now need to switch Switch to the open "SSH2" window in Eclipse and copy the text of your public keyit.
  • Switch back to In 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".

ONAP 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 ONAP 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 Modified

ONAP Gerrit user setup in Eclipse

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

  • To see these settings in Login to ONAP Gerrit (https://gerrit.onap.org/), click on the drop down next to .
  • Click your name at the top right and click "Settings".
  • Click or scroll to "Profile and choose "settings". You will see your user name and email. These should be the same as for logging in to Linux Foundation.
    Image Added
  • In Papyrus 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:


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

      • .

Cloning the Information Model from Gerrit into Papyrus

The ONAP Information Model currently resides in Gerrit in the modeling/modelspec repository. In order to visualize it or make updates, you need to download the model to your local machine by cloning it into a local Git repository and adding it to your Papyrus workspace.

  • In Papyrus, go to the Git perspective, for example
  • 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 selecting "Git".
  • Once in the Git perspective, your screen should have the following on top:

...

  • Select the "cloud" icon with a repository and a green arrow. This is your "clone repository" function in Git:
  • In the popup window, you need to supply the URI for the Source Git Repository. The format of that URI is ssh://{LF UseridGerrit_UserId}@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. your ONAP Gerrit password. This should be the same as for logging in to Linux Foundation. Once the screen is filled in, select "Next".
  • It will then prompt you for the branches to select. Choose: Click "Deselect All", then choose just "master" (DESELECT everything else) and click "Next". The popup should looks like this:
    Image RemovedImage Added
  • You will then be prompted to select create 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
    ...
    • after clone finishes".  Your screen at this point should look something like this:
      Image Modified
  • Select "Finish".
    • For a first-time setup, you may get the following message. Select "Yes".
  • 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".

...

  • Go to the Papyrus perspective by selecting  , for example by selecting the menu item "Window"→"Perspective"→"Open Perspective"→"Other..." on the top of your screen and then select selecting "Papyrus".
  • This perspective should show a "Project Explorer" on the left side of the screen that looks something like this:


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

...

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.
  • Next, go to the Git perspective, for example by selecting "Window"→"Perspective"→"Open Perspective"→"Other..." on the top of your screen and then select selecting "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 It might also be on the right-hand side of your screen based depending on your layout.)
    • It looks like this
    : Image Removed
    • , with a little green down-arrow:
      Image Added
  • The Git Staging window looks like this:
  • 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:
    • After you hit the green "++" it should look something like this:

...

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

                   

...

Commiting to your local repository and

...

pushing 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).


    • 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:
  • Click "Finish".

...

  • 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:
  • 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...".:
    • Select "Remote Tracking"→"origin"→"master", then "Mixed", and then click "Reset".
    • This operation will let your local back to keep aligned with the remote merged changes, then you can do a new commit.

...

Exporting the ONAP Model

...

Exporting to a Word Document

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

...

  • Once you have updated the GenDoc template, right-click on the template file and select "Generate documentation using Gendoc"
  • The GenDoc utility is invoked and the template is run.
  • 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 your own private folder for the Gendoc template by selecting  "File"→"New"→"Folder". Give the folder a name.
    • Then select "File"→"Import"→"File System" and import the Gendoc template from your "ONAP Information Model"/Gendoc directory .
    • This imported file is now your own private copy. You can run the template using the same procedure described above.

...

Exporting to an Excel File

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

...