Configuring the Jira Align Jira Connector: Field Mapping and Sync Direction That Won't Corrupt Your Data

The decision that matters: one authoritative system per field

The Jira Align connector is not a two-way merge engine. It applies your field mappings on each polling cycle, and for every mapped field — summary, description, status, assignee, story points — one side effectively wins. If you configure a field as bidirectional and people edit it in both tools between sync cycles, you get last-writer-wins overwrites, and the losing edit disappears without an error message.

The practical rule: give each field exactly one editing audience, and set sync direction to match. Bidirectional is only safe for fields where one group realistically edits them — for example, status, which developers move in Jira and which Align should simply reflect.

How the connector actually works

The connector runs as a service (cloud-hosted, or an on-premise agent for Jira Data Center) that polls Jira through its REST API using a dedicated service account. It matches Jira issues to Jira Align work items using stored Jira issue keys and IDs, then applies your mapping and direction rules each cycle. Sync is polling-based, not real time — expect minutes of lag, and longer cycles when you map many custom fields or sync a large issue volume, because every mapped field adds API calls and can run into Jira's rate limits.

Two consequences follow. First, the service account's permissions define what syncs: if a Jira project is restricted or uses issue-level security, those issues silently never appear in Align. Second, deletions are asymmetric — deleting a Jira issue typically does not delete the Align work item; it gets orphaned or flagged, so stale items accumulate unless you schedule cleanup.

A worked configuration

A common, defensible setup for a program running PI planning in Align while teams execute in Jira:

The story-points row is the one teams most often get wrong. If points are bidirectional, a well-meaning edit in Align during planning overwrites the team's re-estimate in Jira on the next cycle.

Hierarchy: bridging Epic > Story to Epic > Feature > Story

Jira Align expects a three-tier Epic > Feature > Story structure; vanilla Jira only has Epic > Story. If you map Jira epics straight to Align epics, PI rollups aggregate at the wrong level. The standard fix is to introduce an intermediate layer in Jira — a dedicated issue type or an epic-link layer — and map it to Align Features, so stories roll up through features into epics correctly.

State mapping: the most common silent failure

Jira workflows have statuses like "In Review" or "Blocked"; Align uses a simpler state model. Every Jira status in scope must be explicitly mapped to an Align state. Unmapped statuses don't throw errors — items appear stuck, or flip to an unexpected state on the next sync. After your first full run, check the connector's sync log or audit report specifically for unmapped-status and failed-item entries.

For custom fields, map by the Jira custom field ID (the customfield_10123-style identifier), not the display name. Two fields can share a display name across projects, and picking the wrong one fails silently.

Verifying the setup before rollout

1. In a sandbox Jira project, create one epic, one feature-level issue, and one story. Confirm they appear in Align with the correct hierarchy and status after one sync cycle.
2. Edit the same mapped field in both tools between cycles and observe which value survives. This confirms your configured direction behaves as documented rather than as assumed.
3. Measure end-to-end propagation time — edit in Jira to visible in Align — and communicate that lag to stakeholders so nobody treats Align as a live board.
4. Review the sync log for orphaned items and set a recurring cleanup task for them.

Limits and caveats

Exact field names, connector UI, and supported Jira deployment types vary by Jira Align release — validate this configuration against your version's documentation before writing runbooks. Sync lag grows with issue volume and custom-field count, so resist mapping fields nobody reads. And treat any bidirectional field as a standing risk: if two audiences genuinely need to edit it, decide which tool is the system of record and retrain the other audience rather than relying on the connector to arbitrate.