Mapping Jira Work to Jira Align: Keep Team Boards Intact While Rolling Up to Portfolios

Problem: One Roadmap, Many Boards

Senior leaders often need a single, trustworthy roadmap that spans dozens of Jira projects. Teams, however, have invested heavily in their own Jira boards, workflows, and issue‑type conventions. The question becomes: how can we surface a portfolio‑level view without forcing teams to abandon the tools they use every day?

Thesis: Sync Up, Don’t Push Down

The key engineering decision is to keep execution in Jira and let Jira Align aggregate that work into its own planning hierarchy. This requires a deliberate mapping of Jira issue types, statuses, and custom fields to Jira Align’s portfolio, feature, and story levels. The result is a trustworthy program board that reflects the teams’ reality, yet lives in Jira Align.

Understanding the Hierarchy

Jira Align organizes work in a 5‑level tree:

• Portfolio – Strategic initiatives, often represented by a portfolio epic.
• Program – A collection of teams (e.g., an ART in SAFe).
• Feature – A slice of value that spans multiple teams.
• Story – Team‑level work items, typically Jira stories.
• Defect – Bugs or issues that need to be tracked.

The connector must decide which Jira issue type lands at each level. The most common convention is:

• Jira Epic → Jira Align Feature
• Jira Story → Jira Align Story
• Jira Bug/Defect → Jira Align Defect

Step‑by‑Step: Configuring One Team Connector

1. Create a Jira Align Team that represents the group of Jira projects you want to sync. In Jira Align, navigate to Administration > Teams and click Create Team.

2. Set up the Connector in Jira Align: Connectors > Jira Software. Choose the connector type (Cloud or Server, depending on your Jira deployment). Provide the Jira instance URL, authentication credentials, and the Jira project key(s). The connector screen will show a list of available issue types and statuses.

3. Map Issue Types:

   • Under Issue Type Mapping, set Epic to map to Feature.
   • Set Story to map to Story.
   • Optionally map Bug or custom defect types to Defect.

4. Map Statuses:

   • Choose Jira statuses that represent the core board states (e.g., To Do, In Progress, Done).
   • Map each to the corresponding Jira Align state (e.g., Ready, Committed, Released).
   • Ensure that the mapping covers all statuses used in the team’s workflow; otherwise, items may appear in an undefined state in Jira Align.

5. Field Mapping – Decide which custom fields should roll up. Common fields are Story Points and Assignee. In the Field Mapping tab, link the Jira field to the Jira Align counterpart.

6. Validate the Sync – After saving, run a Test Sync. The connector will show a preview of items that will be imported. Verify that at least one epic, a handful of stories, and a defect appear in the preview.

7. Enable Production Sync – Once satisfied, toggle the connector to Active. The sync will run on a schedule (configurable in the connector settings). The first full sync can take several minutes depending on the size of the project.

Concrete Example: Six Teams, One Program

Imagine a portfolio with an ART called Customer‑Onboarding. Six teams each own a separate Jira project (e.g., UI, Backend, API, Testing, Docs, Ops). The steps above are repeated for each team, but the mapping is identical:

• Epic → Feature
• Story → Story
• Bug → Defect
• Statuses: To Do → Ready, In Progress → Committed, Done → Released
• Story Points → Effort

After the first sync, the Customer‑Onboarding program board in Jira Align shows all six features, each with a bar chart of story points that aggregates stories from the six teams. The program board also displays cross‑team dependencies because each story can reference a parent feature that is shared across teams. Teams continue to work in their own Jira boards; the connector only pulls data upward.

Trade‑Off: The Cost of Two Hierarchies

Because Jira Align maintains its own feature hierarchy, an epic in Jira is effectively a duplicate of a feature in Jira Align. This duplication can lead to confusion if teams are not clear on where to create new work items. Governance is therefore essential:

• Ownership – Assign a Portfolio Owner who controls the mapping and ensures that new issue types or statuses are added consistently.
• Change Management – A workflow change in Jira (e.g., adding a new status) requires a mapping update in Jira Align. Without a process, the sync will fail or produce incomplete data.
• Documentation – Keep an up‑to‑date mapping matrix that lists Jira issue types, statuses, and fields alongside their Jira Align counterparts.

Another limitation is that the connector does not push portfolio details back into Jira. If a stakeholder needs to see the feature name or PI goal in Jira, they must rely on the Jira Align view or a custom report. This is usually acceptable because the primary goal is to keep daily execution in Jira.

Actionable Checklist

1. Confirm your Jira deployment type (Cloud, Server, Data Center) and verify it is supported by the Jira Align connector.
2. Create a mapping matrix and store it in a shared location.
3. Set up one connector per team, using the same mapping rules.
4. Run a test sync and review the preview.
5. Activate the connector and monitor the first full sync for errors.
6. Establish a change‑management process for any future workflow or field changes.

By following these steps, you can deliver a trustworthy, portfolio‑level roadmap without forcing teams to abandon their familiar Jira boards.