Solutions

 View Only

Data Exchange User Guide (3.0)

By Chris Asakawa posted 01-15-2020 15:41

  

Version 3.X

April, 20th 2022


Table of Contents

  • About
  • Use Cases
  • Intended Uses
  • Getting Started
  • Quick Start Guide
  • Mapping Generation
  • Import Only
  • Export Only
  • Settings
  • Exchange Via Conversation
  • Attachments


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

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

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
  • The user running the Data Exchange needs user admin privileges in Jama Connect

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.

Launching Data Exchange

Simply 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.

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.

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 dropdown 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 dropdown.

Please note that when mapping for a Round Yrip; 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.

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:
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 dropdown 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
  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
  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.

Settings

back to top

These settings can be found by clicking the File menu option in the top right-hand corner of the application

  • Export as ReqIFz: Output exports as ReqIFz. ReqIFz is a single output package consisting of the ReqIF file and its attachments zipped into a single archive file.
  • Reverse Relationship Direction: Import & Export relationships with the To/From item's swapped
  • Remove HTML from name field: Strip all HTML markup tags from any field that is mapped to a Jama name field
  • Remove HTML from all text fields: Remove HTML markup tags before writing to a jama text field.
  • Use Project ID (DocKey) as name when undefined: In Jama Connect the name field is required and must be populated. In the event that there is no data in the field mapped to name, Data Exchange will insert a default value of "DEFAULT" Selecting this option will set the name to the items document key. NOTE: this will incur a performance penalty of 3x per item.
  • Exchange Test Case Steps: When exchanging data with another Jama, you can transmit test step data. Test step data will be packed into the ReqIF tool extension.
  • Verify SSL Certificate: When disabled the Data Exchange will not verify the signature of the SSL Certificate used by the Jama Connect Server. This can be useful if your Jama Connect instance is using a self-signed SSL certificate.
  • Enable asynchronous requests: Select this option to increase performance. If you are having trouble completing an import or export, try deselecting this option. Some self-hosted instances of jama may not have sufficient resources to keep up with the request rate.
  • Throttle requests per second(1-15): Defaulted to 10 this setting defines the maximum number of requests per second the application is allowed to make to the server
  • Recreate doors project module hierarchy: When this option is selected, ReqIF files imported from doors will have the tool extensions inspected for doors folder path from the module to the project. These folders will be recreated in Jama as components and the Module will be created as a set in the created componenet tree.
  • Generate import report: When Selected this will output a CSV report post import. The report will contain one row for each imported item and will display the ReqIF identifier, The Jama ID, and the data from a specifiable attribute(See below)
    • Remove HTML from attribute: Strip any HTML from the attribute before writing to CSV.
    • Spec-Object attribute for import report: This is the name of an attribute to output to the CSV import report
  • Filter deleted objects: During import, when this option is selected inspect the specified boolean attribute, if its value is set to true, the object will be considered deleted and will not be imported. (Note: children of deleted items will also be ignored.)
    • Attribute for filtering deleted objects: The LONG-NAME of a reqif attribute to write to the CSV import report.

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. 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

Note: Before starting this process it is important to ensure the items to be exported are not locked, as this will prevent the Data Exchange from being able to update the Round Trip Identifier's on the items in Jama Connect.

  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 dropdown, 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 dropdown, 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

Note: Before starting this process it is important to ensure the items to be exported are not locked, as this will prevent the Data Exchange from being able to update the Round Trip Identifier's on the items in Jama Connect.

  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 dropdown, 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 Sets.

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 dropdown, 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 dropdown, 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.
0 comments
2313 views

Permalink