Set up your Jira integration

Ready to unlock the power of our Jira integration and connect your product discovery and product delivery processes in one, seamless workflow? Let's do it!

In this article, you'll learn how to set up your Jira integration. To learn more about the Jira integration, what it can do, and how you can use it, see our article Integrate with Jira.

• Using Jira next-gen projects? See Integrating with Jira next-gen project.
• Using Jira Server (Jira self-managed/on-prem)? See Integrate with Jira self-managed.

Already configured your integration, but you're trying to solve a problem? See our article Troubleshooting Jira. 

In this article:

• Configuring your Jira integration
  • Checking your Jira permissions
  • Authorizing Jira integrations
    • Authorizing a Jira integration for the first time with OAuth
    • [JIRA Cloud] Authorizing a Jira integration for the first time with an API Token 
    • [JIRA Server and Data Center] Authorizing a Jira integration for the first time with a Personal Access Token (PAT)
    • Authorizing a second Jira integration
  • Adding a Productboard URL field
  • Mapping Jira fields to Productboard
  • Verifying Edit Issue & Create Issue screens
• Configuring Jira integration settings
• Default field mappings between features/issues
• Configuring multiple Jira integrations 
• Managing Jira integrations
  • Renaming a Jira integration
  • Reauthorizing a Jira integration
  • Disabling a Jira integration
  • Removing a Jira integration
  • Deleting an authorization

Configure your Jira integration

Checking your Jira permissions

When setting up an integration between Productboard and Jira, a specific user authorizes the integration - we'll call that user the Authorizer. Productboard is only allowed to do in Jira whatever the Authorizer is allowed to do in Jira - so it's important to choose the right Authorizer!

Note: In Jira, you will always see the admin user who authenticated the integration as the user who created the issue in the history tab. For that reason, we recommend creating an artificial “Productboard” user in Jira and authenticating with that artificial user, so that you see issues that originated in Productboard (and not the specific admin user who authenticated). The Feature owner can be different and will be displayed as “Reporter” in Jira. For more information, see Troubleshooting Jira.

1. When looking at the Jira project you wish to connect with Productboard, on the left side menu click Project settings.
2. On the left side menu, click Permissions.
3. Review the permissions for your project, and make sure that your Authorizer has the following permissions:
   • Browse projects (Why? So Productboard can ask users which Jira project to push a feature into.)
   • Create issues (Why? So Productboard can create Jira issues when a Productboard feature is pushed into Jira.)
   • Edit issues (Why? So Productboard can update fields during synchronization.)
   • Modify Reporter (Why? So Jira can accurately capture the user who owns the feature in Productboard. For more information, see here.)
     

Note: You do not need to grant your Authorizer Delete Issues permission. Productboard's integration will never delete an issue from Jira.

In other words, if Productboard needs the ability to do X in your Jira project, your Authorizer needs the ability to do X in your Jira project. For more information about how Jira's project permissions work, see Atlassian's documentation here.

Once your Authorizer has double-checked that they have the right Jira permissions, you're ready to set up your integration.

Authorizing JIRA integrations

You can add many Jira integrations to your Productboard workspace if your plan allows it.

Every integration you add belongs to a Jira workspace, so you can easily find the integration you want to configure.

Depending on whether you add the first integration to your workspace or the second, you'll go through a different authorization flow.
Also, the authorization flow will differ slightly depending on whether you're using JIRA Cloud or Server. When the authorization flow is different for the two JIRA versions, it's marked in the sections' titles below.
Below, you'll find the steps on adding a Jira integration for the first time and your options if you want to add a second integration.

Authorizing a Jira integration for the first time with OAuth

To add the first JIRA integration to your workspace follow these steps:

1. Click on the avatar, and select Integrations ():
   
   

   

2. Scroll to Jira, and click the plus button ():
   

   

3. The setup of your first integration starts here. To complete the setup you'll need to follow four steps. The first step is entering your Jira URL:
   

   https://JIRA_SPACE_NAME_HERE.atlassian.net

   
   
   

4. Choose an authentication type:
   
   • OAuth - Requires Jira admin access. Unlocks full functionality.
   • API Token Doesn't require Jira admin access. Limited functionality. If you choose this option follow this flow below.
     
     

     

5. Then, you need to Configure Jira for Productboard access. Make sure you're logged into Jira as an administrator. Then click the Open Jira button, which will take you to the Application Links page in your Jira instance (Alternately, open your Jira project, click the Settings gear icon > Products > Application Links on the left side menu.): 
   
   

   
   
   

6. On the Application Links page in Jira, paste the link of your Productboard workspace and click Create New Link:
   
   

   

7. Using the Copy icon to the right of each field, copy and paste the values above into the popup form in your Jira project, then click Continue:
   

   

8. Now copy the remaining details. Click the Copy icon to copy and paste the Consumer Key and Consumer Name into Jira. Click the Copy to clipboard button to copy the long Public Key. Paste these values into Jira, then click Continue.
   

   

9. Jira should display the following message: ✅ Application Link '[your URL here] created successfully.'
   

   

10. Back to Productboard. Click Done. You may see a popup window asking you to grant read and write access to your data. Click Allow.
    

    

11. To finish the setup, name your integration and click Create integration:
    

    

If you encounter any error messages during the authorization step, see our Troubleshooting Jira article.

[JIRA Cloud] Authorizing a Jira integration for the first time with an API Token 

If you use this option, you don't need a Jira admin to set up the integration for you. However, some functionality might not be available due to a lack of admin access.

To authorize JIRA with an API token, follow these steps:

1. Click on the avatar, and select Integrations ():
   
   

   
   
   

2. Scroll to Jira, and click the plus button ():
   
   

   

3. The setup of your first integration starts here. To complete the setup you'll need to follow four steps. The first step is entering your Jira URL:
   

   https://JIRA_SPACE_NAME_HERE.atlassian.net

   

4. Choose an authentication type:
   
   • OAuth - Requires Jira admin access. Unlocks full functionality. If you choose this option follow this flow above.
   • API Token (Personal Access Token for Jira Server & Data Center) - Doesn't require Jira admin access. Limited functionality. 
     
     

     
     
     

5. Create an API token so Productboard can access your Jira instance. Then, you need to Configure Jira for Productboard access.
   
   Click on the Open Jira button, which will take you to the API token / Personal Access Token page in your Jira instance:
   

   
   

    

6. On the API Tokens page in Jira click on Create API Token:
   
   
   
   
7. Type a token label (E.g. Productboard):
   
   
   
   
8.  Copy your API token and insert it in the API token field along with your Jira email/account:
   
   
   
   
9. You should see Productboard was authorized to access your workspace. Then, name your integration and click Create integration:
   
   
   

Limitations: Some features in the integration require JIRA admin access, but API tokens can be used by those without Jira admin access. Please note that the below features that require admin access won’t work if the token is generated by a user that is not a JIRA admin.

• Webhooks don't work. You can create webhooks manually. Learn more here.
• Auto-import
• The status won't update in the task column.
• 2-way sync

[JIRA Server and Data Center] Authorizing a Jira integration for the first time with a Personal Access Token (PAT)

If you use this option, you don't need a Jira admin to set up the integration for you. 

To authorize JIRA with a PAT token, follow these steps:

1. Click on the avatar, and select Integrations ():
   
   

   
   
   

2. Scroll to Jira, and click the plus button ():
   
   

   

3. The setup of your first integration starts here. To complete the setup you'll need to follow four steps. The first step is entering your Jira URL:
   

   YOUR_PROJECT_NAME_HERE.com

   

4. Choose an authentication type:
   
   • OAuth - Requires Jira admin access. Unlocks full functionality. If you choose this option follow this flow above.
   • Personal access token - Doesn't require Jira admin access. Limited functionality. 
     

     
     
     

5. Create a PAT token so Productboard can access your JIRA instance. Then, you need to Configure Jira for Productboard access.
   
   Click the Open Jira button, which will take you to the API / Personal Token page in your Jira instance.
   
   
   
   

6. Type a token label (E.g. Productboard):
   
   
   
   
7. You should see Productboard was authorized to access your workspace. Then, name your integration and click Create integration:
   
   
   
   

Limitations: Some features in the integration require JIRA admin access, but Personal Access Tokens can be used by those without Jira admin access. Please note that the below features that require admin access won’t work if the token is generated by a user that is not a JIRA admin.

• Webhooks don't work. You can create webhooks manually. Learn more here.
• Auto-import
• The status won't update in the task column.
• 2-way sync

Authorizing a second Jira integration

If you already have a Jira integration in your Productboard workspace, you can add another integration to an existing workspace or create a new one.

To add another integration:

1. On the Integrations, scroll down to Jira, then click the plus button ():
   

   

2. Choose if you want to connect the new integration to an existing workspace or create a new one:
   

   

3. Authorize the new integration using existing Authorizers or use a different Jira admin:
   

   

4. To finish the setup, name your integration and click Create integration:
   

   

⚠️ Wait! Don't keep scrolling! There are two important configuration steps to complete before you configure your integration settings or conduct your first import. We'll come back to this page, we promise.

Adding a Productboard URL field (Jira Next-Gen or Jira Team Managed Project) 

When you authorize the Jira integration, a new Productboard URL field is automatically created for you in Jira, to help you jump back and forth between Jira issues and Productboard features/subfeatures easily. We strongly recommend that you create this field before conducting your first Jira import.

1. In your Jira project, click Project Settings > Issue types > Choose your preferred Issue Type (Epic, Story, Bug, etc)
2. In the right-hand menu called Fields, under Create a Field, click the box called Short Text.
3. Under Enter Field name, type Productboard URL.
4. Click Save Changes.
5. Drag the Productboard URL under the Context Fields section
6. Repeat the same steps for any other Issue Type as needed
7. From the right-hand menu under Previously Created Fields, drag the section Productboard URL under the context fields section
8. Click Save Changes
9. Repeat the same steps for the other Issue Types – Story, Task, and Subtask, ensuring to click Save Changes for each one.

You'll now see a Productboard URL field displayed on issue screens.

Mapping Jira fields to Productboard

As soon as you set up the integration, map any fields in Jira that you'd like to remain synced with fields in Productboard.

Our field mapping applies to standard and custom fields like name, description, reporter, etc. You can also map a Jira story points field with the standard Productboard effort field or a custom field (must be a custom number field, not a dropdown).

Only fields of the same type can be mapped. For example, a checkbox field in Jira cannot be mapped to a dropdown field in Productboard.

To map the custom member field with the Jira custom single-user picker field, the person authorizing the integration must have global permission to “Browse users and groups".

Verifying Edit Issue & Create Issue screens

Jira fields must be visible on Create issue and Edit issue screens to sync data with Productboard.

1. In your Jira tab, select the Settings menu (gear icon) > Projects and search for your project.
2. Click ••• to the right of your project, select Project settings.
3. On the left side menu, select Screens.
4. Uncollapse the screen schemes and see which screens are associated with the Edit Issue and Create Issue operations.
5. Ensure the Productboard URL field and any relevant custom fields are associated with these screens.

Now that you've authorized your integration, added your Productboard URL, and mapped any custom fields, you're ready to enable your new Jira integration!

1. Return to your Settings > Integrations page.
2. Under Jira, locate your new integration. It will be nested under # Integration.
3. Slide the toggle to enable this integration, so you can add it to your Features board.
4. Want to configure your integration settings or import your Jira issue backlog into Productboard? Click the blue text of your integration.

Configuring Jira integration settings

Now that you've authorized your integration, added your Productboard URL, and mapped any custom fields, you're ready to dig in and configure your Jira integration in the way that works best for your team! Return to Settings > Jira and click on the name of your Jira integration.

Default field mappings between features/issues

When features/subfeatures are pushed into Jira, the fields are mapped to Jira issue fields based on your field mapper configuration. Productboard <> Jira fields are generally mapped to Jira issue fields in the following way:

Productboard | Jira

• Feature name | Issue name
• Feature name | Issue summary
• Feature description | Issue description.- In Jira, make sure to configure this field to be rich-text so we can support formatting. Learn more
• Feature Timeframe from | Jira Issue Start Date
• Feature Timeframe to | Jira Issue Due Date
• Jira "Task" status | Issue status
• Release | Fix version
• Feature owner | Reporter 
• Feature Tags | Jira Labels

Reporter is only mapped if a user with a matching email address exists in Jira.

Required Fields

The default minimum that needs to be mapped in the field mapper is the required fields. Those fields in Jira need to be filled for the issue to be created.

Please follow the steps shown in the banner underneath the field mapper section. 

Note: The “Missing required fields” banner will only pop up if there are required fields that: 

1. Are part of the supported data type.
2. Have not been mapped yet.

Configuring multiple Jira integrations 

You may wish to create multiple integrations between Jira and Productboard, whether you're linking multiple Jira projects to Productboard, or whether you're linking the same Jira project to Productboard multiple times. Here are three common circumstances when teams may decide to configure multiple Jira integrations:

Note: For multiple Jira integrations, you do not need to set up another application link if connecting to the same Jira instance. Just click "Authorize" at the bottom of the integration set up page.

Managing Jira integrations

Renaming a Jira integration

You may wish to rename a Productboard <> Jira integration, especially if your team is using multiple Jira integrations (see section above). 

Changing the Jira integration name in the Settings page will change the integration's name in the task column. Note: this will not apply if the integration has already been manually renamed in the task column view.

Reauthorizing a Jira integration

If the user who authorized the integration is no longer working at your company or if they changed their credentials, you can reauthorize the integrations.

To re-authorize, follow these steps:

1. Click Manage close to the Jira workspace.
2. Choose which group you want to re-authorize, then click Re-authorize.
3. Then, you need to choose which user you'd like to re-authorize as:

Note: To re-authorize a Jira integration, a user must be a Productboard admin with Global Permissions in the relevant Jira project.

Need to swap out the Jira administrator associated with a Jira integration?

In Integrations > Jira> [Your Jira integration], scroll down to the Authorize section. You should see a confirmation message displayed, along with the name of the Jira administrator who originally authorized the integration:

1. Click Re-authorize integration. 
2. You may be presented with a pop-up permissions window. Select Allow.

Disabling a Jira integration

You can disable a Jira integration at any time by toggling off the integration. To reactivate it simply toggle the integration back on:

Removing a Jira integration

If you want to remove a Jira integration:

1. Click on the name of the integration
2. Then, click Remove.
3. Confirm the removal by clicking Delete:

Deleting an authorization

If you want to delete existing authorizations, follow these steps:

1. Click Manage close to the workspace URL:
   

   

2. Choose the authorization you want to delete, and click Remove this authorization:
   

   Note: Should the owner of your Integrations change, contact us to reset your integration permissions.

   

school Productboard Academy Webinar

Learn best practices for setting up your Jira integration in our on-demand webinar. A member of Team Productboard will explain key concepts, share tips, and answer all your questions so you feel prepared to hit the ground running.

👉 Save your seat 👈

Note: Webinars are available for trial users and paid customers only.

school Productboard Academy Course

Take a look at our quick tip academy course on safely activating the JIRA Integration. You can safely turn it on and configure it however you like before information starts flowing back and forth. Here's a video walkthrough if you don't believe us.

👉watch now 👈

See also:

• Integrate with Jira
• Troubleshooting the Jira integration