Connect Atlassian (Jira and Confluence)

Create an Atlassian OAuth 2.0 (3LO) app, add the Jira, Confluence and User identity permissions, and add it to Workforce Intelligence as a connection.

For: Administrators (the admin ability) · Last updated

This page walks through connecting Atlassian Cloud end to end. Workforce Intelligence (WI) uses an OAuth 2.0 (3LO) app you create in the Atlassian developer console, so people sign in with Atlassian and WI acts with their access. The general connection form, the Allow, Ask and Block defaults and who may use a connection are covered in Connecting outside systems; this page covers what is specific to Atlassian.

You need the admin ability in WI and an Atlassian account that can create developer apps. Pick Atlassian in the catalog to offer both Jira and Confluence. Pick Jira if you want Jira only.

Create the app#

  1. Open the Atlassian developer console (from developer.atlassian.com, use your profile icon and choose Developer console), select Create, then OAuth 2.0 integration.
  2. Enter a name people will recognize.
  3. In WI, open Settings, select Review on the Connectors card, then Add a connection, and pick Atlassian. The form shows Redirect URI to register.
  4. In the console, open Authorization, select Configure next to OAuth 2.0 (3LO), paste that redirect URI as the Callback URL and select Save changes.

Add permissions#

In the console open Permissions. For each API, select Add, then Configure to choose its scopes. People who connected before you added scopes must connect again to receive them.

API Scopes to add What they unlock
User identity API read:me Shows "Connected as" with the person's name. Without it the sign-in is refused.
Jira API read:jira-work, read:jira-user; write:jira-work for changes Searching, reading issues, projects and people; creating and editing issues, comments, status, assignment and time logs
Jira API (Jira Software boards and sprints) read:board-scope:jira-software, read:project:jira; read:sprint:jira-software; for a sprint's issues also read:issue-details:jira and read:jql:jira Listing boards, sprints and their issues. Jira Software uses granular scopes only.
Confluence API search:confluence, read:page:confluence, read:space:confluence, read:comment:confluence, read:attachment:confluence Search; reading pages, spaces, comments and attachment lists
Confluence API (changes) write:page:confluence, write:comment:confluence, write:confluence-content Creating and updating pages, commenting, adding labels

WI also uses offline_access to keep a connection active without signing in again; it goes in the scope list on the WI form. Add only the scopes you need.

Copy the client ID and secret#

Open Settings in the console and copy the Client ID and the Secret.

Share the app#

An app can be used only by its owner until it is shared. To let other people connect, open Distribution in the console, edit the details it asks for and turn on sharing under Enable sharing. Atlassian describes the distribution settings in its OAuth 2.0 (3LO) documentation.

Add the connection in WI#

  1. On the form, enter a Display name, the Client id and the Client secret. The Authorize URL already carries the settings Atlassian needs.
  2. In the Permissions checklist, tick the same scopes you added in the console. New connections start with Read Jira work, Read Jira people, Search Confluence and the read-only Confluence permissions, plus See which Atlassian account is connected and Stay signed in. The checklist also offers the Jira Software board and sprint permissions.
  3. Select Add connection, then Connect and sign in with your own Atlassian account.

Attach Jira and Confluence#

On the Atlassian connection, Jira and Confluence are separate services, each with its own Attach tools button and functions. Attach the one or both you need, tick the functions to turn on and choose Allow, Ask or Block for each. Functions the permissions do not cover stay greyed under Needs more permissions and name what is missing. Coworkers write Jira descriptions and comments and Confluence pages as plain text; WI converts them.

How the site is found#

Atlassian tokens work on api.atlassian.com, not on your <name>.atlassian.net address, so WI first asks Atlassian which sites the person can reach. It uses that site automatically the first time and keeps it. This works for an account that reaches exactly one site. When an account reaches several sites, the call is refused with a message that an administrator must choose the site, and nothing runs.

People connect their own accounts#

A Supervisor turns the connection on for each Coworker that should use it. Each person then connects their own Atlassian account under Connected accounts (in Settings > My API keys). A Coworker acts with the access of the person it is working for.

Troubleshooting#

What you see What it means and what to do
Atlassian refuses the sign-in Check that the Callback URL matches the redirect URI shown on the WI form exactly, and that the User identity API with read:me is added.
Confluence calls fail with 401 for people who connected earlier They connected before you added the Confluence scopes. Add the scopes in the console and in WI, then ask them to connect again.
Jira Software boards or sprints are greyed or fail Add the granular scopes read:board-scope:jira-software, read:project:jira and read:sprint:jira-software, plus read:issue-details:jira and read:jql:jira for a sprint's issues, then connect again.
Someone else cannot connect The app is not shared. Turn on sharing under Distribution.
A person sees "Needs new access — connect again" under Settings You changed the connection's permissions after they connected. They select Connect again.
The call says an administrator must choose the site The account reaches more than one Atlassian site.