Prepare Jira for synchronization

This topic lists the recommended steps to perform before you use Jira as a data source for a synchronization.

In this topic:

Create a dedicated Jira board

When you create a board, it should only be accessible to the Connect Jira data source user account. Ensure that no other Jira users can use, see, or modify this board. The user account specified in the Jira data source must have the locale/profile set to EN-US.

Use the following guidelines:

• For each project being synchronized, create a dedicated board to use for synchronizing your data. Do not reuse an existing board by changing its filter.

• Give the board a distinct name. Do not use special characters or spaces. To avoid potential issues, use all uppercase characters.

  Suggested format: MFCONNECT<projectname><projectkey>

  Example: MFCONNECTGLOBGL, where GLOB is the project name, and GL is the key.

• Make sure to never change the board's filter.
• Use the dedicated board both as the sample project in the data source, and in the connection itself.

• Make sure that all statuses are mapped to the board.

• Boards which span multiple projects are not supported and may cause unpredictable behavior. An example of a board that spans multiple projects is (ProjectKey=ABC AND Component = 123) OR (ProjectKey = DEF AND Component = 456).

For Connect to discover the board, click the Actions button in the top banner and choose Flush Server Cache. For details, see Flush data and reload configurations.

Back to top

Define "Create" screens and "Edit" screens

Connect recognizes fields defined within Jira “Create” and "Edit" screens. As a result, these fields are added to the list of available fields in the user interface.

For a Jira issue to be created by Connect, the relevant fields must be present on the “Create” screen.

For a Jira field to be modified by Connect, it must be present on the “Edit” screen.

Do the following in Jira:

1. Define Create screens or Edit Screens for the relevant data types.
2. Include in the Create or Edit screens all the fields that you want to include in synchronization.
3. Assign the Create or Edit screens to the dedicated Connect user.

Back to top

Jira item workflows and Connect

Connect requires the ability to move artifacts from any status value to any status value. Certain products, such as Azure DevOps, have a bypass workflow access privilege which can be granted to the data source user. This access privilege permits an Any-to-Any status change for that user, while still ensuring that all other users honor the workflow.

Jira currently does not have a bypass workflow permission. All users, including users running REST tools such as Connect, must honor the Jira workflow for the items they are editing. This may cause issues with item updates.

For example:

Consider the following status phases for defects: New, Open, In QA, Signed Off, Closed

In the following scenario, Connect would synchronize successfully with Jira using these steps:

• Developer creates a new defect: Status=New

• Connect runs a sync iteration

• Developer updates defect to open: Status=Open

• Connect runs a sync iteration

In the following scenario, however, synchronizations may fail, since an item can move between multiple workflow steps between iterations.

• Developer creates a new defect: Status=New

• Connect runs a sync iteration

• Developer updates defect to open: Status=Open

• After some minor code changes, Developer updates defect to In QA. Status=In QA

• Connect runs a sync iteration – fails to move status for bug from New to In QA

The only solution at present is to add additional transitions to the Jira workflow, from every status to every status. These transitions can be restricted by access rights to ensure that they can only be used by the service account specified in the Connect Jira data source: For details, see Prevent specific users from executing workflow transitions in Jira server.

Back to top

Exposed fields for Jira synchronization

In a Jira project, fields and screens can be customized by modifying schemes.

The following project screens and schemes control how the fields are exposed to the Jira REST APIs that Connect uses to synchronize data:

• Create Screen and associated screen

• Edit Screen and associated screen

• Associated Field scheme

Connect uses a sample project in the data source that determines the exposed fields that can be synchronized from JIRA to any other endpoint. These fields must be on either the Create or Edit screens in order for Connect to update Jira artifacts from another endpoint, for bi-directional synchronization.

A connection can also be created to synchronize from multiple Jira Projects. In this case, the exposed fields determined by the data source's sample project must be available in all other projects. This means that for all mapped projects, the fields that are part of the Create screen and Edit screen, and exposed by the Associated Field scheme, must be the same as in the sample project.

The following section describes how to gather information on your Jira projects to show what fields are exposed to Connect and how to use this data to create a successful synchronization.

To determine the exposed fields:

1. Log into Jira using the Connect Data Source user.

2. Select Administration > Projects

3. Select your Jira project.

4. For each Jira issue type that you are synchronizing, determine the fields that are exposed by clicking on the Associated Scheme for the Create and Edit screens. The scheme for Create and Edit can be different, depending on your JIRA configuration. The following example shows differences between Create and Edit screens for different schemes:

   

5. Make a list of all fields in your Create and Edit screens. These are the fields that are available for a successful synchronization. You use this list to create your Field mapping in your Connection.

   The image below shows the differences between the Create and Edit screens for the Bug issue type. Connect only exposes the fields shown on the Create screen. The "Epic Status", "Parent Link", and "Due Date" fields will also be exposed by Connect.

   

   Note that the Epic Link field is only shown on the Create screen, and not in the Edit screen. As a result, this field cannot be updated by Connect from another endpoint.

6. Using the Create Screen field list that you created above, check that all fields are available in the project's Associated Field scheme and Associated Screens. The top heading indicates the field scheme used by the project. The right column shows the screen for which the field is exposed.

   

Back to top

Best practices

This section lists some best practices and tips for your Jira synchronizations.

• To ensure an accurate synchronization for the item statuses, make sure to ignore normal workflow transition rules. Check that the role assigned to the Connect user is not limited by workflow transition rules.

• Field contexts can determine for which projects and types your custom fields will be displayed. Check the context for any fields that you intend to use with a synchronization. For details about editing a custom field's context, see the Atlassian documentation.

Back to top

Next steps:

• Create a data source