Jira

What your agents can doCopy Anchor Link

Helios agents can use the Jira Cloud platform, Jira Software, Jira Service Management, Assets, Forms, and Jira Service Management operations and incident APIs, subject to the connection's permissions.

• Create issues from a bug report, an alert, or a Slack thread, with a type, labels, priority, and assignee
• Search with JQL and summarize the results, such as the issues in an open sprint
• Transition issues through your workflow, assign them, log work, and attach files
• Plan sprints: read boards and backlogs, move issues into a sprint, and start or close it
• Answer service desk requests, add participants, and handle approvals
• Find and update Assets objects with AQL, such as the laptop assigned to the person who opened a request
• Fill in and submit the forms on an issue or request
• Acknowledge and close alerts, check who is on call, and add responders to an incident
• Comment on issues and reply to comments

The integration works with Jira Cloud sites on atlassian.net. Jira Data Center is not supported. Atlassian serves Assets, Forms, and the operations and incident APIs from its API gateway at api.atlassian.com, and Helios sends each connection's calls to them there. The stakeholder communications API, which manages status pages and their subscribers, works only with Jira API Token. Atlassian documents it only for API tokens. Assets paths include your Assets workspace ID, which an agent gets from GET /rest/servicedeskapi/assets/workspace. Helios does not support Assets imports or the Jira Software DevOps APIs, such as development information, builds, deployments, feature flags, remote links, and security information. Those accept Connect and Forge apps, and some also accept OAuth 2.0 credentials that a site admin creates for on-premises tools, which Helios doesn't support.

AuthenticationCopy Anchor Link

Jira API Token can call the supported APIs, subject to the account's permissions, and can receive the trigger events listed below. Your own Jira OAuth app can call the APIs its scopes cover, and receives issue, comment, issue property, sprint, and version events only. See Integration authentication for how credentials are stored and injected.

Jira API TokenCopy Anchor Link

You need an Atlassian account that can use the Jira site. For triggers, the account also needs the Administer Jira global permission.

1. Sign in to Atlassian as the account Helios should act as, and open API tokens.
2. Select Create API token. Don't use Create API token with scopes. Scoped tokens only work through Atlassian's API gateway, and Helios calls your site's address.
3. Give the token a name and an expiration date, and copy it.
4. In Helios, choose Jira API Token. Enter the account's email address in Atlassian Account Email and the token in API Token.
5. Set Base URL to your site's address, such as https://your-site.atlassian.net. Use the atlassian.net address with no path.
6. Save.

The token has no scopes of its own. The agent can do what the account can do in Jira. For full access, give the account the Administer Jira global permission and the Administer Projects permission in the projects agents work in, and make it an agent in the service projects agents work in. Helios registers the webhook for triggers through Jira's admin webhook API, which needs Administer Jira. Without it, agents can still call APIs permitted by the account, but Helios cannot register triggers, and the trigger picker shows every event as unavailable.

An API token expires after at most 365 days. Before it expires, create a new one and enter it in Helios through Manage.

Your own Jira OAuth appCopy Anchor Link

You need an Atlassian account to sign in to the developer console. The person who approves access must be able to use the Jira site.

1. In the Atlassian developer console, select Create, then OAuth 2.0 integration, and give the app a name. If you're asked for a grant type, choose OAuth 2.0 (3LO).

2. Open Permissions. Select Add next to Jira API, then Configure.

3. On the Classic scopes tab, select Edit Scopes and turn on every classic scope in the first table below. On the Granular scopes tab, select Edit Scopes and turn on every granular scope in it. If you'll check Admin access in Helios, also turn on the scopes in the second table.

4. Open Authorization. Select Configure next to OAuth 2.0 (3LO), set Callback URL to this URL, and select Save changes:

   Copy Text

   https://api.heliosapp.com/integrations/jira/oauth_callback

5. Open Settings and copy the Client ID and Secret.

6. In Helios, choose Your own Jira OAuth app and enter them in Client ID and Client Secret. Check Admin access if you turned on the admin scopes.

7. If the app can reach more than one Jira site, set Base URL to the site to connect, such as https://your-site.atlassian.net. Helios reads it when Atlassian sends you back, so set it before you save.

8. Save. Atlassian asks you to choose the site and approve access.

Helios asks for every scope in the first table, and Atlassian expects an app to have each scope it asks for. Turn on all of them.

Admin access adds these scopes. The endpoints they cover need Jira, project, or board administrator permissions, or the object schema manager role in Assets.

You turn on 48 scopes in the developer console, or 63 with the admin scopes. Helios also asks for offline_access, which isn't counted. Atlassian recommends fewer than 50 scopes for each app. Helios asks for every scope its APIs need, so with the admin scopes the app has more. The developer console shows the count. The admin scopes are needed only when you check Admin access.

Jira records changes as the person who approved access, and the agent can do only what both the scopes and that person's Jira permissions allow. This method can't redact issue fields or read a user's email address regardless of their profile visibility. Those endpoints accept only an API token.

Helios renews the access token with the refresh token. Atlassian replaces the refresh token on each renewal, and a refresh token expires after 90 days without use. Helios renews it every day when it refreshes the webhooks for triggers. If it expires, open the connection and click Re-connect. After you rotate the app's secret, enter the new one through Manage. After that, or after you change the app's scopes or Admin access, click Re-connect.

A new app is private, so only you can approve access. To let other people approve it, open Distribution and turn on sharing.

TriggersCopy Anchor Link

Jira can start a Workflow when something happens in your site. Helios registers the webhooks when you save the connection, so there is nothing to set up in Jira. Deleting the connection removes them.

• Jira API Token: Helios registers an admin webhook named Helios, subscribed to every event below for every project. This needs the Administer Jira global permission.
• Your own Jira OAuth app: Helios registers Jira's webhooks for OAuth apps, which needs the manage:jira-webhook scope. Jira sends OAuth apps only the issue.*, issue_property.*, comment.*, sprint.*, and version.* events. The trigger picker shows the other events as unavailable on the connection. The webhooks cover the projects the approving person can see, and expire after 30 days. Helios refreshes them every day and adds projects created since the last refresh. Jira allows one webhook URL for each app and Atlassian account, so one OAuth app and account can receive events on one Helios connection only.

Every filter is optional. Patterns are case-sensitive.

• Project lists the projects the account can see. Choose one or more. Issue, issue property, and comment events match on the issue's project. Project events match on the project, and version events on the version's project.
• Issue type matches the type's name, such as Bug or Story. For issue_type.* events, it matches the name of the issue type that changed.
• Moved to status matches only updates that changed the issue's status, when the new status's name matches, such as In Progress or Done.
• Changed field matches an update when the name or ID of any changed field matches, such as assignee, priority, or customfield_10016.
• Property key matches the key of the issue property that was set or deleted.
• Link type matches the name of the link type, such as Blocks or Duplicate.
• Board lists the boards the account can see. Sprint events match on the board the sprint was created on.
• Setting matches the setting that changed: voting, watching, unassigned_issues, subtasks, issuelinks, timetracking, or timetracking_provider.
• Adding, editing, or deleting a comment does not start an issue.updated run. Use the comment.* events for comments.

Admin webhook deliveries are verified with the HMAC-SHA256 X-Hub-Signature header. OAuth app deliveries are verified with the JWT that Jira signs with the app's client secret. Deliveries more than two hours old are rejected. Jira retries a failed delivery up to five times, 5 to 15 minutes apart, and Helios ignores a delivery it has already received. After a URL fails for 30 minutes, Jira sends each event once, without retries, until a delivery succeeds.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Jira rejected the credential. Click Test Connection to check again.
• The webhook: for a Jira API Token connection, open Settings → System in Jira, then WebHooks under Advanced. A webhook named Helios should be listed. Only Jira admins can open this page.
• A trigger:
  1. Add issue.created to a workflow with no filters.
  2. Create a test issue in Jira.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Jira answers 429 Too Many Requests with a Retry-After header when a connection sends too many requests. See Atlassian's rate limiting docs.

An OAuth app can register at most 5 webhooks for each Atlassian account on a site, and Helios uses 4. See Webhooks for Jira's limits on OAuth app webhooks.