Data Exchange User Guide (3.0)

By Chris posted 01-15-2020 15:41

  

Version 3.3.X

July, 20th 2020


Table of Contents



About

back to top
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 tools 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 translate Jama information into ReqIF format, and to import ReqIF information into Jama.

Use Cases

back to top
  • Export from Jama as source (Archival)
  • Import to Jama from another repository (Migration)
  • Begin a new conversation
  • Continue a conversation


Intended Uses

back to top
Data Exchange Overview

Jama to ReqIF Data Exchange

The Data Exchange for Jama Software can be used to improve the efficiency of collaborating with third parties using ReqIF compliant requirements management tools by facilitating the ongoing exchange of data over time. As an example, an automotive components manufacturer is collecting product requirements from their customers. To eliminate redundant documentation and requirements gathering efforts, Data Exchange for Jama Software is used to import requirements information authored by the customer in another tool. After the initial import, the development team uses Jama to review and make changes to the requirements.

Upon completion of the review and update process, the customer's requirements are exported from Jama Connect as ReqIF and sent 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 product development cycle, 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.

Jama to Jama Data Exchange

Similar to the previous use, the Data Exchange for Jama Software can be used to share information between separate instances of Jama. This is especially useful when one or both Jama environments are running in a network not connected to the public internet. For example, a government agency might contract development of a navigation system to a third party contractor who also uses Jama Connect. Each party would be able to import and export data using the Data Exchange.

In another example, a company might manage secure and non-secure requirements in different instances of Jama to achieve ITAR compliance. Reusable requirements from the non-secure instance can be exported and imported into the secure instance without having to have a direct integration. This can be a one-time import or cycle like other ongoing exchanges.

Migrations

The Data Exchange for Jama Software is an easy to use tool to migrate data from other ReqIF compliant tools.

Getting Started

back to top

Prerequisites

Recommended Hardware

  • Multicore processor >= 2 Ghz
  • >= 4 GB RAM
  • Network connection

Software Requirements

  • Java 8 by Oracle(must contain JavaFX libraries)
  • Windows or MacOS

Minimum Jama Version Requirements

  • Full support - Any supported version of Jama Connect
  • Best effort support - Jama Connect version 8.20+

Jama Configuration Requirements

  • Each ReqIF Spec Type Attribute that is to be imported into Jama must have a corresponding field. These Jama fields may already exist, e.g., Name and Description, or must be added through Item Type configuration. See "Data type mapping and casting" in the Mapping Generation section below for more details
  • The user running the Data Exchange needs read/write access in Jama Connect to the content they are importing/exporting

Licensing

A license must be obtained from Jama Software 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 in the Util directory is required for command line execution.
Util folder structure

Launching Data Exchange

simple double click the .jar file. Alternatively you can run the following console command to launch the jar file.
java -jar path/to/jar/DataExchange3.0.jar
In order to run the application from the command line supply a properties file as a parameter that specifies the desired behaviour of the exchange. (See: Creating a properties file for command line execution below)
java -jar DataExchange3.0.jar jama.properties

Creating a Properties file for command line execution

When executing the Data Exchange programmatically or via the command line the user must supply a .properties file that contains the configuration settings to describe the desired behaviour for this execution. One properties file will describe one execution of Data Exchange.

An Example jama.properties file

# Connection Settings
            jamaURL=https://<YOURDOMAIN>.jamacloud.com
            #clientID=1234567890ABCDEF
            #clientSecret=FEDCBA0987654321
            username=USERNAME
            password=PASSWORD

            # Tool Configuration
            specObjectLegacyIDConfiguration=DEFAULT
            specificationLegacyIDConfiguration=DEFAULT
            reverseRelationshipDirection=false
            deliveryNote=true

            # Import/Export common settings
            exchangeType=IMPORT|EXPORT
            isExchange=true
            projectID=48
            mappingFile=/PATH/TO/MAPPING/FILE.json
            newConversationName=Desired new conversation name, if a name is already present for this conversation, no change will be made.

            # Import specific settings
            source=/PATH/TO/FILE.REQIF  OR /PATH/TO/FILE.REQIFZ
            importRootIDType=PROJECT|ITEM
            importRootID=1234(int)

            # Export specific settings
            exportType=PROJECT|LOCATION|FILTER|BASELINE
            exportRootID=1234(int)
            conversationID=_ABCDEF1234567890
            useRootAsSpecification=false
            outputLocation=/PATH/TO/OUTPUT/LOCATION
            packageAsReqifz=true
        


Quick Start Guide

back to top
This section will guide you through your first export and import. We strongly recommend you do your initial testing in a Sandbox or Test project and not use your production environment.

Example Export

The following steps outline the process to export Jama content into a ReqIF file.
  1. First identify a Jama project and a location from which to export. This can be at the root of the project, component, set or folder of items
  2. Launch Data Exchange and log in
  3. Select the Export tab
  4. Select Export Only as the exchange purpose
  5. Select export from Location
  6. Select the project identified in step 1
  7. Select the location to export from
  8. For mapping select New. This will open up the mapping generation, and then click save without making any changes. This will create a default mapping
  9. Click Export
All the items under the location selected will be serialized into ReqIF with its relationships and attachments included.

Example Import

The following steps outline the process to import ReqIF data into Jama.
  1. Download a sample ReqIF file
  2. Launch Data Exchange and log in
  3. Select Import Only as the exchange purpose.
  4. Click the select button on the source ReqIF file, and navigate to the downloaded sample .reqifz file
  5. Select any project to test example import in
  6. Select the root of the project as the location
  7. Click the new button on the mapping option, and fill out the required mapping in the four tabs
  8. Click Import
Login to Jama and navigate to the selected project and location to see the content that was just imported from Data Exchange.

Mapping Generation

back to top
The Data Exchange requires a mapping file for both import and export. The Data Exchange is used to generate these mapping files and edit existing mapping files. Generally you should create a mapping for each new import or export. In some specific cases with conversations to certain 3rd party systems you may be instructed to re-use an import mapping file for an export to preserve the original systems metadata.

Import Mapping - required fields

Initiate the import mapping creation by first selecting a Source ReqIF file, then the Project and the Location. These fields are required in order to generate an import mapping file.
setup for export mapping creation

Export Mapping - required fields

Initiate the export mapping creation by first selecting Export From, the Project, and the Location. These fields are required in order to generate a mapping file.
How to create an export mapping

Mapping Specifications and Spec Objects

Each ReqIF specification will be represented in Jama as either a component, set, or folder. These specifications can be thought of as root containers to hold requirements. Each specification type mapping needs to follow Jama's hierarchy rules, see the table below.
Jama Type Hierarchy Parent Rules Child Item Type
Component Parent must be a project or another component multiple item types
Set Parent must be a project or a component single item type
Folder Parent must be a set or another folder single item type
Each spec object type needs to be mapped a corresponding Jama Item type. If using Data Exchange for round trip exchanges, be sure to use a one-to-one mapping of each ReqIF spec-object type to Jama Item type.

Mapping Spec-Relations

In order to exchange relationships each spec-relation needs to be mapped. When creating an import mapping, use the drop down to select a Jama Relationship Type to map the ReqIF Spec-Relation. For export there will be a text field which maps to the ReqIF longName attribute.

Mapping Enumerations

Each ReqIF enumeration will need to be mapped to a corresponding Jama Pick List.

For import, first select a pick list, next map each ReqIF enumeration-option to a Jama Pick List Option by using the provided drop down.

Please note that when mapping for a round trip; you must have a one-to-one mapping between enumeration values to picklist options. It is recommended that picklist has the same number of options as the enumeration has values. This will preserve data integrity between Jama and the external system (e.g. DOORS).

Round Trip ID

The round trip ID must be mapped in order to do exchanges. It is recommended to create a dedicated custom field on each item type being used, and make this field read only with allow api override.
item type config
On import the ReqIF identifiers will be mapped to this field and on export this field will be used to write back out the original ReqIF identifiers.

Doors 9.6 export mapping defaults

If exchanging and ReqIF format "IBM Doors 9.6" is selected then each name and description fields will be mapped as follows.
conversation name dialog
Jama Name Field Jama Description Field
Specification ReqIF.name ReqIF.description
Spec Object ReqIF.chapterName ReqIF.text
These values can be overridden, but this naming convention is required in order to maintain interoperability between Jama and Doors 9.6.

Data type mapping and casting

Jama and ReqIF each have their own base data types. In order to maintain functional round trip exchanges data can only be cast between logical data types.

On import Data Exchange will force the mapping selection into default type mappings. This means that the Data Exchange will only show you valid fields you can map to in the GUI drop down selection.
ReqIF Attribute Definitions Jama Field Data Types
Boolean Flag
Date Date
Integer Integer
Real Text Field or Text Box
String Text Field | Text Box | URL
Enumeration Pick List
XHTML Rich Text
Exporting from Jama as the source will generate these ReqIF data type attributes automatically.

Import Only

back to top
Data Exchange import screen
  1. Data Exchange version
  2. Jama Connect instance logged into
  3. Import / Export mode tab selection
  4. Purpose: Exchange vs Import Only
    1. Exchange: Use when you want to send updates back to the original system. Preserves ReqIF identifiers and spec types in Jama
    2. Import-Only: Use when you do not care to export updates for this data. does not preserve ReqIF identifiers
  5. Source ReqIF: Select the source .reqif or .reqifz file from your file system that you would like to import
  6. Select the Project you would like to import this ReqIF data into
  7. Select the Location within your project to import to
  8. Select or create a Mapping file (see Mapping Generation)
  9. Validate button: confirms your mapping file is valid with the selected import parameters
  10. Import: click this button when you are ready to begin your import
  11. Logs: execution and error logs will be output here


Export Only

back to top
Data Exchange export screen
  1. Data Exchange version
  2. Instance: Informs the user which Jama Connect instance the Data Exchange is connected to
  3. Import / Export mode tab selection
  4. Purpose: Exchange vs Export Only
    1. Exchange: Use when you want to send updates back to the original system Preserves ReqIF identifiers in the RoundTrip Identifier field
    2. Export-Only: Use when you do not care to re-import updates for this data at a later time. Does not preserve ReqIF identifiers
  5. ReqIF Format: This setting informs the data exchange of the system intended to consume the exported ReqIF. Changing this selection will change the default mappings for field names. This setting allows for improved compatibility with other tools
    1. Jama ReqIF - Default name mappings
    2. DOORS 9.6: applies default naming to mapping's that follow the naming conventions used by DOORS.
  6. Export Type: You may export requirements data from the following:
    1. Any location in the Jama Item tree
    2. A filter
    3. A Baseline
  7. Project: Select the project that you would like to export data from
  8. Location / Filter / Baseline: this dropdown will change depending on your export type selection 6. Use this dropdown to select the location filter or baseline you would like to export
  9. Include in Export checkbox: Checking this box will export the selected location as the single specification in this ReqIF export. Unselecting the box will export each immediate child of the selected location as a specification
  10. Mapping File: Select or Create a new Mapping File. (See Mapping Generation)
  11. Export To: This is the desired export directory to store your export. If you would like to export as ReqIFZ choose File > Settings > Export as ReqIFZ
  12. Export button: Click to begin the export
  13. Log panel contains the export execution information

Notes on Exporting Baselines and Filters

When exporting a Baseline or a Filter, there are a few special considerations. This is due to the fact that baselines and filters are exporting data that may be historical or disjoint (not in a common hierarchy tree).
  • Baseline and Filter exports are not eligible for Conversation(described below) creation or round trip usage
  • Filters cannot span multiple projects, they must be created for a specific project.
  • Baselines and Filters should be structured to export a single tree (specification) in order to export Jama items as Spec Objects. The container (component, set or folder) needs to be included in the export and requires some special consideration when creating filters or baselines
  • Baselines created from test-plans are currently not supported by data exchange and cannot be exported.
  • Orphaned attachment items returned form a baseline will not be included in the export. Attachments must be embedded in a rich-text field for that attachment object to be exported into ReqIF.


Exchange via Conversation

back to top
The back and forth exchange of requirements data between systems is accomplished with conversations. Conversation IDs are a standard in ReqIF that represent one thread of exchange or flow of data between two requirements systems via ReqIF. Jama will store metadata in a conversation attachment on the project, as well as within a predefined field on each item. Doing so allows exporting the ReqIF with the same identifiers assigned by the originating system.

Data Exchange allows for setting the name of each conversation.
Conversation name dialog
This will allow the user to quickly select the appropriate conversation for re-use in the future. The mapping file is also stored in your conversation meta data to facilitate quick re-use.

Jama to Jama

This section describes the general flow of data between two Jama Systems. referred to as Jama-A and Jama-B.

Step 1: Export requirements data from Jama-A to ReqIF

  1. Log into Data Exchange connecting to Jama A and Select the Export Tab
  2. Select Exchange as the purpose
  3. Select Jama ReqIF as the ReqIF Format
  4. Select "New Conversation" from the drop down, click select, name your new conversation
  5. Select a project to export from
  6. Select a location to export
  7. Create a new Mapping file (See generating a mapping)
  8. Choose a directory to save the export. To export as ReqIFZ. choose File > Settings > Export as ReqIFZ
  9. Click Export
  10. Log out of Data Exchange

Step 2: Import requirements data from ReqIF to Jama-B

  1. Log into Data Exchange connecting to Jama B and select the Import tab
  2. Select Exchange as the purpose
  3. Select the ReqIF created in Step 1 as source
  4. Select "New Conversation" from the drop down, click select, name your new conversation
  5. Select the Project to import to
  6. Select the Location to import to
  7. Create a new Mapping File(see Mapping Generation.)
  8. Click Import
  9. Log out of Data Exchange

Step 3: Export requirements data from Jama-B to ReqIF

  1. Log into Data Exchange connecting to Jama B and select the Export Tab
  2. Select Exchange as the purpose
  3. Select Jama ReqIF as the ReqIF Format
  4. Select the Conversation created in Step 2 from the drop down, click select
  5. The project to export should be populated from the conversation data. If it is not, select the project now
  6. Select the location to export
  7. Create a new Mapping file (See generating a mapping)
  8. Choose a directory to save the export. To export as ReqIFZ. choose File > Settings > Export as ReqIFZ
  9. Click Export
  10. Log out of Data Exchange

Step 4: Import requirements data from ReqIF to Jama-A

  1. Log into Data Exchange connecting to Jama A and Select the Import tab.
  2. Select Exchange as the purpose
  3. Select the ReqIF created in Step 3 as source
  4. The conversation should be recognized and populated
  5. Project and location should already be populated from the conversation metadata. if they are not select the appropriate project and location now
  6. Create a new Mapping File (see Mapping Generation)
  7. Click Import
  8. Log out of Data Exchange

Jama to Doors

This section describes the general flow of data between Jama and IBM Doors. Our strategy is to map Doors Modules to Jama Set's.

Step 1: Export requirements data from Jama to ReqIF

  1. Log into Data Exchange and Select the Export tab
  2. Select Exchange as the purpose
  3. Select IBM DOORS as the ReqIF Format
  4. Select "New Conversation" from the drop down, click select, name your new conversation
  5. Choose the project to export from
  6. Choose the Location to export
    1. Note: It is important to select a compatible export that doors will be able to consume, select a location that contains only sets as children, This will cause each set to be created as a module in doors
    2. Uncheck the include in export box
  7. Create a new mapping file (See Mapping Generation)
  8. Choose a directory to save the export, To export as ReqIFZ, choose File > Settings > Export as ReqIFZ

Step 2: Import requirements data from ReqIF to Doors

  1. Select or create a new project in doors
  2. Import your ReqIFZ file into Doors, Doors will automatically create a new ReqIF Definition for the conversation ID contained in the ReqIF file

Step 3: Export requirements data from Doors to ReqIF

  1. Export the ReqIF Definition created in Step 2

Step 4: Import requirements data from ReqIF to Jama

  1. Log into Data Exchange and select the Import Tab
  2. Select Exchange as the purpose (this is the default)
  3. Select the ReqIF file produced in Step 3
  4. The Exchange conversation should be populated
  5. The Project and location should be populated, if not enter the desired project and location to import now
  6. Create a new Mapping File (See Mapping Generation)
  7. Click Import
  8. Log out of Data Exchange

Doors to Jama

This section describes the general flow of data between IBM Doors and Jama. Our strategy is to map Doors Modules to Jama Set's.

Step 1: Export requirements data from Doors to ReqIF

  1. Create a new ReqIF Definition (Be sure to lock all data or no updates will be applied on the re-import of the data)
  2. Export the ReqIF Definition to a ReqIFZ file. (Choose export .ole as .rtf option)

Step 2: Import requirements data from ReqIF to Jama

  1. Log into Data Exchange and select the Import Tab
  2. Select Exchange as the purpose (this is the default)
  3. Select the ReqIF or ReqIFZ file produced by your export from doors in Step 1
  4. Pick "New conversation" in the drop down, click select, and give this conversation a name
  5. Select the Project you wish to import this ReqIF file to
  6. Select the Location within this project you would like to import to
  7. Create a new mapping file (see Mapping Generation)
  8. Validate your mapping file with the validate button
  9. Click Import to start the import

Step 3: Export requirements data from Jama to ReqIF

  1. Log into Data Exchange and select the Export Tab
  2. Select Exchange as the purpose (this is the default)
  3. Select ReqIF Format: IBM Doors
  4. Select Exchange Conversation. Choose the conversation created in Step 2
  5. Select your export location. this should be whatever container, is directly above the doors modules imported as sets
  6. Deselect the "Include in export" checkbox
  7. Select the mapping file created in Step 2 in order to restore the correct ReqIF identifiers expected by the Doors system

    Note: You must use the mapping file created during import in Step 2 above. You may edit this mapping if you wish. However if you choose to create a new mapping then you will end up creating all new modules in DOORS instead of updating the existing ones.

  8. Choose a location to export to. It is suggest to export as ReqIFZ. choose File > Settings > Export as ReqIFZ
  9. Click Export

Step 4: Import requirements data from ReqIF to Doors

  1. Import your ReqIFZ file into Doors. Doors will recognize the conversation and match it with the ReqIF definition created in STEP 1
  2. Merge the imported ReqIF with the ReqIF Definition created in Step 1 to update and release the locks on the module


Attachments

back to top
ReqIF documents may be distributed with attachments, usually stored in a location relative to the .reqif file. Data Exchange will attempt to import any attachments included with a ReqIF import. Data Exchange will attempt to determine if this attachment already exists in the Jama database and if it does, the existing attachment will be reused rather than uploading a duplicate file.

Importing Attachments from DOORS to Jama

When exporting attachments from DOORS to ReqIF select the option found in DOORS to export OLE's as RTF's. This will increase the compatibility of the exported attachment within Jama. OLE's can also be imported into jama, however OLE's have a tendency to be more difficult to view.

Note: Attachment import/export is only supported for Jama rich text fields.  Attachments will not be imported to or exported from the Attachment Widget.

CSV Support

back to top
Data Exchange supports importing and exporting CSV items and relationships. It's important to note that this does not support attachments nor can it represent item hierarchy.

Exporting Projects and Filters

Data Exchange can export items and relationships from either a single project or a public filter.

Exporting Items

Items of specified types in a project can be exported into CSV format. When mapping items you will start with a list of every item type available to export, select the item types you want exported and map their field names to column names in the exported CSV file. Each item type will be exported into its own file which needs to be specified.

Exporting Relationships

Relationships in a project can also be exported into CSV format. Mapping relationships to export requires an upstream and downstream type to be specified. This will then pull down all the projects's relationships that match the item type conditions specified.

Importing Items

Items can also be imported from CSV format. When mapping import items, you will need to specify each file name and their corresponding Jama item types. Each individual CSV file will be represented as a single item type in jama. Data Exchange will create new items or update them if there is a round trip ID present.

Importing Relationships

Relationships can be imported into a project from a CSV file. When mapping import relationship specify the file name and up/down stream types for each relationship.csv file being imported. Data Exchange will only create new relationships.
0 comments
882 views