Connect Jira Service Management

Connect a Jira Service Management cloud site with an API token. Requests from your service desks reach the agent, and approved replies go back to the customer or stay as internal notes.

In the appPlatformSettingsTicket system

If your customers raise requests in Jira Service Management, connect it directly. Jira tells us when a request comes in or changes. We read each request from Jira with your API token, and approved replies go back into Jira.

This works with Jira Cloud only: a site at an address like https://yourcompany.atlassian.net.

Before you start#

You need:

A Jira user of its own for the agent, such as Support Agent, with an email address of your team's. Jira shows our replies, notes and findings as written by whoever owns the API token. With your own token, they look as if you wrote them. The user needs access to your chosen service desks, and an agent licence to reply to customers.
A Jira admin for one step. Adding the webhook needs the Administer Jira permission.

Connect it#

1
At Atlassian, sign in as the agent's own user. Go to id.atlassian.com › Security › API tokens and choose Create API token. Don't choose Create API token with scopes: those tokens don't work here. Give it a name, choose an expiry date, and click Create. Copy the token. Show me how on our page shows these steps too.
2
Here, go to Settings › Ticket system. On the Connection tab, click Connect a ticket system and choose Jira Service Management.
3
Under Your Jira site, fill in the Site address, the account's Email and the API token. Click Connect Jira Service Management. Then click Check connection.
4
Under Which projects, tick the service desk projects whose requests this platform takes. Choose how Approved replies go back, and whether to add the Agent's findings in Jira. Click Save.
5
In Jira, as a Jira admin, go to Settings (the cog) › System. Under Advanced, choose WebHooks, then Create a WebHook. Fill in Jira's form as below.

Jira's webhook form, from the top#

Name: Cerberius Agents. Status: Enabled.
URL: the Webhook address from our page.
Secret: the Signing secret from our page. Don't use Generate secret.
Jira Software related events: leave them all unticked.
Issue related events: replace All issues with the JQL filter from our page. If our page shows no filter, leave All issues. Tick Issue: created and updated, and Comment: created. Leave the other columns unticked.
User, Jira configuration and Project related events: leave them unticked.
Leave Exclude body unticked, and ignore Transitions. Click Create.

Try it. Raise a test request in one of your chosen service desks. It shows under Tickets here within a minute, and our page says Last heard from Jira Service Management with the time.

That is all we need. A file added to an issue comes with the issue, or with the comment it was added with.

Setting	What it does
Site address	The address you open Jira at, for example `https://yourcompany.atlassian.net`. You can paste any page of your site: we keep the start of it.
Email	The Atlassian account the API token belongs to. It must be an agent on your service desks.
API token	The token you made at Atlassian. Once saved, it is never shown again. Type a new one to replace it. Atlassian tokens expire after a year at most. When yours does, Jira refuses it and Check connection says so: make a new one and paste it here.
Check connection	Shows once Jira Service Management is connected. It asks Jira whose token it is, and checks that Jira Service Management answers.
Webhook address	Shows once connected. Paste it into Jira, with Copy. Keep it private.
Signing secret	Shows once connected, to people who may change settings. Paste it into the webhook's Secret in Jira. Jira then signs every call, and we refuse calls without the signature. Make a new secret makes another one: the old one stops at once, so paste the new one into Jira straight away. A connection made before signing secrets has none: our page warns about it, with Make a secret.
Last heard from Jira Service Management	When Jira last called the webhook address. Never yet means Jira hasn't called: check the webhook's steps. If a call was refused, it says when and why, such as wrong signature.
JQL filter	Shows once you choose projects. Paste it into the webhook in Jira, so Jira only tells us about those projects. When you change the projects here, change it in Jira too.
Which projects	Shows once connected: your service desk projects, read from Jira. Tick the ones whose requests come to this platform. With none ticked, every service desk's requests come here, so choose them. A project that another of your platforms takes from the same site can't be ticked, and says which platform takes it.
Approved replies	Reply to the customer: a public comment on the request. Jira tells the customer, as for any reply from your team. Add it as an internal note: only your team sees it, and they send the reply themselves.
Agent's findings in Jira	When on, an internal note with what the agent found goes on the request as soon as a reply is ready to approve. Only your team sees it, never the customer. Off at first.

Once connected, change anything here and click Save at the bottom.

What happens with a request#

A new request in one of your chosen projects reaches the agent, with its files. The requester is the request's customer, as Jira records them. A customer's privacy settings can hide their email address. The agent then works without it.
A public comment from the customer reaches the agent as a follow-up, with any files they added. Your team's comments, internal notes and our own replies are skipped.
Resolving or closing it in Jira stops the work on it here. Any status in Jira's green Done category counts.
Closing it here moves it to a done status in Jira. We use the workflow's Resolved, Done or Closed step, and set its resolution to Done when Jira asks for one. If the workflow needs anything else filled in to close it, the ticket here says so. Close it in Jira instead.
Moving it to another project keeps the same ticket here, under its new key.

Only requests that came from Jira Service Management go back to it. Other tickets on the same platform, from the log watcher for example, don't.

One Jira site, a platform per service desk

A company with several service desks on one Jira site can give each its own platform. Connect each platform to the same site, and under Which projects tick that platform's service desks. Each platform has its own Webhook address and JQL filter: add each as its own webhook in Jira. Two platforms never take the same project.

Stop#

Click Disconnect… at the top of the Connection tab, and confirm. New requests stop coming in, and replies stop going back. The webhook address stops working at once.

Then, in Jira, go to Settings › System › WebHooks, and delete or disable the webhook. To stop the token too, revoke it at id.atlassian.com › Security › API tokens.