Objectives

The learning objective of this exercise is: understand and experience how to create new SysML_Jama Mappings for Model Transform connections.

This is intended for an advanced user who creates and manages transform mappings that are used by other members of the organization.

Preparation

This exercise requires that the student has:

Cameo System Modeler 18.0 - 19.0 (or MagicDraw with SysML plug-in) installed correctly on his or her machine with a valid license for use, and
Syndeia 3.4 installed as a plugin for Cameo/MagicDraw with a valid Syndeia license for use
Syndeia Jama interface, correctly installed with a valid Syndeia license feature for JAMA
Access ti a Cameo model which has the Syndeia Profiles installed
Setting of the Syndeia Use Mapping setting to enabled (yes, checked, on) with those Settings applied for the current Cameo and Syndeia session.

The user can use any Jama repository they have available with the ability to create and edit elements within a Jama project. It is generally advisable to carry out these exercises in a non-production repository, a "sandbox", set up for training and practice purposes.
We recommend that the student view the videos 1.6, 1.7, and 1.8 in the Introduction Section of the Syndeia training materials before attempting this exercise. These videos provide important background on creating custom mappings. Hands-on tutorials omit much of the logic behind the actions in the interest of clarity and brevity.

We will use the MagicDraw project Syndeia_Jama_Mapping_Tutorial.mdzip provided with the tutorials for this exercise, which loads the profile Syndeia_Mapping_Tutorials_Profile.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009). We also use the syndeia34Tutorial.mappings file provided, which has been installed in the .syndeia folder and renamed as syndeia.mappings.

Any Syndeia user can use or view the mapping specifications, but Syndeia requires a special license in addition to the regular Syndeia license in order to create, modify or delete mapping information. It is good practice to confine this duty to a very limited number of experienced users or system administrators, who will provide mappings for the general users.

Special Note on SysML Stereotypes

As demonstrated below, some mappings require special SysML stereotypes so that the SysML element involved in the mapping has tag value slots for the attributes to be mapped. In this exercise, you will use stereotypes from the Syndeia_Mappings_Tutorial_Profile.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009) which should be loaded automatically with the model. However, in your own work, you can create stereotypes as needed and add them to your SysML model, either individually or as a profile. See the documentation for your SysML tool for instructions.
It is critical to remember that the mapping recognizes the stereotype by its ID, not its name. If the stereotype ID in the model is not the same as in the mapping, the mapping will not function as intended. The easiest way to avoid problems is to distribute the mappings file and the SysML profile as a pair which has been tested to ensure that the IDs match for the users.

Exercise

Open the SysML project Syndeia_Jama_Mapping_Tutorial.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009), right-click the Jama_Mapping package, and launch the Syndeia dashboard.
Go to the Mappings tab. If you expand SysML-Jama under Mapping Groups in the left column, the window should appear similar to Figure 1. The first task will be to create a new mapping using existing artifacts. We assume you have completed Exercise 7.6 and added Failure Mode as an artifact type to Model Types: Jama. If not, do Exercise 7.6 now.

Figure 1 Syndeia dashboard, Mappings tab, SysML-Jama Mapping Group
1. Right-click SysML-Jama and select Add Mapping
2. Modify the Mapping
  1. Change Name to Activity - Failure Mode (no attributes)
  2. Change Description to SysML Activity – Jama Test Case with no attributes
  3. Change Source Artifact Type to Activity, using pull-down menu
  4. Set Target Artifact Type to Failure Mode, using pull-down menu
  5. Set Structure Level to NO_CHILDREN, using pull-down menu
  6. Set Include Attributes to Exclude Attributes, using pull-down menu
  7. The window should look similar to Figure 2.
    
    Figure 2 Syndeia dashboard, Mappings tab, Adding Mapping to SysML-Jama Mapping Group
  8. Click Save Mapping at bottom of right side (scroll down if necessary).
Use the new Mapping you just created
1. Go to the Connection Manager tab. Open a Jama repository in the right column, the SysML model in the left column, and select Model Transform in the center.
2. Drag the J2::Test_NewFeature activity in the SysML model into an empty set or component in Jama (Jama_Tutorial in this example).
3. A small pull-down menu will appear on the Syndeia dashboard, as Figure 3, showing the possible mappings available for an activity dragged into Jama.
4. Select Activity – Failure Mode (no attributes) and click OK.
5. Expand the Jama_Tutorial component on the right side of the Connection Manager. Check that a new Failure Mode has been created in Jama.
  
  Figure 3 Connection Manager while creating new Jama Failure Mode with new mapping
The second task is to create another new mapping, this one with attributes shared between the SysML and Jama elements. We will use the Clone Mapping command rather Add Mapping. Clone Mapping saves time when not all features of the new mapping need to be modified.
1. Right-click Activity – Failure Mode (no attributes) under Mapping Groups/SysML - Jama in the left column and select Clone Mapping
2. Initially, the window should appear similar to Figure 4.
  
  Figure 4 Syndeia dashboard, Mappings tab, cloning a mapping in the SysML-Jama Mapping Group
3. Modify the Mapping
  1. Change Name to Activity – Failure Mode (attributes)
  2. Change Description to SysML Activity – Jama Failure Mode with attributes
  3. Keep Source Artifact Type as Activity and Target Artifact Type as Failure Mode.
  4. Set Structure Level to NO_CHILDREN, using pull-down menu
  5. Set Include Attributes to Include Attributes, using pull-down menu
  6. Click the plus sign box under the Stereotypes table.
  7. A Select stereotype window will open. The window should look similar to Figure 5 (see Special Note on SysML Stereotypes above).
    
    Figure 5 Syndeia dashboard, Mappings tab, modifying the cloned mapping, part 1
Select Jama_FailureMode and click OK. This choice will appear in the Stereotypes box.
Click the Retrieve Available Attribute Definitions button below the Attribute Definition Mappings table.
Click the plus box below the Attribute Definition Mappings box.
In the new row, select Failure Mode on the right (Target) side of the table, using the pull-down menu showing Jama attributes.
In the new row, select modeName on the left (Source) side of the table, showing SysML attributes.
Repeat steps xi through xii for the other attributes (GlobalID/Id, Project ID/project, and Cause of Failure/source) so that the final table looks like Figure 6.

Figure 6 Syndeia dashboard, Mappings tab, modifying the cloned mapping, part 2
Click Save Mapping at bottom of right side.
Use the cloned Mapping you just created
1. Go to the Connection Manager tab. Open the Jama repository you used above in the right column.
2. Drag the Test_NewFeature Jama testcase created earlier into the empty SysML J3 package.
3. A small pull-down menu will appear on the Syndeia dashboard, as in Figure 7, showing the possible mappings available for a Jama Failure Mode artifact dragged into SysML.
  
  Figure 7 Connection Manager while creating new SysML Activity with cloned mapping
4. Select Activity – Failure Mode (attributes) and click OK.
A new activity (named Test_NewFeature) should appear under J3 on the SysML side. It will have the <<Jama_Failure Mode>> stereotype in addition to Activity and all the tag values associated with that stereotype. In a SysML diagram, this would appear as in Figure 8.

Figure 8 New SysML activity created by cloned mapping

Note that SysML activities do not normally have any place to receive the Jama attributes. Because the <<Jama_Failure Mode>> stereotype was chosen in the new mapping definition, the new activity was created with that additional stereotype and tag values ready to receive the desired Jama attributes.
Only three of the four Jama attributes mapped in the Activity – Failure Mode (attributes) mapping have been populated in the SysML element because Cause of Failure was empty in the Jama Failure Mode.
Modify the new Jama Failure Mode Test_NewFeature
1. Open the Jama Failure Mode Test_NewFeature from the Syndeia dashboard or the SysML model and add a Cause of Failure, like that shown in Figure 9. Save the change.
  
  Figure 9 Jama failure mode, showing added Cause of Failure
Compare across the new connection, the one with attribute mapping
1. In the Syndeia dashboard, Connection Browser tab, find the connection from J3::Test_NewFeature.
2. Right-click and choose Compare Source & Target
3. The Comparison Result tab should show a discrepancy in the source field, like that shown in Figure 10.
  
  Figure 10 Syndeia dashboard, Compare Results tab
4. On the top row of the Comparison Result table, right-click and choose Sync Target-> Source
5. When the sync is complete, the diff table should be solid green, with the Cause of Failure written to the source tag in the SysML element