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.
FAQs
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.
Was this helpful?
Thanks!
Tim Keyes
18 comments