Mappings.

Owned by Debesh Roy Chowdhury
Last updated: Feb 22, 2024
7 min read

Introduction

Since its first release, Syndeia has provided a powerful capability for model transformations, the ability to generate models in a target repository/tool from a model in a source repository/tool. For example, using SysML blocks to generate issues in JIRA or items in Teamcenter (and vice versa), or using SysML requirements to generate requirements in Jama, Teamcenter, or DOORS-NG (and vice versa). In addition to generating models, this process also creates persistent connections between source and target model elements which can be used for compare and synchronization as the source and target models evolve over time. 

Model transformations are based on mapping rules, referred to as mappings hereafter, that specify the types of model elements that will be generated in the target model from the types of model elements in the source model. For example, there is a pre-defined mapping in Syndeia that maps a SysML Block to a Teamcenter Item, and this mapping is used when a Teamcenter element of type Item is used to generate elements in a SysML model or when a SysML element of type Block is used to generate elements in Teamcenter.

Syndeia 3.2 made it possible for users to define custom mappings between artifact types and attributes in different repositories, and use those mappings to govern model transformations, comparison, and synchronizations.

Syndeia 3.3 introduced the ability to define relationship mappings in addition to artifact mappings and attribute mappings. As a result, users can map SysML relationship types (e.g. Containment, Part Property/Associations) to relationship types in other repositories (e.g. Jira link types - Blocks, Relates). 

A general approach for using the mapping capabilities is presented below, followed by a list of hands-on step-by-step tutorials to get started with the mappings.

General Approach

The mapping capabilities in Syndeia are simple to set up and use. A general approach is presented below. 

Mapping Authors and Users

With great power, comes great responsibility. Mappings are fundamental to operations in Syndeia. Mappings should be created or edited by advanced users of Syndeia who are knowledgeable about the type systems being mapped. We will refer to these advanced users as Mapping Authors, and users who will use mappings for generating, comparing, and synchronizing models as Mapping Users. 

  1. Mapping Authors can create, edit, or delete artifact types, mappings, and mapping groups. Mapping Users can use mappings during model transformation, compare, and synchronize operations but not create, edit, or delete mappings.
  2. Syndeia provides a Mapping Author license file that every Mapping Author should have available with the regular Syndeia license. Syndeia checks for this license file to identify Mapping Authors versus Mapping Users.

Defining Artifact Types

Syndeia's mapping capabilities are available from the Mappings tab in the Syndeia Dashboard, as shown below. In Syndeia, model elements from all repositories/tools are referred to as artifacts. Since mappings are defined between artifact types, we must first add (register) an artifact type from a given model / repository type to Syndeia. The LHS of the Mapping pane has two section: (1) Model Types, and (2) Mappings. The Model Types section lists the different types of models / repositories supported in Syndeia, such as DOORS-NG, Jama, JIRA, SysML, and Teamcenter. Right click on a model type and select the Add Artifact Type menu to add an artifact type from that model / repository type to Syndeia.

For a given repository, Syndeia will fetch all the available artifact types. For example, it will fetch all Jama item types for a given Jama repository. When a specific artifact type is selected (e.g. System Requirement in Jama), Syndeia can fetch all the available properties for that artifact type. In Syndeia, these are called "attribute definitions". For example, 5 attribute definitions are available, as shown in the table, for the System Requirement artiact type in Jama. For each attribute definition, Syndeia gathers its meta-information, such as its type, if it holds a single value or collection of values, if it is modifiable, if a value is required, default value(s) of the attribute, and the allowable values if it is an enumeration type. In the table, users can select all or specific attribute definitions for Syndeia to use.

Mapping Groups and Mappings

It is a good idea to organize mappings into groups based on the source and target model type, such as create a mapping group "SysML - Jama" to organize all the mappings between SysML artifact types and Jama artifact types. For example, four different mapping groups are shown below, SysML - DOORS-NG, SysML - JIRA, SysML - Jama, and SysML - Teamcenter. Users can add new mappings in each group by selecting a source artifact type and a target artifact type. For example, details of SysML Activity - JIRA Task mapping are shown below. For each mapping, users can specify the following:

  1. Source Artifact Type and Target Artifact Type - Artifact types, originaing from two different model / repository types, that are being mapped. For example, SysML Activity is mapped to JIRA Task in the exampel shown below. It is mandatory to specify source and target artifact types in each mapping.
  2. Structure Level - Option to generate structure when transforming an artifact of source artifact type to the target model (and vice versa). In the example shown below, CHILDREN_RECURSIVE is selected. This implies that when a SysML Activity element (artifact) is used to generate JIRA Task artifact, the activity structure (call behavior actions) are used to generate linked JIRA issues recursively. The following options are available for Structure Level.
    1. NO_CHILDREN - Indicates that no children will be generated
    2. CHILDREN_IMMEDIATE - Indicates that only immediate children will be generated
    3. CHILDRENT_RECURSIVE - indicates that children will be generated in a recursive manner
  3. Attribute Definition Mappings - Mapping of attribute definitions of the source and target artifact types. In the example shown below, assignee, info, priority, and summary attribute definitions (tags originating from multiple stereotypes) on a SysML Activity artifact type are mapped to Assignee, Status, Priority, and Summary attribute definitions for JIRA Task artifact type respectively.
  4. Stereotypes - List of stereotypes to be applied to SysML artiact types participating in the mapping. The list of SysML stereotypes is used to derive the attribute definitions for the SysML artifact type (e.g. Activity) that can be mapped to attribute definitions of other artifact types (e.g. JIRA Task), as shown in the Attribute Definition Mappings.
  5. Relationship Mappings - Mapping of relationship types of the source and target artifact types. In the example shown below, the Derived Requirement and Verified by relationship types in SysML are mapped to Derived from and Verified by relationship types in Jama.

Using Mappings

To use mappings in Syndeia, go to the Settings tab in the Syndeia Dashboard and select the Use Mapping option (in General category) as shown below. If this option is not selected, then Syndeia will only use the pre-defined mappings when generating models, as in the previous releases of Syndeia.


If the Use Mapping option is selected and a user tries to drag and drop an artifact from a SysML model to another model / repository (or vice versa), Syndeia will check for available mappings and present an option to select a mapping. For example, if we drag and drop a JIRA Task (JIRA issue of type Task) to a SysML package, Syndeia will present all mappings between SysML artifact types and JIRA Task. In this example, there are four mappings available for JIRA Task and the first one has been selected. Based on this selection, Syndeia will generate SysML Activity elements (artifacts) for the given JIRA tasks.

Getting Started

In Syndeia 3.3, the mapping capability is available for model transformations involving SysML models and the following repositories. Refer to the step-by-step tutorial exercises linked below.

Limitations

There are 2 main limitations in the mapping capability in this version of Syndeia. We are actively working to expand the mapping capabilities and address these limitations in the next version of Syndeia.

  1. Mapping capabilities are supported for mapping SysML artifact types to Jama, Teamcenter, JIRA, and DOORS-NG artifact types.
  2. Once the mappings are finalized by the Mapping Authors, the syndeia.mappings file (located in the .syndeia) folder must be distributed to all the mapping users to include in their .syndeia folder. Mapping definitions are stored locally in this version of Syndeia. It will be managed on Syndeia Cloud in the next release of Syndeia.