Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Jira and Jira Align 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

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: 


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


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 Atlassian Team Jan 24, 2022

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

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

Like Rae Gibbs likes this
Rae Gibbs Atlassian Team Apr 12, 2022

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


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

Rockin' the Roadmap - How to make most of the Roadmap with Jira Align

The roadmap challenge for large scale agile enterprises Regardless of the agile framework you use, the agile enterprise has a massive scale with the challenge to connect hundreds of teams and thous...

2,527 views 7 25
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