#Jira integration

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

#Choose import or sync

• Import copies existing Jira data into Sharkly. Use it for historical work or a controlled migration.
• Sync links a Jira project to a Sharkly Space and keeps recent changes connected. Sync does not import historical data by itself.
• 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. The default is Do not use a private network proxy (direct from the server). 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
• A personal access token

Sharkly validates the credentials, stores an organization-level connection, and attempts to load the projects visible to that account. 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, but Jira changes will not arrive until webhook access is available.

#Manual webhook recovery

If automatic installation fails, the disabled link shows Configure webhook. Give its one-time configuration packet to a Jira administrator. It includes the callback URL, the product-branded X-HiFox-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. HiFox 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 Sharkly Space.

1. Open the Jira integration page.
2. Select Add new link.
3. Choose a Jira project and a Sharkly 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.

Available directions are:

• Bidirectional: Jira issues and epics sync with Sharkly Tasks and Projects in both directions. New Tasks and Projects in the linked Space can create Jira issues and epics.
• Jira to Sharkly: Jira issues and epics create or update their linked Sharkly records, but new Sharkly 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, Sharkly Tasks, or Sharkly Projects. Disconnecting the Jira connection disables all of its links and also leaves existing records intact.

#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 (Linear, TAPD, Asana, and similar) use their own file wizards. TAPD file import uses the official Excel export.

The current API flow includes these steps:

1. Enter the Jira host, account, token, project key, optional JQL, and target Space.
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

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 Sharkly status or create a new status with a selected category and order. If no explicit mapping is supplied, import uses category-based defaults.

For sync links, saved mappings take priority. Sharkly 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 is conservative by default. You can leave users unassigned, map Jira users to existing members, or invite a new member by email. If user import is disabled, assignees remain unassigned and imported comments use the importing member as author.

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 Sharkly 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 personal access token. Update the stored credentials after a token 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 Sharkly 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 Sharkly 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 Sharkly 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 Sharkly 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 Sharkly 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 Sharkly 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 Sharkly

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, Sharkly 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.