JIRA Connector FAQ

By Jama posted 03-18-2015 16:45


How do you map a Release in Jama to JIRA?
Release type fields (standard and custom) can be synced from Jama to JIRA.  The Release field must be mapped to a Version Picker field in JIRA. All valid versions in Jama must be added as versions in JIRA.

Do I have to map all required fields in JIRA?
If you have an issue in JIRA with a required field, you must map the required field in JIRA to a field in Jama. You should use required fields in Jama or a default value for the mapping, or else the sync may fail.
If Jama is not mapped to a required field in JIRA, it can update an existing item in JIRA if that field already has a value, but cannot create a new one.

Can you map to date fields?
Yes, you can map a date field in Jama to a date picker in JIRA.

Can you map a Jama field to the Security Level field in JIRA?
This ability was made possible with Jama version 2014.1+.

How do you map pick lists?
The values in both Jama and JIRA need to match exactly. If there is a problem with the sync and the values look the same, make sure none of the values have extra spaces.

Can more than one JIRA instance be mapped to one Jama instance?
No, this is not possible with the legacy connector. It is, however, possible with the Jama Integration Hub.

Is it possible to change the JIRA Item Type after I've created a mapping?
No, you will need to create a new Item Type Mapping.

Can you map to fields that are created by plugins in JIRA?
No. Mapping to fields that are created by plugins is not supported.


What is the maximum length for a text field?
The regular text field in JIRA has a maximum length of 255 characters. To avoid truncation, it is best to sync a Rich Text Field in Jama to a Text Field (multi-line) in JIRA.

Why does my text lose formatting when I sync items from Jama to JIRA?
Atlassian utilizes a proprietary syntax for its rich text in JIRA. If you have a local installation of JIRA, you can enable the Wiki Renderer Macro and HTML Macro so all of the formattings syncs from Jama to JIRA. More info can be found in the install guide.


Can you sync relationships between JIRA and JAMA?
No. The simplest workaround is to enter in the relationships in custom fields in Jama that are synced to JIRA, which is slightly better than having to enter it in in JIRA separately, but not by much. However, this feature is available in the Jama Integration Hub.

Can you sync attachments between Jama and JIRA?
No, this is not possible. However, this is possible in hosted versions of Jama with the Jama Integration Hub.

Why can’t I sync to the status field in JIRA?
"Status" cannot be synced because it is a workflow-enabled field in JIRA.

Can I map fields that are part of a Jama workflow?
As of version 2014.1, it is possible to sync from Jama workflow fields.

What happens when I select Clear Synchronization Data? 
Clearing sync data starts you at square one for all items that have already been mapped with the connector. If you clear synchronization data, when you re-sync an item it will create brand new items. This means if you did not delete the items in JIRA after your first sync, your second sync (after clearing the mapping) will essentially duplicate these items. The same will happen for any items in Jama created from a JIRA item.

Can you sync to JIRA projects with a key that matches a reserved JQL (JIRA Query Language) word?
Using reserved JQL words as keys in JIRA Projects is not supported when syncing items from JIRA into Jama.


What permissions does my JIRA user need to make the connector work?
As of Jama version 2014.1, permission requirements have changed. The JIRA user needs full access (Admin, Developer, and User Role default permissions of a project), but full system access is no longer required. For more information on the necessary permissions, visit our help guide

Will changing the user's password affect the sync?

If the password changes for the Jama user, the connector will still work. If the JIRA user password changes, the connector will need to be updated with the new password in Jama. 

Can our hosted Jama instance connect to an on-premises version of JIRA?
If we host your Jama instance, your JIRA needs to be publicly accessible. If there is a firewall enabled, you will need to poke a hole for the Jama instance. While Support helping configure your firewall is out of the supported scope, Support can provide the IP address of your Jama instance.

Can I install Jama and JIRA in the same Tomcat instance?

No, the two tools can interfere with each other during startup and run time. Because of this, both the Jama application and its database need to be hosted on their own dedicated servers (physical or virtual). Installing JIRA on either one of these servers is an unsupported configuration. See supported software for more information about recommendations.

Will I be notified if a sync fails?
If you have enabled the Failure Notification, the specified user will be sent an email just once after a failed sync. The user will receive another email after a successful sync. This is to avoid spamming your mailbox with the same error message frequently. This email will tell you how many items failed to sync, but it will not tell you which items failed.

How can I tell which items are failing to sync?
Hosted Jama users can check the activity stream of a project where you will find synchronization information for individual items. You can search for the string "JIRA Integration failed to synchronize with an integration..." Once an item syncs successfully, you will see either "JIRA Integration created..." or "JIRA Integration edited..." depending on if it's a new item or an update to an existing item. You can also contact Support with a time frame for the failure so they can check the logs for you. NOTE:  You can refine your search in the activity stream using the ID or name of an item. 

On-Premises customers can also look in the contour-integrationsync.log. You can do this by searching for the text "FAILING ITEM SYNC." Your log may have several days worth of information, so it is important to look at the date of the error to verify if this is an issue that occurred at the time of the failed email notification or from before. The line corresponding to the failed item sync will look something like the following example.

[WARN ] - FAILING ITEM SYNC [item DOCUMENT-KEY] : failure message 

Typically, the failure messages will be straightforward. If the message is not clear or you are unsure how to fix the issue, reach out to Support with your contour-integrationsync.log, contour.log and a time frame for when they sync began failing.

How can I tell if sync is running?

The connector is designed to work in the background, but that can make it hard to diagnose. If you are using a hosted instance of Jama, there is not a way for you to check that status of a currently running sync. If you are on-premises, there are a few ways to check. 

You can tell if sync is currently running from the Scheduled Jobs tab of the root login screen. The job for the JIRA connector will be created once the JIRA connector is setup and will belong to the group AppSynchronization. If the job is running, the Running column will have a status of "Yes."

Another way to check the progress of a synchronization job by tailing the contour-integrationsync.log. When a sync job has completed, you will see "END SYNCHRONIZATION WITH JIRA" followed by the number of items synced. 

2015-10-19 08:00:20,417 jamaSchedulerFactoryBean_Worker-15  [INFO ] - END SYNCHRONIZATION WITH JIRA:
27 of 30 items successfully synced to JIRA
0 of 0 items successfully synced from JIRA

1 comment


03-18-2015 18:28

We're not using this yet, but these notes look quite helpful when we do-