Jira Service Management (JSM)

Unthread can sync conversations with Jira Service Management (JSM) so support teams can work from either system. A synced Unthread conversation maps to a Jira issue, and conversation messages map to Jira comments.

The sync is bidirectional for conversation metadata and comments, with a few safeguards to prevent loops and accidental overwrites.

Who can set this up

You need an Unthread admin account and permission to connect apps. In Jira, use an account that can access the JSM site, service desks, request types, issue fields, comments, attachments, and webhooks for the projects you want to sync.

Create the JSM connection

1. In Unthread, go to Settings > JSM.
2. Select Connect JSM Instance.
3. Enter your Jira site name. For example, enter acme for acme.atlassian.net.
4. Complete the Atlassian authorization flow.
5. Optional: add a Jira personal API token. This is used for JSM Teams support and as a fallback for some Jira API calls.
6. Go to Channels > JSM or the project-specific JSM channel setup page.
7. Select the service desks you want to connect. Each selected service desk becomes a JSM channel in Unthread.
8. Go to the project's JSM Sync Settings.
9. Add a relay rule:
   • Choose the JSM service desk.
   • Optionally choose a default request type.
   • Optionally add filters, such as ticket type, status, priority, tags, customer, account, or custom fields.
   • Enable and save the rule.

After a rule is saved, new matching Unthread conversations are created in Jira automatically. Existing messages on the conversation are sent after the Jira issue is created.

What syncs from Unthread to JSM

When a conversation matches a JSM relay rule, Unthread creates a Jira issue in the selected service desk. Unthread chooses the Jira request type by first trying to match the Unthread ticket type name to a JSM request type. If that does not match, Unthread uses the rule's default request type. If needed, it falls back to available Jira issue types.

Unthread syncs these conversation fields to Jira when Jira allows the field to be edited:

• Conversation title to Jira summary
• Conversation description to Jira description
• Submitter and assignee to Jira users
• Due date to Jira due date
• Priority to Jira priority, based on matching priority labels
• Tags to Jira labels
• Supported custom fields, matched by field name
• Status/sub-status transitions, when the Unthread sub-status maps to a Jira workflow status and a valid Jira transition can be found

Unthread messages become Jira comments. Message text is converted to Jira's rich text format, and supported attachments are uploaded to Jira. Comments include a short author attribution, such as "Comment by Jane Doe".

Unthread also adds an internal Jira comment linking back to the Unthread ticket when it creates the issue.

What syncs from JSM to Unthread

Jira sends webhook events to Unthread for issue and comment changes in connected service desk projects. For an issue or comment to update an Unthread conversation, the Jira issue must already be linked to an Unthread conversation.

Issue updates can sync these fields back to Unthread:

• Jira summary to Unthread title
• Jira description to Unthread description
• Jira assignee to Unthread assignee
• Jira reporter to Unthread submitter
• Jira priority to Unthread priority, based on matching priority labels
• Jira labels to existing Unthread tags
• Jira status to Unthread status or sub-status
• Supported Jira custom fields to Unthread ticket fields, matched by field name

Jira comments sync back to Unthread as conversation messages. Public Jira comments become normal messages. Internal Jira comments become private notes in Unthread and are posted into the triage/private thread when available.

Jira comment attachments are downloaded and attached to the corresponding Unthread message. If a Jira comment contains only attachments, Unthread adds fallback text such as "File attached" so the message is visible.

How conflicts are handled

Unthread uses a three-way sync model. For each field, it compares:

• the current Unthread value
• the current Jira value
• the last value that successfully synced

If only Jira changed, the Jira value syncs into Unthread. If Unthread changed, Unthread syncs to Jira. If both sides changed the same field before the next sync, Unthread wins and its value is sent back to Jira.

This prevents Jira webhooks from overwriting newer Unthread edits with stale data and helps avoid infinite sync loops.

Important details and gotchas

• Webhooks are scoped to connected service desk projects. If a service desk is not connected as a JSM channel, its Jira issues will not sync.
• Unthread does not create new conversations from arbitrary Jira issues. Jira issue updates and comments sync back only when the Jira issue is already linked to an Unthread conversation.
• Relay rules only apply to conversations that match the saved filters. If a conversation does not create a Jira issue, check the rule conditions, selected project, selected service desk, and whether the rule is enabled.
• Request type selection matters. If the Unthread ticket type does not match a JSM request type and no usable default is set, issue creation can fail or fall back to a Jira issue type.
• Custom fields match by name. The Unthread field label must match the Jira field name closely enough after normalization.
• Not every custom field type is supported. File upload fields and user group fields do not sync as conversation fields. Some Jira values may be coerced, such as multi-value Jira fields becoming a single Unthread value when the Unthread field only accepts one value.
• Jira labels only become Unthread tags when matching tags already exist in Unthread. Sync does not create new tags from unknown Jira labels.
• Priority sync depends on matching priority labels between Jira and the Unthread project's priority configuration.
• Status sync works best when Jira statuses and Unthread sub-statuses have matching names. Otherwise, Unthread falls back to Jira status categories such as To Do, In Progress, and Done.
• Private notes and system messages are treated carefully. Messages marked private, system-generated, private explanations, triage-thread messages, or messages sent before the conversation was ready are sent to Jira as internal comments.
• The sync skips webhook events created by the integration/service account to prevent echo loops.
• Deletes are conservative. Deleting a synced object in one system does not always hard-delete the object in the other system. In particular, Unthread avoids deleting Jira issues or comments unless it can tell the deleted Unthread item originally came from Jira.
• Attachment rendering can depend on Jira permissions. Uploaded Jira attachment links may require the viewer to be logged in to Jira.

Troubleshooting checklist

If a conversation did not create a Jira issue:

• Confirm the JSM integration is connected under Settings > JSM.
• Confirm the service desk is connected under Channels > JSM.
• Confirm the project has an enabled JSM relay rule.
• Confirm the conversation matches the rule filters.
• Confirm the selected request type and Jira issue fields are valid for the target service desk.

If Jira changes are not appearing in Unthread:

• Confirm the Jira issue is in a connected service desk project.
• Confirm the Jira webhook is registered for that JSM instance.
• Confirm the change was not made by the integration account.
• Confirm the field type is supported and the field name matches the Unthread field label.

If a field appears to be overwritten:

• Check whether the same field changed in both systems before the next sync. In true conflicts, Unthread is the source of truth and wins.