Skip to main content

Jama Connect Interchange User Guide

Troubleshooting and FAQs

Question

Answer

How do I update field mappings for an existing integration that is running?

  1. Turn off the integration.

    integration_off.png

  2. Modify the field mappings you need to change, then select Save Changes.

  3. Turn the integration back on.

I created a Jama Connect to Jira integration and ran the first sync, but now I need to add another field mapping to the integration. How do I do this without overwriting any data for the synced items?

  1. Turn off the integration.

    integration_off.png

  2. Select the Field Mappings tab, and add a row for the new field mapping.

    troubleshooting_1.png

  3. Use the drop-down lists to select the fields you want to map.

  4. Use the arrows to select the directionality for the field mapping.

  5. Select Save Changes.

  6. Turn the integration back ON.

  7. Select Full Sync.

  8. On the first page of the Full Sync wizard, select Custom sync.

  9. On the second page of the Full Sync wizard, select only the newly mapped field and its sync direction. For example, if all information for this field is currently stored in Jama Connect, select → so that information flows from Jama Connect to Jira when the custom sync is run.

  10. On the final page of the wizard, select Confirm to execute the sync.

For more information about using the Full Sync wizard, see Perform a full sync for Jira integrations.

An item I created in Jama Connect isn’t automatically created in Jira, and vice versa.

If an item isn’t created in the destination system as expected, check the following:

  • Directionality — On the Integration dashboard, make sure the sync is configured to create items bidirectionally, and not one-way. For more information, see Integrations.

    directionality.png

  • Item location — Make sure the item you created is located within the correct set (Jama Connect) or project (Jira). You can confirm the integration’s configured Jama Connect set and Jira project on the Integration dashboard.

    item_location.png

  • Creation rules — Make sure no creation rules exclude this item from the sync. For more information, see Configure creation rules.

  • Lock status — If the item was created in Jama Connect, make sure that it isn’t currently locked by another user.

  • Link errors — On the Links tab, search for the item using its API ID. You can identify the API ID by looking at the item’s URL.

    For example: https://[jama-instance]/perspective.req#/items/

    If an item can’t be created because of an error or misconfiguration, the error message “Unable to create entity” is displayed for the item on the Links page. The most common cause for this error is that required fields in the destination system were left blank. Make sure those fields are mapped on the Field Mappings page and marked as required in the source system.

If a link is created between two items and one of the items is later deleted, how do I create a new link to the remaining item?

For example, I create a Requirement in Jama Connect, and a corresponding Epic is automatically created and linked in Jira. The Epic in Jira is deleted by mistake. How do I link the Jama Requirement to a new Jira Epic?

Create a new link if one of the original linked items is deleted:

  1. Turn off the integration.

    integration_off.png

  2. Go to the Links page and delete the old link for that item.

    add_link.png

  3. Turn the integration back on.

  4. Select Full Sync.

A new item is created in the destination system and linked to the existing item in the source system.

I created an Excel Functions integration that isn’t populating values the way I expect.

Before contacting Support, check the following:

  • Make sure the functions in the Excel template are working correctly on their own. Test the functions directly in the Excel template and address any errors before attaching the template in Jama Connect.

  • Make sure the functions in the Excel template are supported. For a full list of supported functions, see Appendix – Supported Excel Functions.

  • Make sure the Excel template is attached to the Jama Connect item that you specified in the integration wizard.

  • Check for errors on the Links page and Logs page in Interchange.

How does Jama Connect Interchange handle conflicting changes in mapped fields? For example, if one user makes changes to an item in Jama Connect, and another user makes changes to the corresponding Jira item, how are changes reconciled when the sync is run?

When the Delta Sync runs, the most recent update for each field is honored. For example, in the following scenario where a Delta Sync is configured to run every 10 minutes:

  • The Jama Connect Name field is updated at 12:00

  • The Jira Name and Description fields are updated at 12:02

  • The Jama Connect Description field is updated at 12:05

When Delta Sync runs, both items will be updated with the Jira Name and the Jama Description.

Can the Excel Functions integration be used with Jama Connect lookup matrix fields?

Yes. Using the Excel Functions integration, values can be written directly to lookup matrix picklists. This allows you to use both solutions together for more advanced workstreams.

My Jama Connect Interchange system is configured with many integrations running simultaneously. How does the Jama Connect Interchange execution service determine the order in which to process each integration?

Most Jama Connect Interchange instances are configured with five execution threads, meaning up to five integrations can be processed at the same time. If more than five integrations are queued to process, Jama Connect Interchange prioritizes them in the following order:

  1. Integrations that have never run before.

  2. Integrations with the longest delay since the last run time.

Note: Integrations with links in error are retried constantly until errors are resolved, leading them to be prioritized over other integrations. If you find that integrations aren't processing in a timely manner, addressing or turning off integrations with errors can help restore bandwidth to the execution service.

My Jama Connect Interchange system is configured with many integrations running simultaneously. How does Jama Connect Interchange execution service determine the order in which to process each integration?

Most Jama Connect Interchange instances are configured with five execution threads, meaning up to five integrations can be processed at the same time. If more than five integrations are queued to process, Jama Connect Interchange prioritizes them in the following order:

  1. Integrations that have never run before.

  2. Integrations with the longest delay since the last run time.Integrations with the longest delay since the last run time.

Note

Integrations with links in error are retried constantly until errors are resolved, leading them to be prioritized over other integrations. If you find that integrations aren't processing in a timely manner, addressing or turning off integrations with errors can help restore bandwidth to the execution service.

Does Jama Connect Interchange support the X-ray plugin for Jira?

Interchange doesn't formally support the X-ray plugin for Jira. However, you can still sync X-ray issues from Jira to Jama Connect in practice. X-ray issues are viewed by the integration as normal Jira issues with added specialty plug-in fields. Using Interchange, you can sync the standard Jira fields included on the X-ray issue (such as Summary and  Description), but you can’t sync the specialty X-ray fields.

The integration log occasionally displays the message "Token is expired." What does this message mean?

If your Jama Connect connector uses oAuth authentication, the Logs page occasionally displays this message when the Oauth token has expired and is being regenerated. This is a normal, automated process that doesn’t interrupt the integration.

On the Links page for my Excel Functions integration, the Status column for some items is blank. What does this mean?

A blank status for an Excel Functions link indicates the item was unable to sync successfully on the first run of the integration. In this scenario, the integration initially fetched these items and added them to the Links page. However, after the initial fetch, an error occurred when the mapped values were synced to the Excel template. These errors typically occur because of a missed configuration in the template or on the Field Mappings page. Check the Logs page for a corresponding error message with more information.

Where can I find the configuration service log for my self-hosted Jama Connect Interchange instance?

Run the following command to copy the file to your system:

sudo docker cp config-svc-interchange:/services/config-svc/logs/config-svc.log  

I am attempting to create a connector to my Jira Data Center instance, and am receiving an error.

Or

I was able to successfully create a Jira Data Center connector and configure an integration, but items are not syncing and I receive an “Unable to get items from Connector” or “Unable to initialize integration” error in the logs.

If you are having trouble connecting or syncing with Jira Data Center, it's usually due to an authentication issue on the Jira side.

Check the following:

  • (Recommended) Authenticate using a Personal Access Token (PAT) — For more information, see Link to your Jira instance.

  • Verify user permissions — Make sure the service account user in Jira has the necessary permissions to read and write to the Jira projects and issue types you are syncing. The simplest way to verify this is to log in to Jira as that user and try creating or updating items in the project you intend to sync.

  • Verify authentication type — If your Jira Data Center connector uses basic authentication, ensure that basic authentication is enabled on your Jira system for all users, or at minimum for the Jama Connect Interchange user.

    • If you must authenticate using basic authentication, see Creating an allow list when basic authentication is disabled.

      In step 2, enter the following script, and replace "svc-jama-integration" with the username for your Jama Connect Interchange service account.

      {
              "block-requests": true,
              "allowed-paths": [
                             "/rest/issue/*",
                             "/rest/search/*",
                             "/rest/myself/*",
                             "/rest/project/*",
                             "/rest/field/*",
                             "/rest/workflow/*"
              ],
              "allowed-users": [
                             "svc-jama-integration"
              ],
              "show-warning-message": true

Verify IP and URL allow lists — Add the Jama Connect Interchange IP address and URL to your Jira allow lists.

  1. Add URLs to the allow list

    Use your Jama Connect Interchange URL in the format "https://<name>.jamainterchange.com"

  2. Specify IP addresses for product access

    Submit a support ticket to obtain the Jama Connect Interchange IP address

In this section: