> 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
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 **Connect**
#### Step 2: Authenticate with Atlassian
1. You will be redirected to Atlassian to authorize the connection via OAuth
2. Sign in with an Atlassian account that has admin permissions
3. Review the requested permissions and click **Accept**
#### Step 3: Configure the Integration
1. After authentication, select which **JSM service desks** to pull tickets from
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 enable **Allow agents to manually export tickets to JSM**
4. Use the **Bidirectional Sync** toggle 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 **Save**
{% 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 5 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 sync to silently fail. The integration health check automatically detects this condition and surfaces an actionable warning on the JSM integrations page so you know exactly what to fix before it affects your support workflows.
### 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, and Assign Issues, and shows a detailed pass/fail breakdown for each project.
* **Fix Permissions**: Harmony can guide you to resolve identified gaps so the integration user has the correct access before you go live.
#### Outbound Sync Permission Warning
When you enable outbound sync, Harmony checks whether the OAuth user has the necessary JSM agent permissions to perform updates on the connected project. If the OAuth user is missing JSM agent group membership (`jira-servicemanagement-users` or the legacy `jira-servicedesk-users` group), an amber warning banner appears next to the outbound sync toggle explaining exactly which permissions are missing and what to do next.
### 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 JQL Filters for Inbound Sync
You can define a custom JQL filter to control exactly which JSM tickets are pulled into Harmony during inbound sync. Your JQL clause is combined with the existing sync filters, giving you precise control over the scope of tickets that flow in - limiting syncing to specific projects, issue types, statuses, or any other criteria supported by JQL without affecting the rest of your sync configuration.
{% hint style="info" %}
Custom JQL filters are being rolled out incrementally. Contact your Harmony representative to have this enabled for your account.
{% endhint %}
### 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 |
| **JSM Get Request** | Fetch an existing JSM service request from within an agent flow |
| **Raise request on behalf of** | Raise a JSM request on behalf of an employee using their email address |
| **Additional fields (JSON)** | Set arbitrary additional fields on a JSM request |
### 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.