Map Jira Epics to Jira Align Features to Prevent Broken Roll-Ups

The Problem: When Jira Epics Map to Jira Align Epics, Roll-Ups Break

If your Jira Align reports show orphaned Features, double-counted scope, or roll-up totals that disagree with Jira boards, the connector’s issue-type mapping is the first place to look. The fix is usually simple: map Jira Epics to Jira Align Features, not to Jira Align Epics.

Why Epic-to-Feature Mapping Preserves Parent-Child Semantics

Jira teams treat an Epic as the top-level container for a body of work. Jira Align uses a deeper hierarchy: Initiatives contain program-level Epics, and those Epics contain Features, which in turn contain Stories and Tasks. When you map a Jira Epic to a Jira Align Epic, the connector creates a program-level container where a team-level container belongs. The result is orphaned Features, scope counted twice, and reports that do not match the Jira board.

Mapping Jira Epic to Jira Align Feature keeps the parent-child relationship that Jira users already expect. The Jira Epic becomes the Feature; Stories and Sub-tasks roll up beneath it exactly as they do in Jira.

Jira Issue Type	Jira Align Type	Role in Hierarchy
Epic	Feature	Team-level delivery scope
Story	Story	Work item under a Feature
Sub-task	Task	Granular work under a Story
(none)	Initiative / Epic	Program-level containers curated in Jira Align

Worked Configuration: Setting Up the Connector

Run these steps in the Jira Align web interface. You need Jira Align administrator permissions or equivalent connector-administration rights. Menu labels vary by tenant version—look for Jira Settings or Connections.

1. Open the Jira connector settings and authenticate to your Jira instance at [Jira Instance URL].
2. Select the target Jira project, for example [PROJECT_KEY].
3. In the issue-type mapping table, set Story → Story, Epic → Feature, and Sub-task → Task. Avoid mapping two Jira types to the same Jira Align type unless you have an explicit disambiguation rule.
4. Set the parent-link field to the Jira Epic Link custom field. This tells the connector that Stories belong to the mapped Feature.
5. Confirm the connector-managed custom field (the field that stores the Jira Align identifier) appears on all create, edit, and view screens in Jira. The connector writes the Jira Align key back to this field; it is the durable join key.
6. Save the configuration and run a manual sync.

Risk: If you remove the Epic Link field or rename Jira issue types after saving, the mapping breaks silently. Sync errors appear in the Jira Align connector log, not in Jira, so teams may assume data is flowing when it is not.

Verifying the Mapping Works

Use a controlled test before trusting production reports.

1. In Jira, create a test Story under a test Epic.
2. Trigger a manual sync from the Jira Align connector.
3. Open the corresponding Jira Align project and confirm the Story appears under the expected Feature with the correct parent link.
4. Inspect the Jira issue’s connector custom field and verify it holds a stable Jira Align identifier that matches the work item shown in Jira Align.
5. Open the Jira Align connector log for the project and check for unmapped-issue-type or missing-parent errors.

Limits and Common Mistakes

Do Not Map Epic to Epic

Mapping Jira Epic to Jira Align Epic is the most common error. Because Jira Align expects Features beneath program Epics, the mismatch produces orphaned Features and roll-ups that disagree with Jira boards.

Never Edit the Connector Custom Field

The connector-managed custom field and the Jira Align key on each issue are the durable join. Manually editing or clearing them can sever the link and create duplicate work items on the next sync.

Upper Hierarchy Is Curated Separately

The connector primarily pushes Jira work items and statuses into Jira Align. Planning artifacts above the mapped Feature—Initiatives and program-level Epics—are maintained in Jira Align and are not generated from Jira. You must build that upper hierarchy manually or through other integrations.

Project Type Support Varies

If your Jira teams use next-gen or team-managed projects, verify connector support before promising two-way sync. Those projects handle custom fields and issue types differently, and the connector may not support them.

Large Instances Need Patience

Expect incremental sync with possible API throttling. The initial backfill of long histories can take hours. Schedule it outside peak usage and monitor the connector log for rate-limit warnings.

A Practical Check Before You Trust the Reports

Compare a Jira Align Feature roll-up report against a Jira board filter for the same Epic. Scope should match: no Features without parents, no Stories counted twice, and no totals that appear only in one system. If the numbers diverge, re-open the connector log first—unmapped issue types and missing parent links are the usual culprits.

Because Atlassian periodically updates the Jira Align interface, confirm exact menu labels and field names in your tenant. Treat any label differences as a prompt to re-verify the mapping table rather than assuming the configuration is unchanged.