Using SysML – DOORS NG Mappings.

The new learning objective of this exercise are to explore and use existing SysML – DOORS NG 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 DOORS NG interface, correctly installed with a valid license for user.

We will use the provided Rhapsody project Syndeia_DOORS_NG_Mapping_Tutorial.rpy. The user can use any DOORS NG repository they have available with the ability to create and edit items within a DOORS NG 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.

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.+))$

Special Note on DOORS NG Artifact Types

1. Model transforms from SysML to DOORS NG are complicated by a special feature of DOORS NG. DOORS NG artifact types are registered on a project-by-project basis. It is only possible for Syndeia to create a new artifact in a DOORS NG project if that project already recognizes that artifact type and the user has permission to create new artifacts in that project.
2. As a general practice, the available artifacts will be set by the user who creates the mappings, as described in Exercises 5.6 and 5.7, not by users who use pre-existing mappings as shown in this exercise. Because of this feature, the user may need to modify the instructions for the following exercise to accommodate the specific DOORS NG project available, with its artifact types and user permissions, and complete the exercise.
3. To discover what artifact types are already available in a specific DOORS NG project, the user can
   1. open DOORS NG in a web browser
   2. navigate to the desired project (Figure 1), click the Administration icon in the upper right corner, and select Manage Project Properties.
      
      
      
      
   3. The available artifact types for this project (Sandbox in our example) are shown in the column on the left. If we select on of the artifact types, the Default artifact format field shows us what generic type of artifact it is (Figure 2).
      
      
      
      
4. Syndeia can only handle default artifact formats of Text and Collection. DOORS NG artifacts having other formats, such as Diagram or Module, cannot be created in DOORS NG by Syndeia using model transforms.

Exercise

1. Open the SysML project Syndeia_DOORS_NG_Mapping_Tutorial.rpy right-click the DOORS NG package, and launch the Syndeia dashboard
2. Go to the Settings tab (Figure 3) and check the Use mapping element under the General heading, if not already checked. Click Apply.
   
   
   
   
3. Go to the Mappings tab. The contents of the main area on the right will depend on the element selected on the left. Expand Mapping Groups and select SysML-DOORS NG on the left to see the existing mappings in this area (Figure 4).
   
   
   
   
4. In the first example, we will use a mapping with no attributes when we drag a SysML requirement into DOORS NG.
   1. Set Connection Type to Model Transform in the central column
   2. Drag the SysML Feature_1_Environmental requirement onto the target DOORS NG folder (Tutorial Sandbox in this example)
   3. In the Select Mapping Specification window, select Requirement-Requirement (no attributes) and click OK (Figure 5).
      
      
      
      
5. We can view the new DOORS NG requirement created by expanding the right side of the Connection Manager (see Figure 6). Note that the child requirements in SysML are not transformed. A DOORS NG requirement cannot have child requirements. In the next exercise, we will use a different approach to transform a requirements hierarchy.
   
   
   
   
   1. You can view the new requirement created in Rhapsody. If you right-click the new requirement 524 – Feature_1_Environmental and select Open, the DOORS NG web interface should open to that requirement.
   2. While the DOORS NG 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 Primary Text, Priority and Status fields in DOORS (among others) are empty. Enter some values into these fields, as shown in Figure 7, and save.
      
      
      
      
6. In the next step, we will use a different mapping to pull the new DOORS requirement back into SysML. In the Mappings tab in the Syndeia dashboard, select the mapping Requirement - Requirement (attributes) in the left column (Figure 8). At the bottom right, we see that this mapping is associated with a SysML stereotype, <<DOORS_Requirement>>, which contains tag values priority and status, 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 DOORS NG (Target) attributes.
   
   
   
   
   1. In the Syndeia dashboard, Connection Manager tab, with Connection Type still set to Model Transform, drag the DOORS NG requirement 524 – Feature_1_Environmental back into the empty package DNG3 in the SysML model. This time, choose a different mapping, Requirement – Requirement (attributes), in the Select Mapping Specification window. A new SysML requirement is created as shown in Figure 9. Note that new requirements has the additional applied stereotype <<DOORS_Requirement>> and has values ID, Text, priority and status populated from the DOORS NG requirement.
      
      
      
      
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, as in Figure 10. Note that the Text and status values have been changed.
      
      
      
      
   2. Go to the Syndeia Dashboard, Connection Browser tab, and find the new connection between the SysML and DOORS NG requirements (see Figure 11).
      
      
      
      
   3. Right-click the connection and select Compare Source and Target and confirm. The Comparison Result tab will open (Figure 12), showing differences in the Text and status fields between the SysML and DOORS NG requirements.
      
      
      
      
   4. Return to the Connection Browser and select Sync Target to Source. Confirm that the SysML requirement tag values have returned to original DOORS 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 DOORS requirement. This assumes that the user has Write privileges to the DOORS repository and that the DOORS attribute is editable through the DOORS NG 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.