The integration at a glance

Using Workpath’s integration with Azure DevOps, you can link the strategic Goals of your organization to the everyday work of your teams in Azure DevOps Boards:

Link Azure DevOps work items to Workpath Goals directly from within Azure DevOps Services
In Azure DevOps, see the linked Goal and its progress directly next to related work items
In Workpath, see all work items linked to a goal, and the status of all child issues, if any

Setting up the Azure DevOps Integration

ℹ️ To perform the steps in this document, admin rights in Azure DevOps and Workpath are required.

These are the steps to get started with the Workpath Azure DevOps Extension:

Create a Personal Access Token (PAT)
Enter the PAT in Workpath
Install the Azure DevOps extension
Start linking work items to Goals!

Step 1: Create a Personal Access Token (PAT)

ℹ️ A Personal Access Token (PAT) is an API token which makes it possible for the Workpath backend to synchronize data for work items which have been linked to Workpath Goals.

In Azure DevOps, choose or create a technical user which will be used to link Workpath with Azure DevOps. It’s recommended that you create a separate user called “Workpath Integration” for this.
Add this user to all projects for which it should be possible to link work items with Workpath Goals.
Access Azure DevOps with this user, click on the user settings icon (upper right), and select “Personal access tokens”.
Click “New Token”. Name the token “Workpath Integration” or similar.
Choose an expiration date in line with your security policies. (When this token expires, you will have to intervene manually to recreate the token, and then repeat step 3.)
Select “Custom defined” scopes, and then select “Read” under “Work Items”.
Click “Create”. On the following screen, copy the token – make sure to store it in a secure location.

Step 2: Enter the PAT in Workpath

As an admin user, navigate in Workpath to “Settings” → “Integrations” → “Azure DevOps”.
Click on “Add a new connection”
Enter your organization’s Azure DevOps URL, for example https://dev.azure.com/acme/
… As well as the PAT you’ve created in the previous step.

Step 3: Adding multiple tenants

You can connect multiple Azure DevOps tenants to your Workpath tenant by adding their URL and a PAT for them. Repeat step 2 from above for all the tenants that you want to connect.

Please also send the list of tenants to solutions@workpath.com so they can be configured on the Workpath back end. This step is important to properly configure multiple tenants for Azure DevOps.

Step 4: Install the Azure DevOps extension

Ensure that your user has the rights to manage extensions, for example by becoming a member of the “Project Collection Administrator” group.
Navigate to “Organization Settings”, then to “Extensions”, then “Shared”.
Click on the Workpath extension, then select “Install”. If you do not see the extension listed here, reach out to the Workpath support team.
The Workpath extension requires access to data from Azure DevOps to perform its function. To enable this, grant access to the requested scopes.

Step 5: Configure Azure DevOps to show the Workpath Extension

Workpath adds a so-called custom control, which can be added to the forms where you view and edit epics in Azure. You need to take some extra steps to configure for which processes and issue types Workpath gets displayed.

These instructions need to be followed by a user who can customize your organization’s processes in Azure DevOps.
Navigate to “Organization Settings”, then to “Process” in the “Boards” section.
Select the process for which you want to show the Workpath extension. Alternatively, create a new process.
Select the “Epic” work item type.
Select “Add custom control”, select the Workpath custom control, and place it on the form
Afterwards, navigate to an epic in a project which uses the process you just customized. Verify that the Workpath custom control shows up on the form.
Repeat the step above for any other work item types you would like to be able to link.

Step 6: Start linking work items to Goals

Next, ask your teams to link Azure DevOps work items to Workpath Goals. To save time, we recommend to link epics or other work item types which contain child issues, rather than linking child issues individually.

Navigate to an Azure DevOps project with a user who also has access to the corresponding team(s) in Workpath.
Navigate to a work item.
You should be seeing a list of Goals to pick from

Done!

You should now be able to use the integration. Please reach out to us if there are any additional questions.