Set up your Jira integration

Essentials_and_up.svg

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.

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

gfgd.png

In this article:

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.)
      Group_f4112.svg
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.

Screenshot_151_2__1__1_.svg

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

    Group_4114.svg

  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.

      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:

    Screenshot_132.png

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

    Group_4114.svg

  2. Scroll to Jira, and click the plus button (gtj.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. 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
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 (cbbg.svg):

    Group_4114.svg

  2. Scroll to Jira, and click the plus button (gtj.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

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

    Screenshot_159-1.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

⚠️ 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).
Screenshot 2022-11-21 at 10.56.28 (1).png

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".

Screenshot 2022-11-21 at 10.58.11.png

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!

Screen_Shot_2021-01-28_at_8.08.00_PM.png

  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.

 

Project

Thinking about connecting multiple Jira projects to Productboard? See our Help Article here.

If you know you'll always be pushing features to the same Jira project, select it here and skip seeing a dialog screen every time you do.

Product Association

If you know you will never be pushing features from this Jira project into one of your Productboard products, you can unselect that product here.

Auto Import

If you leave this feature checked, you can create a trigger so that a certain action taken in Jira will automatically create a feature in Productboard. (Psst - need help writing a JQL query? Here's a handy cheat sheet.)

Auto-import can only create features in one area of your product hierarchy. If you wish to auto-import features into multiple parts of your product hierarchy, you can create multiple Jira integrations. (e.g. one Jira integration auto-imports into "Brickly Desktop", another Jira integration auto-imports into "Brickly Mobile", etc.)

Fix Version

Leaving the Sync Fix version box checked will sync your Productboard release group with your Jira fix versions.

 

Each Jira integration can only sync fix versions to one release group in Productboard. If your team works with multiple release groups, we recommend creating multiple Jira integrations (see below).

Status

Tell Productboard which color to use for each of your Jira statuses. 

Custom fields

Always map your Jira custom fields before importing your first issuesWe know you're excited to bring your backlog into Jira, but don't skip this step - otherwise custom field values won't sync until fields are manually updated.

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

 

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:

Your team uses multiple release groups.

One Jira integration syncs to one release group, meaning the releases contained within your Productboard release group will sync with your Jira versions. If, for example, one team releases on a sprint cadence while another team releases on a quarterly cadence, you could create multiple Jira integrations to sync your quarterly release group to your quarterly Jira fix version and your sprint release group to your sprint Jira fix version.

You want to auto-import Jira issues into multiple sections of your hierarchy.

One Jira integration auto-imports to one section of your hierarchy. If, for example, you wanted to import Jira issues with a "BUG FIX" status to one section of your hierarchy and other Jira issues with a "BACKLOG" status to another section of your hierarchy, you should create multiple integrations.

Your teams each have their own Jira project.

Don't step on one another's toes! Create multiple Jira integrations to correspond with multiple Jira projects. For more information, see Integrate with multiple Jira projects.

 

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

Jira-rename.gif

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:

2022-01-28_15.25.27.gif

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:

Re-authorization.png

  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:

2022-01-24_18.45.44.gif

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:

2022-01-24_18.50.00.gif

Deleting an authorization

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

  1. Click Manage close to the workspace URL:

    Screenshot_174.png

  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.

    Screenshot_171_1.svg

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:

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

Comments

0 comments

Article is closed for comments.

Articles in this section

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.