Jira and Jira Align Integration: Jira Issue Field Best Practices

[#1]

Best Practice #1:

In preparation for integrating projects in Jira with Jira Align, it is necessary to confirm that the fields that will be synced between the two are present on the Create and Edit screens in Jira for each of the issue types.

Why:

When an item is created or edited in Jira Align and then syncs to Jira, the synced fields need to be present in Jira for the connector to pass the info through.  If these fields are not present, syncs from Jira Align to Jira will fail.

Action to take:

Perform the following steps in Jira for each issue type.

1.  Navigate to a project that will be integrated

2.  Click Project Settings and then Screens

3.  Select the Screen listed for Create Issue or Edit issue

4.  Confirm appropriate fields are listed.  These are the minimum fields to sync from Jira Align to Jira.  There could be more fields listed.

• Epics
  • Name
  • Summary
  • Description
  • Estimate (Points)
  • Acceptance Criteria
  • Assignee
  • Status
  • Fix Version (if used)
  • Labels
  • Issue Type
  • Reporter
  • Program Increment (optional custom field)
  • Parent Jira Epic Name (optional custom field)
  • Why? (optional custom field)
• Stories
  • Summary
  • Description
  • Estimate (Points)
  • Parent Epic
  • Acceptance Criteria
  • Assignee
  • Status
  • Fix Version (if used)
  • Issue Type
  • Labels
  • Epic Link
  • Reporter
  • Sprint
  • Assigned Team (optional custom field)
• Sub-Tasks
  • Summary
  • Description
  • Assignee
  • Parent Story
  • Reporter
• Bug
  • Summary
  • Description
  • Estimate (Points)
  • Assigned Team
  • Sprint
  • Assignee
  • Priority
  • Status
  • State
  • Fix Version

5.  If a field isn't listed, use the dropdown at the bottom to add the missing field

For projects that do not share the same Screen Schemes, the steps above will need to be repeated for those projects

Best Practice #2:

Fields that are NOT synced between Jira Align and Jira cannot be marked as required in Jira.

Why:

If an item is created in Jira Align and there is a required field in Jira that does not sync with Jira Align, the sync will fail and the item will not be created in Jira.  This is because Jira is looking for the connector to pass this info from Jira Align but it doesn't exist in Jira Align.  Since Jira sees this as a required field for creation, it will not create it.  This is most common with custom fields.

Action to take:

Perform the following steps in Jira.

1.  Click on the Settings cog

2.  Select Issues

3.  Select Field configurations

4.  Select the appropriate Field Configuration

5.  Review the list and confirm any fields that are marked as required are fields that can be synced.  Reference list above.  If fields are not synced via the connector, they must be changed to Optional.

Best Practice #3

Required Jira fields that ARE synced between Jira Align and Jira must have a value entered in Jira Align when initiating the sync from Jira Align.

Why:

If an item is created or updated in Jira Align and there is a value missing in a Jira Align field that syncs with a field that is required in Jira, the sync will fail and the item will not be created or updated in Jira. Similar to Best Practice #2, Jira is looking for the connector to pass this info from Jira Align, but it is not present. Since Jira sees this as a required field, it will not create or update the issue without it.

Action to take:

Make the field required in Jira Align as well. Doing this will help ensure the field stays populated and requirement of fields can be controlled by Portfolio. This can only be done by a user that has the appropriate permissions to access the Details Panels Settings in the Jira Align Admin Console. 

Noteworthy:

There are a few exceptions where Jira Align may not enforce the required field:

• when a work item is created or updated via the API
• when a work item is created or updated via an import
• when a work item is created or updated via its parent work item's Quick Add Feature

The above will generate an entry in the Audit Log of the Jira Align work item indicating that it failed to sync to Jira

---

Related Articles

• Jira and Jira Align Integration: Sprint Best Practices
• Jira and Jira Align Integration: Issue Best Practices
• Jira and Jira Align Integration: Workflow Best Practices
• Jira and Jira Align Integration: Story Resolution Transition Best Practices 
• Jira and Jira Align Integration: Release Vehicle/Fix Version Best Practices

[Paul Flynn]

@Rae Gibbs   Under Epic where you have 

• Parent Jira Epic Name (optional custom field)

Is this meant to be the Jira Align Epic or Capability?  

[Rae Gibbs]

@Paul Flynn Yes.

[Timothy Beran]

@Rae Gibbs Under stories you have Assigned Sprint and Sprint.  Not sure I understand the difference.  Unless by Assigned Sprint (Custom field) would be what was planned in JA and Sprint (Jira Standard) is where it actually is? 

[Rae Gibbs]

@Timothy Beran That was just a mistake on my part. There should only be one Sprint field. It is called Assigned Sprint in Jira Align and Sprint in Jira. Those fields are the same and sync with each other.

[Scott Grossman]

Do Jira TASKs (not subtasks) that are part of an epic sync from Jira to Jira Align?

[Tracy Walton]

@Rae Gibbs Thank you for this article! Are there any plans to map/sync the Severity field? Maybe similar to how Priority can be sync'd?

 

[Tracy Walton]

@Scott Grossman You may have already found this answer, but yes. You can set up other issue types to come on over to Jira Align from Jira. Jira custom issue types are converted to a "Story of type ..." 
For example in your case, a Jira Task would appear as a Story of type Task in Jira Align.

First, set up the types in Jira Align here: Administration > Platform > Dropdowns section.

Then configure the mapping in Jira Align here: Administration > Jira Settings > Custom Issue Types tab

Note: You'll need to know the Jira custom issue type IDs. 

[Rae Gibbs]

@Tracy Walton I have not heard any mention of that. There was a Community Article put out by Head of Product for Jira Align about some changes coming in the near future with the connector and that was not listed.

[Ashwini Patil]

@Rae Gibbs  How do you map custom fields in Jira to custom fields in Jira Align apart from the standard ones under the Jira Setup -> Custom Fields. eg., I have a scenario - when a bug is created we have a custom field 'impacted environment' that we want to see in Jira Align as well. Is there a way we can do the mapping?

[Rae Gibbs]

@Ashwini Patil Unfortunately, it is not possible to sync Jira custom fields with Jira Align custom fields. The only custom fields that are supported are the ones that are available on the Jira Setup tab.