Data Exchange for Jama Software User Guide

By Ryan posted 11-21-2017 16:21

  

Data Exchange User Guide

Organizations utilizing requirements management tools often have the need to exchange large sets of information with other business units or organizations. The associated relationships and other metadata about individual information items must be persisted across different requirements management solutions as part of the exchange of data. ReqIF (Requirements Interchange Format) is a standard format created to facilitate ease of data exchange across solutions. Data Exchange for Jama Software (Data Exchange) is a utility provided for Jama users to transmogrify Jama information into ReqIF format, and to import ReqIF information into Jama.

Use Cases

back to top

Jama-to-ReqIF Data Exchange

Data Exchange for Jama Software can be utilized to share requirements information with customers, vendors, systems integrators, suppliers, etc. who are utilizing other requirements management tools in order to improve the efficiency of collaboration.As an example, an automotive components manufacturer is collecting product requirements from their customers. To eliminate the need for redundant documentation and requirements gathering efforts, Data Exchange for Jama Software is used to import requirements information that is authored by the customer in their requirements management tool. After the initial import, the development team uses Jama to review and make changes to the requirements.
Picture1.png
Upon completion of the review and update process, the customer requirements are exported out of Jama back to ReqIF, and sent back to the customer. The customer imports the updated requirements into their requirements management tool and generates updates and reports as necessary. This exchange process continues throughout the development of the customer product, keeping both the supplier and customer teams informed and up-to-date about modifications without the need for additional documentation, external messaging, or other integrations. When the ReqIF file returns to Data Exchange for a follow-up import into Jama, the existing Jama Items are updated and versioned appropriately with the new changes (instead of creating duplicate items during each new import).

Jama-to-Jama Data Exchange

Data Exchange for Jama Software can be used to share information between disconnected instances of Jama. This is especially useful when one or both Jama environments are running in an air-gapped network configuration and traditional integration platforms are not feasible.

Migrations

Data Exchange for Jama Software can also be used to migrate the information within an existing requirements management tool to Jama as a one-time migration.

Prerequisites Prior to Running Data Exchange

back to top

Setup

See detailed setup instructions for system prerequisites

Jama Project Setup

  1. The Attachment widget must be enabled on the Component item type. Data Exchange uses this to persist metadata for the integration.
  2. Configure a custom text field for legacy ID information on the Component, Set, Folder and Text item types
  3. Configure a custom text field for legacy ID information on all item types intended to be included within the scope of Data Exchange imports / exports.

Data Exchange License Activation

back to top
A license must be obtained from your Professional Services consultant in order to operate the application. Once you have your license, create a folder in the directory where the jar application is located titled "Util". Place your license file in this Util folder, and it will be auto-detected and interpreted by the application. Placing your license with theUtil directory is required for command line execution.

Running the Data Exchange from the Command Line

back to top
The Data Exchange can be run via the command line and is set up to mimic the user interface's functionality.

Import

To import content into Jama using the Data Exchange, you can run the jar application with the following command: java -jar DataExchange.jar -i

Users will need to include the necessary parameters to perform an import via a properties file

  1. Place your license file in Util directory located in the same directory as the executable jar
  2. Rename the properties.dst to jama.properties and modify the following settings:
    1. jamaURL=https://instance.jamacloud.com
    2. For Basic authentication, include:
      1. username=
      2. Password=
    3. For OAuth authentication, include:
      1. clientID=
      2. clientSecret=
    4. specObjectLegacyIDConfiguration=DEFAULT (or the name of the Jama field this attribute is mapped to)
    5. specificationLegacyIDConfiguration= DEFAULT (or the name of the Jama field this attribute is mapped to)
    6. projectID= comma separated list of import target project API IDs. If only one project is listed, all source files will be imported into the same project. Otherwise, specify as many projects as there are folders within the source directory
    7. source= absolute path to source directory. Imports should be organized into folders (containing the ReqIF source file, any attachments, and the associated mapping file) within the source directory. The number of folders within the source directory should correspond to the number of import target projects (unless importing all content into a single project)

Export

To export content from Jama using the Data Exchange, you can run the jar application with the following command: java -jar DataExchange.jar -e Users will need to include the necessary parameters to perform an export via a properties file
  1. Place your license file in Util directory located in the same directory as the executable jar
  2. Rename the properties.dst to jama.properties and modify the following settings:
    1. jamaURL=https://instance.jamacloud.com
    2. For Basic authentication, include:
      1. username=
      2. Password=
    3. For OAuth authentication, include:
      1. clientID=
      2. clientSecret=
    4. specObjectLegacyIDConfiguration=DEFAULT (or the name of the Jama field this attribute is mapped to)
    5. specificationLegacyIDConfiguration= DEFAULT (or the name of the Jama field this attribute is mapped to)
    6. projectID= comma separated list of export target project API IDs. If only one project is listed, all components will be exported from the same project. Otherwise, specify as many projects as there are component IDs
    7. componentID= comma separated list of component document key(s) to be exported. The number of component document keys should correspond to the number of project IDs (unless exporting all content from a single project)
    8. outputLocation= absolute path to output directory for export(s)
    9. mappingFile= comma separated list of absolute path(s) to mapping file(s) for export(s). The number of mapping files listed should correspond to the number of component document keys. If all exported components require the same mapping file, only one mapping file must be specified.
    10. deliveryNote= true, if you would like an html export summary created for all exports, false otherwise
    11. reqifzPackage=true, if you would like a ReqIFz package created for all exports, false otherwise

Advanced Settings

back to top
Advanced settings allow the application to retain user previously configured settings relating to:
  1. Batch (multiple) imports/exports
  2. Delivery Note
  3. ReqIFz Package

Saved Settings

The application will attempt to save a user's last login credential, as well as their saved settings (Batch, Delivery Note, and Packaging). This will allow users to quickly pick up where they left off without having to reset their last used settings. Last used credentials and advanced settings will be saved to a file titled "settings.json" in the "Util" folder. The "Util" folder, if it doesn't exist, will be created in the same directory the jar application is located in. We do not recommend users modify these configurations, but can if they are familiar with the .json format.

Setting Configurations

The following settings are configurable for both user interface usage as well as command line execution:
  • Batch

    The application supports the import of multiple .reqif source files, and the export of multiple Jama components at one time. To enable batch imports and/or exports from the user interface:
    1. Login to the application
    2. Click on the Settings menu option
    3. Click on Batch
    4. Select Batch from the drop-down menu
    5. Click OK
    The user interface will now reflect the required configuration to support multiple imports/exports.
  • Import

    1. Source Location: Absolute path to the source directory. Imports should be organized into folders (containing the ReqIF source file, any attachments, and the associated mapping file (if required)) within the source directory. The number of folders within the source directory should correspond to the number of import target projects (unless importing all content into a single project)
    2. Select the project you would like to import each ReqIF source into.
    3. Click Import
  • Export

    1. Output Location: Absolute path to output directory for export(s)
    2. For each component you wish to export from Jama, click Add Component
    3. Select the Project, Component, and mapping file for each component. If you do not wish to use a mapping file for a particular component, do not specify a mapping file for that component
    4. Click Export
  • Delivery Note

    A delivery note is an html output file containing a summary of exported content. If multiple Jama components are exported, the delivery note will contain a summary of each export. To enable generating delivery notes:
    1. Login to the application
    2. Click on the Settings menu option
    3. Click on Delivery Note
    4. Select Yes from the drop-down menu
    5. Click OK
  • ReqIFz Package

    A ReqIFz package is a zip file containing all exported content and is a standard format for distributing multiple ReqIF sources and is typically accompanied by a Delivery Note. To enable generating ReqIFz packages:
    1. Login to the application
    2. Click on the Settings menu option
    3. Click on ReqIFz Package
    4. Select Yes from the drop-down menu
    5. Click OK
  • Attribute Legacy ID Configuration

    Round trip operations are common for users who need to import an incoming ReqIF document, author updates, and export the imported content with authored changes. The IDENTIFIER element of every ReqIF item is used as the default legacy ID that achieves this round-trip functionality. Users are now able to modify this setting to select an attribute within SPEC-OBJECTs and SPECIFICATIONs to be used as the legacy ID for round trips. The attribute selected should match your "legacyFieldName" mapping configuration for SPEC-OBJECT/SPECIFICATION mappings. To edit the default legacy ID setting:
    1. Login to the application
    2. Click on the Settings menu option
    3. Click on Attribute Legacy ID Selector
    4. The DEFAULT setting is selected for both SPEC-OBJECT and SPECIFICATION
    5. To change the DEFAULT setting, click on the element you wish to set an attribute-level legacy ID for.
      1. To change the default setting, click on the drop-down list and select Add Attribute
      2. You will be prompted to enter an attribute's mapped Jama field name
      3. Clicking on OK will return you to the previous selection screen with the newly entered attribute added to the drop-down list.
      4. Select the newly created attribute and click OK
    6. Once you've selected an attribute, you will be taken back to the Attribute Legacy ID Selection window to select another element.
    7. ClickClose when you're finished to save your settings

Authentication

back to top
  • Basic authentication (username & password)
  • OAuth 2.0 (client ID & client secret)

Import Validations

back to top
ReqIF Import Validations: there are two new ways to validate your import content before actually running the import:
  • Pre-Flight Validation: is automatically run when you select a source ReqIF file to be imported. This pre-flight report will run quickly and give you basic information on your ReqIF source content.
  • Main Import Validation: the main import validation is activated from a validation button on the import view. This main validation will validate the source ReqIF file and a mapping file. This validation report will determine if the mapping is correct and will ensure that the ReqIF identifier are present in the source content and also will look into Jama Connect to see if all the item types, item type fields and relationship types exist. In addition to this there is also an option for the user to save the validation report to an HTML file.

The validation process verifies the following mappings:

Item Types & Specification Mappings
  • Item type selection is present in Jama Connect
  • Item type fields are present in Jama Connect
  • SPEC-OBJECT / SPECIFICATION field attributes are present in the source ReqIF
  • The source and destination field level types are valid
Relationship Mappings
  • Verifies that the destination relationship type is present in Jama Connect
  • Verifies that the source SPEC-RELATION type is present in the source ReqIF content

Data Mapping

back to top
The mapping file contains a set of instructions for creating and maintaining a mapping of ReqIF SPEC-OBJECT-TYPEs and SPEC-RELATION-TYPEs to specified Jama Items and Relationship types within a given Jama instance. This mapping is necessary for Data Exchange to understand how information should translate the project information across tools.

Mapping Operations

For each SPECIFICATION-TYPE mapping, 4 parameters must be specified within each mapping operation:
  1. operation - mapSpecificationType
  2. reqifSpecificationTypeIdentifier - SPECIFICATION-TYPE identifier (string)
  3. legacyIdFieldName - A custom text field name used to support round-trip exports (string)
  4. fields - An array of field mappings, each containing the following attributes:
    • reqIfAtttributeName - The long name of an attribute (string)
    • jamaFieldName - A Jama field name (string)
For each SPEC-OBJECT-TYPE to Jama Item type mapping, 5 parameters must be specified within each mapping operation:
  1. operation - mapItemType
  2. reqifSpecObjectTypeIdentifier - SPEC-OBJECT-TYPE identifier (string)
  3. jamaItemTypeId - A Jama item type identifier (string)
  4. legacyIdFieldName - A custom text field name used to support round-trip exports (string)
  5. fields - An array of field mappings, each containing the following attributes:
    • reqIfAttributeName - The long name of an attribute (string)
    • jamaFieldName - A Jama field name (string)
For each SPEC-RELATION-TYPE to Jama Relationship type mapping, the following 3 parameters must be specified within each mapping operation:
  1. operation - mapRelationshipType
  2. reqifSpecRelationTypeIdentifier - SPEC-RELATION-TYPE identifier (string)
  3. jamaRelationshipTypeId - A Jama Relationship type identifier (string)

Limited mappings

The Data Exchange mapping allows you to specify a limited mapping of fields to export and import. Meaning you can import with a limited set of fields specified in the mapping file, and only those fields will update in Jama. Likewise you can also export a limited set of mapped fields, and only the specified fields will appear in the objects in the exported ReqIF file.

limited mapping for specifications

In order to perform an export with limited mapping of a specification you must add an additional field to the mapping file that informs the data exchange which Jama item type is being exported.

  1. Open your mapping file
  2. add a new argument called "jamaItemTypeId" to your specification mapping object.

Create a Mapping with the User Interface

back to top

Overview

Within the Data Exchange a mapping file defines how items and relationships translate between Jama Connect and ReqIF. Setting up the mapping file correctly is important for the Data Exchange to work as expected.


Global Application Settings

Global application settings are pre-set with the values pictured below. These values are NOT saved in mapping file itself, instead these settings within settings.json file. These values will update into the proprieties file once you save and close the mapper, or you close the tool itself (hitting 'Cancel' will not save the changes).

  1. Default Unique ID: This field is used to set the jama default field name to store the default unique id pulled from the ReqIf source (this is required for round-trip import/export). the mapping level "legacy id field" will overwrite this global value.
  2. Custom Spec-Object / Specification Attribute: This specifies the field in which your unique identifier will be used. Leaving this as DEFAULT uses "IDENTIFIER ATTRIBUTE" of the spec-object/specification. Ensure that this attribute value is unique across the document. (Its highly recommended to leave this field set to DEFAULT)
  3. Package export as ReqIFz: By checking this, once the export completes Data Exchagne will package up the content as a ReqIFz.
  4. Export with delivery report: by checking this checkbox, export will also create an export report summary (in HTML).

How to Create Mapping between ReqIF and Jama

Generate Mapping from Source

This section describes the process to generate a import mapping file from a ReqIF source file with the mapping UI.

  1. Open the Mapping UI by clicking the manage button on the right side of the mapping file field.Click the manage button to open the Mapping UI
  2. Click the Generate Mapping button.
    Generate Mapping from source button
  3. Select the source ReqIF file from the file picker dialog.

  4. For each Item, Type click the edit button to configure mapping for that item.
    Select Item Type Screen
  5. To configure an Item Type, first decide what Jama Item Type the ReqIF item type will map to. This can be accomplished by copying the ReqIF Object Type string and searching for it in the ReqIF source file. Find the <SPEC-OBJECT-TYPE> with the IDENTIFIER that matches the ReqIF Object Type string displayed in the Data Exchange. Use the LONG-NAME and <SPEC-ATTRIBUTES> to decide which Jama Item type is an appropriate match. Select the identified item type from the dropdown menu.
    Map item type screenReqIF Searching
  6. Optionally select a Round trip ID from the dropdown. "legacy_id" is the default name used for this.

  7. For each ReqIF attribute listed in the left column, select a Jama Item Type field to map to from the drop down box in the right column. The field chosen must have a compatible data type with the ReqIF attribute. The ReqIF attribute data type can be determined by looking in the ReqIF file at the <SPEC-OBJECT-TYPE> identified previously. Within the <SPEC-OBJECT-TYPE> element will be a <SPEC-ATTRIBUTES> element that contains a number of <ATTRIBUTE-DEFINITION-<some data type>> by identifying the attribute definition that has a matching "LONG-NAME", you can determine the data type of the ReqIF attribute.
    Map Item Type Screen

  8. Click the Done button to apply these mappings.

  9. Click the Specification Types tab. For each Specification Type, click the Edit button to configure the mapping for that specification.
    Select Specification Type

  10. Optionally select a Round Trip ID from the dropdown box. Map any fields that are to be imported.
    Map Specification Type

  11. Click Done to apply the mapping.

  12. Click the Relationship Types Tab.

  13. For each relationship type click the Edit button to configure the relationship.
    Select Relationship Type

  14. Select a Jama Relationship type from the dropdown menu on the right and click Done.
    Map Relationship Type

  15. Click on the Save and Close button when you have finished configuring all of your items, specifications, and relationships. A file save dialog will open, choose a name for the mapping file. A .json file extension will automatically be applied if omitted.

  16. Congratulations you have created your first mapping file from source. Use the Select button to the right of the Mapping File text box to select the file you have just created.

Data Type Casting

back to top

The following table shows how ReqIF's attributes definitions map to and from Jama's field data types

ReqIF Attribute Definitions Jama Field Data Types
Boolean Flag
Date Date
Integer Integer
Real Text Field or Text Box
String Text Field or Text Box
Enumeration Pick List *
XHTML Rich Text

* When configuring the pick list to map between an enumeration, make sure that all the ReqIF "Enum Values" have corresponding Jama pick list values to associate to. Make sure that that each picklist option's "Display" field exactly matches the Enum Value's "long-name" field.

Download Sample Mapping File

back to top
A sample mapping file can be retrieved from the Data Exchange UI. The sample is intended to illustrate the how Jama Item types can be mapped to the ReqIF standard format and to provide a starting point for authoring a custom mapping file.

Generate Starter Mapping File

back to top
A mapping file with field mappings pre-configured based on an existing ReqIF file can be generated. This generated mapping file will include all of the
SPECIFICATION-TYPEs, SPEC-OBJECT-TYPEs (Item types), their ATTRIBUTES (Item type fields), and SPEC-RELATION-TYPEs (Relationship types) found within the specified ReqIF file, as well as placeholders for the user to fill in the necessary Jama configurations for mapping.There are 4 Jama-specific attributes in the mapping file that need to be configured:
  1. legacyIdFieldName - This field is specified as ‘legacy_id' by default, but can be configured to support a custom text field name, as required.
  2. jamaItemTypeId - For each ‘mapItemType' operation, the ‘jamaItemTypeId' attribute must be configured.
  3. jamaFieldName - For each field mapping, the ‘jamaFieldName' attribute must be configured.
  4. jamaRelationshipTypeId - For each ‘mapRelationshipType' operation, the ‘jamaRelationshipTypeId' attribute must be configured.

Exporting

back to top

What is Exported

Jama Components must be used to encapsulate the scope of an export. A Component is specified in the Data Exchange Export, and the following elements contained within that Component are used to populate the ReqIF content:
  1. Items and their associated fields and metadata
  2. Relationships between Items contained in the specified Component
  3. Hierarchy structures within the specified Component

What is Not Exported

  • Comments and collaborative elements such as Questions, Answers, and Decisions
  • Item Versions
  • Custom Filters
  • Tags
  • Test Plans, Test Cycles, Test Runs, and Test Groups cannot be exported. (Test Cases can be exported if they're included in the specified Component)
  • Attachments added to the Item attachment widget are excluded (However, embedded attachments are included. See the Attachment Handling section of this document for further detail).
  • Releases are excluded from the export (but a Release field on an Item is included in the export as a text field)

Importing

back to top
Any valid file that adheres to the ReqIF standard can be consumed by Data Exchange. The Jama Items types should be configured in advance with on the SPEC-OBJECT attributes (Item fields) found within the ReqIF file.

Attachment Handling

back to top

Embedded Attachments

Image files embedded inside of the Item rich text editor, including diagrams, equations and download links, are referenced within the generated ReqIF file and stored in the ‘Attachments' subdirectory of the export.

Jama Item Attachment Widget

Files attached to Jama Items via the ‘Attachment' widget on Items are not supported by Data Exchange for Jama Software due to structural limitations in the ReqIF standard.
Picture2.png
It is recommended that users embed attachments within the Rich Text Editor. Disabling the Attachment widget on Items within the scope of exchanged Components may mitigate user confusion between the available methods (the Attachment widget is still required on the Component Item type to enable round-trip functionality through Data Exchange).

Best Practices

back to top
  • Disable the attachment widget on Items to ensure users do not add attachments that cannot be exported (However, attachments on Component item must be enabled because Data Exchange stores ReqIF metadata required for round-trip functionality on Component attachments).
  • The Legacy ID field name can be customized for all mapped SPECIFICATION-TYPEs and SPEC-OBJECT-TYPEs, as required.
  • The Legacy ID custom text fields added to Jama Items should be configured as Read-Only and allow for an API overwrite as illustrated below, in order to prevent users from inadvertently changing a field value that Data Exchange depends upon for round-trip exchange operations.
Picture3.png
  • Create a Baseline in Jama prior to running a Data Exchange Export in order to capture of snapshot of the project at time of export for later reference
  • Never map legacy_id fields
  • Release, User, URL must be mapped to text fields types
  • documentKey and globalId should be mapped to external text fields (not those same field names)

Support and Maintenance

back to top

Versions

Data Exchange for Jama Software is supported on Hosted and On-Premise Jama environments running Jama 8.0 or later with the REST API enabled.

Post a Discussion

For assistance with using Data Exchange, best practices and FAQs, please post a discussion to the Professional Services community page.

Create a Support Request

For technical problems using Data Exchange, send an email to pss@jamasoftware.zendesk.com for assistance. Please include details about the source and destination for the operation, any errors you're encountering, and any relevant screenshots or log output.
0 comments
622 views