Configuring your Azure DevOps integration settings

After successfully setting up your Azure DevOps integration, you'll be directed to the integration settings page. On this page, you'll have the opportunity to specify how you want the integration to operate.

In this article:

• Mapping fields between Azure DevOps and Productboard
  • Issue Types and Required Fields
  • Syncing fields between Azure DevOps and Productboard
• Automatically update a Productboard Feature status based on an Azure DevOps status
• Mapping child items to parents
• Deactivating your Azure DevOps integration

Mapping fields between Azure DevOps and Productboard

While creating new features from Productboard in Azure DevOps (ADO) or linking with existing ADO items, the data you care about will be in sync. And it is possible thanks to the Field Mapper configuration.

You are able to map two fields between each other, define the synchronization type, and keep your data in sync. So, no more manual updates.

To set up the field mapper: 

1. Click on your workspace name and navigate to Integrations ()
2. Scroll down to open the specific ADO integration you would like to enable 2-way sync
3. Find the Field Mapper Section
4. Click on the + add mapping button
5. Select a Productboard field that you would like to map
6. Select the ADO field that you would like to map the Productboard field to
7. Select the synchronization behavior:
   1. Select 2-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 or Link operations
8. Go through steps #4 - #7 as many times as you need to map all the fields that you and your team care about
9. Click on the Save Field Mapping Button
10. Congratulations, you are set up! 
    

    Note: This will only apply to newly pushed or linked features.

Learn how to set up field mapping and syncing in this video:

Issue Types and Required Fields

When integrating Productboard with Azure DevOps, it's essential to ensure that your data is seamlessly synchronized between these two platforms. A crucial part of this integration is mapping Productboard fields to Azure DevOps issue fields.

Generally, Productboard fields are mapped to Azure DevOps issue fields according to your field mapper configuration. Here's a breakdown of how these fields are typically mapped:

Mapping the required fields in your integration setup is essential to ensure data flows accurately between different systems. You are able to remap them, but it is recommended to have them mapped to ensure the correct behavior of the integration. For more information on creating custom fields, see Add custom fields to your boards.

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.

Syncing fields between Azure DevOps and Productboard

Synchronizing fields between Azure DevOps (ADO) and Productboard is a powerful way to keep your project management and product development workflows aligned. Let’s explore the two syncing options available: one-time sync and two-way sync, and review how to enable a two-way sync for automatic updates.

Note: Only an admin maker can enable the synchronization options in your Productboard space under the integration settings.

One-Time Sync

A one-time sync is a straightforward way to transfer data between ADO and Productboard. With this sync option, data is moved from one system to another at a specific point in time (e.g. during Push or Link). This is useful for ensuring the data is consistent between the two platforms when needed. However, it doesn't provide real-time updates when changes occur in either system.

Two-Way Sync

A two-way sync is a more dynamic approach that allows for automatic updates between Productboard features and ADO issues. Here's how it works:

• When a change is made in ADO (e.g., assignee, dates, or description changes), it automatically updates the corresponding feature in Productboard.
• Conversely, if a change is made in Productboard (e.g., feature description or timeline), it synchronizes with the related ADO issue.

Automatically update a Productboard Feature status based on an Azure DevOps status

In today's fast-paced development environment, keeping your product management and development teams aligned and up-to-date is crucial for success. Automatically updating a Productboard Feature's status based on the status changes in Azure DevOps saves you time but also ensures that everyone is on the same page, fostering seamless collaboration.

A Maker Admin of your Productboard workspace can set this up by following the steps below:

1. In Productboard, click your account name in the top right to open your main menu. Then click on Integrations.
2. Scroll down to your Azure DevOps Integration and select the Azure DevOps Integration you want to set up the status sync for.
3. Scroll down to the section Status Sync Updates and click on the + Add status rule button.
   
4. On the left dropdown, select all the Azure DevOps statuses that, if changed in Azure DevOps will trigger a status change in Productboard.
   
5. On the right dropdown, select the Productboard status that will change in Productboard if the associated Azure DevOps work item is changed to any of the selected statuses on the left side. If you have not set up your Productboard statuses yet, see our article Customize status values for features.
   

6. Repeat the previous steps as many times as you need to automate the status sync.

   Note: You don't have to do this for all the statuses, only the ones you care about.

7. Click Save the delivery status tracking. From now on, if anybody changes a connected Azure DevOps issue status to the one you predefined, the status of the connected Productboard feature will be changed based on the rules you’ve set.
   

Error Handling

When automating the propagation of an Azure DevOps status to a Productboard feature status, from time to time, you might receive some errors. The steps below describe how to resolve these errors.

Status no longer exists in Azure DevOps

If the status is deleted on the Azure DevOps side but is mapped for this integration on Productboard, it will be highlighted and won’t be updated in Productboard.

To resolve the error:

1. Remove the highlighted status from the rule by clicking the X button in the status box.
2. Remap the status that corresponds to your current flow.
3. Save status rules.

Status no longer exists in Productboard

If the Productboard status is removed, the dropdown will be highlighted, and the rule won’t work until the status is remapped.

To resolve the error:

1. Click on the dropdown and select the status that corresponds to the Azure DevOps statuses mapped.
2. Save status rules.

Loading of states failure. All or partial fail

It may happen that statuses may fail to load, fully or partially. In this case, You can try to load them again.

To resolve the error:

• Click the Try Again button to load the statuses.

Rule not configured entirely

It won’t be possible to save the rule if any of the statuses is not selected. Both dropdowns will be highlighted, and the Save status rule button will be disabled.

To resolve the error:

• Select at least one Azure DevOps status and one Productboard status to save the rule.

Mapping child items to parents

If you want to keep track of the feature (mostly epic) to subfeature relationship (mostly features or other types of work items), you can add parent-child relations to work items.

To add parent-child relations to work items:

1. In Productboard, click your account name in the top right to open your main menu. Then click on Integrations:
   

   

2. Select the Azure DevOps integration you'd like to enable parent-child relations for:
   

   

3. Check Map child items to parents:
   

   
   You can also apply links backward by clicking the Apply backwards button. If you do so, the existing parent-children relationships will be updated.
   If you decide not to apply links backwards and only enable this option, you'll see the links for the newly pushed or linked items only.

After you enable this functionality, the work items or subfeatures you push will be linked with the already pushed Work Items.

If you push the child's sub-feature first and then the parent feature, the sub-feature will be linked to that parent.

Deactivating your Azure DevOps integration

If you no longer want to use the Azure DevOps integration, you can remove it on the Integrations page. Follow these steps:

1. In Productboard, click your account name in the top right to open your main menu. Then click on Integrations:
   

   
   
   

2. Click on Azure DevOps, and toggle the integration off:
   

   

3. Then select the integration name you wish to remove, and click on the trash bin icon ():

   

See also: 

• Integrate with Azure DevOps
• Using the Azure DevOps integration in Productboard
• Troubleshooting Azure DevOps
• Azure DevOps - FAQs