Exercise 8.5 - Creating SysML–JIRA Mappings

Owned by Ambarish Ganesh (Unlicensed)
Last updated: May 13, 2022 by Debesh Roy Chowdhury
7 min read

 

Objectives

The new learning objective of this exercise is to create new 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", 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

  • Syndeia Mappings license, to modify syndeia.mappings file from the Syndeia dashboard (without the special mappings license, existing mappings can be used, but not modified)

We will use the provided MagicDraw project Syndeia_JIRA_Mapping_Tutorial.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009). 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

  1. A mappings file, syndeia34Tutorial.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 syndeiaTutorial.mappings into the .syndeia folder

    4. Rename syndeia34Tutorial.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.

  2. A mappings profile, Syndeia_Mapping_Tutorials_Profile.mdzip, which is loaded like other profiles

Exercise

  1. Open the SysML project Syndeia_JIRA_Mapping_Tutorial.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009), right-click the JIRA package, and launch the Syndeia dashboard

  2. Go to the Mappings tab. The first task will be to create a new mapping using existing artifacts.

    1. Right-click SysML-JIRA under Mapping Groups in the left column and select Add Mapping. Initially, the window should appear similar to Figure 1.

      Figure 1 Syndeia dashboard, Mappings tab, Adding Mapping to SysML-JIRA Mapping Group

    2. Modify the Mapping

      1. Change Name to Activity – New Feature (no attributes)

        Figure 2 Syndeia dashboard, Mappings tab, Adding Mapping to SysML-JIRA Mapping Group, part 2

      2. Change Description to SysML Activity - JIRA New Feature with no attributes

      3. Change Source Artifact Type to Activity, using pull-down menu

      4. Change Target Artifact Type to New Feature, using pull-down menu

      5. Set Structure Level to CHILDREN_RECURSIVE, using pull-down menu

      6. Set Include Attributes to Exclude Attributes, using pull-down menu

      7. The window should look similar to Figure 2.

      8. Click Save Mapping at bottom of right side (scroll down if necessary).

  3. Use the new Mapping you just created

    1. Go to the Connection Manager tab. Open a JIRA repository in the right column.

    2. Drag the Feature E activity in the SysML model into a JIRA project

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

      Figure 3 Connection Manager while creating new JIRA issue with new mapping

    4. Select Activity – New Feature (no attributes) and click OK.

    5. Expand the Syndeia Demo Box Project and Reported by me folder. Check that a new JIRA issue of type New Feature has been created with default attribute values assigned by JIRA.

  4. The second task is to create another new mapping, this one with attributes shared between the SysML and JIRA 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 – New Feature under Mapping Groups/SysML - JIRA 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-JIRA Mapping Group

    3. Modify the Mapping

      1. Change Name to Activity – New Feature (Attributes)

      2. Change Description to SysML Activity - JIRA New Feature with attributes

      3. Keep Source Artifact Type as Activity and Target Artifact Type as New Feature

      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 + sign box under the Stereotypes table.

      7. A Select stereotype window will open. The window should look similar to Figure 5 (review Video 1.8 on SysML Stereotypes, if needed).

        Figure 5 Syndeia dashboard, Mappings tab, modifying the cloned mapping, part 1

      8. Select JIRA_Artifact. This choice will appear in the Select stereotype box on the right.

      9. Click Retrieve Available Attribute Definitions below the Attribute Definition Mappings table

      10. Click the + box below the Attribute Definition Mappings box.

      11. In the new row, select Priority (Priority) on the right (Target) side of the table, using the pull-down menu

      12. In the new row, select priority (priority) on the left (Source) side of the table, using the pull-down menu

      13. Repeat steps xi through xiii for Summary. The final table should look like Figure 6.

        Figure 6 Syndeia dashboard, Mappings tab, modifying the cloned mapping, part 2

      14. Click Save Mapping at bottom of right side (scroll down if necessary).

  5. Use the cloned Mapping you just created

    1. Go to the Connection Manager tab. Open the JIRA repository you used above in the right column.

    2. Drag the Feature E JIRA issue created earlier from the JIRA column into an empty SysML package, e.g. J3.

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

      Figure 7 Connection Manager while creating new SysML Activity with cloned mapping

    4. Select Activity – New Feature (Attributes) and click OK.

  6. A new activity (named Feature E) should appear under J3 on the SysML side. It will have the <<JIRA_Artifact>> stereotype in addition to Activity and all the tag values associated with that stereotype. However, only the two JIRA attributes mapped in the Activity – New Feature (Attributes) mapping (i.e. priority, summary) have been populated in the SysML element from the JIRA issue (see Figure 8).

    Figure 8  New SysML activity created by cloned mapping

    Note that SysML activities do not normally have any place to receive the JIRA attributes. Because the <<JIRA_Artifact>> 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 JIRA attributes.

  7. Change priority from Major to Minor in the JIRA issue created from Feature E (named SDB-1837 in our example) through the JIRA web interface

    1. Find the connection between the JIRA Issue and the new SysML activity (J3::Feature E) in the Connection Browser.

    2. Right-click the connection and select Compare Source and Target.

    3. The Comparison Result tab should appear similar to Figure 9.

      Figure 9 Comparison Result tab after modifying JIRA issue priority

    4. Return to the connection in the Connection Browser and select Sync Target to source and update the priority tag value on the SysML block to Minor.

    5. Repeat the comparison and see that all differences have been resolved by updating the SysML model from JIRA