Overview

Connecting a Jira Service Management (JSM) Cloud tenant to imper.ai lets imper.ai update the verification status, change a ticket's status, and open tickets in Jira.

The connection is set up once and involves creating a service account, issuing it a scoped API token, granting it access to the service project, and adding one automation rule that notifies imper.ai when a relevant ticket is opened.

To learn how agents trigger a verification and how results appear on the ticket once the integration is in place, see Securing Help Desk Flows with ITSM.

---

Prerequisites

Requirement	Details
Jira Service Management Cloud	Server and Data Center are not covered by this guide.
A service project	The queue that receives verification-relevant tickets.
Organization admin	Required to create a service account and its API token.
Project admin on the service project	Required for the role grant and the automation rule.

---

Setup

Step 1 - Create a service account

1. Go to admin.atlassian.com and select your organization.

2. Go to Directory > Service accounts > Create service account.

3. Name it - 6-30 alphanumeric characters, for example imperintegration.

4. Record the account's email and account ID.

WARNING

A service account's email address cannot be changed after the account is created.

Step 2 - Create a scoped API token

1. In Directory > Service accounts, select the account you created in Step 1, then select Create credentials > API token > Next.

2. Name the token and set an expiry. The permitted range is 1-365 days; one year is the maximum.

3. Select the following scopes:

Scope	Why it is needed
read:jira-work	Read tickets, fields, and available transitions.
write:jira-work	Move tickets between statuses and update fields.
read:jira-user	Resolve a person to their Jira account.
read:servicedesk-request	Read service desk requests and their request type.
write:servicedesk-request	Create requests and post comments.

4. Copy the token immediately. It cannot be retrieved again.

WARNING

Scopes cannot be changed after a token is created. Changing the scope list means issuing a new token.

Step 3 - Grant access to the service project

1. Give the service account product access to Jira Service Management.

2. In the service project, go to Project settings > People and add the service account to the Service Desk Team role.

That role grants Browse Projects, Create Issues, Edit Issues, Add Comments, Transition Issues, and Resolve Issues - everything imper.ai needs to read a ticket, comment on it, and resolve it.

Step 4 - Create the inbound automation rule

This rule tells Jira to notify imper.ai when a relevant ticket is opened.

4a. Create the rule

1. Go to Project settings > Automation > Create rule.

2. Trigger: Work item created.

3. New action: Send web request.

4b. Configure the request

Field	Value
Webhook URL	Provided by imper.ai.
HTTP method	POST
Header name	X-Automation-Webhook-Token
Header value	The shared secret provided by imper.ai.
Request body	Custom data

WARNING

Type the header name by hand rather than pasting it. A trailing space makes every request fail with 400 Bad Request: invalid header name, and Jira's audit log reports this only as a failed web request - which points you at the wrong end of the problem.

4c. Set the custom data

{
  "issue_key": "{{issue.key}}",
  "issue_id": "{{issue.id}}",
  "project_key": "{{issue.project.key}}",
  "summary": {{issue.summary.asJsonString}},
  "description": {{issue.description.asJsonString}},
  "status": "{{issue.status.name}}",
  "issue_type_id": "{{issue.issuetype.id}}",
  "request_type_id": "{{issue.customfield_10010.requestType.id}}",
  "reporter_account_id": "{{issue.reporter.accountId}}",
  "reporter_email": "{{issue.reporter.emailAddress}}",
  "assignee_email": "{{issue.assignee.emailAddress}}",
  "initiator_account_id": "{{initiator.accountId}}",
  "initiator_email": "{{initiator.emailAddress}}",
  "created": "{{issue.created}}"
}

WARNING

summary and description intentionally have no quotation marks around them. The .asJsonString suffix adds its own. Adding quotes breaks the rule the first time a ticket title contains an apostrophe.

4d. Turn the rule on

New rules are disabled until you enable them. Use the toggle at the top right of the rule editor.

---

Information you will provide to imper.ai

Three values:

Value	Where to find it
Site URL	Your Jira address, for example https://acme.atlassian.net.
Service account email	From Step 1.
API token	From Step 2.

---

Testing the configuration

Check	Expected result
Create a test ticket using one of the chosen request types.	The automation rule runs.
Open Project settings > Automation > the rule > Audit log.	The log shows a successful run, not an error.
Complete a verification against that ticket.	An internal comment appears on the ticket with the outcome.
Let a verification pass and its action complete.	The ticket moves to your configured resolved status.

---

Troubleshooting

Symptom	Possible cause	Solution
Audit log: 400 Bad Request: invalid header name	A trailing space or a colon in the header name.	Retype the header name by hand and remove any empty header rows.
Audit log shows no runs at all	The rule was never enabled.	Enable it with the toggle in the rule editor.
Audit log: the rule ran, but the body errors	Quotation marks were added around an .asJsonString value.	Remove the surrounding quotation marks.
imper.ai reports 401 Unauthorized	The token expired, or scopes are missing.	Issue a new token with the scopes listed in Step 2. Scopes cannot be edited after creation.
imper.ai reports 403 Forbidden on the site URL	Calls are being sent to https://<site>.atlassian.net.	Scoped tokens only work through Atlassian's API gateway, which imper.ai resolves from your site URL. Contact imper.ai support.
Tickets close, but reports show no resolution	A closing transition ran without setting a resolution.	Tell imper.ai which resolution to set. Jira does not enforce this and fails silently.
Nothing happens for some request types	That request type is not selected in imper.ai.	Select it on the imper.ai setup screen.

---

Ongoing maintenance

Task	When
Rotate the API token	Before it expires - one year at most. The integration stops working the moment the token expires.
Review the request-type list	Whenever you add a request type that needs verification. Renaming an existing one is safe.

WARNING

Token expiry is the most likely cause of a working integration suddenly stopping. Set a calendar reminder ahead of the expiry date.