Set up your Jira integration

V12 4:24 Start+.svg

 

When setting up an integration between Productboard and Jira you may want to configure the integration to a single Jira project or multiple Jira projects. This article will discuss how to successfully configure the integration between Productboard and Jira. 

In this article:

Relevant to both new and legacy boards

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. When you aunthenticate with this user you will see issues that originated in Productboard (and not the specific admin user name 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.
      Group_f4112.svg

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

Note: Starter and Essentials plan customers have access to 1 Jira integration. Pro plan customers have access to 5 Jira integrations. Enterprise and Enterprise Plus plan customers have access to unlimited Jira integrations.

Every integration you add belongs to a Jira workspace. You can easily find the integration you want to configure by going to the Jira integration page of your Productboard workspace.

Screenshot_151_2__1__1_.svg

There are a few ways to authorize your Jira integration, depending on whether you have access to a Jira admin account and whether you’re using Jira Cloud or Jira Server. Using the OAuth pathway requires a Jira admin, and offers full functionality.

Using the API token or Personal Access Token (PAT) options won’t require a Jira admin, but your functionality will be limited. 

Limitations: When the token is generated by a user who is not a Jira admin, the integration will not be able to conduct auto-imports or 2-way syncing, and the issue status won’t update in the task column. To enable any of these functions, you’ll need to create webhooks manually. Learn more here.

When you add additional integrations to your workspace, the authorization flow will be different.

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 workspace name, and select Integrations (Integration.svg):

    navigating_to_integrations.jpg

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

    Screenshot_159.png

  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

    Screenshot_120_1.svg

  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.
      Note: Customers who set up the On-Prem (Server) integration, will see PAT and OAuth1. For more information, see Integrate with Jira self-managed.

      Screenshot_280.png

  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.): 

    Group_4116.svg

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

    Group_4117.svg

  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:

    Group_4119.svg

  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.

    Group_4123.svg

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

    Group_4124.svg

  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.

    Screenshot_130_1.svg

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

    2023-04-04_10-48-46.jpg

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 workspace name, and select Integrations (Integration.svg):

    navigating_to_integrations.jpg

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

    Screenshot_159__1_.png

  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

    Screenshot_120_1.svg

  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. 

      Screenshot_12.png

  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:
    Screenshot_13.png

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

[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 workspace name, and select Integrations (Integration.svg):

    navigating_to_integrations.jpg

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

    Screenshot_159.png

  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

    Screenshot_120_1.svg

  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. 

      Integration.png

  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.
    Screenshot_19.png

  6. Type a token label (E.g. Productboard):
    tokenlabel3.png

  7. You should see Productboard was authorized to access your workspace. Then, name your integration and click Create integration:
    Screenshot_21.png

Authorizing a second Jira integration (Pro+ Plans)

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 (Group_4115.svg):

    Screenshot_159.png

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

    Screenshot_135_1__2_.svg

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

    Screenshot_138_1__1_.svg

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

    Screenshot_139_1.svg

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.

Note: 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.

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.

Watch now!

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:

Was this article helpful?
1 out of 4 found this helpful

Articles in this section

See more
Our Support hours:
Monday to Friday from 9:00 am - 2:00 am CET. Monday to Friday from 0:00 am - 5:00 pm PST.
Productboard Academy
Become a Productboard expert with self-paced courses, quick tip videos, webinars and more.
Product Makers Community
Connect with product leaders, share and find product jobs, and learn how to approach similar challenges. Come join our Product Makers community.