Objectives

The new learning objectives of this exercise are to generate and synchronize structures of folders, sets, and components as well as items in Jama with structures of packages and other elements in Cameo/MagicDraw. This capability will build on custom mapping tutorials Exercise 7.8 - Creating a Custom SysML-Jama Mapping with Relationships and Exercise 7.9 - Jama - SysML Compare & Sync with Custom Mappings.

This tutorial consists of 2 parts, with 2 scenarios each.

Part 1: Generate Jama to SysML
- Scenario 1a – Jama set with requirement hierarchy (no folders) mapped to a SysML package.
- Scenario 1b – Jama set with requirement hierarchy (including folders) mapped to SysML packages and requirements.
Part 2: Generate SysML to Jama
- Scenario 2a – Drag and drop SysML package with requirements to a Jama component to generate a Jama set with requirements
- Scenario 2b – Drag and drop SysML package and requirement hierarchy to a Jama set to generate folders and requirements

Preparation

This exercise assumes the student has:

Cameo System Modeler (or MagicDraw with SysML plug-in) supported version installed correctly on their machine with a valid license for use.
Syndeia installed as a plugin for Cameo/MagicDraw with a valid license for use.
Jama repository (server) that can be connected over the network from the Syndeia Repository Manager.

The user can try out this capability in a sandbox Jama repository or project to ensure that their installation is working fine before using on a production repository / project.

Exercise

The Cameo model Syndeia_Jama_Mapping_Tutorial.mdzip used in these demos can be downloaded from SysML Models, Profiles and Mappings.

Part 1 - Generate Jama to SysML

In this section we will create new mappings and use them to generate from Jama → SysML, compare, and sync.

Scenario 1a – Jama set with requirement hierarchy (no folders) mapped to a SysML package

In this Scenario 1a we will create and use mappings for transforming, comparing, and synchronizing Jama Sets and SysML Packages, and Jama Requirements with SysML Requirements.

Begin with a Set with Requirements in Jama as shown in Figure 1.

Figure 1 Jama Set with nested Requirements
Open the SysML project Syndeia_Jama_Mapping_Tutorial.mdzip (get it here - SysML Models, Profiles and Mappings), right-click the Jama_Relationship_Mapping package, and launch the Syndeia dashboard. Select the Syndeia Cloud project, if used.
Go to the Settings tab (Figure 2) and check the Use mapping setting under the General settings, if not already checked. Click the Apply button.

Figure 2 Syndeia dashboard with Settings tab selected and Use mapping checked
Go to the Mappings tab. The first task will be to make a new Jama artifact type and SysML Package artifact type available for mapping (if not already).
1. Select Jama under Model Types in the left column. Initially, the window should appear similar to Figure 3.
  
  Figure 3 Syndeia dashboard with Mappings tab selected, showing initially-available Jama artifact and relation types
2. Add a new Jama artifact type. See Exercise 7.6 - Adding SysML-Jama Artifact Types for a more extended example with screen shots.
  1. Right-click Jama under Model Types and select Add Artifact Type.
  2. Choose a Jama Repository from the top pull-down menu.
  3. Click the Get Jama Item Types button.
  4. Select Set from the Item Types pull-down menu.
  5. Click OK. We do not need to add any attributes for this example.
    
    Figure 4 Add SysML Artifact Type window when creating the Set artifact type
3. Add a new SysML artifact type.
  1. Right-click SysML under Model Types and select Add Artifact Type.
  2. Set Type to Package. This must be used as the base artifact type defined in SysML.
  3. Set Name to Package and Description to SysML Package Artifact. These can be changed at your discretion.
  4. Click OK.
    
    Figure 5 Add SysML Artifact Type window when creating the Package artifact type
The second task is to create a new mapping using the Jama Set artifact.
1. Right-click SysML - Jama under Mapping Groups in the left column and select Add Mapping.
2. Set Name to Package - Set.
3. Set Description to SysML Package – Jama Set.
4. Set Source Artifact Type to Package, using pull-down menu.
5. Set Target Artifact Type to Set, using pull-down menu.
6. Set Structure Level to CHILDREN_RECURSIVE, using pull-down menu.
7. Set Include Attributes to Exclude Attributes, using pull-down menu.
8. Set Include Relations to Include Relations, using pull-down menu.
9. Using the plus button under Related Mappings, add the related mapping as shown in Figure 6, Requirement - Requirement (attributes).
10. Click Save Mapping at the bottom. The window should appear similar to Figure 6. The new mapping should appear in the list under the SysML – Jama mapping group in the left column.
  
  Figure 6 Syndeia dashboard, Mappings tab, adding a mapping in the SysML-Jama Mapping Group
Drag and drop the Requirement Set artifact – e.g. System Specification 1 which was shown in Figure 1 – into an empty SysML package, J4, and select the Package - Set mapping as shown in Figure 7.

Figure 7 Model transform from Jama System Specification 1 to SysML Package J4
Verify that SysML package was created for the Jama set and SysML Requirements were created for the Jama Requirement hierarchy as shown in Figure 8.

Figure 8 Package and Requirements generated from Jama
Return to the Syndeia Dashboard, open the Connections Browser tab, select the SysML Repository, then expand to the package used in step 6, J4. Expand and select the connection under the package System Specification 1, right-click it, and select Compare Source & Target as shown in Figure 9.

Figure 9 Connections Browser with connection selected to Compare Source & Target
The Comparison Result tab should show that the System Specification 1 package in SysML and System Specification 1 set in Jama are in sync, and their child requirements are also in sync as in Figure 10.

Figure 10 Comparison result for Package with requirements

Scenario 1b – Jama set with requirement hierarchy (including folders) mapped to SysML packages and requirements

In this Scenario 1b we will add to the mappings in Scenario 1a by including a mapping to transform, compare, and sync Jama Folders and SysML Packages. This will enable you to generate and sync a mixed structure of folders and requirements from Jama to SysML.

Begin with a Set that contains Folders and Requirements in Jama as shown in Figure 11.

Figure 11 Jama Set with nested Folders and Requirements
You should already have the Artifact Types and Mappings we added in Scenario 1a. We will now make a new Jama artifact type for Folder available and map it to a SysML package.
1. Add a new Jama artifact type. See Exercise 7.6 - Adding SysML-Jama Artifact Types for a more extended example with screen shots.
  1. Right-click Jama under Model Types and select Add Artifact Type.
  2. Choose a Jama Repository from the top pull-down menu.
  3. Click the Get Jama Item Types button.
  4. Select Folder from the Item Types pull-down menu.
  5. Click OK. We do not need to add any attributes for this example.
    
    Figure 12 Add Jama Artifact Type window when creating the Set artifact type
Next, we will create a new mapping using the Jama Folder artifact, and modify the Package - Set mapping to include it as a related mapping.
1. Add a new Package - Folder mapping.
  1. Right-click SysML - Jama under Mapping Groups in the left column and select Add Mapping.
  2. Set Name to Package - Folder.
  3. Set Description to SysML Package – Jama Folder.
  4. Set Source Artifact Type to Package, using pull-down menu.
  5. Set Target Artifact Type to Set, using pull-down menu.
  6. Set Structure Level to CHILDREN_RECURSIVE, using pull-down menu.
  7. Set Include Attributes to Exclude Attributes, using pull-down menu.
  8. Set Include Relations to Include Relations, using pull-down menu.
  9. Using the plus button under Related Mappings, add the related mapping as shown in Figure 13, Requirement - Requirement (attributes).
  10. Click Save Mapping at the bottom. The window should appear similar to Figure 13. The new mapping should appear in the list under the SysML – Jama mapping group in the left column.
    
    Figure 13 Syndeia dashboard, Mappings tab, adding a mapping in the SysML-Jama Mapping Group
2. Modify the Package - Set mapping’s related mappings.
  1. Select the Package - Set mapping under the SysML-Jama Mapping Group.
  2. Using the plus button under Related Mappings, add an additional related mapping as shown in Figure 14, Package - Folder. This step ensures that when a Set is transformed to a Package, the folders in the set are transformed to Packages as well.
  3. Click Save Mapping at the bottom.
    
    Figure 14 Syndeia dashboard, Mappings tab, adding an additional Related Mapping to the Package - Set mapping
Drag and drop the Requirement Set artifact – System Specification 2 which was shown in Figure 9 – into an empty SysML package, J5, and select the Package - Set mapping as shown in Figure 15.

Figure 15 Model transform from Jama System Specification 2 to SysML Package J5
Verify that SysML packages was created for the Jama set and folders and SysML Requirements were created for the Jama Requirements in the hierarchy as shown in Figure 16.

Figure 16 Packages and Requirements generated from Jama
Return to the Syndeia Dashboard, Connections Browser tab, and expand to the package used in step 4, J5. Expand and select the connection under the package System Specification 2, right-click it, and select Compare Source & Target as shown in Figure 17.

Figure 17 Connections Browser with connection selected to Compare Source & Target
The Comparison Result tab should show that the System Specification 2 package in SysML and System Specification 2 set in Jama are in sync, and their children, including folders and requirements, are also in sync as in Figure 18.

Figure 18 Comparison result for Package with sub-packages and requirements in SysML corresponding to Set with folders and requirements in Jama

Note: In this example, there are two item types in Jama (Set and Folder) that are mapped to the same element in SysML (Package). This works for generation and sync from Jama → SysML. However if we wish to sync the structure bidirectionally, we would need to distinguish the elements in SysML, typically by applying a unique stereotype to at least one of the artifact types (Package) generated from Jama Set or Folder, and defining it in the mapping. In general, we advise that you define 1-1 mappings, i.e. one SysML element type (with stereotype) maps to one Jama item type, for bi-directional transformation, compare, and sync. Scenario 2b shows an example of this.

Part 2: Generate SysML to Jama

In this section we use the mappings created in Part 1 and use them to generate from SysML → Jama, compare, and sync.

Scenario 2a – Drag and drop SysML package with requirements to a Jama component to generate a Jama set with requirements

In this Scenario 2a we will use the mappings created in Scenario 1a in the reverse direction to generate a Jama set with requirements from a SysML package with requirements.

For this scenario we will use the structure that was generated in Scenario 1a above as a base. Copy and paste System Specification 1 into the same package and rename it System Specification S as shown in Figure 19:

Figure 19 SysML package System Specification 1 copied and pasted, then renamed System Specification S
Refresh the package J4 in the Syndeia Connection Manager on the LHS. Drag and drop the SysML package System Specification S to a Jama Component, and select Package-Set mapping.

Note: A Set can only be created in a Jama project or a Component. This approach will also only work with the current mappings because the package System Specification S does not have any sub-packages. When generating the package from SysML to Jama the mapping chosen will be used for all packages. If you have packages nested in packages and want to maintain the structure as folders in Jama then use approach 2b instead.

Figure 20 Model transform from SysML System Specification S to Jama Component Jama_Tutorial
Verify that a Jama set with nested requirements was created for the SysML package System Specification S and its child requirements in the hierarchy as shown in Figure 21.

Note: The related mapping for the Package - Set mapping shown in Figure 5 and 11 was used to determine the child item type of the Jama Set. Syndeia looks at all related mappings that are not to a folder to determine set type. All nested SysML requirements will use this mapping. Other nested elements will be ignored.

Figure 21 Set and Requirements generated from SysML shown in Jama
Compare the connection under System Specification S in the Connections Browser and see that its structure is in sync.

Figure 22 Comparison result for Package with requirements in SysML corresponding to Set with requirements in Jama

Scenario 2b – Drag and drop SysML package and requirement hierarchy to a Jama set to generate folders and requirements

In this Scenario 2b we will use the mappings created Scenario 1b in the reverse direction to generate Jama folders with requirements from SysML packages with requirements. This is an example of 1-1 mapping: SysML packages mapped with Jama folders, and SysML requirements mapped with Jama requirements.

For this scenario we will use the structure that was generated in Scenario 1b above as a base. Copy and paste System Specification 2 into the same package and rename it System Specification N as shown in Figure 23:

Figure 23 SysML package System Specification 2 copied and pasted, then renamed System Specification N
In Jama, create a Set of the type Requirement, i.e. the type we used as the related mapping as shown in Figure 24:

Figure 24 Set named New Requirements Set created in Jama
Refresh the package J5 in the Syndeia Connection Manager on the LHS and the parent project or component of the new Set created in Jama on the RHS. Drag and drop the SysML package System Specification N to the New Requirements Set, and select the Package - Folder mapping.

Note: Folders can only be created in a Set in Jama. This is why we created the Set manually first. Alternately, if we wish to use both Set and Folder mappings for SysML → Jama, we could make some tweaks to the artifact types and mappings. In the mappings we have made so far, there are two item types in Jama (Set and Folder) that are mapped to the same element in SysML (Package). This works for generation and sync from Jama → SysML, however if we wish to sync SysML packages with Jama sets which contain folders bidirectionally or generate them from SysML → Jama, we would need to distinguish the elements in SysML, typically by applying a unique stereotype to at least one of the artifact types and creating a separate and distinct SysML Artifact Type with that stereotype applied to use in the mapping.

Figure 25 Generating System Specification N into New Requirements Set in Jama with the Package - Folder mapping
Refresh the Jama Explorer and see that a Jama folder with nested sub-folders and requirements was created for the SysML package System Specification N and its child folders and requirements in the hierarchy as shown in Figure 26.

Figure 26 Folder hierarchy with Requirements generated from SysML shown in Jama
Compare the Package - Folder connection under System Specification N in the Connections Browser and see that its structure is in sync.

Figure 27 Comparison result for Package with sub-packages and requirements in SysML corresponding to a folder with sub-folders and requirements in Jama

Congratulations! You have now learned how to map, transform, compare, and sync SysML element structure to/from Jama item structure with custom mappings of mixed types - SysML package / elements with Jama sets / folders / requirements (or items of any type).

Exercise 7.11 - Custom SysML-Jama Mappings for mixed structures