How to troubleshoot Legacy Connector issues

By Carmen posted 05-05-2016 10:21


Most of the legacy connectors allow you to set an email notification for when a sync is unsuccessful, as described in JIRA, Rally and TFS sections of the help guide.

You can troubleshoot synchronization failures by tracking integration records in your project’s Activity Stream. You will need to configure your Activity Stream View for this, which can be done by opening the Activity Filter Settings in the top right Cog in the Activity Stream.

In the Activity Filter Settings you need to select the Integration in the activity types for this information to be displayed. You can also chose to filter by date range and specific Item Types in your view.

You will now see success or failure messages in the Activity Stream each time an item is synced. Users can use the Search field to look for specific item information, or use a string like "failed to synchronize" to sort for all failed syncs.

These activity records contain details about the synchronization failure, pointing to its cause. 

Although failed and succeeded syncs are tracked in the activities, some items may be skipped from synchronization and no activity entry is added. Reasons behind skipping items can be found in the contour-integrationsync.log.

The most common reason for items to be skipped is being in a locked state. Items can be momentarily locked for editing or be purposely locked for longer periods, in which case will need to be manually unlocked if you want them to sync. Both the person who locked the item and the Org. Admin can unlock the item in such cases, as described in this article.

Other common Integration Issues

  • Jama Software cannot make a successful connection to my HTTPS-enabled server
If you have SSL/HTTPS enabled on your Integration server and your Test Connection result is reporting an SSL Handshake exception, you may need to add the server's SSL certificate to the list of trusted authorities in your Jama Software server's underlying Java installation. This will enable Jama Software to make a proper connection with JIRA's web services. Please see step 3 here for more instructions on how to import your certificate into Java's cacerts keystore.

  • The 'Test Connection' button succeeds, but no items are being created
Usually, this is due to insufficient permissions assigned to your Integration's user. Please double-check that you have set your permissions according to our setup guides here. JIRA, in particular, has a complicated permissions scheme; there's more information on what permissions are included in the standard user groups we recommend here.

  • Some items/item types are created correctly, but others fail
Generally, this indicates a field mapping issue. Please ensure that all required fields for the synchronized item types are mapped in your field configuration and populated in each item. If you have a required field on one side of the integration, it's good practice to set the corresponding field on the other side to be required as well.

  • Rich text fields are not properly displayed by JIRA
JIRA stores and displays rich text in a different manner than Jama Software does, but the connector can be configured (for on-premises JIRA installations) to convert between these different styles. For hosted JIRA instances, sending rich text to JIRA is not currently possible; see the same guide for instructions on how to disable the rich-text markup and send plaintext instead.

  • Items are being created, but certain fields are always or often missing
This is generally caused by a mismatch in select-list values. If the field contains a select-list (Release, User, picklist, etc) please ensure that the values in each tool are exactly the same for the mapped fields. If you are mapping on a user field, the connectors will match on the username (e.g. "jdoe"), not the display name ("John Doe"). If you synced an item before the lists matched, and have since corrected the values contained in the lists, your synced item may not attempt another synchronization until a change is detected. This can be forced by either making a change to the item itself, or to its field mapping in your connector settings.

  • My sync was working, but it seems to have stopped
A few events in Jama Software (such as letting your connector subscription temporarily lapse) can cause Jama Software to automatically disable your sync. Please ensure that you have synchronization enabled on your connector settings. There are three levels at which you can enable or disable synchronization: the organization level, the project level and the item type level. All three of these synchronization options must be enabled for your sync to run.

  • Some fields are synced correctly to TFS, but clear out the values in Jama Software
Some fields in TFS, such as the History field, are actually composed of two components: a rich-text editor component for inputting data, and a display component for viewing previous updates. Jama Software can sync to the rich-text editor component for these fields, but because the editor never contains saved data, the blank value will erroneously overwrite any data entered into the synced Jama Software field. Given this limitation, we recommend mapping to these fields using one-way sync from Jama Software only.

If you have another sync issue or these suggestions did not fix your issue, please contact Jama Software Support for more detailed assistance.