Jira and Jira Align Integration: Issue Best Practices

[#1]

Before integrating Jira with Jira Align, there are some best practices that should be considered. Some are a little more rigid than others; while others can lend themselves to some workarounds. Let's explore further to understand what these are, why these are important and the potential impacts. 

Issues cannot be shared across boards

Team-level issue types (stories, bugs, etc.) cannot be shared on multiple (integrated) Jira boards. This is controlled by the board filter.

Why: Stories can only belong to one team in Jira Align. The connector can only assign a story to one team in Jira Align.

Do not mark custom fields as required

Do not configure custom fields that are synced between Jira and Jira Align as required. This does not apply to locked custom fields in Jira (i.e. Summary, Sprint, etc.).

Why: When a custom field is configured as required in Jira and the corresponding field in Jira Align is not populated with a value, this results in the work item failing to sync with Jira if it is created or updated in Jira Align.

Related article: Issue Field Best Practices for Create and Edit Screens

Moving stories between sprints

If a story needs to be moved out of an active sprint, first move it to the backlog before reassigning it to another sprint. When completing a sprint, move incomplete stories to the backlog first before moving to the next sprint.

Why: When moving a story directly from one sprint to another, the original sprint may be retained, and the subsequent sprint simply added. In this case, the sprint on the story will remain with the original sprint in Jira Align. This will cause the sprints to be out of sync on the story b/w Jira and Jira Align and cause potential impacts on the Program Board.

Workaround: If a bulk update is performed to change the sprint on the story, it will remedy the issue.

Known issues: 

• Using the move to backlog option when closing a sprint still retains original sprint in Jira Align

Moving stories between boards

If a a story needs to be moved from one board to another and has been assigned to a sprint, first move it to the backlog before moving it to the new board. 

Why: The story will retain the sprint from original board and will create a duplicate sprint on the new board.

Fields and permissions needed on screens

Issue fields to be synced need to be present on “Create” and “Edit” screens for the Issue Type Screen Scheme/s being used for the project/s to be mapped.  API Service Account also needs appropriate permissions.

Why: If the fields are not present on these screens, syncs from Jira Align to Jira will fail and errors will be displayed in the connector Jira API log.  If sync failures go unnoticed this can lead to “data drift” where updates on issues will continue and can become overwritten in future syncs.

Related article: Issue Field Best Practices for Create and Edit Screens

Canceling or deleting issues

“Canceled” and “Deleted” statuses in Jira workflow are both supported via the connector. Use case should determine which status to use.

Why: When the “Delete” option (not status) is used in Jira, the issue cannot be recalled. This option also isn’t automatically synced with Jira Align so the issue will remain in JA until the Admin (or someone who has the permission) runs a report in the connector to delete. 

“Canceled” or “Deleted” statuses can be synced between the tools and will update accordingly. In Jira Align, canceled items are moved to the Canceled Recycle Bin. If using a “Deleted” status in Jira, a query would need to be run in Jira for issues in this status to then be permanently deleted from Jira.

Does not apply: Data Center supports syncing of "Delete" option.

Integration behaviors to be aware of

• Issues are synced by project
  • Issues are synced from Jira to Jira Align by project, not board. If there are boards connected to a project that are not being mapped, those issues will be synced to Jira Align.
  • Work items in Jira Align are dependent on the project being set to sync the issue over to Jira
• Each Custom Issue Type results in additional API call per project
  • Only Customer Issue Types that are related to feature work should be mapped

---

Related Articles

• Jira Integration: Sprint Best Practices
• Jira Integration: Issue Field Best Practices for Create and Edit Screens 
• Jira Integration: Workflow Best Practices
• Jira and Jira Align Integration: Story Resolution Transition Best Practices 
• Jira Integration: Release Vehicle/Fix Version Best Practices

[Richard Wilson]

Thanks Rae. A great list. I would add not shuffling the candidate sprints either.  Jira Align reads them in the order they are created not the order they appear in Jira. 

[Rae Gibbs]

@Richard Wilson Great point and we have that called out in the Sprint Best Practices article.

[Rupinder Pannu]

Thank You @Rae Gibbsfor sharing your knowledge. Is it ok if I share these articles with my team?

[Rae Gibbs]

@Rupinder Pannu Absolutely! These articles are outputs of a collaboration among the Advisory Services team. Glad you are finding them useful!

[Richard Wilson]

Thanks to the support team pointing out this list again to me. 

[Matt Rosenbluth]

@Rae any ideas on how we can get WSJF fields to sync as part of the integration, it's a total disconnect between the two systems (different WSJF scores for the same issue).

I posted this regarding the issue too: https://internal.jiraalign.com/ideaZone/ideas?ideaID=2499

Thanks,

Matt

[Rae Gibbs]

@Matt Rosenbluth Unfortunately not at this time. I don't know if there are plans to accommodate this in the future. Best thing to do is what you already have done, which is submit it as an idea. Sorry I don't anything additional to offer.