The Azure DevOps integration bridges the gap between product discovery and product delivery by empowering product managers and developers to work together.
Product managers and developers focus on two different areas: product discovery and product development. Product managers find and prioritize the right problems, and developers build the right solutions to those problems. But, developers use different tools from product managers, so they often need to switch between them, resulting in siloed information.
This is where the Azure DevOps integration comes into play. The integration shows critical information in both systems so the product and development team work harmoniously. The product managers can push features as a new work item or link them to an existing work item in Azure DevOps. This way, developers know what to build next and why.
In this article:
- Installation requirements
- Installing and configuring your Azure DevOps integration
- Using the Azure DevOps integration in Productboard
- Pushing a feature or subfeature from Productboard into Azure DevOps
- Linking a feature or subfeature to an existing Azure DevOps work item
- Unlinking a feature or subfeature from an Azure DevOps Work item
- Understanding how fields map across Productboard and Azure DevOps
- Filtering features or subfeatures by Azure DevOps status
- Using two-way sync to update fields automatically across tools
- Mapping child items to parents
- Deactivating your Azure DevOps integration
- Automatically update a Productboard Feature status based on an Azure DevOps status
Installation requirements
To install the integration, you must be a maker with admin access in Productboard and a build administrator role in Azure DevOps.
Not sure which Azure product your organization has? See Microsoft's documentation here.
If you are using Azure DevOps Server (on-premise), you'll need to:
- Run Azure DevOps Server, version 2018 (Team Foundation Server 2018) or higher. For more information, contact support@productboard.com.
- Whitelist the following static IP addresses on your firewall with port 443:
100.25.97.8135.174.223.6652.6.23.216
Note: If you run into an error, double check with your network administrator that Productboard has access to your Azure DevOps network.
Your Azure DevOps on-premise setup needs to be in a public network with a public IP address. The IP address can be inaccessible from the internet in general, but it must be available to Productboard.
Installing and configuring your Azure DevOps Integration
- In Productboard, click the avatar on the bottom right. Then click on Integrations:
- Next to Azure DevOps, click [+] to add a new integration:
- Name the integration. You can change this at any time, and add your Azure DevOps Server URL (i.e. https://dev.azure.com/zlack). This is a great way to distinguish multiple integrations.
Then, click on the Create integration button.
Note: If you're using a legacy version of Azure DevOps, your URL may have a different format: http://youraccount.visualstudio.com instead.
- Click the Open Azure DevOps button to go to the Personal Tokens page of your Azure DevOps admin account.
Note: The user who is configuring the integration has to be a member of Project Collection Service Accounts in Azure DevOps.
If you need to go back to the Personal Tokens page, in Azure DevOps click on User Settings > Personal access tokens.
- In Azure DevOps click on + New Token:
- Click Give your token a name (i.e. Zlack DevOps Account), and make sure you select the same Organization you used in Productboard. For instance, if you entered https:// zlack.azure.com/, the Organization value is zlack.
- Under Expiration (UTC), select Custom defined from the drop-down menu. Using the calendar drop-down, select the furthest possible date from today.
- Then authorize the scope access of the token you created. You need to add permissions for the following scopes for the integration: Notifications and Work Items.
For both, select the Read and Write authorization. Then, click Create.
- Copy your unique token. You won't be able to do this again in the future, so don't forget!
- Go back to the Productboard Integrations page. Paste your unique token and click Authorize integration.
- If the token authorization is successful, you'll see a Valid check (
) letting you know that you finished the integration setup.
Finally, you can associate this integration with the relevant products in your account (this is an Enterprise-only feature).
Using the Azure DevOps integration in Productboard
Once you configure the integration, you can collaborate with your developers. The following sections will cover:
- Pushing a feature or subfeature from Productboard into Azure DevOps
- Linking a feature or subfeature to an existing Azure DevOps work item
- Unlinking a feature or subfeature from an Azure DevOps Work item
- Understanding how fields map across Productboard and Azure DevOps
- Filtering by Azure DevOps status
- Using two-way sync to update fields automatically across tools
- Deactivating your Azure DevOps integration
Pushing a feature or subfeature from Productboard into Azure DevOps
There are two ways to push a feature from Productboard into Azure DevOps:
Note: You can push a Productboard feature or subfeature to Azure DevOps as any type of work item (including user story, bug, task, etc). You can change the work item type in Azure DevOps at any time.
Pushing features from the list view your Features board
- On the Features board, click the Tasks icon (
), and find your Azure DevOps integration. Toggle on the integration to display it in the list view of your Features board.
- Then click on the integration name and select the Products you want to use (this is an Enterprise-only feature).
- On the list view of your Features board, you'll see a column for the Azure DevOps integration.
- Click on the Azure DevOps logo to push features or subfeatures into Azure DevOps.
- Then, associate the feature or subfeature with an Azure DevOps project and Work item type.
- (Optional) - Choose the Azure DevOps Area Path you'd like to push the feature or subfeature to. You'll see this option when you have more than one area for the chosen project.
- Push the feature to Azure DevOps.
Pushing features from feature or subfeature detail view
You can also push features or subfeatures from the detail view. To do this follow the steps below:
- Click on a feature or subfeature.
- Click on the Azure DevOps logo to push features or subfeatures into Azure DevOps.
- Associate the feature or subfeature with an Azure DevOps project and Work item type.
- (Optional) - Choose the Azure DevOps Area Path you'd like to push the feature or subfeature to. You'll see this option when you have more than one area for the chosen project.
- Click Push to push the feature to Azure DevOps. In the detail view of the feature or subfeature:
-
Linking a feature or subfeature to an existing Azure DevOps work item
If you already have existing Work items in Azure DevOps, you can link features or subfeatures to them. You can do this from the list view of your Features board or the feature or subfeature detail view.
Linking features or subfeatures enables clear and consistent communication, so teams are up to date on the delivery status.
To link a feature or subfeature to an existing Work item, follow the same steps we covered earlier either under Pushing features from the list view your feature board or Pushing features from feature or subfeature detail view.
- Once you followed the steps, when you click on the Azure DevOps logo, select Link to existing:
- Select the Azure DevOps Project and enter the Work item ID. Productboard will automatically display the Work item type, name, and status. Confirm that the listed Work item is correct. Then, click Link.
Unlinking a feature or subfeature from an Azure DevOps Work item
If you connected the Productboard feature or subfeature to the wrong Work item in Azure DevOps, you can remove the link by clicking the Break icon (
) next to the push button in the feature or subfeature detail view.
Then you can click Unlink. This way, you can push or link the feature or subfeature to the correct Work item in Azure DevOps.
Understanding how fields map across Productboard and Azure DevOps
When you push or link a feature or subfeature into Azure DevOps, fields will be mapped across Productboard and Azure DevOps to ensure product managers and developers can work seamlessly together.
This is the information that is shared between the two systems:
- Feature or subfeature Title.
- Feature or subfeature Description with formatting.
- Creator (the person who pushed the feature) is displayed in the Azure DevOps history (Activity Log).
- Azure DevOps work item status.
- Productboard feature or subfeature link will be created in the Azure DevOps comments section and links section, so you can easily switch between the systems.
You can see an overview of how the fields are linked between the two systems in the image below, where you can see Azure DevOps on the left and Productboard on the right:
Note:
- While subfeatures are often pushed to Azure DevOps as user stories, product backlog items, issues, or features (depending on your Features board setup), you can use any other custom Work item type as well.
- Within Productboard, you can change a feature to a subfeature, or vice versa, without impacting the associated Work item in Azure DevOps.
Filtering features or subfeatures by Azure DevOps status
You can also filter features and subfeatures on your Features board to display only those that have certain Azure DevOps statuses associated.
- Click the Filter icon (
) in the header. - Select Tasks.
- Find your Azure DevOps integration.
- Select the status(es) you wish to see.
Using the two-way sync to update fields automatically across tools
The Azure DevOps and Productboard integration let you synchronize fields between the two systems automatically.
The integration supports two-way sync of the following fields:
- Productboard feature Name <> Azure DevOps Work Item Title
- Productboard feature Description <> Azure DevOps Work item Description
NOTE: Two-way sync is disabled by default. It must be explicitly enabled in the Integration settings (see below).
Enabling and configuring the two-way sync between Productboard and Azure DevOps
To enable the two-way sync between Productboard and Azure DevOps you need to meet the following requirements:
- The user who originally authorized the Productboard <> Azure DevOps integration needs the following permissions, at least temporarily, to enable the two-way sync (see Installation requirements).
- The account should be a member of the Project collection service account or Project collection administrators groups in Azure DevOps. Detailed instructions can be found on the authorization screen in Settings where a new auth token can be entered.
To turn on the two-way sync, follow those steps:
- Go to Productboard's Integration Settings.
- Select the Azure DevOps integration for which you want to enable two-way sync.
- Under Synchronization, select the fields you'd like to sync bi-directionally and click Save sync settings.
Understanding the two-way sync limitations
If you decide to enable the two-way sync, you should take into account the following limitations:
- No data will be synced retroactively when the two-way synchronization is enabled.
- There may be minor discrepancies when syncing rich text descriptions between Productboard and Azure DevOps, and some formatting may be lost.
- Minor text corruptions may occur after multiple syncs. These can be fixed with manual edits, and both editors provide version history.
- Inline images are displayed only with the user is logged into both systems, as the images are not stored locally.
- Productboard edits will be written to Azure DevOps using the account of the user who authorized the integration.
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:
- In Productboard, click the avatar on the bottom right. Then click on Integrations:
- Select the Azure DevOps integration you'd like to enable parent-child relations for:
- Check Map child items to parents:
You can also choose to apply links backwards by clicking the Apply backwards button. If you do so, all of 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 what to use the Azure DevOps integration, you can remove it on the Integrations page. Follow these steps:
- In Productboard, click the avatar on the bottom right. Then click on Integrations:
- Click on Azure DevOps, and toggle the integration off:
- Then select the integration name you wish to remove, and click on the trash bin icon (
):
Automatically update a Productboard Feature status based on an Azure DevOps status
A Maker+admin of your Productboard workspace can set this up by following the steps below:
-
Click your Avatar in the bottom left of your account and then click Integrations (
). -
Scroll down to your Azure DevOps Integration and select the Azure DevOps Integration you want to set up the status sync for.
-
Scroll down to the section Status Sync Updates and click on the + Add status rule button.
-
On the left dropdown, select all the Azure DevOps statuses that if changed in Azure DevOps will trigger a change of status in Productboard.
-
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.
-
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.
- 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 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’s going to be highlighted and won’t be updated on the Features Board.
To resolve the error:
- Remove the highlighted status from the rule via clicking the X button in the status box.
- Remap the status that corresponds to your current flow.
- Save status rules.
Status no longer exists in Productboard
If the Productboard status is removed, the dropdown is going to be highlighted and the rule won’t be working until the status is remapped.
To resolve the error:
- Click on the dropdown and select the status that corresponds to the Azure DevOps statuses mapped.
- 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 be able to save the rule.
See also:
Comments
Article is closed for comments.