Mapping fields between Jira and Productboard


V12 4:24 Start+.svg


Our Jira integration gives you maximum control and flexibility over how you sync data between Jira and Productboard. Map standard and custom fields in the configurations that best serve your team’s needs.

In this article:

Mapping fields between Jira and 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.

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.


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 Field Jira Field Notes
Feature name Issue Name  
Feature Description Issue Description In Jira, make sure to configure this field to be rich-text so we can support formatting. Learn more
Timeframe: Start Jira Issue Start Date  
Timeframe: End Jira Issue Due Date  
Jira "Task" status Issue status  
Feature status Issue status Learn more
Release Fix version  
Feature owner Reporter Reporter is only mapped if a user with a matching email address exists in Jira.
Effort Story points  
Custom field Story points Must be a custom number field, not a dropdown
Custom member field Custom single-user picker field The person authorizing the integration must have global permission to “Browse users and groups". Learn more
Custom Description field Custom field - Paragraph In Jira, make sure to configure this field to be rich-text so we can support formatting. Learn more
Feature Tags Jira Labels  
Team Custom Fields: Select List (Multiple choices), Group Picker (Multiple Groups) We are not supporting mapping of this field against a single select fields cause in Pb this field is Multi-select Member Field.


Using Markdown in a feature description

If your Productboard description field contains Markdown elements, those elements will be represented in your Jira issue description field (or custom field).

At the moment, the Productboard Editor supports the following:

  • Headings (H1 and H2)
  • Bold, italic, underline, and strikethrough
  • Code and code blocks
  • Quotes
  • Bullet and numerical lists
  • Links
  • Dividers

You can use additional, Jira-supported notation in your Productboard descriptions. The formatting won’t be visible in Productboard, but it will be visible when your description is synced to Jira.

2023-04-04 11.16.39.gif

Issue Types and Required Fields

The field mapping feature only works for Productboard and Jira integrations with one Project selected. The default minimum that needs to be mapped in the field mapper is the required fields. Those fields in Jira must 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.

Untitled (53) (1).png

Mapping Productboard’s Description fields to a custom field in Jira

If the Description field is a required field in Jira, we suggest mapping it as soon as possible to avoid any issues with the integration.
The default is to map the Jira Description to a Productboard Description. This works well if the descriptions between Productboard and Jira are identical.
However, if you want to separate the Go to Market teams’ description and the Engineering description, you can create a custom Description field in Productboard and map it instead.
The Productboard description can be mapped against a Jira multi-line or a text field. The same applies in reverse - Jira multi-line or a text field can be mapped against custom and built-in Pb description fields. We don’t recommend mapping this field against a Jira text field because it is a single-line field by default and has a character limit. Mapping the Productboard description against a single-line field is only suitable if your Productboard description is a short single-line sentence with no formatting.
To ensure full compatibility between the Productboard description and Jira multi-line field, we recommend mapping the Productboard description against a Jira Multiline Custom Field with the paragraph configuration in Jira.

Paragraph custom fields must be explicitly configured in Jira to display formatted text synced from Productboard. To set this up, navigate to Jira and set the field Renderers using Wiki Style Renderer, Learn more. Any formatting will be lost if a Productboard Description is mapped to a Jira Text field without this configuration.


Mapping Productboard’s Plain text custom field to a custom field in Jira

When mapping Productboard’s Plain text custom field to a custom field in Jira, text formatting synced from Jira Multiline Custom Field will be lost during the sync when syncing with a plain text field in ProductboardParagraph custom fields must be explicitly configured in Jira to display plain text synced from Productboard. Navigate to Jira and set the field Renderers using the Default text renderer, Learn more.


Pre-existing links will now update when there is a change in either platform.

If you have no pre-existing links, you will either need to conduct the one-time import or push individual features from Productboad to your Jira issues.

Syncing fields between Jira and Productboard

When synching fields between Jira and Productboard, you can set the sync as a one-time or two-way sync. The Jira two-way sync is used to automatically update your Productboard feature and your Jira issue when there is a change in either platform.

Note: Only an admin maker can enable the 2-way sync through in your Productboard space. (41) (1).gif

To enable two-way sync:

  1. Navigate to your workspace name and click Integrations (Integration.svg).
  2. Scroll down to open the specific Jira integration and scroll to the section Field mapping and syncing
  3. Click on the + Add Mapping button
  4. Select a Productboard field that you would like to map
  5. Select a Jira Field that you would like to map the Productboard field to
  6. Select the synchronization behavior:
    1. Select two-way sync if you want to keep the field synchronized at all times
    2. Select Set once, if you want the synchronization to apply ONLY during the Push, link, or import operations
  7. Go through steps 4 -7 as many times as you need to map all the fields that you and your team care about
  8. Click on the Save Field Mapping Button

Once you have selected the two-way sync button, nothing will happen initially. The two-way sync will only take place after an update to a field is made.

If you are using a single project, you can determine which issue types (e.g., Epics, Story) are impacted by the Field Mapper Configuration. This choice then shows the required fields from the selected issues in the Field Mapper.

jira picker (1).png


If I delete a feature in Productboard that's already linked to Jira will the 2-way sync delete the story in Jira?

No, the Productboard link in Jira will disappear but the data in Jira will remain.

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.

See also:

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



Article is closed for comments.

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.