Configure Bi-Directional Epic and Feature Sync Between Jira Software and Jira Align

The synchronization problem this solves

Teams planning in Jira Align and executing in Jira Software often maintain two separate records for the same work. A Feature created in Jira Align for a Program Increment never appears in Jira Software, so delivery teams create a duplicate Epic. When status changes in either tool, the other system stays stale, and portfolio reports lose reliability.

Useful takeaway

Install one Jira Align Connector instance between the two systems, map Epic and Feature entities plus their fields, and verify with a single test issue before enabling production programs. The connector handles API calls and polling; you control what syncs through mapping and filter rules.

How the connector moves data

The Jira Align Connector is a standalone service installed on a host with network access to both systems. It authenticates to Jira Software using OAuth 2.0 or a personal access token (PAT), and to Jira Align using an API key. Changes in Jira Software can reach Jira Align through webhooks for near-real-time updates; changes from Jira Align to Jira Software are typically picked up on a poll interval. The connector does not merge records by itself; it applies field mappings and direction rules you define.

Unfamiliar terms: a webhook is an HTTP callback that Jira Software sends to the connector when an issue changes. Polling means the connector repeatedly asks Jira Align for updates. A custom field ID is the internal identifier, such as customfield_10024, used to reference a field in API calls.

Worked configuration: connector properties and field mapping

Run the following steps on the host where the connector will run. You need a Java 11+ runtime, network access to both Jira Align and Jira Software, and permission to edit files in the connector installation directory.

1. Create the connector in Jira Align

In Jira Align, create a new Jira Software connector and record the generated API key and connector ID. The exact administration menu path varies by release, so confirm the connector creation screen in your tenant before proceeding.

2. Edit connector.properties

On the connector host, edit connector.properties. Replace placeholder values with your own:

jira.align.url=https://your-tenant.jiraalign.com
jira.align.api.key=REPLACE_WITH_ALIGN_API_KEY
connector.id=prod-connector-01
jira.software.url=https://jira.example.com
jira.software.auth.type=OAUTH2
oauth.client.id=REPLACE_WITH_OAUTH_CLIENT_ID
oauth.client.secret=REPLACE_WITH_OAUTH_CLIENT_SECRET
sync.poll.interval.seconds=60
entity.map=Epic:Feature, Feature:Story

Permissions: the connector service account must read this file and make outbound HTTPS calls to both URLs. Risk: committing secrets to version control can expose credentials; store the file outside source control or use a secrets manager.

3. Define field mapping in mapping.json

Create mapping.json in the connector config directory. This example maps a Jira Software Epic to a Jira Align Feature and controls which fields flow in which direction:

{
  "entityMappings": [
    {
      "sourceSystem": "Jira Software",
      "targetSystem": "Jira Align",
      "sourceType": "Epic",
      "targetType": "Feature",
      "direction": "BI_DIRECTIONAL",
      "projectFilter": ["PROJ1", "PROJ2"],
      "labelFilter": ["SAFe"],
      "fieldMappings": [
        {
          "sourceField": "summary",
          "targetField": "title",
          "direction": "BI_DIRECTIONAL"
        },
        {
          "sourceField": "customfield_10024",
          "targetField": "businessValue",
          "direction": "JIRA_TO_ALIGN"
        },
        {
          "sourceField": "statusCategory",
          "targetField": "status",
          "direction": "BI_DIRECTIONAL",
          "transform": {
            "To Do": "Backlog",
            "In Progress": "In Progress",
            "Done": "Done"
          }
        }
      ]
    }
  ]
}

The transform block prevents unmapped status values from stalling issues. Custom fields must exist in both systems before mapping; reference them by ID, not by display name.

Sync rules and directionality

Sync rules limit which issues enter the pipeline. In the example above, only Epics in projects PROJ1 and PROJ2 with the SAFe label are considered. Directionality options generally include bi-directional, Jira-to-Align, and Align-to-Jira. For fields such as Description, avoid mapping the same field in both directions unless you add a last-updated comparison; otherwise each system can trigger the other repeatedly, creating an update loop.

Jira Align's SAFe hierarchy (Portfolio, Solution, Program, Team) does not mirror Jira's flat project structure. Map projects to programs deliberately. Capability and Theme levels are generally read-only from Jira Align; plan your hierarchy before enabling sync.

Limits and common mistakes

• The connector does not sync comments, attachments, or work logs by default.
• Conflicting concurrent edits are resolved with last-write-wins based on timestamp; there is no merge conflict UI.
• Mismatched status categories leave issues in an unmapped status queue.
• Forgetting to enable Jira webhooks for the connector callback URL delays updates from Jira Software to Jira Align.
• Mapping required fields incorrectly causes create failures.
• Running multiple connector instances with the same connector ID against one tenant can cause duplicate processing.

Large instances with more than roughly 50,000 issues may need adjusted poll intervals and batch sizes to avoid API rate limits. Network latency between the connector host and Jira Software should ideally stay under 100 ms; higher latency can cause timeouts. These thresholds depend on your connector release and should be confirmed against current documentation.

Verify the sync without disrupting production

1. Create a test Epic in Jira Software with the SAFe label and one of the filtered project keys.
2. Check Jira Align under the mapped Program. With webhooks enabled, expect the Feature within about two minutes; with polling only, expect it within the configured interval.
3. Change the Epic status in Jira Align and confirm the status appears in Jira Software after the next poll cycle.
4. Open the Connector Health dashboard in Jira Align and confirm zero errors and increasing sync counts.
5. Review connector.log on the connector host for successful HTTP requests to both APIs and no mapping exceptions.
6. Run a full re-sync from the connector UI and compare issue counts in Jira Align's Program Room against a JQL query in Jira Software.

These timing figures are typical defaults and should be treated as unverified until you observe them in your environment.

Undoing the configuration

Because installing the connector and writing configuration changes system state, rollback means stopping the connector service, removing or backing up connector.properties and mapping.json, and deleting the connector definition in Jira Align. Issues already created in the target system remain; you must archive or delete them manually if they were created only for testing.

Review before production: UI menu paths, exact default poll interval, connector upgrade windows, and issue-count thresholds in this guide come from general product knowledge and require verification against your Jira Align release and connector version.