Skip to main content

How to prepare for Jira Align in Jira

Objective

Do you want to learn more about our recommendations for preparing the Jira instance for Jira Align (JA)? This document outlines some key steps to help you prepare for Jira Align for your organization.

Be sure to let your Advisory Services representative know if you're interested in learning more about Jira Align. They can kick off a conversation with the Jira Align team.

Jira configuration key takeaways

There is a lot to consider when preparing for a Jira Align integration, and there are a lot of resources available to you. This table aims to highlight key takeaways for critical Jira configurations and provide you with detailed articles that go in-depth on the reasoning behind each recommendation or best practice.

Jira Align allows you to selectively synchronize based on issue type or project. If you want to synchronize a board that contains a subset of issues from one or more projects, please note that all issues from those project(s) will be synchronized to Jira Align. Regardless of whether they are on the board or not, all of those issues are subject to applicable takeaways below.

  • The first table below dives into specific checks that are called out @ Jet By Jira Align/ JET checks and their implications for those teams planning to onboard to Jira Align. Note that these are also detailed in the links we’ve provided, but this page attempts to consolidate this information into an easy-to-consume format.
  • The second table covers additional considerations for Jira Administrators that are not covered by the Jet tool but are important to the Jira and Jira Align integration and scaling practices in Jira.
  • While we do our best to call out specific checks and considerations, impacts, and actions to resolve any issues, there is a wealth of additional information indexed @ Jira Align and Jira Integration Best Practices and FAQ Table of Contents. Some relevant articles are linked in the tables below, but this is another great reference to assist you with your Jira and Jira Align integration.
Check in Jira
Why you need it
Impacts
Action to fix
Reference article
Custom fields
Mark custom fields as optional, not required.
Custom field configuration can affect your ability to integrate with Jira Align. If you only sync from Jira to Jira Align and you leave any fields as required, they will not be synced. If bi-directionally syncing between Jira Align and Jira, your issue will fail to sync if none of the required field information is provided.
  • This will negatively impact the Jira Align connector as some items will not get synced due to those required custom fields.
  • These issues will negatively impact Jira Align reporting.
    •  
  • Please mark any fields other than Description, Reporter, Priority, and Summary from your issue types custom fields as optional.
  • Avoid custom field requirements via Field Configuration Schemes or Workflow Transitions for integrated issues.
    • Jet By Jira Align (Check #5)
    Epics and fix versions
    All Epics should have an assigned fix version.
    Epics should have fix versions to dictate what release the epics will be shipped on; releases are tied to a project in Jira.
    Not having this data hygiene won’t break the Jira Align connector, but it will prevent the real-time release progress visibility in Jira Align.
  • Assign a fix version in the "Version" item under a project's settings.
  • Note: When preparing to complete a program increment, you should split unfinished features in Jira Align — this is covered in more detail in the second table below.
  • Jet By Jira Align (Check #3)
  • Release Vehicle/Fix Version Best Practices
    • Issues
    Stories should be associated with parent epics.
  • Stories missing a parent won’t show up in key reports in Jira Align, and you won't be able to see the overall progress on execution.
  • Stories missing a parent will miss alignment with Portfolio Epics and Strategic themes; for example, teams are producing “outputs” in terms of finished stories, but there is no alignment with “Outcomes.”
  • If you are using the “Why” button on the story work item, a PO/SM can see how that story is contributing to the overall strategy of the organization. This info can also be sent into Jira from Jira Align + be made available on a custom field in Jira so that the devs working on the story can see the relevant parent features, portfolio Epic, and the Strategic Theme.
  • Orphan stories don’t contribute to the progress of any Program feature and Portfolio Epic, for example, the burn-down charts; therefore, having many Orphan stories will lead to poor predictability in the longer run. This is important even if stories are created for business as usual (BAU) maintenance work; it’s important to tie them with a long-running BAU Portfolio Epics so that we can track how much effort is being spent.
  • In the work tree view, you can drill down and see the effort spent from the Portfolio epics down to the child story.
    • Not having this data hygiene won’t break the Jira Align connector, but it prevents overall visibility of the real-time progress.
  • Make sure you've linked an Epic in your story. Otherwise, they will be represented as “Orphan Objects” in Jira Align.
  • Use Epics to represent large bodies of work – avoid using them for other purposes just for their inherent ability to group stories.
  • Jet By Jira Align (Check #1)
  • Issue, Story, and Epic Management
    • Sprints
    A single sprint should only be tied to one sprint board
    Since one sprint board represents one team, if you have a sprint across multiple boards, it can be difficult to measure team-level progress.
  • This will negatively impact the Jira Align connector because it will randomly pick which team to show the associated issue.
  • These issues will negatively impact Jira Align reporting.
  • Make sure you only have one sprint associated with one board.
  • If your team is structured in a way that you can't edit Filter Shares, instead select Edit Filter Query and ensure only a single team's sprints are tied to a board.
  • Jet By Jira Align (Check #6)
  • Sprint Best Practices
    • Sprints
    Sprints on a sprint board should not have overlapping dates, and the sprint should not be shared across multiple teams.
    Sprints represent a planning and execution time slot for a single team—only one sprint should be active at a time.
  • This will negatively impact the connector and cause sprint misalignment issues in Jira Align.
  • These issues will negatively impact Jira Align reporting.
  • Make sure your sprints' start and end dates don't overlap.
  • Allow one active sprint per each integrated Agile Board.
  • Disable “parallel sprints” as a precaution if possible in Jira.
  • Jet By Jira Align (Check #7)
  • Sprint Best Practices
    • Stories and story points
    Stories should have estimated story points.
     
  • Stable teams and estimated stories give way to stable velocity, which leads to team predictability and helps you build the right stuff by making the right demand versus capacity considerations.
  • There are multiple views that help you in the demand versus capacity decisions and that are driven by the estimated versus actual points in Jira Align.
  • In the Program feature (Jira Epics) backlog, you can see the progress of the features by story point progress as Jira Align rolls up the points estimated at the story level.
  • If you are using strategic drivers across portfolio epics, then based on the story points, you can also see the actuals, for example, points accepted across portfolio epics.
    • Not having this data hygiene won’t break the Jira Align connector, but it prevents overall visibility of the real-time progress and reporting.
  • Add estimates to the story point field in your stories in Jira – this should ideally be done at issue creation and refined/re-estimated during sprint planning.
  • Note: When preparing to close sprints, you should remove or split unfinished stories. This is covered in more detail in the second table below.
  • Jet By Jira Align (Check #2)
  • Issue, Story, and Epic Management
    • Teams and boards
    There should only be one project assigned to a Jira board.
  • Multiple projects linked to a single board can make it difficult to measure team-level progress: That board can represent multiple teams and have sprints with overlapping dates.
  • Having multiple projects assigned to a Jira board makes the integration unnecessarily complex; if the teams are separated across boards in Jira, then work item integration to Jira Align is smooth.
  • This will negatively impact the Jira Align integration because the same story could either be included in multiple team backlogs or not show up at all because the connector won’t be able to determine which team to assign it to.
  • These issues will negatively impact Jira Align reporting.
  • Assign one team to each integrated Agile Board (Scrum or Kanban) →
  • Ensure only one project is tied to a board by navigating to Board Settings, selecting Edit Filter Shares, and removing all but one project. You may also fail this check if there are no projects tied to your board.
  • Isolate issues, so they only exist on one integrated Agile Board.
  • Leverage JQL.
  • Note: Don't use the “Component” system field for this purpose as Jira Align does not currently support mapping of the Component system field—this is covered in more detail in the second table below.
  • Jet By Jira Align (Check #4)
  • Teams and Sprints
    • Additional consideration
    Why you need it
    Impacts
    Action to fix
    Reference article
    “Team” custom field and “Component” system field
    This applies if you have multiple teams on a Jira project and you are using a custom Team field to separate issues across different boards.
  • Team fields should be configured as a Select List (single choice), Select List (multiple choices), or Select List (cascading) field type and should be present on the Create and Edit screens of the standard issue types like Story, Task, etc.
  • Note that “Team” custom fields configured in Jira “Epics” are not synchronized to Jira Align “Features.”
  • The “Component” system field is not supported in the Jira Align Connector at this time; Components can vary across projects and are governed by project administrators.
  • Do not use this field to isolate issues across different Agile Boards.
  • Do not require this field via Field Configuration Schemes or Workflow Transitions.
    • Team in Jira Align is specific to JA and doesn’t sync directly as a part of the connector.
  • Use Team custom to sync to a team JA.
  • Use Jira project or board to a team in JA.
  • Syncing the Team Field Between Jira Software and Jira Align
  • Jira Connector - Feature sync failure "Component is required"
    • “Priority” system field
     
  • Use consistent priority schemes in Jira projects that are integrated with Jira Align.
  • This will help reduce your mapping configuration burden and prevent complications.
    • Too many priorities/priority schemes can cause complexity in your Jira ↔︎ Jira Align mapping configurations.
  • Use a consistent priority scheme in Jira.
  • Work with your Jira Administrator to ensure that the priority field is available on Jira and that there is alignment between Jira and Jira Align on valid priorities that can be set.
    • Jira Connector - Feature sync failure "The priority selected is invalid."
    Issue deletion
  • Deleted issues require special handling and pruning in Jira Align.
  • Generally, as a governance best practice, we always recommend that teams disable the “Delete Issue” permission for all Jira projects and leverage the “Resolution” field or leverage Cancelled/Duplicate statuses. Benefits of this approach include:
  • Never have to deal with accidental data loss due to issue deletion.
  • Never have to deal with deleted issue artifacts in integrated systems like Jira Align.
  • Keep Jira issue keys sequential when migrating projects from one instance to another.
  • It causes both to get out of sync if deletes are not synced.
  • Can lead to inconsistent reporting.
    • Disable the “Delete Issue” permission for all Jira projects, leverage the “Resolution” field, or leverage Cancelled/Duplicate statuses.
    Managing Jira Deleted Issues
    Custom issue hierarchy apps
    Jira Align does not integrate or account for app configuration. Any custom hierarchy established through an app will need to be re-configured and built as part of your initial Jira Align integration for each Program of Portfolio. Examples of such apps include:
  • Advanced Roadmaps
  • Structure
  • BigPicture
    • Any issue above the Jira Epic within Jira does not properly sync to Jira Align.
  • Don’t create issues above Jira Epic/Feature in Jira.
  • Create a migration plan to move those issues above Jira Epic/Feature out of Jira into Jira Align (if you choose to be in Jira Align).
    • Issues in sprints (Jira) and features in program increments (Jira Align)
     
     
     
     
    Carrying over issues across sprints in Jira or Features over program increments in Jira Align will adversely impact your reporting within Jira Align.
  • If the issue (Story, Feature, Epic) has the sprint updated after the sprint is closed, then the reports in Jira Align may not accurately reflect the reports.
  • Changed issues after the sprint is closed may not show in the report for that sprint.
  • When preparing to close sprints in Jira, you should remove or split unfinished stories and adjust estimates.
  • Note: Make sure you move the issue to the backlog BEFORE proceeding to the next sprint to properly clear and set the Sprint field.
  • When preparing to complete/close a program increment in Jira Align, you should split unfinished features and move features to the appropriate program increment.
    • Workflow
  • A good practice is to standardize on a common workflow and have a defined mapping between Jira Workflow Status and Jira Align Statuses.
  • There are a defined set of statuses in Jira Align, and there isn’t flexibility in Jira Align to mirror all the Jira Workflow Status.
  • There might be more Jira Workflow Status than Jira Align Statuses, and an update to a Jira Align Status can only be synced into one Jira State.
  • If the mapping is unclear, changes in the Jira Workflow Status or the Jira Align Status will be out of sync between both products.
  • These issues will negatively impact Jira and Jira Align reporting.
  • Build out a diagram that maps BOTH directions, what Jira Workflow Statuses go to Jira Align Statuses, and what Jira Align Statuses go back to Jira Statuses.
  • If there are changes to either product’s workflow, you will need to update the mappings to properly reflect these changes.
    • Workflow Best Practices

    Was this content helpful?

    Connect, share, or get additional help

    Atlassian Community

    Purpose-fit guidance and support to ensure your team's success

    Each deployment of Atlassian products is unique, so we offer a breadth of services to design, implement, and optimize solutions for scale.

    Learn More