Skip to main content

​
About Jira Data Center

The Jira Data Center integration connects Serval to a Jira instance you host yourself. It’s a separate integration from Jira (Cloud): it talks directly to your own host and authenticates with an API token you provide instead of OAuth. Once connected, Serval can sync tickets two-way with Jira Service Management projects, and workflows and Catalyst can call your instance’s API on demand. The integration is marked Beta in the connect UI. If your Jira lives at yourcompany.atlassian.net, use the Jira (Cloud) integration instead. Authentication: API token. You supply your instance’s Base URL and a personal access token; Serval stores the token securely server-side and attaches it to every request on your behalf, so workflows never see the raw token. Basic auth (username plus password) isn’t supported. Ticket sync on Data Center doesn’t use the Serval Forge app. Data sync: Two-way ticket syncing with Jira Service Management projects runs in the background once sync settings are configured (Serval polls your instance; inbound webhooks aren’t used). Workflow actions run on demand.

​
Attribution and service account

Jira Data Center personal access tokens can’t act as another Jira user. Jira records the token owner as the actor for every write, transition, assignment, and comment. For ticket syncing, create a dedicated Jira service account with the display name Serval and generate the token from that account. Don’t connect an employee’s personal token, because Jira would present that employee as the actor for every change Serval syncs. Grant the service account Jira Service Management agent access and the Modify Reporter project permission. It also needs permission to browse the project, create and update requests, add comments, transition issues, and assign issues. For tickets created in Serval, Serval matches the creator’s email to a Jira username and sends raiseOnBehalfOf to set the request reporter. Jira still records the Serval service account as the actor. For human comments, Serval adds the person’s name and email to the comment body. Jira shows the service account on the comment. Serval-generated comments use the Serval service-account identity.

​
What the Jira Data Center integration enables

Anything defined in the Jira Data Center API can be accessed through Serval.

​
Get your credentials

Create the token while signed in as the dedicated Serval service account. There are two ways to get a token, depending on how your instance is set up.
On Jira 8.14 and later, use a built-in Jira personal access token. Atlassian’s guide is Using Personal Access Tokens.
1

Open your profile

In Jira, select your avatar at the top right of the screen, then select Profile.
2

Go to Personal access tokens

Select Personal access tokens in the left-hand menu.
3

Create the token

Select Create token and give it a name. You can optionally set an expiry - if you do, plan to rotate the token in Serval before it expires.
4

Copy the token

Copy the token immediately - Jira shows it only once.
Atlassian also documents personal access tokens in more depth in its developer guide.

​
Connect in Serval

1

Select Jira Data Center

In Serval, open your workspace’s integrations page and select Jira Data Center. The integration is marked Beta.
2

Enter the Base URL (required)

Enter your instance’s address, for example https://jira.example.com. The helper text reads: The base URL of your self-hosted Jira Data Center instance (e.g. https://jira.acme.com).Enter the host. Serval removes the https:// prefix and a trailing slash, and keeps a port (entering https://jira.example.com:8443/ stores jira.example.com:8443). Submitting the field empty is rejected with “Base URL is required”, and a value Serval cannot read as a host is rejected with “Base URL must be a valid Jira host, e.g. https://jira.example.com”. A value with a path after the host is rejected too, because Serval stores only the host: see Context-path deployments.
3

Enter the API Token (required)

Paste the token you created into the password field. The helper text directs you to create it from a dedicated Jira service account named Serval and explains that Jira attributes synced changes to that account. Native Jira personal access tokens are the first-party path on Jira 8.14 and later. Resolution app users can generate a token from the app’s token page.Serval rejects an empty value and displays API Token is required.
4

Submit and let the health check run

Submit the form. Serval saves the connection and automatically runs the connection health check.
When editing an existing connection, the Base URL field comes pre-filled with the stored host, and the API Token field shows a masked placeholder (bullet characters plus the last 4 characters of the stored token) behind a replace control. Leaving the token untouched or blank keeps the stored token, and leaving Base URL blank keeps the stored host - you only need to fill in the field you are rotating.

​
Configure ticket syncing

Ticket syncing on Jira Data Center is Beta. It is available to every workspace with the integration connected, and the Ticket Syncing tab is marked Beta in the app.
Ticket syncing is for Jira Service Management (JSM) service-desk projects. After the connection health check passes, open the Jira Data Center app in Serval and turn on Ticket Syncing. Then select the project, select the request type, set the priority mapping, set the status mapping, and choose the sync strategy. Serval polls your instance for new and updated issues. Data Center ticket sync doesn’t use inbound webhooks or the Serval Forge app. The connected service account needs the permissions listed in Attribution and service account, including Modify Reporter for reporter mapping. Priority mapping offers only the priorities in the selected project’s priority scheme, because Jira rejects any other priority when Serval writes an issue. Reading a project’s priority scheme is an administrator-level API on Data Center, so if the connected service account can’t read it, the priority mapping section shows an error and can’t be edited until the account is granted that access. Existing mappings keep syncing in the meantime. Ticket links By default, Serval builds links back to Jira issues from the host you connected. If people reach Jira at a different address (for example, through a reverse proxy or a vanity hostname), set an optional Browse URL in the Jira Data Center app settings, and Serval uses it for issue links instead of the connected host. Leaving it blank keeps the connected host.

​
Verifying the connection

The integration has one health check, Validate Jira Data Center API Connection. It runs automatically when you connect and again when you save credential changes, and you can re-run it any time from the integration’s settings page. It confirms that Serval can reach your instance at the stored Base URL and sign in with the stored token by looking up the account the token belongs to.
  • On success: “Successfully connected to Jira Data Center as [name].” - [name] is the account’s display name, or its username if no display name is set. If your instance returns neither, it shows “Successfully connected to Jira Data Center.” instead.
  • On failure: “Unable to connect to Jira Data Center. Please verify your base URL and API token are correct.”
If the health check passes but a workflow step fails, the token is usually the issue, not the connection. The health check only verifies sign-in - it does not check Jira permissions. Make sure the account the token belongs to has permission in Jira for the projects and actions your workflow touches.

​
Gotchas and troubleshooting

This integration is for self-hosted Jira Data Center. If your Jira lives at yourcompany.atlassian.net, use the Jira (Cloud) integration instead. The two aren’t interchangeable.
Serval always connects to your configured host over HTTPS, so the instance must serve TLS - one that only speaks plain HTTP will not work. Serval also blocks requests to hosts that resolve to internal or private IP addresses, so an instance reachable only on a private network cannot be connected and the health check will fail even with a valid token. Expose the instance on a publicly resolvable HTTPS address and allow inbound access from Serval before connecting.
Serval stores only the host portion of your Base URL, so Jira must be served at the root of its host. If you enter a Base URL with a path after the host (for example, https://apps.example.com/jira), Serval rejects it rather than saving a connection whose requests would go to the wrong address. Ports are fine: https://jira.example.com:8443 is stored as jira.example.com:8443.
Serval sends the token as a Bearer authorization header. Native Jira personal access tokens (Jira 8.14 and later) support this out of the box. Tokens from the Resolution “API Token Authentication” app accept it only from app version 1.7.0 onward - older app versions require basic authentication, which this integration does not support.
This version provides two-way ticket sync for Jira Service Management projects, typed API access for custom workflows and Catalyst, and the connection health check. It doesn’t include prebuilt workflows (such as create issue, transition issue, or list projects), catalog or entity ingestion, inbound webhooks, or the Serval Forge app. The integration is marked Beta in the connect UI.
Data Center exposes version 2 of the Jira REST API, while Cloud workflows are typically built against version 3, and issue search works differently on Data Center (a different search call with page-by-page offsets). Workflows written against the Cloud Jira integration will not run unmodified - rebuild them against this integration, or ask Catalyst to, and the correct Data Center endpoints will be used.
When editing the connection, the Base URL field comes pre-filled with the stored host, and the API Token field shows a masked bullets-plus-last-4 placeholder behind a replace control. Leaving the token untouched or blank keeps the stored token, and leaving Base URL blank keeps the stored host. Fill in only the field you are rotating.
Need help? Contact support@serval.com for assistance with your Jira Data Center integration.