Objectives

The objective of this exercise is to create a new SysML-JIRA mapping by 1) adding a new JIRA element type, 2) adding a new SysML element type, and 3) adding a new SysML-JIRA mapping. This exercise differs from the content of Exercises 8.5 and 8.6 by including the possibility of SysML value properties in the mapping.

Preparation

If you have not used mappings before, you will need to load the mappings file, syndeiaTutorial.mappings, which initializes the model types and mapping groups along with specific starting artifact types and mappings used in this exercise. 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 syndeiaTutorial.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.
   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.

Exercise

1. Open or create a SysML project with Syndeia_Profile.mdzip (get it here - https://intercax.atlassian.net/wiki/spaces/SYN34/pages/2407364009) added as a module, then right-click the main package in the model and launch the Syndeia dashboard.
   
   

2. Select or add the JIRA repository you intend to use for this exercise in the Repository Manager tab to ensure that your credentials are entered correctly before beginning.

   Open

   

   Figure 1 Syndeia dashboard, Repository Manager tab, showing JIRA repository loaded correctly
   
   

3. Go to the Mappings tab. You should see Model Types and Mapping Groups listed on the LHS as shown in Figure 2. If you don't, go back and perform the steps under Preparation.
   
   

   Open

   

   Figure 2 Syndeia dashboard, Mappings tab, showing Model Types and Mapping Groups
   
   

4. The first task will be to make a new JIRA artifact type available for mapping.
   
   

   1. Select JIRA under Model Types in the left column. Initially, the window should appear similar to Figure 3, with three existing JIRA artifact types available.
      
      

      Figure 3 Syndeia dashboard, Mappings tab, showing available JIRA artifact types
      
      

   2. Add a new JIRA artifact type.
      
      

      1. Right-click JIRA and select Add Artifact Type
         
         

      2. A new window appears, Add JIRA Artifact Type
         
         

      3. Use the JIRA Repository pull-down menu to choose the JIRA repository you have previously entered the credentials for in step 2.
         
         

      4. Use the Project pull-down menu to select the JIRA Project that contains the issue type you are planning to map.
         
         

      5. Use the pull-down menu next to Issue Types to view all the JIRA artifact types Syndeia can find, as shown in Figure 4. Yours will look different. 
         
         

         Figure 4 Add JIRA Artifact Type window, upper half
         
         

      6. Select the JIRA issue type you wish to use for mapping, in this example we have selected Improvement.
         
         

      7. ID, Type, Name, and Description of the JIRA issue type are automatically populated. You can modify the name and description if needed.
         
         

5. Specify the JIRA artifact type attributes to be available for mapping
   
   

   1. If you click the Get Issue Properties button at this point without an entry in the Key of sample issue field first, Syndeia will return all properties for the given Issue Type in the given Project that can be set by the user when an issue is created.
      
      

   2. For the issue type we have selected, the attributes are populated as shown in Figure 5. The properties that can be set at creation here include fields such as Assignee, Description, and Due Date, but do not include other properties that are set automatically by the system such as key and created date, or can be changed later, such as status and resolution.
      
      

      Figure 5  Add JIRA Artifact Type window, lower half: all properties set by user upon issue creation
      
      

      1. If you see all the properties you wish to map at this point, you can select them with the checkboxes or the Select All button (you can choose which ones to map later) and click OK to create your artifact type and move to step 6.
         
         

      2. If you do not see all the attributes you would like to map yet, then continue to step 5c to use a sample issue key to return the rest of your attributes.
         
         

      3. If some attributes you would like to map are missing, find an existing JIRA issue of the desired issue type or create a new one that has all the attributes populated that you wish to map. Figure 6 shows a sample Improvement issue I have created, making sure to populate the Resolution field in order to expose that field for mapping. Some fields such as key and created date have been populated automatically by JIRA.
         
         

         Figure 6  Sample JIRA Improvement issue with all desired fields populated
         
         

   3. Enter the key of your sample issue (in my case SDB-1671) into the field labeled "Key of sample issue" and click. The table will be populated as shown in Figure 7, including all attributes that had been populated for the sample issue.
      
      

      Figure 7  Add JIRA Artifact Type window, lower half: all properties set by user at point of creation PLUS any additional attributes populated for the specified sample issue

       

   4. You can select all the properties at this stage by clicking Select All and later choose the ones you want to map. Click OK.
      
      

6. From here you have two options,

   1. Option 1 – If you are mapping JIRA issues to a SysML block, you can map JIRA issue properties to value properties of the SysML block (Option 1). If you want to map JIRA issue properties to tags of stereotypes applied to the SysML block, use Option 2 below. Proceed to steps 7-8 if you are using Option 1

   2. Option 2 – You can use this option if:

      1. You are mapping JIRA issues to SysML elements that are not blocks (e.g. requirement, activity, etc.) and want to map JIRA issue properties to tags of stereotypes applied to those SysML elements. OR
         
         

      2. You are mapping JIRA issues to SysML blocks but want to map JIRA issue properties to tags of stereotypes applied to those SysML blocks, and not value properties.
         Proceed to steps 9-10 if you are using Option 2.
         
         

7. Option 1 - If you plan to map JIRA issue properties to SysML block value properties, you will need to add a SysML artifact of Block type and then add the appropriate value properties.
   
   

   1. Under Model Types in the left column, right-click SysML and select Add Artifact Type.
      
      

   2. In the Add Artifact Type window that appears, set Type to Block and set Name, Block (JIRA Properties) in this example, and Description as desired. Click OK.
      
      

   3. Expand SysML under Model Types, right-click the artifact type that you just created, e.g. Block (JIRA Properties), and select Add/Edit Attribute Definition.
      
      

   4. The name and documentation fields of the SysML element are already entered under Attribute Definitions. Use the + button to add an additional line for each value property you would like available to map to JIRA properties.
      
      

   5. Fill out Display Name, Internal Name, and Description (they can all be the same thing) that you want the value properties to have in the SysML artifact.
      
      

   6. For Meta Type column, use ValueProperty as shown for all attributes.

   7. You can uncheck isRequired column, then click OK
      
      

      Figure 8 Add/Edit Attribute Definition for SysML Artifact type to be used in SysML-JIRA mappings
      
      

8. The next task is to create a new mapping using the new JIRA and SysML model element types.
   
   

   1. Right-click SysML - JIRA under Mapping Groups in the left column and select Add Mapping
      
      

   2. Set a name and description reflecting the SysML and JIRA artifact type you are using along with any other information about the mapping you wish to preserve.
      
      

   3. Set Source Artifact Type to your SysML artifact type, Block (JIRA Properties) in our example, using pull-down menu,
      
      

   4. Set Target Artifact Type to your JIRA artifact type, Improvement in our example, using pull-down menu
      
      

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

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

      Figure 9 Syndeia dashboard, Mappings tab, adding a mapping in the SysML-JIRA Mapping Group
      
      

   7. To map the attributes between Block (JIRA Properties) and Improvement, follow this process.
      
      

      1. Click Retrieve Available Attribute Definitions
         
         

      2. Click the + button to create rows for the attributes you wish to map, selecting the value properties you created for the SysML block type Block (JIRA Properties) on the left hand side (Source) and the JIRA properties from Improvement on the right hand side (Target)
         
         

   8. Click Save Mapping at the bottom. The new mapping should appear in the list under the SysML – JIRA mapping group in the left column and should be available in the Select Mapping Specification window when creating a Data Map or Model Transform connection.
      
      

9. Option 2 - If using stereotype tags instead of block value properties for the mapping, you will not need to create a new SysML artifact type, but you will need to create or modify a SysML stereotype with tags corresponding to the values you wish to map.

   1. The Syndeia mapping tutorials come with a special profile, SyndeiaTutorialMapping.mdzip – Either open this file to modify the stereotypes and tags, or provide your own stereotypes. Here, we will discuss how to modify and use the stereotypes that comes with SyndeiaTutorialMapping profile. Note: Do not modify or use the Syndeia_Profile.mdzip profile for mappings.
      
      

   2. Open the SyndeiaTutorialMapping.mdzip file in MagicDraw. Once you have opened the profile you should expand <<JIRA_Issue>> to view the tag values. All properties except -base_class will be available as tags for mapping.
      
      

   3. Here you see we have created status, priority, reporter, assignee, components, summary, issuetype, description and resolution. Add a new property to this stereotype (or to your own stereotype) for each custom value you wish to map to a stereotype tag value, and type it with a value type such as String
      
      

   4. Save the profile once you have added the tag values you will need and add the profile as a module to your SysML project, or reload it if you had already added it before making the above modifications.
      
      

   5. Make sure the changes are reflected in the tree
      
      

       

10. Next, we create another new mapping using the new JIRA model element type and SysML stereotype.
    
    

    1. Right-click SysML - JIRA under Mapping Groups in the left column and select Add Mapping
       
       

    2. Set a name and description reflecting the SysML and JIRA artifact type you are using along with any other information about the mapping you wish to preserve.
       
       

    3. Set Source Artifact Type to the desired SysML artifact type (e.g. Block), using pull-down menu
       
       

    4. Set Target Artifact Type to your JIRA artifact type (Improvement in our example), using pull-down menu
       
       

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

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

    7. Go down to the Stereotypes section and click the + sign and navigate to the stereotype modified in step 9
       
       

    8. Map stereotype values to JIRA attribute values as shown below
       
       

       1. Under Attribute Definition Mappings, click Retrieve Available Attribute Definitions
          
          

       2. Click the + button to create rows for the attributes you wish to map
          
          

       3. Select the tag values you created for the SysML stereotype on the left hand side (Source) and the JIRA properties from the JIRA artifact type you created on the right hand side (Target)
          
          

          Figure 10 Syndeia dashboard, Mappings tab, adding a mapping in the SysML-JIRA Mapping Group
          
          

    9. Click Save Mapping at the bottom. The new mapping should appear in the list under the SysML – JIRA mapping group in the left column and should be available in the Select Mapping Specification window when creating a Data Map or Model Transform connection.
       
       

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

    Figure 11 Syndeia dashboard, Settings tab, Use mapping checked
    
    

12. Create a block in SysML if not already created and then refresh the package on the LHS, then drag the block to 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 Intercax Help Desk in our examples).
       
       

    2. Choose Data Map or Model Transform in the central column.
       
       

    3. Drag-and-drop block on the left onto the JIRA project on the right.
       
       

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

    5. Select the mapping you created and click OK.
       
       

       Figure 12 Syndeia dashboard, Connection Manager tab, drag Improvement A block into Intercax Help Desk project and select Block-Improvement mapping
       
       

    6. Expand the project, Issues, and Reported by me folder (Figure 13). A new JIRA issue (IHD-443 in this example) has been created with default attribute values assigned by JIRA.
       
       

       Figure 13 Connection Manager after new JIRA issue is created
       
       

    7. If the mapping in step 10 uses a special SysML stereotype, Syndeia will automatically apply that stereotype to the SysML elements from which the JIRA element was created. If you wish to set the SysML tag values before generating the JIRA issue, apply the stereotype first and populate the tag values.
       
       

    8. You may also drag and drop a JIRA issue of the same type to SysML and it will create the block with the specified value properties.
       
       

    9. You should be able to compare and sync these values using the mapping applied when the connection was created.
       
       

    10. Options 1 and 2 in this exercise can be combined, i.e. a SysML element of type Block can have both tag values and value properties that map to attributes of the JIRA element. After the new SysML artifact is created (step 7), but before the mapping is created (step 8), select the new SysML element, Block (JIRA Properties) in our example, under Model Types, SysML in the left column, and add a stereotype with the desired tag values. After clicking Refresh, the tag values should appear in the Attribute Definitions table below and will be available for assignment during mapping.
        
        

13. If the mapping in step 10 uses a special SysML stereotype, Syndeia will automatically apply that stereotype to the SysML elements from which the JIRA element was created. If you wish to set the SysML tag values before generating the JIRA issue, apply the stereotype first and populate the tag values.
    
    

14. You may also drag and drop a JIRA issue of the same type to SysML and it will create the block with the specified value properties
    
    

    Figure 14 Connection Manager after new JIRA issue is created
    
    

15. You should be able to compare and sync these values using the mapping applied when the connection was created
    
    

16. Options 1 and 2 in this exercise can be combined, i.e. a SysML element of type Block can have both tag values and value properties that map to attributes of the JIRA element. After the new SysML artifact is created (step 7), but before the mapping is created (step 8), select the new SysML element, Block (JIRA Properties) in our example, under Model Types, SysML in the left column, and add a stereotype with the desired tag values. After clicking Refresh, the tag values should appear in the Attribute Definitions table below and will be available for assignment during mapping.
    
    

    Figure 15 Adding a stereotype with tag values to a new SysML artifact type