Using SysML – Jama Mappings.

The new learning objective of this exercise are to explore and use existing SysML_Jama mappings for Data Map and Model Transform connections.

This exercise assumes the student has

• IBM Rational Rhapsody 8.2 installed correctly on his or her machine with a valid license for use, and
• Syndeia 3.2 installed as a plugin for Rhapsody with a valid license for use
• Syndeia Jama interface, correctly installed with a valid license for user.

The user can use any Jama repository they have available with the ability to create and edit model elements within a Jama model.  It is generally advisable to carry out these exercises in a non-production repository, a “sandbox”, set up for training and practice purposes.

Using mapping in Syndeia requires two new elements which are provided with these tutorials

• A mappings file, syndeiaTutorial_Rh.mappings, which contains the specific starting mappings used in this and the following exercises. To install this,

1. Close Rhapsody, if it is open
2. Rename the existing syndeia.mappings file in the .syndeia folder to something like syndeiaOld.mappings
3. Copy syndeiaTutorial_Rh.mappings into the .syndeia folder
4. Rename syndeiaTutorial_Rh.mappings as syndeia.mappings
5. When you have completed the mapping tutorial exercises, you may want to reverse this process to restore the original mappings file.

• A mappings profile, SyndeiaTutorialMapping.sbs, which is loaded into a TutorialMappingProfile folder in the profiles folder of Syndeia installation:
  C:\Users\<account>\<Rhapsody installation> \Share\Profiles\Syndeia\profiles\

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. Some mappings require a special SysML stereotype to correctly transform attributes to or from a SysML element, so each mappings file should be paired with a SysML profile that holds the required stereotypes, as we have done here.

Many organizations customize their Jama installation, creating new artifact and relationship types for their purposes. This tutorial exercise uses common artifact types in a standard Jama installation, but you may need to adapt the instructions if these artifact types are not available to you. Prior to your doing this exercise, a user with the mapping license described above would need to register the new artifact types for mapping (as described in Exercise 7.7) and create mappings using them (as described in Exercise 7.6).

Caution: Rhapsody has, by default, restrictions on the naming of SysML elements, which can create problems when Syndeia tries to create Rhapsody model elements that violate these restriction, e.g. beginning a SysML block name with a number.  We recommend modifying any Rhapsody models you create to relax these restrictions. Modify the properties of the top-level package of the model under General::Model::NamesRegExp with the following string and save.

^(([a-zA-Z0-9_][a-zA-Z0-9_ ():-]*)|(operator.+))$

Exercise

1. Open the SysML project Syndeia_Jama_Mapping_Tutorial.rpy, right-click the Jama package, and launch the Syndeia dashboard
2. Go to the Settings tab (Figure 1) and check the Use mapping element under the General heading, if not already checked. Click Apply.
   
   
   
   
3. Go to the Mappings tab. Any Syndeia user can 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. The contents of the main area on the right will depend on the element selected on the left. Expand Mapping Groups and select SysML-Jama on the left to see the existing mappings in this area (Figure 2).
   
   
   
   
4. The first task is to drag a hierarchy of SysML requirements into Jama to create an equivalent Jama hierarchy.
   1. Go to the Connection Manager tab and set Connection Type to Model Transform in the central column
   2. Drag the Product Spec requirement onto the target Jama component (Jama_Tutorial in this example)
   3. Select Requirement-Requirement (no attributes) and click OK (Figure 3).
      
      
      
      
5. We can view the new Jama requirements created by expanding the right side of the Connection Manager (see Figure 4). The SysML requirement structure is preserved.
   
   
   
   1. You can view the new requirements created in Jama. If you right-click the new requirement Feature_1_Environmental in either column and select Open, the Jama web interface should open to that requirement.
   2. While the Jama interface is open, modify the requirement. The model transform operation just performed used a mapping that did not carry over attributes from SysML, so the Description and Priority fields in Jama (among others) are empty, while the ID and Status fields have default entries. Enter some values into Description and Priority, as shown in Figure 5, and save.
      
      
      
      
   3. While in the Jama web interface, refresh the parent requirement, Product_Spec, of the requirement just modified, before closing the interface. This is necessary to update the parent requirement before proceeding with the second part of the exercise.
6. In the second example, we will use a different mapping when we drag the Jama requirement back into SysML.
   1. Return to the Mappings tab in the Syndeia dashboard and select the mapping Requirement - Requirement (attributes) in the left column (Figure 6). At the bottom right, we see that this mapping is associated with a special SysML stereotype, <<Jama_Requirement>>, which contains tag values priority and status, corresponding to Jama attributes that are not part of the standard SysML requirement, but that we want to bring into the SysML model. On the right side next to Attribute Definition Mappings, there is a table showing the desired mappings between the SysML (Source) element tag values and the Jama (Target) attributes.
      
      
      
      
   2. In the Syndeia dashboard, Connection Manager tab, select the Model Transform connection type, drag the Feature_1_Environmental item into an empty SysML package, and select the Requirement - Requirement (attributes) mapping.
   3. You can view the new requirements created in Rhapsody. If you create and populate a requirements diagram, it should appear similar to Figure 7. Both the <<Jama_Requirement>> and <<requirement>> stereotypes have been applied and the associated tag values have been added.
      
      
      
      

7.  The Compare & Sync features of Syndeia work with custom-mappings just as they do with default mappings. To demonstrate,

   1. Modify the SysML requirement attributes, e.g set priority to High and Text to 95% recyclable.
   2. Go to the Syndeia Dashboard, Connection Browser tab, and find the new connection between the SysML and Jama requirements (see Figure 8).
      
      
      
      
   3. Right-click the connection and select Compare Source and Target and confirm. The Comparison Result tab will open (Figure 9), showing differences in the Text and priority fields between the SysML and Jama requirements
      
      
      
      
   4. Return to the Connection Browser and select Sync Target to Source. Confirm that the SysML requirement tag values have returned to original Jama values and that a comparison between the two requirements shows all green.
   5. Alternatively, the sync in d) could have been Sync Source to Target, using the modified SysML attributes to update the Jama requirement. This assumes that the user has Write privileges to the Jama repository and that the Jama attribute is editable through the Jama API (Id, for example, is not).
      
8. Save and close the model. If you have a Mapping license that allows you to modify mappings, proceed to the next tutorial exercise.