Diagnosing Jira Align ↔ Jira Software Connector Sync Failures

Recognizable Conditions

When the Jira Align connector stops delivering work items, fields, or hierarchy data to Jira Software, the symptom usually falls into one of the following categories. Identify the condition you see, then follow the linked diagnostic steps.

Condition	Typical Symptom	Primary Cause
Missing Epics/Features	Work items created in Align never appear in the target Jira project	Project not linked in Connector config or issue‑type mapping missing
Field Values Stale	Story Points, Sprint, or custom fields don’t update bidirectionally	Field mapping disabled, type mismatch, or target field absent from Jira screen
Duplicate Issues	Same Align work item creates multiple Jira issues	Connector re‑initialized without external‑ID match or multiple rooms sync to same project without distinct issue‑type mapping
Auth Errors (401/403)	Connector log shows “401 Unauthorized” or “403 Forbidden”	API token expired, insufficient Jira permissions, or IP allowlist blocks Atlassian cloud IPs
Broken Hierarchy	Capabilities → Features → Epics → Stories not linked in Jira	Hierarchy levels unmapped to Jira issue types or Parent Link field not configured
Sprint/PI Data Missing	Sprint or Program Increment values not reflected in Jira	Board is Kanban (no sprints) or PI custom field not mapped
Stale Data Despite “Healthy”	Connector status green but last successful sync > 15 min ago	Default 15‑min interval with queue backlog on large instances
Picklist Options Not Syncing	Dropdown values from Align don’t appear in Jira	Option values differ case‑sensitively; Align options must be subset of Jira options

Ordered Diagnostic Checks

1. Open the Connector Log – In Jira Align go to Administration → Jira Connections → Connector Log. Filter by error level and note the timestamp of the last successful sync per project.
2. Verify Project Mapping – Under Administration → Jira Connections → Project Mappings, confirm the target Jira project is listed and an issue‑type mapping exists for each Align work‑item type you expect.
3. Inspect Field Mappings – For each mapped project, open Field Mappings. Ensure the Sync toggle is on for every required field and that the target Jira field ID matches a field present on the relevant screen (e.g., customfield_12345 for Story Points).
4. Check External ID Field – In Jira, open a sample synced issue and locate the custom field Jira Align Key (or the configured external‑ID field). It must be populated and unique. Absence indicates a mapping or re‑initialization problem.
5. Validate Hierarchy Mapping – In Administration → Jira Connections → Hierarchy Mapping, confirm each Align level (Capability, Feature, Epic, Story) maps to a Jira issue type that has a Parent Link field (e.g., parent for Epic → Feature).
6. Confirm Board Type – If sprint data is missing, verify the Jira board is a Scrum board. Kanban boards do not support sprints.
7. Review Sync Interval – In Connector → Sync Status check Last Successful Sync. If the interval is 15 min and the instance is large, consider raising the interval or limiting the number of projects in scope.
8. Test Picklist Sync – In a field mapping for a picklist, click Sync Options. This pushes Align options to Jira; ensure Align’s option set is a case‑sensitive subset of Jira’s options.

Fixes Tied to Findings

Missing Epics/Features

• Add the missing Jira project to Project Mappings and create an issue‑type mapping (e.g., Align Epic → Jira Epic).
• Trigger a manual sync: in the Connector UI click Sync Now for that project. Verify the new Epic appears in Jira within 2 minutes.

Field Values Stale

• Enable the Sync toggle for each field.
• If the field type mismatches (Align numeric vs. Jira text), change the Jira field to a compatible type or add a scripted field to convert.
• Ensure the target field is on the Create and Edit screens for the mapped issue type.

Duplicate Issues

• Confirm the Jira Align Key custom field is present on all mapped issue types and is set to Unique.
• If multiple Align rooms sync to the same Jira project, assign distinct issue‑type mappings per room (e.g., Room A Epic → Jira Epic, Room B Epic → Jira “Epic‑B”).
• Re‑run a manual sync after correcting mappings; duplicates should not reappear.

Auth Errors (401/403)

• Rotate the API token in Administration → Jira Connections → Authentication.
• Ensure the connector service account has Jira permissions: Browse Projects, Create Issues, Edit Issues, and Administer Projects for the mapped projects.
• Whitelist Atlassian’s published cloud IP ranges in any firewall or IP allowlist.

Broken Hierarchy

• Map each Align hierarchy level to a Jira issue type that supports a parent link (e.g., Epic → Feature via parent field).
• In Jira, open an Epic linked to a Feature and verify the Parent Link field shows the Feature key.

Sprint/PI Data Missing

• Change the board to Scrum if sprint sync is required.
• Create a Jira custom field (e.g., Program Increment) and map it to the Align PI field in Field Mappings.

Stale Data Despite “Healthy”

• Increase the sync interval (e.g., to 30 min) or reduce the number of projects in the connector scope.
• Monitor Sync Status → Queue Length to confirm backlog is draining.

Picklist Options Not Syncing

• In the field mapping UI, click Sync Options.
• Verify Align’s option list is a case‑sensitive subset of the Jira field’s options; add missing options in Jira if needed.

Escalation Criteria

• Connector log shows repeated 5xx errors from Jira Cloud after token rotation and permission fixes.
• Sync queue length grows beyond 10,000 items for more than two consecutive intervals.
• Hierarchy or field mappings cannot be saved due to schema lock (e.g., Jira field locked by another app).
• Atlassian Statuspage reports an ongoing incident for Jira Align or Jira Cloud.

When any of the above occur, open a support ticket with Atlassian providing the Connector Log excerpt, the project mapping screenshot, and the exact error code.

Practical Verification Steps

1. Create a test Epic in Align, assign it to a mapped project, and click Sync Now in the Connector UI.
2. In Jira, search for the Epic key (e.g., PROJ-123) and confirm the Jira Align Key field matches the Align work‑item ID.
3. Check that Story Points, Sprint, and any custom fields reflect the Align values.
4. Open the Epic’s Parent Link field to verify the Feature link appears.
5. Confirm the Connector Log shows a successful sync entry with timestamp within the last 2 minutes.

Limitations & Gotchas

• Sync is eventually consistent; do not rely on real‑time updates for reporting.
• Deleting a work item in Align does not delete the linked Jira issue unless Delete Behavior is configured in the project mapping.
• Large initial syncs (thousands of issues) can hit Jira API rate limits; schedule during low‑usage windows.
• Changing field mappings after the first sync may cause data divergence; always test in a sandbox first.
• Jira Cloud IP ranges change periodically; keep firewall allowlists updated via Atlassian’s published JSON.

Quick Reference: Connector User Requirements

Role in Jira Align:   Administrator (full access)
Role in Jira Cloud:   Jira Admin + Project Admin for each mapped project
Authentication:       Dedicated service account (not a personal user)
Token rotation:       Every 90 days or after any permission change
IP allowlist:         Atlassian cloud IP ranges (https://ip-ranges.atlassian.com)