#Jira integration

Use the Jira integration to bring existing Jira work into Anakin and keep selected Jira projects connected to Anakin Spaces. Jira Cloud and Jira Server or Data Center are supported.

#Choose import or sync

• Import copies existing Jira data into Anakin. Use it for historical work or a controlled migration.
• Sync links a Jira project to a Anakin Space and keeps recent changes connected. Sync does not import historical data by itself. If the Space has the Triage inbox enabled, newly synced Jira issues enter the Triage status first. One-time historical imports still follow status mapping and do not necessarily enter Triage. GitHub and other synced tasks use the same source and link banner in task detail as Jira-synced tasks.
• Import and then sync imports the selected history and can enable ongoing sync with the credentials already entered in the wizard. You do not need a pre-existing Jira connection. Use a private network proxy appears only for self-hosted / Server / Data Center Jira; Jira Cloud does not show it. When the host is a private-network address, import and connect use a private-network proxy Computer rather than a direct cloud connection. If step 1 used a proxy computer, import and bidirectional sync both reuse that computer. If the proxy is unavailable or authentication fails, follow the error on the page.

#Connect Jira for ongoing sync

Open Integrations, select Jira, and choose Connect Jira.

For Jira Cloud, enter:

• The bare host name, such as acme.atlassian.net
• The Jira account email address
• An Atlassian API token

For Jira Server or Data Center, enter:

• The full Jira base URL
• The Jira username
• Authentication method: Personal access token, or Username & password

Anakin validates the credentials, stores an organization-level connection, and attempts to load the projects visible to that account. After a successful connection, a guidance dialog offers Set up data sync first, then Import data. Connecting Jira does not sync or import by itself. Choose Not now to continue later. Project loading is best effort, so a valid connection can be saved even when the account cannot browse projects. Use Refresh Jira projects after correcting access.

The Jira account needs access to every project you intend to link. Automatic webhook installation also requires Jira administration permission. A missing webhook permission does not block creation of the connection or link; use Configure webhook and give the packet to a Jira administrator. Jira changes will not arrive until webhook access is available.

#Manual webhook recovery

When you create a sync link, Anakin prepares its webhook right away: with Jira administration permission it registers the webhook in Jira directly; without it, it produces the configuration packet for an administrator. The link records its callback status and Last callback received time — the amber banner prompting you to configure appears only while no callback has ever been received (or a received callback failed to process).

If automatic installation fails, an amber notice appears directly under that link's row with Configure webhook — you do not have to expand anything. Give its one-time configuration packet to a Jira administrator. It includes the callback URL, the product-branded webhook secret header, query-secret fallback, required events, and project JQL. Copy the packet before dismissing it: regenerating the secret invalidates the previous value immediately.

After the administrator saves the webhook, modify a test issue in the linked Jira project. Anakin enables the link only after it receives and successfully processes that signed event. If the link reports Callback received, processing failed, use the displayed timestamp and request ID for support; it is an inbound processing incident, not a Jira-permission failure.

#Create and manage sync links

A sync link pairs one Jira project with one Anakin Space.

1. Open the Jira integration page.
2. Select Add new link — the New sync wizard opens in place and walks you through five steps: Configure (binding, project, target Space, and direction — bidirectional by default), Map statuses, Map users, Import options, and Confirm. For self-hosted Jira, the Configure step can also choose an intranet proxy computer.
3. Choose a Jira project and a Anakin Space.
4. Choose a direction.
5. Review the issue and project status mappings.
6. Save the link.

One Jira project can have only one active Space link. Multiple Jira projects can link to the same Space. The Jira project and Space cannot be changed after creation; delete the link and create a new one to select different targets.

Each link's row shows Sync configuration before its chevron; opening it shows that link's settings in a drawer with three tabs — Sync settings (continuous-sync switch, direction, and history import), User mapping, and Status mapping. Changes must be saved to take effect, and leaving with unsaved changes asks for confirmation first. When a link needs your attention, an amber notice appears directly under its row with the action to take, so you do not have to open the drawer first.

Available directions are:

• Bidirectional: Jira issues and epics sync with Anakin Tasks and Projects in both directions. New Tasks and Projects in the linked Space can create Jira issues and epics.
• Jira to Anakin: Jira issues and epics create or update their linked Anakin records, but new Anakin records are not created in Jira. Supported updates to records that are already linked can still be written back to Jira.

Deleting a link stops future sync without deleting Jira issues, Jira epics, Anakin Tasks, or Anakin Projects. Disconnecting the Jira connection disables all of its links and also leaves existing records intact.

#Consistent identifiers

When creating a sync, or later from the Sync settings tab of the sync configuration, you can enable consistent numbering so this Space's Task identifiers follow Jira:

• Tasks already linked to Jira switch to their Jira identifiers; the remaining existing Tasks are renumbered immediately to "old number + X" (e.g. 12 becomes 12X);
• new Tasks created in the Space first get an X identifier (e.g. HF-12X). With bidirectional sync, the identifier switches to the Jira one once the Task is created there; with one-way sync (Jira to Anakin) the Task is never created in Jira and keeps the X identifier;
• replaced identifiers are remembered on the Task detail as former identifiers, and a Task is still found by searching its former identifier with the X suffix;
• only one sync link per Space can have consistent numbering on at a time; if another link holds it, turn it off there first;
• before enabling, you confirm that existing identifiers will be modified and that old identifiers already shared in IM messages, git commits, or comments may point to different Tasks. After disabling, existing identifiers stay as they are (X identifiers remain X) and new Tasks continue from the current highest number.

Consistent numbering is not Jira-only: sync links such as Shortcut, Linear, and Asana, as well as GitHub and GitLab repository links, support it with the same rules; Linear follows the selected team's identifiers. Only one link per Space can have it on, mutually exclusive with Jira.

#Import Jira data

Open Settings, then Import & export, and start a Jira import. There are two ways in:

1. API import: enter host, account, token, project key, optional JQL, and the target Space. Use this for a full migration and for ongoing sync after import.
2. File import: upload a Jira CSV exported with Issues → Export → CSV (all fields). Map columns in the wizard (a title column is required) and import into the chosen Space. Unmapped fields may become custom fields. Mapping options follow the wizard.

File import is for a CSV you already have, or when API access is not available. Comments, attachments, and ongoing sync still use the API flow.

Other sources in the same Import & export screen use their own file wizards. Mapping options follow each source's wizard.

The current API flow includes these steps:

1. Enter the Jira host, account, token, project key, optional JQL, and target Space. The first option in the Space selector is + Create new space; choose it to create a Space without leaving the import flow. After creation, Anakin returns to the wizard and selects the new Space as the import target.
2. Validate the connection and review counts for issues, epics, statuses, labels, users, task types, custom fields, and existing Tasks.
3. Choose open issues, closed issues, or both, and exclude individual issues if needed.
4. Map Jira statuses.
5. Map Jira users or choose not to import users.
6. Choose import options and confirm the result.

Import options include:

• Sync issues and epics after import. First-time import can enable this with the credentials already entered in the wizard; a matching organization connection is not a prerequisite. The option is bidirectional, syncs only changes after this import, and reuses an intranet proxy computer chosen in step 1. You can later change the link to one-way, pause it, or remove it in External app integrations. Use Use a different account if the long-term sync account should differ from the import account, while keeping the same Jira host.
• Add the Migrated label, enabled by default
• Overwrite mutable Jira-sourced data on records imported earlier
• Import Jira Sprint data
• Switch the target Space to the Jira Sprint mode when Sprint import is enabled

#Import history after sync

A sync link keeps later changes connected; it does not backfill the project's existing Jira history. To bring in that history after the link exists, use the Jira integration's historical import action. Anakin reuses the saved Jira connection, so you do not need to paste the token again.

Historical re-import skips Tasks already identified from the same Jira source by default. If you enable Overwrite import, the confirmation step shows the number of existing Tasks and asks you to confirm. Overwrite refreshes mutable Jira-sourced data in place and preserves the Anakin Task identity; it does not create duplicates. Progress, per-item failures, cancellation, and the seven-day rollback window follow the regular API import rules below.

Only one Jira import can run in a Space at a time. You can cancel an active import; records already created remain. A completed or failed import can be rolled back within seven days, which removes the Tasks and Projects created by that import but does not change Jira data. A canceled import cannot currently be rolled back automatically.

#Data and mappings

The import and sync flows use these core mappings:

Imported labels belong to the target Space, so they do not affect label pickers in other Spaces. If the Organization already has a label with the same name, the import reuses that Organization label instead of creating another Space label with the same name.

For import status mapping, each Jira status can use an existing Anakin status or create a new status with a selected category and order. The create option is shown as Create new status (source status name) so you can confirm which Jira status it represents. If no explicit mapping is supplied, import uses category-based defaults.

For sync links, saved mappings take priority. Anakin then tries an exact Jira status name and finally the Jira status category. A missing or invalid mapping can prevent a status update from being written to Jira.

User import defaults to keeping people reachable instead of dropping them. Each Jira user can be mapped to an existing member, invited by email, or imported as an external account; choosing not to import is an explicit skip. Untouched rows default to import as external account: users already matched by email keep that match, and previously saved mappings or skips are reused.

If user import is disabled entirely, assignees remain unassigned and imported comments use the importing member as author.

The user-mapping step is conditional. When the source platform does not offer a fast user list, the wizard skips the step; when the current credential cannot read the user list, it is skipped automatically and the import-options step explains that user mapping was skipped, instead of waiting on "Fetching users…". Skipping matches users by email and leaves the rest as external accounts.

#External accounts

When an import or sync meets a user on the source platform who does not correspond to an Organization member, Anakin creates an external account instead of leaving work unassigned or forcing everyone to become a member.

An external account is a source identity: which platform and instance the person came from, plus their name or email. It is not an Organization member, takes no seat, and cannot sign in. "Import as external account" is the default during import; users discovered later by sync become external accounts the same way.

The mechanism is not limited to Jira: unknown users met in the Slack, GitHub, and GitLab integrations are captured as external accounts the same way and linked here. Where each platform produces external accounts, and when they link automatically, differs slightly — see "External accounts and user linking" on those integration pages.

External accounts are managed in People → External accounts:

• Filter by platform, instance, and link state (linked / unlinked), or search by name, email, or source key;
• Link an external account to an Organization member. A unique email match, or the person verifying the same platform account under Connected accounts, links automatically; a manual link always wins;
• After linking, Anakin backfills the assignee on the historical tasks this account held — only tasks that still carry the external identity and were never hand-edited; assignees a person chose manually are not overwritten;
• Unlinking restores the external identity on those tasks.

The members list also gains a Linked accounts column, so you can see at a glance which members hold external identities.

Members can connect a personal Jira account after an organization connection exists. Personal credentials are used for comment identity and identity-field mapping. If a personal credential is unavailable, comment publishing falls back to the organization integration account.

#Permissions and security

• Organization owners and admins can connect or disconnect Jira, update credentials, refresh projects, create or remove links, and start, cancel, or roll back imports.
• Organization members can view connection and link status. A member can connect or disconnect their own personal Jira account.
• Organization and personal Jira tokens are encrypted at rest. Connection responses expose token metadata rather than the full token.
• Import credentials may be retained in encrypted job state so an interrupted import can resume and a prior import can be prefilled for re-import. Restrict administrative access and rotate Jira tokens when needed.
• Jira webhooks use a link-scoped secret. The plaintext secret is returned only by the one-time recovery action and is never shown in link status.

Use a Jira account with only the permissions required for the selected projects, plus Jira administration permission if Anakin must install webhooks. Rotate API tokens and personal access tokens according to your security policy.

#Troubleshooting

When a task or project shows a Jira sync banner, read the original Jira error after the title (for example no transition to status "In Progress"). Use that line to pick the matching action below, then retry sync.

#Match the banner error

#Credentials are rejected

For Jira Cloud, use the bare *.atlassian.net host, the account email, and an Atlassian API token. For Jira Server or Data Center, use the correct base URL, username, and either a personal access token or a username and password. Update the stored credentials after a token or password expires or is revoked. Confirm the account can browse the project and create or edit issues. If comment sync failed, check whether the comment author needs a personal Jira account.

#The Jira item was not found

The Anakin item is still linked, but the Jira issue is missing, archived, or no longer visible to the integration account. Open the Jira issue from the banner. Restore it in Jira if it was deleted, or disconnect the sync link if you no longer need it.

#Jira Epic type is unavailable

This usually happens when Anakin tries to write a project as a Jira Epic. Enable an Epic issue type for the linked project, confirm the integration account can create Epics, or switch the link to one-way sync.

#Required Jira fields blocked sync

The Jira create or edit screen has a required field Anakin does not write, such as component, version, a custom field, or security level. Remove the required setting or give the field a project default, then retry.

#A workflow or field constraint blocked sync

The banner title is the same for several failures. Use the original error after the title.

#no transition to status "xx"

Jira has that status, but this issue cannot move there from its current status in one step. Custom workflows often block jumps. Auto-mapping can also collapse several Anakin in-progress statuses onto one Jira status.

1. Open the Jira issue and check the current status and allowed transitions.
2. Open the Space Jira sync link and fix status mapping. Map Anakin In Progress to the matching Jira status, not every started status to the same Jira status.
3. Confirm the target Jira status is reachable in one step. If Jira requires an intermediate status, move it in Jira first or change the mapping.
4. Retry sync.

#The status is not mapped

This Anakin status has no Jira mapping. Open the sync link status mapping, choose a Jira status or leave it unmapped, then retry.

#field cannot be set or unknown field

The current Jira screen or field context rejects the write. Check the edit screen, field context, and issue type, then retry.

If the original error does not match those cases:

1. Confirm the mapped Jira status is the intended one.
2. Check workflow validators, conditions, and post functions.
3. Retry after the Jira configuration or mapping change.

#Jira changes do not reach Anakin

Confirm that the project has an active link and that the Jira account has permission to install and manage webhooks. Check that the webhook project filter covers the linked project. JQL used during import limits only the import and does not limit ongoing sync.

#Showing category-based status defaults

Live Jira statuses could not be loaded, so the mapping UI falls back to category defaults. Update or reconnect the Jira credentials, confirm the account can read project statuses, refresh Jira project metadata, then pick exact Jira statuses.

#Comments use the integration account

Connect or update the member's personal Jira account. If the personal credential is missing or invalid, Anakin uses the organization integration account.

#An attachment fails to sync

Check the attachment size, Jira attachment settings, and the integration account's file permissions, then retry the affected record.

#No Jira projects appear

Confirm that the integration account can browse the project, then select Refresh Jira projects. Refreshing metadata does not create links or repair failed items.

#Why do some Task identifiers end with X?

That is what identifiers look like in a Space with consistent numbering on: Tasks not yet created in Jira (or the external system) use a temporary X identifier, one-way-synced Tasks keep it, and existing Tasks were renumbered to "old number + X" when it was enabled. Replaced identifiers still find their Task when searched with the X suffix, and the Task detail lists the former identifiers.