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, Story, and Epic Management

Jira only has a two level backlog hierarchy: Epic -> Story, whereas Jira Align enables at minimum a five-level hierarchy: Strategy -> Theme -> Epic -> Feature -> Story. Capability can also be introduced between Epic and Feature for six levels: Strategy -> Theme -> Epic -> Capability -> Feature -> Story.

Between Jira and Jira Align, an “Epic” in Jira becomes a “Feature” in Jira Align, as it is the natural parent of a Story, a “Story” becomes a “Story”, a “Bug” becomes a “Defect”, and a “Sub-Task” becomes a “Task” under a Story. Any other custom issue types can be configured to integrate, and those will become a “Story” in Jira Align, with a Type field indicating the origin type configured from Jira.


Best practice: Use “Epics” in Jira as you would “Features”

A feature should be a concise unit of value that can be delivered within a single program increment. Any objects in Jira that you use to represent true “Epics” (which are allowed to span a PI), whether they be Jira Epics or another object, should be migrated to be Epics within Jira Align. The feature level should be represented by Jira “Epics”, with stories directly underneath them. True epics have no representation in Jira. The connection between epics and features will be made within Jira Align.


Best practice: Ensure stories in Jira are tied to a parent Jira Epic

Stories not tied to a parent (epic in Jira or feature in Jira Align) are considered “orphaned” stories. The value from these stories cannot be rolled up to any higher level initiative to promote organizational visibility. In Jira Align, you can use Program > Backlog (select PI at the top left, and then click Orphan Objects at the top right), to see your orphaned stories and assign them to a parent feature.

Best practice: Ensure stories in Jira have a story point estimate

Without an estimate, it is impossible to forecast completion for a backlog. Estimates are also what drive the velocity number for a team per sprint. Each portfolio in Jira Align can be configured to estimate stories in one of two ways: Modified Fibonacci or Power of Two. Ensure your stories use the correct estimation system for your portfolio and that the majority are estimated. At the least, there should be no unestimated stories assigned to an active sprint. In Jira Align, you can use Program > Backlog (select PI at the top left, and then click Orphan Objects at the top right), to see your unestimated stories.


Best practice: Finish story within a sprint, otherwise, move or split it before closing the sprint

Within Jira, if an issue (story, etc.) is unfinished when you close the sprint, Jira will tell you it is moving the story to the backlog. Unfortunately, that story will forever be tagged with the sprint where it was not finished if you do it this way. Let’s say another team picks up the story in their sprint. Now it looks like that story belongs to two sprints, and in fact the Jira reports for the original team will now include the new team’s sprint in the filter drop-down menu. When this occurs, you also have to tell Jira Align which sprints belong to which teams, by going to Team > Manage > Sprints, and then selecting the Manage Jira Sprints option from the More Actions menu at the top-right of the page. You will need to remove wrong sprints from teams where they do not belong.

To avoid this whole issue in both Jira and Jira Align, remove the stories from the sprint BEFORE closing the sprint. This will accurately report in Jira that you had a scope change for the sprint, and it will not forever tag that story with the sprint it was not completed in. Another work around is to split the story within Jira Align, allowing part of the story to be properly closed out in one sprint, and the remainder to go to the backlog or any future sprint.



Q: What if I use Jira Components, the Structures Plugin, or some other way to mimic a three- or four-tier hierarchy in Jira?

A: The Jira Align/Jira integration does not support Components or third party plugins. Plan to use Jira Align for all layers above the feature, which is represented natively in Jira as a Jira Epic. You will need a migration plan for importing your higher level layers into Jira Align, which can easily be done via Portfolio > Epics > More Actions > Import Epics or Solutions > Capabilities > More Actions > Import Capabilities (if using capabilities).

Q: What if my team does not do any story estimation?

A: If your team does not estimate stories, then Agile common sense would indicate that all your stories are approximately the same amount of work (“sized” the same). If that is the case, the best thing is to estimate all stories with the same value (1 or 2, for example). That way the velocity can still be calculated (by both Jira and Jira Align) and will reflect the number of stories completed. If the stories are NOT all of similar size, then not estimating them means you will not be able to calculate a velocity, you cannot make trade-offs between larger and smaller stories, you cannot do any forecasting, and a host of other anti-patterns. In this case, your teams should begin to estimate your stories ahead of putting them into sprints, at a minimum, according to Agile best practices.

Q: What if my team makes heavy use of custom issue types?

A: Any custom issue types can easily be configured to integrate to Jira Align. These issues will be represented in Jira Align as stories, and you can preserve the original issue type name in the field called Type on the story.


Q: What if I map the same Jira field (Story Points) to two unique Jira Align fields (LOE for stories and Points for features)?

A: A custom field is created or exists by default in Jira. This field is added to the Story Points field ID mapping in Jira Align under Administration > Jira Settings > Jira Setup. You need to turn on the Enable Feature Point Sync on the Jira Setup page. In Jira, you need to make the Story Points field show up on the Jira story and epic pages.

The story’s LOE field in Jira Align syncs with the Story Points field in Jira. The feature’s Points field in Jira Align would sync with the Story Points field on the Jira epic.

Note that Jira Align features (Jira epics) have story points in Jira Align that is a rollup of children stories LOE. Jira Align does not sync this field with Jira epics; it syncs the feature’s Points field which is a separate estimate. 

Q: How do I prioritize Jira epics and stories?

A: To enable rank synchronization between Jira Align and Jira, a custom field ID for rank must be set in the Rank text field on the Jira Settings page within Jira Align Administration. In the field, enter the default Jira rank field’s ID. The setting Enable Rank Sync on the same page must also be set to Yes.

Rank synchronization is not performed automatically; ranking must be either pushed to or pulled from Jira Align on demand. To do this, navigate to the feature or story backlog, ensure a program is selected in the Configuration bar, and set the program increment to None. Rank synchronization to or from Jira requires setting the PI to None as PIs don't exist in Jira. Then, select Pull Rank and choose to either push or pull the rank from the external system.

Once a push or pull request has been made, a job order to the external system is created and the rank synchronizes after the job finishes. After the job order is sent, the options for push and pull rank are not selectable until the job completes.

If Push rank to the External System has been selected, the rank of all items in the selected Jira backlog updates according to the ranks of their corresponding Jira Align issues. If Pull rank from the External System has been selected, the Jira Align backlog rank updates according to the ranks of their corresponding Jira issues. 

Note that only items that are visible on the Jira Align backlog when push or pull rank is performed will be updated.

Q: Why are issues in Jira sometimes updated with the connector ID and sometimes by an actual user?

A: The updates made via the service account were made in Jira Align. Updates made by a specific user were made in Jira. In Jira Align, the service account will use Jira user information when available due to matching external ID or emails between Jira Align accounts and Jira accounts. Updates made to Jira are made by the service account via the API so they will have the service account's name. If you need to verify who made the update, you can typically check the Jira Align audit log.

Q:  What is the expected behavior for the acceptance criteria field for Epics that are synchronized into Jira Align from Jira Software?

A: If a Story or Jira Epic is created in Jira to sync with Jira Align, The Acceptance criteria will sync to one field in Jira Align.  On Jira Align,  only one field will available for the input of acceptance criteria.  If additional criteria is needed it should be separated by a new line and the "*" character to start the line.

Q: What is the expected behavior when multiple Acceptance Criteria are added to new epics in Jira Align? Are all of these synchronized to Jira into its single Acceptance Field or will only the first criteria from Jira Align be synchronized over?

A: If a Story or Jira Epic is created in Jira Align to synchronize with Jira and there are multiple acceptance criteria fields populated, the fields will collapse into one field in Jira Align, with each criteria separated by a new line and the "*"  character.  This collapsed field is what will synchronize to Jira.


Mirek Community Leader Dec 30, 2019

Good article @Tim Keyes however personally I would add here couple screenshots or images to give more visual effect to your steps

Tim Keyes Atlassian Team Dec 30, 2019

G'day Mirek,

I hope all is well and thank you for reaching out!

I have added a couple of screenshots and will add some more in over time!

We have a larger listing of Jira Align and Jira Integration Best Practices listed here:


Happy Holidays!



Tim Keyes

Like # people like this

It is nice article and best practice for Epic and user story

Like Andy - PTC Redundant likes this

Hi Tim, super useful FAQs and I found the best practice on"Finish story within a sprint, otherwise, move or split it before closing the sprint" helpful. Also, I am not sure why I can't see your images that you posted on this article, I can only see the legend and Jira and Jira Align tables.

Like # people like this
Tim Keyes Atlassian Team Jan 06, 2020

Hi Jodi,

Thank you for the note on this and the other articles.  All the images should now be accessible outside the Atlassian Network.

Your assistance is greatly appreciated!


Tim Keyes

Like # people like this

Thanks so much Tim!


Mirek Community Leader Jan 07, 2020

Hi @Tim Keyes , thank you for adding screenshots. Not it looks a lot better :)

Nice article, @Tim Keyes. I thought you handled the topic well, and that defects deserved an article of their own, so I wrote this one, only to discover afterwards you already wrote this one!  Oh well, back to enjoying my last day of Cancun vacation with a rum and Coke.... Cheers!

Like # people like this
Kat Marketplace Partner Jan 07, 2020

This is a great article with tips that can help my team even though we do not use Jira Agile. 

Like Tim Keyes likes this

@Tim Keyes Hell yes to THEMES! Love them.

It still bemuses me that Jira doesn't offer these multiple levels of Work breakdown strategy as a standard. 

A great article to share with the Rotterdam Community Event members

Like # people like this

The function beyond the two level backlog hierarchy has always been a feature that many Chinese teams want Jira to support. The integration of Jira and Jira Align provides a good scenario and example for large-scale team use. Thank you for sharing!

@Andy - PTC Redundant I agree that it would be nice if Jira just natively supported adding multiple levels. However, if you have Portfolio you can add levels higher than Epic in Jira. Also, CPrime has an app that will let you rename (really it just uses the translate functionality) Epic to something else ... such as Feature.

Thanks for sharing this article, it clearly explains hierarchy mapping in a simple and easy to understand format. Now story mapping would be a much more interesting conversation with the teams.

Like Alison likes this

Very informative. Particularly I like the content on how to manage uncompleted story in a sprint. We come across this situation or scenario very frequently. Thank you

Curious why an Epic in Jira isn't the same as an Epic in Jira Align?

@Joe Mozer An epic in Jira is more in context to what was define in Extreme Programming (XP) and Scrum framework borrowed it for team level agility. It is work item that captures a large body of work, essentially a large user story that can be broken down into a number of smaller stories. It may take several sprints to complete an epic. 

Jira Align is for Agile @ Scale and in frameworks like SAFe an Epic is a container for a significant Solution development initiative that captures the more substantial investments that occur within a portfolio. Due to their considerable scope and impact, epics require the definition of a Minimum Viable Product (MVP) and approval by Lean Portfolio Management (LPM) before implementation.

Features in Jira Align are more aligned to Epics in Jira. 

Very useful, thank you.

I would just note that if you store JS Epic points in the same "Story Points" field as the Stories, the Epic points will be added to the aggregate used for example to determine a burn-up's target, typically and wrongly doubling it.

So we will be testing storing JS Epic points in a different field, maybe in the also also out-of-the-box "Original Story Points" field. With potentially the added benefit that the "Original Story Points" can be used as an alternative unit in some of the JS Reports.


Log in or Sign up to comment

Atlassian Community Events