> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/it-service-management/jira-service-management.md).
# Jira Service Management
Bi-directionally sync service desk tickets between Jira Service Management and Harmony
Jira Service Management (JSM) is Atlassian's IT service desk platform for managing service requests, incidents, and change management. Connecting JSM to Harmony enables bi-directional ticket sync - tickets raised in JSM appear in Harmony, and Harmony agents can export tickets back to JSM when needed.
{% hint style="info" %}
Looking for Jira Software (project management for dev teams)? See the [Jira Software](/integrations/it-service-management/jira-software.md) integration.
{% endhint %}
### What the Jira Service Management integration enables
| Capability | Description |
| --------------------------- | ------------------------------------------------------------------------------ |
| Bi-Directional Sync | Tickets created in JSM appear in Harmony and stay in sync |
| Manual Export to JSM | Harmony agents can push tickets to JSM when escalation is needed |
| Status Synchronization | Ticket statuses update across both systems automatically |
| Comment Sync | Comments added in either system are reflected in the other |
| Custom Agent Builder Blocks | Use JSM actions directly inside Harmony's Custom Agent Builder |
| Sub-Issue Visibility | View linked JSM sub-issues and their live status from the ticket detail page |
| Custom Field Sync | JSM custom fields are surfaced inside ticket descriptions in Harmony |
| Conditional Form Logic | Form questions with conditional visibility are handled correctly during export |
| File Attachments | File attachments in forms are uploaded and linked to created JSM requests |
### Prerequisites
* **Atlassian Admin Permissions**: Required to authorize the OAuth connection
* **Jira Service Management subscription**: Active JSM project(s) to connect
* **Harmony Account**: Active Harmony workspace
### Connect Jira Service Management to Harmony
#### Step 1: Navigate to Integrations
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Jira Service Management** under **IT Service Management** and click its card
#### Step 2: Authenticate with Atlassian
1. Click **Connect**. You will be redirected to Atlassian to authorize the connection via OAuth
2. Sign in with an Atlassian account that has admin permissions
3. Choose the Jira site to connect, review the requested permissions, and click **Accept**
#### Step 3: Configure the Integration
1. After authentication, select **Enable Data Migration** to pull inbound tickets from JSM into Harmony, then select which JSM service desks to pull tickets from (leave the selection empty to sync all service desks)
2. Harmony automatically audits whether the integration user has the required access for each selected project and surfaces any permission gaps as warning banners - see [Permission Checks](#self-service-permission-checks) below
3. Optionally turn on **Manual ticket creation** to allow agents to manually escalate tickets to JSM
4. Use the **Bidirectional synchronization** toggle (shown when **Enable Data Migration** is selected) to enable or disable outbound sync between Harmony and JSM - this toggle is available both during initial setup and on the saved-settings screen
5. Click **Complete Configuration**. Later changes are saved with **Save Changes**
{% hint style="info" %}
When you select your service desks during setup or update, Harmony automatically establishes the necessary inbound sync configuration so tickets begin flowing in without any additional steps.
{% endhint %}
### What Harmony Syncs
**From Jira Service Management:**
* Service desk tickets (summary, description, priority, reporter)
* Ticket statuses and transitions
* Comments and internal notes
* Assignee and queue information
* Request type and service desk metadata
* Custom fields configured on the customer portal form, appended to the ticket description as a clean markdown table
**Sync frequency:** Ticket updates, status changes, and other data from JSM refresh every few minutes, keeping your agents working with current information.
### Email Visibility Warning
If email visibility is restricted in your Atlassian settings, Harmony cannot match JSM accounts to employees by email address, which causes employee matching to silently fail. Make sure the email addresses of your JSM users are visible to the account you connect with.
### Self-Service Permission Checks
When you select JSM service desks during setup, Harmony automatically audits whether the integration user has the required access for each project. Any gaps are surfaced as clear warning banners directly in the setup screen - no need to manually navigate Jira's permission scheme configuration.
* **Check Permissions**: Harmony verifies per-project permissions including Browse Projects, Add Comments, Edit Issues, Transition Issues, Assignable User, Assign Issues, and Modify Reporter, and shows a detailed pass/fail breakdown for each project. In Jira's permission schemes, some of these now go by newer names: Browse spaces, Edit work items, Transition work items, Assign work items, and Modify reporters.
* **Fix Permissions**: When the connected user is a Jira admin, a **Fix Permissions** button lets you grant the integration user a project role so it has the correct access before you go live.
#### Outbound Sync Permissions
To push updates to JSM, the OAuth user needs JSM agent access, such as membership in the `jira-servicemanagement-users` group or the legacy `jira-servicedesk-users` group.
### Manually Export Tickets to JSM
You can manually export any Harmony ticket to JSM as a native service desk request with full form support. From any ticket, open the export dropdown and follow a guided flow to create a properly scoped JSM request.
* **Service desk and request type selection**: choose from the service desks and request types configured in your JSM integration
* **Portal field support**: dynamic fields are discovered per request type, so you only see fields relevant to your chosen request
* **Proforma/Forms support**: when a request type has a form attached, the full form is presented with all relevant fields
* **Conditional question visibility**: questions that depend on a parent dropdown only appear when the relevant option is selected, keeping forms clean - hidden questions are automatically excluded from validation and submission
* **File attachments**: attachment fields in forms are fully supported - files are uploaded to JSM's temporary attachment endpoint and then linked to the created request automatically
* **Backlink to Harmony**: the created JSM request automatically includes a "View in Harmony" link in its description so JSM agents can jump back to the original Harmony ticket at any time - if the link cannot be resolved, the export still completes successfully
#### Form Validation During Export
Harmony validates JSM forms against Jira's required field definitions before submission:
* If a required Jira field is missing from the form, Harmony flags the form as unavailable to prevent incomplete tickets from being submitted
* Questions that map to Jira-required fields are automatically treated as required, even if the original form did not mark them as such
* Dropdown and choice fields use a robust resolution process with multiple fallback sources
* Section-level conditions - where entire groups of questions are shown or hidden based on earlier answers - are correctly resolved down to the individual question level, ensuring hidden fields are never incorrectly treated as required
### Custom Fields in Ticket Descriptions
When a JSM ticket is synced into Harmony, relevant custom fields are appended to the ticket description as a clean markdown table. For JSM tickets, only the custom fields configured on the customer portal form are included - filtering out internal system fields and reducing noise (typically from around 45 fields down to 5-7 relevant ones).
### Sub-Issues
You can view linked JSM sub-issues directly from the Harmony ticket detail page. A collapsible **Sub-Issues** card in the sidebar shows live status and last updated time for each linked issue, fetched in real time from your connected JSM instance.
* Provider icon, clickable ticket ID, and current status badge are shown for each sub-issue
* Last updated time is displayed as relative time
* The card is hidden automatically when no sub-issues are linked
### JSM Blocks in Custom Agent Builder
You can use JSM actions directly inside Harmony's Custom Agent Builder to build agents that interact with JSM without leaving the workflow canvas. The available blocks are:
| Block | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| **Get Jira User** | Look up a Jira user by their details and retrieve their Jira user ID for use in downstream steps |
| **Get JSM Request** | Fetch an existing JSM service request from within an agent flow |
| **Create JSM Request** | Raise a JSM request, optionally on behalf of an employee and with additional request fields |
| **List JSM Request Types** | Query the available request types in a JSM service desk |
### Message Sync for ITSM Tickets
When agents reply or workflows send messages on a JSM ticket, those messages are captured and reflected in the ticket's message history. This ensures the full conversation thread - including automated workflow messages and agent responses - is consistently available on ITSM tickets.
### Use Cases
Unified Ticket View
Surface JSM tickets alongside tickets from other channels in a single Harmony inbox - no tab switching required
Escalation to JSM
When a Harmony ticket needs formal tracking in JSM, agents can export it with one click, preserving full context including file attachments and form fields
Status Transparency
Keep requesters updated automatically as ticket statuses change in either system
Cross-Team Collaboration
Route tickets between IT teams using Harmony's automation and JSM's queues without losing history
Automated Agent Workflows
Use the Custom Agent Builder's JSM blocks to create agents that look up users, fetch requests, and raise tickets on behalf of employees - all from within Harmony's workflow canvas
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.harmony.io/integrations/it-service-management/jira-service-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.