Skip to main content

​
About Jira

The Jira integration connects a Jira Cloud site (yourcompany.atlassian.net) to Serval. Once connected, Serval can sync tickets two-way between Serval and Jira, run prebuilt Jira workflows, and automate anything the Jira Cloud REST API supports - with authentication handled for you. Self-hosted Jira Data Center uses a separate integration and is not covered on this page. Authentication: Atlassian OAuth 2.0 (3LO) - either Serval-managed sign-in (recommended) or your own Atlassian OAuth app. Both paths use the same permission picker, so you choose exactly which Jira scopes the connection requests. Installing the Serval Forge app into your Jira site afterward unlocks ticket syncing and service-account features on connections made with either method. Data sync: Two-way ticket syncing runs in the background once the Forge app is installed and sync settings are configured; workflow actions run on demand. Access tokens are refreshed automatically for both connection methods.

​
What the Jira integration enables

Anything defined in the Jira Cloud REST API v3 can be accessed through Serval.

​
Get your credentials

There are two ways to connect, and only one of them requires Atlassian-side setup.
No credentials to create. Serval uses its own registered Atlassian app - you only need a Jira account with access to the site you want to connect, and you’ll approve the permissions on Atlassian’s consent screen. Skip ahead to Connect in Serval.

​
Connect in Serval

This option is badged Recommended in the connect modal: “Connect using the Serval-managed Jira integration.”
1

Enter your Jira site

Fill in the Jira site field (required) with your subdomain only - the .atlassian.net suffix is fixed next to the input. Helper text: “For example, if your Jira URL is acme.atlassian.net, enter acme.” Leaving it empty shows “Jira subdomain is required”; anything other than letters, numbers, and hyphens - or a value that starts or ends with a hyphen - shows “Please enter a valid subdomain (letters, numbers, and hyphens only)”.
2

Choose Permission Presets (required)

Under Permission Presets, all three presets - Issue Tracking, Service Management, and Projects & Administration - are checked by default. Uncheck a preset to drop its scopes, or expand it to toggle individual scopes off (a partially selected preset shows a mixed checkbox and a “[n] of [m]” count). The footer shows “[number] Jira permission(s) will be requested.” At least one permission is required - the Connect button stays disabled until you select one, and submitting without one shows “Select at least one permission.”
3

Approve on Atlassian

Serval opens Atlassian’s authorization screen. Sign in and approve the requested permissions, making sure to select the site that matches the subdomain you entered. (If something unexpected goes wrong before the Atlassian screen opens, the modal shows a generic “Failed to initiate Jira OAuth” message.)
4

Done

Serval binds the connection to your site automatically. On reconnect, the Jira site field is pre-filled from your existing install and the picker pre-checks the permissions currently granted, so you only need to add what’s missing.

​
Install the Serval Forge app (required for ticket syncing)

Order matters: connect with Sign in with Jira first, then install the Forge app. The Forge app upgrades your existing Serval-managed OAuth connection with service-account capabilities - it is not a standalone way to connect, but ticket syncing won’t work without it. Connections made with your own Atlassian OAuth app are not upgraded by the Forge app; reconnect with Sign in with Jira if you need ticket syncing.
1

Turn on ticket syncing

In Serval, open the Jira app and turn on Ticket Syncing.
2

Install the app into your Jira site

Install the regional Forge app for your Serval deployment. EU customers on app.eu1.serval.com must use the EU app — the US app sends lifecycle webhooks to the US shard only.
Open the US Serval Forge app install page and install it into the same Jira site you connected.
3

Wait for it to take effect

The install can take up to five minutes to reflect in Serval. Refresh the Serval page to see the updated status. Installing once upgrades every Sign in with Jira connection to that Jira site across your Serval teams.
4

Configure ticket syncing

Select the Jira projects this integration can sync with. Project Management projects appear where PM project syncing is enabled. The project pickers label Service Management projects JSM and Project Management projects PM.In Project Routing, choose a default Jira project. For a JSM project, select its Request type. For a PM project, select its Issue type. Configure the Required fields for that destination using the existing default values and optional AI inference. Serval identifies the project kind from Jira. Changing the project or type reloads its field requirements. Subtask creation isn’t supported.To route some tickets elsewhere, select a Routing workflow, or use Build a routing workflow in Catalyst to describe your conditions. The workflow can choose another configured project and its request type or issue type, with any required field values. Serval creates and links the issue; the workflow doesn’t need to call Jira’s creation APIs. Choose Use default only when you don’t need conditional routing.Configure status and priority mappings for each selected project, then choose the sync strategy. Selected projects are used for incoming sync when enabled and are the allowed destinations for routing. Updates to an already linked issue continue to use that issue’s destination.

​
How ticket sync behaves

The sync direction applies to new tickets only.
  • Sync Out: tickets created in Serval are sent to Jira. Jira issues aren’t imported.
  • Sync In: Jira issues are imported into Serval. Tickets created in Serval aren’t automatically sent to Jira.
  • Two-way Sync: tickets created in Serval are sent to Jira, and Jira issues are imported into Serval.
Updates to synced tickets sync both ways under every direction: changes made in Serval appear on the Jira issue, and changes made in Jira appear on the Serval ticket (comments and attributes, per the Sync Scope toggles). For a one-time import of Jira history with no live connection, use the team’s CSV ticket import page instead of ticket syncing.
Assignees. When an AI-owned Jira issue — for example, a catalog-workflow request Serval created — escalates and syncs out, Serval assigns the issue to its own app account by default. On Jira sources that sync out on escalation, turn on Leave AI-owned tickets unassigned to leave those issues unassigned in Jira instead. Human assignments still sync out as normal, and enabling the setting never strips an assignee a person picked up in Jira. Change activity. When assignment, status, priority, or title changes sync from Jira Cloud, each activity names the person who made that change if Jira’s recent history matches the synced value and identifies an existing user on the Serval team. Otherwise, it keeps the default Serval attribution. Description changes keep the default attribution. A status attributed to a person is also treated as manually chosen by AI status inference. Older activity isn’t retroactively attributed to a person. Attachments. A file synced from Jira lands on the same Serval message as the comment it was attached to. A file added to an internal Jira comment therefore stays an internal note in Serval rather than surfacing as a public timeline message, so it isn’t echoed onto customer-visible or cross-channel threads. AI replies. With AI Auto-Response on, a customer-visible Jira comment starts an AI reply on an AI-active Serval ticket, as long as Serval can match its author to a user (the Jira account has an email address). Internal comments never do. A comment from someone other than the requester pauses the agent on that ticket; it can be brought back from the ticket in Serval.

​
Mirror your Jira workflow as a Request state machine

In the Jira ticket-source setup, the Request State Machine step can import your synced project’s Jira workflow (its statuses and transitions) into Serval’s native status transition rules for the Request ticket type. Map every Jira status first, then turn on Enforce status transitions to build the state machine from Jira. Once enforced, Requests move only between connected statuses, for both people and Serval AI, matching your Jira workflow. Use Rebuild from Jira to re-import after the Jira workflow changes, and edit the result anytime under Settings → Ticket types for the Request type. Turning enforcement off lets Requests move between any statuses again.

​
Verifying the connection

Serval runs three health checks against the connection: Test Jira Connection - validates basic connectivity and authentication by looking up the connected user.
  • Success: “Successfully authenticated with Jira as [name]” (shows “user” when no display name is available)
  • Failure: “Unable to authenticate with Jira. Please verify your API credentials and permissions are correct.”
List Jira Projects - validates that the credentials can list projects.
  • Success: “Successfully listed projects from Jira (sample size: [number])”
  • Failure: “Unable to list projects from Jira. Please verify your API credentials have permission to browse projects.”
Search Jira Issues - validates that the credentials can search issues, using a query for issues assigned to the connected user.
  • Success: “Successfully searched issues in Jira (found: [number])”
  • Failure: “Unable to search issues in Jira. Please verify your API credentials have permission to search and read issues.”
All three checks can pass while ticket syncing still does nothing - they only exercise the OAuth credentials. If sync isn’t working, verify the connection was made with Sign in with Jira, verify the Serval Forge app is installed in the Jira site, and allow up to five minutes after installing it.

​
Gotchas and troubleshooting

The connect modal offers exactly two methods: Sign in with Jira (OAuth) (Serval-managed, badged Recommended) and Use your own Atlassian OAuth app. The Serval Forge app install is a third step that upgrades an existing Sign in with Jira connection - it is required for ticket syncing and service-account features, it is not itself a way to connect, and it does not attach to bring-your-own app connections. (A legacy Jira Connect app path still exists for older installs only; it is deprecated and not offered to new connections.)
After OAuth consent, Serval looks up the subdomain you entered among the sites your Atlassian account authorized. If it isn’t there, the connection fails with: “target Jira site ‘[subdomain].atlassian.net’ not found in accessible resources. Please ensure you have access to this site and selected it during authorization”. If no subdomain was given and your account has multiple sites: “multiple Jira sites found ([number]). Please specify which site to connect by providing the subdomain”.
On reconnect, the modal jumps straight to the custom-app form and pre-fills Display name, Client ID, and Jira site - but the Secret is never pre-filled and there is no keep-existing-on-blank behavior. It is required client-side, and the backend rejects an empty value with “clientSecret is required”. Have the secret handy (or generate a new one in the Atlassian console) before reconnecting.
The Forge app’s credentials are delivered on install and then re-delivered every five minutes, so it may take up to 5 minutes for the installation to take effect. After installing, refresh the Serval page to see the updated status.
Serval requests offline access during authorization specifically so Atlassian returns a refresh token (access tokens expire after about an hour), and refreshes tokens automatically when fewer than 5 minutes of validity remain. If a stored connection somehow lacks a refresh token, calls start failing once the access token expires, with “custom Jira OAuth app access token expired and no refresh token available; reconnect required” - the fix is to reconnect. Also note the connect form’s authorization window is 10 minutes; after that you’ll see “Invalid or expired OAuth state”.
Even with the Forge app installed, Jira calls run as the user who connected the integration unless a workflow opts in: on a Sign in with Jira connection upgraded by the Forge app, sending the X-Use-Connect-Auth: true header switches to the Forge service account, and X-As-Jira-User additionally impersonates a specific Jira account. The opt-in header is harmless on connections without the Forge app, including bring-your-own app connections.
Permissions are baked into the OAuth consent and stored on the connection - Atlassian issues tokens only for the scopes granted when the connection was made. To add permissions (for example, enabling Projects & Administration after the fact), reconnect the integration - the picker pre-checks what’s already granted so you only add what’s missing. On a bring-your-own app, also make sure the new scope is granted on the Atlassian app under Permissions first. A workflow that calls an endpoint outside the granted scopes fails with a 401/403 from Atlassian until you reconnect with the scope selected.
Two sync-configuration reads are gated by Atlassian behind the manage:jira-configuration scope: per-project priority schemes (the priority-mapping picker falls back to the site-wide priority list without it, which can offer options a project’s scheme rejects on sync) and the project workflow graph (the Request State Machine’s import fails without it). These reads always run with the connection’s own token - they do not use the Forge app’s service account - so installing the Forge app does not stand in for the scope. When the connection’s granted scopes lack manage:jira-configuration, the Priority Mapping step shows a warning and the Request State Machine step blocks building or rebuilding (turning an existing state machine off stays possible); reconnect with the Projects & Administration preset selected to clear it.
The full OAuth scope set for bring-your-own apps is the 10 scopes shown under Get your credentials (9 Jira/JSM scopes plus offline_access). Serval requests the subset you select in the picker, but granting the full set on the Atlassian app keeps every selection available. The scopes read:form:jira and read:form.field:jira belong only to the Serval Forge app - do not add them to your OAuth app expecting them to be requested.
Self-hosted Jira Data Center uses the separate Jira Data Center integration and is not covered by this page.
Need help? Contact support@serval.com for assistance with your Jira integration.