Services Practices

Overview 

Jama Connect Interchange™ is a web framework that simplifies the process of linking data across multiple product development applications.  

This document describes the Jama Connect-to-Jira module, which allows you to automatically link Items in Jama Connect to Issue Types such as Stories or Defects in a Jira Cloud project.  

Configuring integrations 

Jama Connect Interchange includes a simple web interface that the Jama Connect organization administrator uses to set up one or more integrations between their Jama Connect and Jira Cloud instances. 

Connectors 

A connector defines one half of an integration. You must create at least one Jama Connect and one Jira Cloud connector, but Jama Connect Interchange supports multiple connectors that can be used to build multiple integrations. 

For example, a Jama Software customer might have multiple Jama Connect instances (Production, Trial, Sandbox, QA) as well as multiple Jira Cloud systems. Jama Connect Interchange allows an administrator to create connectors for each of those systems, and then use them in multiple integrations. 

Integrations 

An integration links two connectors; for example, one Jama Connect connector to one Jira Cloud connector. For each integration, the administrator defines rules that specify directionality when new items are created and how data flows between those items.  

Data can flow in both directions between Jama Connect and Jira Cloud, or it can be limited to flow in only one direction. The administrator can control directionality at two levels: the item creation level and the field level.  

ITEM CREATION LEVEL 

The administrator defines what Jama Connect Interchange does when it encounters a new item in one of the systems: 

• Bidirectional flow — When an item is created in Jama Connect, a corresponding issue is automatically created in Jira Cloud, and vice versa. This keeps both systems in sync with the same number of items. 
• One-way flow — Item creation can be set to flow in only one direction. For example, when an item is created in Jama Connect, a corresponding issue is automatically created in Jira Cloud, but not the other way around. 

NOTE 

The item creation level rules only control how new items are added. Even if item creation is set up with a one-way flow, updates to existing items can still flow both ways. Use the field level integration rules to determine how existing items are updated. 

FIELD LEVEL 

Once items are linked in both systems, the administrator can control the flow of the individual fields mapped between the two items: 

• Bidirectional flow — When a field is updated in Jama Connect, the corresponding field is automatically updated in Jira Cloud, and vice versa. This keeps the values in both systems in sync. 
• One-way flow — Fields can be set to flow in only one direction, which means changes entered in one system always overwrite changes in the other system. 
• Additional rules can be applied to each field mapping, providing further logic and transformation capabilities. 
• Read-only and Required logic are enforced during mapping to streamline the setup process. 

Getting started 

This section guides you in setting up two connectors and creating your first integration.  

The process consists of these tasks. 

Link to your Jama Connect instance 

This section guides you in setting up a Jama Connect connector. 

PREREQUISITES 

• A running Jama Connect instance 
• Credentials for a Jama Connect user with admin privileges 
• A new distinct Jama Connect user account with the username InterchangeServiceAccount  

TO LINK YOUR JAMA CONNECT INSTANCE: 

1. Open the Create a new Connector window: select the Connectors tab and click the + icon. 

2.  Complete these fields: 

• Instance Type — Select Jama. 
• Connector Name — A descriptive name for the connector. 

• Authentication Type — Select Basic or oAuth, whichever your environment uses. 
• Instance URL – Your Jama Connect URL.  
• Username — Enter InterchangeServiceAccount. 
• Password — Enter the password for the InterchangeServiceAccount. 

Link to your Jira Cloud instance 

This section guides you in setting up a Jira Cloud connector. 

PREREQUISITES 

• A running Jira Cloud instance 
• Credentials for a Jira Cloud user with admin privileges 

• A new distinct user account: InterchangeServiceAccount 
• API token for the new user account (refer to Atlassian Support documentation) 

TO LINK TO YOUR JIRA CLOUD INSTANCE: 

1. Open the Create a new Connector window: select the Connectors tab and click the + icon. 

 2.  Complete these fields: 

• Instance Type — Select Jira. 
• Connector Name – Enter a descriptive name for the connector. 
• Authentication Type — Select Basic or oAuth, whichever your environment uses. 

• Instance URL – Enter your Jira Cloud instance URL. 
• Username — Enter InterchangeServiceAccount. 
• API Key — Enter the API token for the Jira Cloud user account. 

Create a simple integration 

Before building a complex integration with multiple mappings and complex rules, we recommend that administrators create a simple integration that maps only the Name and Description fields. This first integration is used to verify connectivity and authentication between the systems. 

TO CREATE A SIMPLE INTEGRATION: 

 
7.  Complete each page of the wizard, then click Next. 

1 Select Integration Type  

• Select integration type — Select Jama Connect to Jira Cloud. 

2 Choose Connectors to Integrate 

• Choose Jama Connect for Source Connector — Select the Jama Connect connector that you want to integrate. This is the same connector you created in Link to your Jama Connect instance. 
• Choose Jira Cloud for Target Connector — Select the Jira connector that you want to integrate. This is the same connector you created in Link to your Jira Cloud instance. 

3 Retrieving Meta Data 

Jama Connect Interchange automatically retrieves project meta data from each instance. No action is required on this page. 

4 Select Project and Type 

• Jama QA — For the Jama Connect connector, select the Jama Connect project that you want to integrate, followed by the container or set within that project that holds the items you want to integrate. 
• Jira QA — For the Jira Cloud connector, select the Jira Cloud project that you want to integrate, followed by the issue type within that project that you want to integrate.

5 Integration Configuration  

• Name your Integration — Enter a descriptive name for the integration. 
• Frequency — Select the frequency with which you want the integration to run. 
• Sync Attachment — Toggle to Enable if you want to sync item attachments. 

• Inline images (images shown inside fields) aren’t considered attachments and are always synched based on Field Mappings. 
• Only attachments under 25 MG are copied between systems. If an attachment exceeds 25 MG, a placeholder text file is created in the other system to indicate that an attachment exists in the linked item. 
• Sync Comments — Toggle to Enable if you want to sync item comments. 

NOTE
Jama Connect doesn’t allow users to edit comments, but Jira Cloud does. Edits to Jira Cloud comments aren’t recognized and aren’t synched back to Jama Connect. Only the original comment text exists in Jama Connect. 

 6 Item Creation Direction and Confirm 

NOTE 

Creation Direction also affects Comment and Attachment creation. 

• Bidirectional Item Creation — When an item is created in Jama Connect, a corresponding issue is created in Jira Cloud, and vice versa. This keeps both systems in sync with the same number of items. Attachments, Comments, and Comment Replies created in either system are added to the other system. 
• Jama to JIRA Creation — Items created in Jama Connect are automatically added to Jira Cloud, but not the other way around. Only Item Attachments, Comments, and Comment Replies created in Jama Connect are created in Jira. 
• JIRA to Jama Creation — Items created in Jira Cloud are automatically added to Jama Connect, but not the other way around. Only Item Attachments, Comments, and Comment Replies created in Jama Connect are created in Jira. 

The integration is saved in a disabled state. 

Configure field mappings 

Complete these steps to map fields in Jama Connect to the corresponding fields in Jira Cloud. 

1. In the left navigation bar, select the integration you just created. 

Enable the integration 

After the integration is set up and field mappings are defined, complete the following steps to turn on the integration. 

1. In the left navigation bar, select the integration you just created. 

Once an integration is enabled, Jama Connect Interchange begins linking items in the two systems. 

Test the integration 

Once you link to your Jama Connect instance and Jira Cloud instance and create an integration, you can test the integration to verify that the systems are communicating correctly. 

1. In Jama Connect:  

1. 1. Go to the project location you selected in the integration wizard (4 Select Connector Project and Type) and create a new Jama Connect item. 
   2. Verify that a corresponding issue is created in Jira Cloud after 15 seconds. 
   3. Verify that the new Jira issue includes the same name and description entered in the Jama Connect item, based on the field mappings you specified on the Field Mappings tab. 
   4. In Jama Connect, edit the name and description fields, and verify the same changes are reflected in the Jira issue after 15 seconds. 

1. 1. Go to the project location you selected in the integration wizard (4 Select Connector Project and Type) and create a new Jira issue. 
   2. Verify that a corresponding item is created in Jama Connect after 15 seconds. 
   3. Verify that the new Jama Connect item includes the same name and description entered in the Jira issue, based on the field mappings you specified on the Field Mappings tab. 
   4. In Jira Cloud, edit the name and description fields and verify the same changes are reflected in the Jama Connect instance after 15 seconds. 

Common tasks 

This section covers the procedures that administrators perform regularly. 

Enable and disable an integration 

When an integration is first created, it is in the disabled state, which allows you time to create field mappings and any rules you might want to apply. To modify an integration, you must first disable it. 

1. In the left navigation bar, select the integration you want to enable. 

Force Run an integration 

Integrations can be configured to run at intervals from every 15 seconds to once every 24 hours. However, if you don’t want to wait for the next scheduled run, you can start the integration immediately. 

1. In the left navigation bar, select the integration. 
2. Select the Dashboard tab. 
3. Open the Integration Control Panel and click Force Run. 

A confirmation message is displayed when the sync is complete. 

NOTE 

If another integration is already in progress, it finishes first before the new one is started. 

Perform a Full Sync 

To maximize performance and minimize load on the Jama Connect and Jira Cloud systems, the only items that are synched are those that were modified since the last integration run. However, you can sync all items with the Full Sync option.  

IMPORTANT 

Only run a Full Sync when advised by Jama Support. A Full Sync can be a performance-intensive operation. It is only required in unusual cases, like if a system was restored from a database backup. 

1. In the left navigation bar, select the integration. 
2. Select the Dashboard tab. 
3. Open the Integration Control Panel and click Full Sync. 

A confirmation message is displayed when the sync is complete. 

Advanced use cases 

These are some more advanced scenarios in using Jama Connect Interchange. 

Pick List fields don’t have the same values in both systems 

The Jama Connect Interchange provides “Single Select to Single Select Rules” that you can use to control how values are mapped when they flow from one system to the other. 

To access these rules, click the Rules button for a Single Select to Single Select field mapping on the Field Mappings tab: 

IMPORTANT CONSIDERATIONS 

• You can map “Many to One.” 

Example: If mapping Priority, you can map both Critical and High to P1. 

• Single Select Rules must be mapped in both directions. 

Example: Jama Connect Critical and High map to Jira P1 and Jira P1 maps to Jama Connect Critical. 

Non-required field mapped to a required field 

Some integrations might have a field in one system that is required, but in the other system, it isn’t. This can lead to failed integrations where the blank value is not valid. To solve this, you can select the Use Default Value option that uses a default value if the field is blank. 

To access this option, click the Rules button for the field mapping on the Field Mappings tab: 

 
This option is located at the bottom of each Field Mapping Rule. 

Required fields exist in other system 

There might be integrations where one system has required fields that aren’t present in the other system. For example, Jira Cloud might require that a component or a team is set, but that information isn’t entered in Jama Connect. 

To solve this issue, you can use the Default Field – Static option to map a non-existent, read-only field that is set to a hardcoded value. 

Appendix — Field value types 

When data moves between Jama Connect and Jira Cloud, each field is converted to a standard type. This allows you to understand how data flows between systems. 

BOOLEAN 

Booleans are used for flags, true/false, on/off, etc. 

DATETIME 

DateTime is usually a specially formatted text field. Knowing that a field is DateTime allows Jama Connect Interchange to correctly convert text into date formats and apply transformations to that data (convert to Unix Time or parse into a specific format). 

FLOAT 

Floats are numbers that allow precision (decimal places). 

INTEGER 

Integers are whole numbers that do not allow decimal places. 

MULTI SELECT 

Multi Select fields allow multiple values to be selected from a specified list. Jira Cloud custom fields like checkboxes, Select List (multiple choice), and Select List (cascading) are examples of Multi Select fields. 

SINGLE SELECT 

Single Select fields allow one value to be selected from a specified list. 

TEXT 

A single line of unformatted text 

HTML 

HTML fields convert rich text fields in Jama Connect and Jira Cloud. We call them HTML fields because we convert the values to HTML as we move the data between systems.