Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Jira Integration: Issue Best Practices

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

Custom fields that are synced between Jira and Jira Align cannot be marked as required in Jira.

Why: If a custom field is marked as required in Jira and it does not exist or not populated in Jira Align, the issue will fail to sync to Jira if it is created or updated in Jira Align.


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.


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.


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

1 comment

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. 


Log in or Sign up to comment
Community showcase
Published in Jira Align

Lean Portfolio Management with Jira Align

Lean Portfolio Management (LPM) is a relatively newer management methodology which draws from lean and systems thinking approaches to drive value-based outcomes, as opposed to more traditional techni...

1,344 views 2 30
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you