Data Exchange Release Notes
Version 3. X
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
Use Cases
- Export from Jama as source (Archival)
- Import to Jama from another repository (Migration)
- Begin a new conversation
- Continue a conversation
Intended Uses
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. For example, an automotive components manufacturer is collecting customer product requirements. 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 the supplier and customer teams informed and up-to-date about modifications without additional documentation, external messaging, or other integrations.
Jama to Jama Data Exchange
Similar to the previous use, the Data Exchange for Jama Software can share information between separate instances of Jama. This is especially useful when one or both Jama environments run in a network not connected to the public internet. For example, a government agency might contract the development of a navigation system to a third-party contractor who also uses Jama Connect. Each party could import and export data using the Data Exchange.Migrations
The Data Exchange for Jama Software is an easy-to-use tool to migrate data from other ReqIF-compliant tools.Getting Started
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 imported into Jama must have a corresponding field. These Jama fields, e.g., Name and Description, may already exist or must be added through Item Type configuration. See "Data type mapping and casting" in the Mapping Generation section below for more details.
- The Data Exchange user needs read/write access in Jama Connect to the content they are importing/exporting.
Licensing
A license must be obtained from Jama Software 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, which the application will auto-detect and interpret. Placing your license in the Util directory is required for command line execution.Launching Data Exchange
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.jarTo run the application from the command line, supply a properties file as a parameter that specifies the desired behavior 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 behavior 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
This section will guide you through your first export and import. We strongly recommend you do 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.- 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.
- Launch Data Exchange and log in
- Select the Export tab
- Select Export Only as the exchange purpose
- Select export from Location
- Select the project identified in Step 1
- Select the location to export from
- For mapping, select New. This will open up the mapping generation, then click save without making any changes. This will create a default mapping.
- Click Export
Example Import
The following steps outline the process to import ReqIF data into Jama.- Download a sample ReqIF file
- Launch Data Exchange and log in
- Select Import Only for the exchange purpose.
- Click the select button on the source ReqIF file, and navigate to the downloaded sample .reqifz file.
- Select any project to test example import in
- Select the root of the project as the location
- Click the new button on the mapping option, and fill out the required mapping in the four tabs.
- Click Import
Mapping Generation
Import Mapping - required fields
You can start the import mapping creation by selecting a Source ReqIF file, then the Project and the Location. These fields are required to generate an import mapping file.Export Mapping - required fields
You can create export mapping by selecting Export From, the Project, and the Location. These fields are required to generate a mapping file.Mapping Specifications and Spec Objects
Each ReqIF specification will be represented in Jama as 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. Please take a look at 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 must be mapped to a corresponding Jama Item type. Using Data Exchange for Round Trip exchanges, use a one-to-one mapping of each ReqIF spec-object type to the Jama Item type.
Mapping Spec-Relations
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, a text field will map to the ReqIF longName attribute.Mapping Enumerations
Each ReqIF enumeration must 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.
Just so you know, when mapping for a Round trip, you must have a one-to-one mapping between enumeration values to picklist options. It is recommended that the 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 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.Doors 9.6 Export Mapping Defaults
If exchanging and ReqIF format "IBM Doors 9.6" is selected, then each name and description field will be mapped as follows:Jama Name Field | Jama Description Field | |
Specification | ReqIF.name | ReqIF.description |
Spec Object | ReqIF.chapterName | ReqIF.text |
Data type mapping and casting
Jama and ReqIF each have their own base data types. Data can only be cast between logical data types to maintain functional Round Trip exchanges.Data Exchange will force the mapping selection into default type mappings on import. 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
- Data Exchange version
- Jama Connect instance logged into
- Import / Export mode tab selection
- Purpose: Exchange vs Import Only
- Exchange: Use when you want to send updates back to the original system. Preserves ReqIF identifiers and spec types in Jama
- Import-Only: Use when you do not care to export updates for this data. does not preserve ReqIF identifiers
- Source ReqIF: Select the source .reqif or .reqifz file from your file system that you would like to import
- Select the Project you would like to import this ReqIF data into
- Select the Location within your project to import to
- Select or create a Mapping file (see Mapping Generation)
- Validate button: confirms your mapping file is valid with the selected import parameters
- Import: click this button when you are ready to begin your import
- Logs: execution and error logs will be output here
Export Only
Data Exchange version- Instance: Informs the user which Jama Connect instance the Data Exchange is connected to
- Import / Export mode tab selection
- Purpose: Exchange vs Export Only
- Exchange: Use when you want to send updates back to the original system. Preserves ReqIF identifiers in the RoundTrip Identifier field
- Export-Only: Use when you do not care to re-import updates for this data at a later time. Does not preserve ReqIF identifiers
- 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.
- Jama ReqIF - Default name mappings
- DOORS 9.6: applies default naming to mappings that follow the naming conventions DOORS uses.
- Export Type: You may export requirements data from the following:
- Any location in the Jama Item tree
- A filter
- A Baseline
- Project: Select the project that you would like to export data from
- 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
- 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
- Mapping File: Select or Create a new Mapping File. (See Mapping Generation)
- 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
- Export button: Click to begin the export
- The log panel contains the export execution information
Notes on Exporting Baselines and Filters
There are a few special considerations when exporting a Baseline or a Filter. This is because baselines and filters export 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 and must be created for a specific project.
- Baselines and Filters should be structured to export a single tree (specification) to export Jama items as Spec Objects. The container (component, set, or folder) must be included in the export and requires special consideration when creating filters or baselines.
- Baselines created from test plans are currently not supported by Data Exchange and cannot be exported.
- The export will not include orphaned attachment items returned from a baseline. Attachments must be embedded in a Rich Text field for that attachment object to be exported into ReqIF.
Settings
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 comprising the ReqIF file and its attachments zipped into a single archive file.
- Reverse Relationship Direction: Import & Export relationships with the To/From items swapped.
- Remove HTML from the name field: Strip all HTML markup tags from any field 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 a name when undefined: In Jama Connect, the name field is required and must be populated. If no data is in the field mapped to the name, Data Exchange will insert a default value of "DEFAULT." Selecting this option will set the name of the item 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 uses a self-signed SSL certificate.
- Enable asynchronous requests: Select this option to increase performance. If you have 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 the 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 component 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
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
Just so you know, before starting this process, it is essential to make sure the items to be exported are not locked, as this will prevent the Data Exchange from being able to update the Round Trip Identifiers on the items in Jama Connect.
- Log into Data Exchange, connect to Jama A, and Select the Export Tab.
- Select Exchange as the purpose
- Select Jama ReqIF as the ReqIF Format
- Select "New Conversation" from the dropdown, click Select, and name your new conversation.
- Select a project to export from
- Select a location to export
- Create a new Mapping file (See generating a mapping)
- Choose a directory to save the export. To export as ReqIFZ. choose File > Settings > Export as ReqIFZ
- Click Export
- Log out of Data Exchange
Step 2: Import Requirements Data from ReqIF to Jama-B
- Log into Data Exchange connecting to Jama B and select the Import tab
- Select Exchange as the purpose
- Select the ReqIF created in Step 1 as the source
- Select "New Conversation" from the dropdown, click Select, and name your new conversation.
- Select the Project to import to
- Select the Location to import to
- Create a new Mapping File(see Mapping Generation.)
- Click Import
- Log out of Data Exchange
Step 3: Export Requirements Data from Jama-B to ReqIF
Just so you know, before starting this process, it is essential to make sure the items to be exported are not locked, as this will prevent the Data Exchange from being able to update the Round Trip Identifiers on the items in Jama Connect.
- Log into Data Exchange, connect to Jama B, and select the Export Tab.
- Select Exchange as the purpose
- Select Jama ReqIF as the ReqIF Format
- Select the Conversation created in Step 2 from the dropdown, click select
- The project to export should be populated from the conversation data. If it is not, select the project now
- Select the location to export
- Create a new Mapping file (See generating a mapping)
- Choose a directory to save the export. To export as ReqIFZ. choose File > Settings > Export as ReqIFZ
- Click Export
- Log out of Data Exchange
Step 4: Import Requirements Data from ReqIF to Jama-A
- Log into Data Exchange, connect to Jama A, and Select the Import tab.
- Select Exchange as the purpose
- Select the ReqIF created in Step 3 as the source
- The conversation should be recognized and populated
- The project and location should already be populated from the conversation metadata. if they do not select the appropriate project and location now
- Create a new Mapping File (see Mapping Generation)
- Click Import
- 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
- Log into Data Exchange and Select the Export tab
- Select Exchange as the purpose
- Select IBM DOORS as the ReqIF Format
- Select "New Conversation" from the dropdown, click Select, and name your new conversation.
- Choose the project to export from
- Choose the Location to export
- Note: It is essential to select a compatible export that Doors can consume and select a location that contains only sets as children; this will cause each set to be created as a module in Doors.
- Uncheck the include in the export box.
- Create a new mapping file (See Mapping Generation)
- 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
- Select or create a new project in Doors.
- When you import your ReqIFZ file into Doors, Doors will automatically create a new ReqIF Definition for the conversation ID in the ReqIF file.
Step 3: Export Requirements Data from Doors to ReqIF
- Export the ReqIF Definition created in Step 2
Step 4: Import Requirements Data from ReqIF to Jama
- Log into Data Exchange and select the Import Tab.
- Select Exchange as the purpose (this is the default).
- Select the ReqIF file produced in Step 3.
- The Exchange conversation should be populated.
- The Project and location should be filled out; if not, you can just enter the desired project and location to import now.
- Create a new Mapping File (See Mapping Generation).
- Click Import
- 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 Sets.Step 1: Export Requirements Data from Doors to ReqIF
- Create a new ReqIF Definition (be sure to lock all data, or no updates will be applied on the re-import of the data)
- Export the ReqIF Definition to a ReqIFZ file (choose export .ole as .rtf option)
Step 2: Import Requirements Data from ReqIF to Jama
- Log into Data Exchange and select the Import Tab
- Select Exchange as the purpose (this is the default)
- Select the ReqIF or ReqIFZ file produced by your export from doors in Step 1
- Pick "New conversation" in the dropdown, click Select, and give this conversation a name
- Select the Project you wish to import this ReqIF file to
- Select the Location within this project you would like to import to
- Create a new mapping file (see Mapping Generation)
- Validate your mapping file with the validate button
- Click Import to start the import
Step 3: Export Requirements Data from Jama to ReqIF
- Log into Data Exchange and select the Export Tab
- Select Exchange as the purpose (this is the default)
- Select ReqIF Format: IBM Doors.
- Select Exchange Conversation. Choose the conversation created in Step 2.
- Select your export location. this should be whatever container is directly above the Doors modules imported as sets.
- Deselect the "Include in export" checkbox.
- Select the mapping file created in Step 2 to restore the correct ReqIF identifiers the Doors system expects.
Note: You must use the mapping file created during import in Step 2 above. You can edit this mapping if you'd like. However, if you choose to create a new mapping, you will create all new modules in DOORS instead of updating the existing ones.
- Choose a location to export to. It is suggested to export as ReqIFZ. choose File > Settings > Export as ReqIFZ.
- Click Export.
Step 4: Import Requirements Data from ReqIF to Doors
- Import your ReqIFZ file into Doors. Doors will recognize the conversation and match it with the ReqIF definition created in STEP 1
- Merge the imported ReqIF with the ReqIF Definition created in Step 1 to update and release the locks on the module
Attachments
Importing Attachments from DOORS to Jama
When exporting attachments from DOORS to ReqIF, select the option found in DOORS to export OLEs as RTFs. This will increase the compatibility of the exported attachment within Jama. OLEs can also be imported into Jama. However, OLEs tend to be more challenging to view.
Related to
Comments
0 comments
Please sign in to leave a comment.