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:
- Configure your Jira integration
- Configure Jira integration settings
- Default field mappings between features/issues
- Configuring multiple Jira integrations
- Rename a Jira integration
- Reauthorize a Jira integration
- Deactivating the Jira integration
Configure your Jira integration
Double-check 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!
- The Authorizer should be a Jira Administrator.
- When looking at the Jira project you wish to connect with Productboard, on the left side menu click Project settings.
- On the left side menu, click Permissions.
- 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!
Authorize the integration
- In your Productboard account, click the bottom left icon to open the main menu.
- Select Integrations.
- Scroll down to Bring features to life > Jira.
- Click the [+] symbol to the right.
- In another tab, open up your Jira project. Copy the URL for your Jira server (see below for example) and hit Continue.
https://YOUR_PROJECT_NAME_HERE.atlassian.net
You will now see a section titled "1. Log Into Jira as an Administrator". Click the Open Jira button to be taken directly to the Application Links section of your Jira project. (Alternately, open your Jira project, click the Settings gear icon > Products > Application Links on the left side menu.)
- Click the Copy icon to copy the URL of your Productboard space. You'll be doing a bunch of copy-pasting in the next few moments, so make sure you use this handy shortcut!
- In your Jira tab, paste your Productboard space URL into the field.
- Click Create new link.
- Let the copy-pasting begin! Using the Copy icon to the right of each field, copy and paste the values above into the popup form in your Jira project.
- Check the box next to Create incoming link.
- Click Continue.
- That's right - there's a bit more copy-pasting left! 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.
- Jira should display the following message: ✅ Application Link '[your URL here] created successfully.'
- Return to your Productboard tab and click Authorize.
- You may see a popup window asking you to grant read and write access to your data. Click Allow.
If you encounter any error messages during the authorization step, see our Troubleshooting Jira article.
⚠️ 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.
Add a Productboard URL field
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.
- In your Jira tab, go to Settings (gear icon) > Issues.
- On the left menu, select Fields > Custom fields.
- Search for the Productboard URL field.
- Click ••• to the right of the field and click Associate to Screens.
- Select the checkboxes for the screens used for your Edit Issue and Create Issue Jira operations. (These are typically named Default screen, but may also be named Scrum Default Issue Screen or Kanban Default Issue screen.) Only select boxes for projects you know you will be syncing with Productboard.
- Click Update.
You'll now see a Productboard URL field displayed on issue screens.
Map custom Jira fields to Productboard
As soon as you set up the integration, map any custom fields in Jira that you'd like to remain synced with custom fields in Productboard.
- Custom field mapping does not apply to standard fields like name, description, status, fix version, reporter, etc. These are automatically synced with standard fields in Productboard (see section below).
- 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 dropdown).
- Note that only custom 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".
Verify Edit Issue & Create Issue screens
Jira fields must be visible on Create issue and Edit issue screens to sync data with Productboard.
- In your Jira tab, select the Settings menu (gear icon) > Projects and search for your project.
- Click ••• to the right of your project, select Project settings.
- On the left side menu, select Screens.
- Uncollapse the screen schemes and see which screens are associated with the Edit Issue and Create Issue operations.
- 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!
- Return to your Settings > Integrations page.
- Under Jira, locate your new integration. It will be nested under # Integration.
- Slide the toggle to enable this integration, so you can add it to your Features board.
- Want to configure your integration settings or import your Jira issue backlog into Productboard? Click the blue text of your integration.
Configure 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.
| Server URL | Your Jira server URL (you probably won't change this) |
| 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. |
| 2-Way Sync |
If you leave this feature checked, Productboard and Jira will automatically sync feature name, description, release/fix version, and custom fields. If you leave this feature unchecked, Productboard and Jira will still continue to sync the feature's status. |
| 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.
Most teams will also check Automatically import any new Jira fix versions as Productboard releases.
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 issues. We 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, their fields are mapped to Jira issue fields in the following way:
Productboard | Jira
- Feature name | Issue name
- Feature name | Issue summary
- Feature description | Issue description
- Jira "Task" status | Issue status
- Release | Fix version
- Feature owner | Reporter
Reporter is only mapped if a user with a matching email address exists in Jira.
Assignee is left blank so it can be filled out in Jira.
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.
Rename 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.
Reauthorize a Jira integration
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:
- Click Re-authorize integration.
- You may be presented with a pop-up permissions window. Select Allow.
Deactivating the Jira integration
You can deactivate the Jira integration at any time by selecting Remove on the Integrations page.
Note: Should the owner of your Integrations change, contact us to reset your integration permissions.
Watch an on-demand webinar!
Learn best practices for setting up your Jira integration. 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.