Azure DevOps Integration

ProductPlan’s integration with Azure DevOps allows you to easily import epics or stories from your projects or boards to ProductPlan. You can link your items to existing ProductPlan Bars or Containers and push new items from ProductPlan to Azure DevOps. Use the integration to synchronize percent complete, start and end dates, title, tags, and description to always stay up-to-date.

ProductPlan will pull completion progress directly from Azure DevOps and automatically update the percent complete on your roadmap. You’ll be able to synchronize the percent complete in ProductPlan by either stories completed or story points.

ProductPlan can also integrate with the on-premise version of Azure DevOps, Team Foundation Server. To integrate with TFS, your server needs to be accessible from outside the firewall. You can find more information on how to set that up here.

Setup Instructions

To set up the integration, go to your Integrations page and click Begin Azure DevOps Integration. You will need to provide your Azure DevOps URL as well as a Personal Access Token in order to configure the integration.

To generate a Personal Access Token:

1. Go to your Azure DevOps security page and click New Token.

2. Set a name and expiration date for your token.

3. Choose which scopes to include. You can include “All scopes” or “Custom defined.” If you choose “Custom defined”, the two required fields you must include are:

• Project and team (read+write)

• Work items (read+write)

Custom Mapping of Fields for Azure DevOps

Once the integration is configured, you can begin choosing which custom fields you’d like to map. You can sync Title, Description, start/end dates, tags and percent complete.

For Basic Plans, the default mapped fields between ProductPlan and Azure DevOps are set to Title, Description, Tags, Start Date, End Date and Percent Complete.

For Professional and Enterprise Plans, you will be able to customize which fields in Azure DevOps will map to the core fields in ProductPlan, as well as adding additional fields. If your team is utilizing Custom Text Fields, you will also have the option to map those fields to your desired Azure DevOps fields as well.

For information on upgrading to our Professional or Enterprise subscriptions email us at sales@productplan.com.

Importing From Azure DevOps to ProductPlan

Once you’ve set up your integration, you can easily import multiple epics or stories straight into ProductPlan all at once. To import, either go to the Table Layout of the roadmap you want to import into and select the Parked tab. Then select "import" from the top tool bar.

You can also import from your Timeline or List view by clicking the triple ellipsis to the right of Azure DevOps under Integrations and click Import, this will take you directly to the Parked section of your Table Layout.

Once you have selected to Import, you will see this window:

Here you will see the fields mappings you have set up on your integrations page. You can also decide if you'd like to map the roadmap's lanes and legend to ADO fields.

Please note, the roadmap owner's field assignments are used when syncing.

There are two ways you can import from ADO to ProductPlan in the Table Layout's Parked Section:

1. Select the project you want to import from, and then search for initiatives you would like to import into the Parked section. Your search should include at least three characters. The search functionality will work exactly the same as it does in Azure DevOps. Take a look at Azure's special operators here to learn about how to filter your search and make importing the right items even easier.

2. You can alternatively use a Query Based Import to bulk import several work items at once. In order to import from a query, you'll need to copy the URL directly from your browser's address bar after saving the Query. Choosing the menu option to "Copy a query URL" will create a temporary URL which is not supported. Azure's Query support article can be found here.

Selecting "save search to auto import new items daily at 10 pm PST" will schedule an automatic daily import of new work items in your selected query. If you'd like to import child work items, select "Import Epics as Containers." This allows you to maintain the hierarchy from ADO as you import items to ProductPlan. If you'd like ProductPlan to keep this epic and child relationship in sync with your integration over the lifecycle of your roadmap, you can consider utilizing the maintain hierarchy feature for your roadmap.

After searching, select “Import” to bring the issues in to the Parked section of your Table Layout. This will include the fields selected from your Integrations page, and it will create a link to the epic or story in Azure DevOps. You can select the issue(s) from Parked and click "Unpark bar" to move these Bars directly onto your roadmap, which will also appear in the Planned section of your Table Layout.

Linking Bars or Containers to Epics or other issues

1. Click on a Bar or Container to open up the details page.

2. Click "Link" and then choose Azure DevOps from the left side.

3. Choose the project from the dropdown menu.

4. Search for the issue that you wish to link (your search must include at least three characters).

Note: When you Link a Bar or Container to an item in AzureDevOps, any information in the Bar or Container will be overridden by the information pulling from AzureDevOps.

Pushing to Azure DevOps 

You can also begin your high-level planning in ProductPlan and then push your issue to Azure DevOps. Once you've created your Bar or Container in ProductPlan, open its details page. Select the triple ellipses in the top right corner, and then "Add to Azure DevOps." As a best practice, we suggest linking at the Epic level to keep your roadmap high-level, however you are able to push a new issue as a story, issue or task as well.

Syncing Dates with Azure DevOps

Using the integration, you can have the start and end dates of your bars/containers update automatically as things change in Azure DevOps.

Keep in mind that the mapping you select here will only be applied for the Roadmaps you are the owner of. If you are collaborating on someone else's Roadmap, you'll need to have the owner set up their mappings.

*Please note: In order for dates to sync, both a Start and End date must be mapped.

When an item's dates are being synced with Azure DevOps a lock icon will appear on the bar indicating that the item can't be moved unless the date sync link is broken by clicking the chain icon next to the dates in the bar description.