Objectives

The new learning objective of this exercise is to explore and use existing SysML_JIRA mappings for Model Transform connections.

Caution

Your JIRA repository may not be identical to ours, so the specific sequence of instructions in this tutorial may not apply to your work. 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. These hands-on tutorials omit much of the logic behind the actions in the interest of clarity and brevity.
If you are new to this process and you have not been provided with a Syndeia mappings file and corresponding SysML profile by your organization specifically for your repositories, we recommend starting with Tutorial Exercise 8.6, "Adding SysML-JIRA Artifact Types", then completing Exercise 8.5, "Creating SysML-JIRA Mappings", before returning to this exercise. This will create a set of artifact types specific to your JIRA repository, which can be used instead of those supplied with these exercises.
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 in the following section.

Preparation

This exercise assumes 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.3 installed as a plugin for Cameo/MagicDraw with a valid license for use

• Syndeia JIRA interface, correctly installed with a valid license for user.

We will use the provided MagicDraw project Syndeia_JIRA_Mapping_Tutorial.mdzip. The user can use any JIRA repository they have available with the ability to create and edit issues within a JIRA project. 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, syndeia33Tutorial.mappings, which contains the specific starting mappings used in this and the following exercises. To install this,

1. Close MagicDraw, if it is open

2. Rename the existing syndeia.mappings file in the .syndeia folder to something like syndeiaOld.mappings

3. Copy syndeia33Tutorial.mappings into the .syndeia folder

4. Rename syndeia33Tutorial.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, Syndeia_Mappings_Tutorial_Profile.mdzip, which is loaded like other profiles

Exercise

1. Open the SysML project Syndeia_JIRA_Mapping_Tutorial.mdzip right-click the JIRA package, and launch the Syndeia dashboard
   
   

2. Go to the Settings tab (Figure 1) and check Use mapping under the General heading, if not already checked. Click Apply.

   Open

   

   Figure 1 Syndeia dashboard, Settings tab, Use mapping checked
   
   

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-JIRA on the left to see the existing mappings in this area (Figure 2).

   Open

   

   Figure 2 Syndeia dashboard, Mappings tab, Mapping Groups/SysML-JIRA expanded on left
   
   

4. The first task is to drag a SysML block into JIRA to create a JIRA issue.
   
   

   1. Go to the Connection Manager tab. In the right column, select the JIRA repository connection and expand Projects to show the project in which you want to create a new JIRA issue (The project is Syndeia Demo Box in our examples).
      
      

   2. Choose Model Transform in the central column.
      
      

   3. Drag-and-drop the System A block on the left onto the Syndeia Demo Box project on the right.
      
      

   4. A small pull-down menu will appear on the Syndeia dashboard, as in Figure 3, showing the possible mappings available for a block dragged into JIRA.
      
      

      Figure 3 Syndeia dashboard, Connection Manager tab, drag System A block into Syndeia Demo Box project and select Block-Task mapping
      
      

   5. Select Block – Task (no attributes) and click OK.
      
      

   6. Expand the Syndeia Demo Box Project and Reported by me folder (Figure 4). A new JIRA issue (SDB-1839 in this example) has been created with default attribute values assigned by JIRA.
      
      

      Figure 4 Connection Manager after new JIRA issue is created in Syndeia Demo Box project
      
      

5. In our second task, we will use a different mapping to drag a hierarchy of SysML blocks into JIRA to create multiple JIRA issues and to link the attributes of the connected SysML and JIRA elements.
   
   

   1. Return to the Mappings tab in the Syndeia dashboard and select the mapping Block – Task (Attributes) in the left column (Figure 5). This mapping is associated with a new SysML stereotype, <<JIRA_Artifact>>, which contains a set of tag values corresponding to some of the attributes of an Issue in JIRA. On the right side under Attribute Definition Mappings, there is a table showing the desired mappings between the SysML (Source) element tag values and the JIRA (Target) attributes. In the next exercise, we will learn how to add stereotypes and create such a mapping.
      
      

      Figure 5 Syndeia mapping for Block-Task (Attributes)
      
      

   2. This mapping also contains a Relation Type mapping between SysML part property and JIRA "Relates to" relationships. Review Video 1.7 in the Introductory module of the Syndeia training materials to learn more about relationship mapping, new in the Syndeia 3.3 release.
      Caution: Not all attribute values can be written from SysML to JIRA by Syndeia. Some, such as Status, Resolution, or Reporter are read-only. Other attribute values are only written if their values are valid, e.g. Assignee must be from the list of user profiles maintained by JIRA.
      
      

   3. Return to the Connection Manager tab and set Connection Type to Model Transform in the central column
      
      

   4. Drag the System B block onto the target JIRA project
      
      

   5. Select Block-Task (Attributes) and click OK (Figure 6).
      
      

      Figure 6 Syndeia Dashboard, Connection Manager tab
      
      

6. To see the new issues created in JIRA, right-click on System B in the Syndeia dashboard and select Open Connected Artifacts (see Figure 7). System B is connected to Task SDB-1842. At the bottom, two additional issues, SDB-1841 and 1843, are shown as linked to 1842. These were created in the same Model Transform process, the part property relationship in SysML between System B and System B1/B2 mapped to a "relates to" relationship in JIRA.
   
   

   Figure 7 JIRA web interface for new System B issue
   
   JIRA has assigned the new issue created as Type:Task, because the mapping was Block – Task. JIRA has also assigned default values to some of the issue fields on creation of the issue, e.g. Priority = Major, Status = Open.
   
   

7. The model transform just completed has also affected the original SysML blocks.

   1. Display the SysML blocks System B, System B1 and System B2, with their part property relationships and tag value compartments. It should appear similar Figure 8.
      
      

   2. Each of the blocks has been assigned the additional stereotype <<JIRA_Artifact>>, as defined in the mapping shown in Figure 5.
      
      

   3. Each of the blocks now holds the tag values associated with the <JIRA_Artifact> stereotype, e.g assignee, components, etc.
      
      

   4. Where the mapping "Block – Task (Attributes)" has mapped attributes between the JIRA and SysML elements, Syndeia has back-populated the SysML tag values with the default values assigned to each issue by JIRA.
      
      

      Figure 8 System B block structure
      
      

8. In the final part of the exercise, we will demonstrate the Compare & Sync feature for the user-defined SysML – JIRA mapping.
   
   

   1. In the JIRA web interface, as shown in Figure 7, click the Start Progress button for System B, changing its status to "In Progress".
      
      

   2. In the SysML model, delete part property b2:System B2 (do not delete the System B2 block itself).
      
      

   3. On the Syndeia Dashboard, Connection Browser tab, find the connection between the System B elements.
      
      

   4. Right-click this connection and select Compare Source and Target.
      
      

   5. The Comparison Result tab on the Syndeia dashboard will show two differences, similar to Figure 9, in the status values and the System B2 relationship to System B.
      
      

   6. Back in the Connection Browser tag, select Sync Target to Source and check that the differences have been resolved.
      
      

      Figure 9 Comparison Result tab, after separate modifications of SysML model and JIRA issue