Guide menu

Azure DevOps integration


With the Azure DevOps integration, you can sync TheyDo solutions with work items in Azure DevOps. This guide explains how to set it up.

Two-way synchronization between Azure DevOps and TheyDo means no more back and forth or misalignment — just a synchronized roadmap around which everyone can collaborate. Customer Experience management just works better when your Epics, Features and even stories are synced with your journeys.

To install the Azure DevOps integration you need to be on the Management plan.

In this article, you will learn how to set up your Azure DevOps integration in TheyDo.

  • Installing and authorizing Azure DevOps in TheyDo

  • Setting up 2-way synchronization (or not)

  • Mapping statuses between your Azure DevOps projects and TheyDo workspaces

  • Working with Azure DevOps and TheyDo

  • Security and rights management

1. Installing and authorizing Azure DevOps in TheyDo

In order to install Azure DevOps in your TheyDo environment you will need the following things:

  • Your Azure DevOps organization server URL.

  • You must have the build administrator role in Azure DevOps.

  • You must be a member of the Project Collection Service Accounts or Project Collection Administrators groups in Azure DevOps.

  • Administrative permissions in TheyDo.

1.1 Find the Azure DevOps integration in the settings

Start by going to Settings in TheyDo. There, choose Integrations and press Enable in the Azure DevOps product integration line.

1.2. Enter your organization URL

Enter your organization URL in the field. You can find this URL when you navigate to your Azure DevOps environment and check the URL bar. Copy the part after

Then click Create integration.

Note: Every Azure DevOps environment can be connected once. If you see an error, please check whether there might be another organization in TheyDo already connected to the Azure DevOps environment you’re trying to connect to.

1.3. Create a Personal Access Token (PAT)

This part is also described in detail within the setup wizard.

1. Open up Azure DevOps user settings as an admin.

Synchronization from Azure DevOps to TheyDo will only work if you are a member of the Project Collection Service Account or Project Collection Administrators groups in Azure DevOps. Navigate to User Settings > Personal access tokens

2. Create a new token by clicking on + New Token


3. Give your token a recognizable name for reference in the future.


5. Select the organization. Make sure this is the same organization that you filled in for the server URL on the previous setup screen.

6. Set the Expiration (UTC) to Custom defined and select the latest possible date. The date defines when the PAT expires and thus when the integration will stop working. Once it expires you’ll have to refresh your PAT and add it to TheyDo again, so the later the date, the less often you’ll have to do this.

7. Add permissions for the Notifications and Work Items scopes to authorize the scope access of the token. Set both to Read & Write. You might need to click on Show all scopes to see both the Notifications and Work Items scope settings.



8. Click on Create

9. Copy your unique token! You won’t be able to see the token again in the future.


10. Paste the token in the Authorize integration field, and then click on Authorize integration.

Congrats, you’ve now installed Azure DevOps in TheyDo! Next, let’s have a look at configuring the integration to make the best use out of it.

Note: Once you enabled the integration, you can connect multiple instances to your TheyDo organization.

ADO Multiple

2. Setting up 2-way synchronization (or not)

TheyDo can automatically synchronize solutions in TheyDo and work items in Azure DevOps. That means that when you create a solution in TheyDo, you can push it to Azure DevOps as an Epic, a Story, a Task or any type of work item that you’ve configured. Afterwards, when the description changes in Azure DevOps, and for example acceptance criteria are added, you will see those changes reflected in TheyDo.

With 2-way synchronization, we keep the Title and Description of solutions in sync with the Title and Description of the Azure DevOps in Jira. For status synchronization see below.


In order to set up 2-way synchronization, first choose a default project. This is the main Azure DevOps project that you want the solutions to be pushed or linked to. You’ll be able to choose the specific project every time, but with this default project we save you a click.

Then toggle 2-way synchronization on and click on update.

Of course, if you don’t want the Title and Description to update after the initial push (or during linking), then keep this turned off.

3. Mapping statuses between your Azure DevOps projects and TheyDo workspaces

This is where the magic happens. Here you can connect the statuses of a specific Azure DevOps project to the solution statuses within a workspace in TheyDo. That means that when a linked work item is updated in Azure DevOps, this update will be reflected in TheyDo.

3.1. Choose the project and workspace

  1. Choose the Azure DevOps project that you want to connect with.

  2. Choose the TheyDo workspace that connects to that Azure DevOps project.

Note: Multiple projects can be linked to one workspace.

3.2. Map the statuses

On the left you see the statuses of the Azure DevOps project. On the right, you can link a TheyDo status to those Azure DevOps statuses. When a work item changes status in Azure DevOps to the status on the left, TheyDo will update the solution status to the linked status. Note: You don’t need to update every Azure DevOps issue status to a TheyDo status, and you can map multiple Azure DevOps issue statuses to one TheyDo solution status.


This feature is very flexible and should be able to support your workflow. For example, in the screenshot above we’ve mapped both Backlog and To Do of the issue work item type to Validated. In this workflow, the service design team, with the help of the product manager first validates solutions (e.g. with research or prototypes), and only then creates a work item in Azure DevOps.

This story can then be prioritized by the product manager/product owner and moved to selected for development. For the service design team, nothing has changed. However, once the team starts implementing the solution (In progress) the status in TheyDo changes to In development, and when it’s moved to Done the solution status is similarly updated to Live. This means the team knows when the solution is implemented and what the current state of the customer experience is.

4. Working with TheyDo and Azure DevOps

For more on syncing TheyDo Solutions to Azure Devops, have a look at our article on the topic.

5. Security and rights management

We comply with Atlassian’s security requirements:

Get a personal demo or try for free