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
- Issue Types and Required Fields
- Mapping Productboard’s Description fields to a custom field in Jira
- Mapping Productboard’s Plain text custom field to a custom field in Jira
- Syncing fields between Jira and Productboard
- Mapping Jira-managed fields to Productboard fields
- FAQs
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:
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. For example:
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:
- Are part of the supported data type.
- Have not been mapped yet.
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. Any formatting will be lost if a Productboard Description is mapped to a Jira Text field without this configuration.
Mapping Productboard’s plaintext 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 Productboard. Paragraph 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.
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 Productboard to your Jira issues.
Syncing fields between Jira and Productboard
When synchronizing 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.
To enable two-way sync:
- Click Workspace menu (top left corner) > Settings > Integrations.
- Click Jira, then select the relevant Jira integration to open its configuration menu.
- Scroll to the section Field mapping and syncing.
- Click on the + Add Mapping button.
- Select a Productboard field that you would like to map.
- Select a Jira Field that you would like to map the Productboard field to
- Select the synchronization behavior:
- Select two-way sync if you want to keep the field synchronized at all times
- Select Set once, if you want the synchronization to apply ONLY during the Push, link, or import operations
- Go through steps 4 -7 as many times as you need to map all the fields that you and your team care about.
- 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.
Mapping Jira-managed fields to Productboard fields
Certain Jira fields can be mapped to Productboard as managed fields. The values in a managed field are read-only in Productboard, and can only be edited in Jira. However, the value assignments of those fields are still synced in both directions.
This prevents accidental or unauthorized changes in Productboard from affecting your Jira data.
When you access a Jira-managed field in Productboard, you'll see a Configured by Jira badge in the sidebar to remind you.
Example: You have a radio button field in Jira called 'Colors'. The values for this field are 'Red' and 'Green'. You map 'Colors' to a single-select field in Productboard as a managed field.
If you assigned the value 'Red' to a feature in Productboard, its matching epic in Jira would also be assigned the 'Red' value. If you then changed 'Red' to 'Green' in Jira, the corresponding Productboard feature's color would change as well.
But if you wanted to add 'Blue' as a value to the 'Colors' field, you could not do so from Productboard. You would have to do it in Jira, because 'Colors' is a Jira-managed field.
Eligible managed field types
Generally, Single-value Jira fields map to single-select Productboard fields, and Multi-value Jira fields map to Multi-select Productboard fields.
Here is a list of the eight field types that can be Jira-managed and what they map to in Productboard:
Notes on managed field behaviors
Here are some managed-field-specific behaviors to keep in mind:
- If you have multiple Jira integrations set up, and you have a Productboard custom field set to 'managed' in one integration, you can't use that field in the other integrations.
- Mapping Jira fields to a managed multi-select field will overwrite any pre-existing values in that field in Productboard. You will be warned of this before saving the new mapping.
- If you unset the mapping of any managed field, the Productboard field will become editable again, but it will retain the previously-assigned value in case you decide to reset the mapping.
- When mapping components: since you are syncing the components from one specific Jira project, you cannot change the Jira integration's target project from Productboard without first unsetting the component map.
FAQs
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.
Note: Webinars are available for trial users and paid customers only.