Connect Jira
Connect your team's Jira Cloud projects with an API token. New issues reach the agent, and approved replies and findings go back as comments on the issue.
If your team keeps its work in Jira projects, connect them directly. Jira tells us when an issue is created or changes. We read each issue from Jira with your API token, and approved replies go back into Jira as comments.
This is for Jira's software and business projects, the team's own work. For a service desk with customers, connect Jira Service Management instead.
This works with Jira Cloud only: a site at an address like https://yourcompany.atlassian.net.
Jira has no private comments
Replies and the agent's findings are comments on the issue. Everyone who can see the issue sees them.
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 and findings as comments written by whoever owns the API token. With your own token, they look as if you wrote them. The user must be able to browse your chosen projects and add comments.
- 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.
- 3
Under Your Jira site, fill in the Site address, the account's Email and the API token. Click Connect Jira. Then click Check connection.
- 4
Under Which projects, tick the projects whose issues this platform takes. Choose 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. Create a test issue in one of your chosen projects. It shows under Tickets here within a minute, and our page says Last heard from Jira 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. |
| The Atlassian account the API token belongs to. | |
| 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 is connected. It asks Jira whose token it is. |
| 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 | 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 software and business projects, read from Jira. Tick the ones whose issues come to this platform. With none ticked, every project's issues 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 | Always a comment on the issue. There is nothing to choose. |
| Agent's findings in Jira | When on, a comment with what the agent found goes on the issue as soon as a reply is ready to approve. Everyone who can see the issue sees it. Off at first. |
Once connected, change anything here and click Save at the bottom.
What happens with an issue#
- A new issue in one of your chosen projects reaches the agent, with its files. The requester is the issue's reporter, as Jira records them. A person's privacy settings can hide their email address. The agent then works without it.
- A comment from the reporter reaches the agent as a follow-up, with any files they added. Comments from anyone else, and our own, are skipped.
- Moving it to a done status 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 issues that came from Jira go back to it. Other tickets on the same platform, from the log watcher for example, don't.
Stop#
Click Disconnect… at the top of the Connection tab, and confirm. New issues 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.