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
- 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.
Note: The mappable fields described here only apply to features and subfeatures. Initiatives work differently; see Push initiatives to Jira for details.
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.
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, 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 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, 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.
To enable two-way sync:
- Navigate to your workspace name and click Integrations (
).
- Scroll down to open the specific Jira integration and 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.
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.
Comments
Article is closed for comments.