Set up a Jira connection

Who can use this feature?

• Organization administrators.
• Available for the Accelerate and Enterprise packages. Also, for the Essential package with the Integrations add-on.

Set up a Jira connection in the platform so your team can sync data from projects and tasks with a Jira project. With a Jira connection, you can push tasks into Jira and manage their progress there, all while seeing updates from within the platform. There’s no limit to the number of issue tracking connections you can have in your organization, so if you have multiple Jira instances or use multiple issue tracking tools, you can connect each of them to the platform.

Note: Your organization only needs to set up the connection once per instance. For example, if another workspace in your organization has already connected to a given Jira instance, you do not need to create another connection.

On this page:

• Requirements
• Create an issue tracking connection
  • Create a connection from the Issue tracking page
  • Create an issue tracking connection from the Project page
  • Set up a Jira Data Center connection with custom headers
• Connect your Jira instance via OAuth
• Jira connection statuses

Requirements

It's best to set up your Jira connection using a service account instead of an employee-specific account. This prevents interruptions to your Jira instance if that employee leaves the company. 

Required Jira permissions

The service account must have the following permissions:

• Global permissions:
  • Browse users and groups
• Project permissions for the projects you want to connect to the platform:
  • Browse projects
  • Create issues
  • Edit issues
  • Transition issues
  • Create attachments
  • Add comments
  • Delete all comments
• If issue-level security is configured, issue-level security permission to view the issue.

Additional requirements and notes

• Jira instance must support application links.
• URL for the Jira instance must be https.
• The platform may not be able to support all Jira calls for self-managed Jira Data Center (on-premise) Jira.

Create an issue tracking connection

The Jira user who creates the connection will be the default assignee for all tickets pushed to Jira. You can manually change the assignee once the ticket is in Jira. 

Note: You can create an issue tracking connection from the Issue tracking page or from the Project page.

Create a connection from the Issue tracking page

To create your issue tracking connection:

1. Navigate to the organizational level. 

2. Under Manage, select Tools & Integrations, and then select Issue tracking.   

3. Select Add connection.
   • If you can't find this button, you likely don’t have permissions to add a Jira connection to the platform. Ask a workspace administrator to change your user group or add the connection for you.
4. Choose Jira as the issue tracking application you want to connect and select Continue.
5. Select the authentication protocol, and then select Continue. Note the following guidelines:
   1. If you are using self-managed Jira Data Center (on-premise), version 8.22 or higher, select OAuth 2.0. You must enter the Client ID and Secret. They are mandatory. If your connection requires custom HTTP headers, you must enter header name and value
   2. If the version is below 8.22, continue using OAuth 1.0.
   3. If you are using Jira Cloud, ensure that OAuth 2.0 (default value) is selected. 

6. Follow the on-screen prompts. Confirm the workspace(s) you want to use this connection and select Continue.

   To add or remove workspaces after creating the connection, you must edit the connection.

Continue set up using OAuth 2.0 or OAuth 1.0.

Create an issue tracking connection from the Project page

To set up a new issue tracking connection: 

1. Go to Projects/tasks.
2. Find the project you want to open and select View project.  
3. Depending on whether issue tracking has been configured for this project:
   1. Select either Connect issue tracking or Edit issue tracking. 
   2. In the Connect to issue tracking software dialog, select set up a new one. 
   3. On the Add connection page, select Jira as the issue tracking application you want to connect, and then select Continue.
   4. Proceed to set up this connection.  After you have set up the new connection, the Project page is redisplayed.

Set up a Jira Data Center connection with custom headers 

Some Jira DC instances require service-token headers on every incoming request. You can  configure custom header name/value pairs when configuring the OAuth 2.0 connection for Jira Data Center. Header values will be stored securely and applied to all subsequent outbound Jira requests.

To set up a JIRA Data Center connection with custom headers:

1. Navigate to the organizational level. 

2. Under Manage, select Tools & Integrations, and then select Issue tracking.   

3. Select Add Connection.

4. Select Jira. 

5. Select the OAuth 2.0 authentication method. 

6. If required by your environment, enter custom header name and value pairs.

7. Finalize the OAuth 2.0 connection by entering the Client ID and Secret.

Connect your Jira instance via OAuth

Learn how to connect your Jira instance via OAuth. 

Connect via OAuth 2.0

To connect your Jira Cloud instance using OAuth 2.0:

1. Enter the Jira URL and select Authenticate. You'll be redirected to Atlassian.
2. Sign in to Jira as the administrative Jira user.
3. Review the permissions required by the Jira administrative user.
4. From the dropdown, choose the Jira instance you want to connect. 
5. Select Continue. You'll be redirected to the Level Access Platform. Your connection is complete.

To connect your instance of Jira Data Center version 8.22 and later using OAuth 2.0:

1. Enter the Jira URL and select Authenticate.  
2. Fill in the following fields:
   1.  Client ID: Paste the client ID from Jira. 
   2.  Client Secret: Paste the client secret from Jira. 
3. Sign in to Jira as the administrative Jira user.
4. Review the permissions required by the Jira administrative user.
5. From the dropdown, choose the Jira instance you want to connect. 
6. Select Continue. You'll be redirected to the Level Access Platform. Your connection is complete.

Connect via OAuth 1.0

Create an application link in Jira

In the Level Access Platform, you should be on Step 2: Create a connection.

To create an application link from Jira:

1. Open Jira in a separate tab.
2. Select Settings (the gear icon) in the top header.
3. Choose Products from the dropdown menu.
4. Select Application Links from the sidebar.
5. Choose Create link.

Complete configuration in Jira

To complete configuration in Jira: 

1. Select Direct application link.
2. Copy and paste the platform URL into the Jira Application URL field and select Continue.
3. A pop-up asking you to configure the application URL will open. Select Continue.
4. Copy and paste the application data from the platform into the Jira fields and select Continue.
   1. For Application Type, choose Generic Application.
   2. Select the checkbox to Create incoming link.
5. Copy and paste the consumer key, consumer name, and public key from the platform into the corresponding Jira fields and select Continue.

Authorize the connection in the Level Access Platform

To authorize the connection between Jira and the Level Access Platform using OAuth 1.0.:

1. In the Level Access Platform, select Continue.
2. Select the workspace you want to connect your Jira instance to.
3. Enter the server URL of your Jira instance. For example, jira.mycompany.com.
4. Select Generate URL.
5. Open the Authorization URL link and select Allow.
6. From the Access Approve page, copy the verification code.
7. Paste the verification code in the platform and select Verify.
8. Select Complete connection.

You can now Connect a Jira instance to a project

Jira connection statuses

This table describes the Jira connection statuses used on the platform. For additional resources, check out our article on troubleshooting Jira integration issues.