👋 Guides welcome
Azure DevOps integration

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 Business or Enterprise plan.

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

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 groupsin 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 https://dev.azure.com/

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.

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. Synchronizing work with TheyDo and Azure DevOps

4.1 Pushing a solution to Azure DevOps as a new work item

To push a solution to Azure DevOps as a new work item, navigate to the solution you want to push and click Link to Azure DevOps.

You’ll be prompted to select the Azure DevOps project (with the default project as a default) and what issue type you want to create.

Below you’ll see the preview of what the work item will look like in Azure DevOps.

When you press Push the work item will be created with the Title and Description of the solution.

4.2 Link a solution to an existing Azure DevOps work item

You can also link a solution to an existing Azure DevOps work item. To do this click on Link to Azure DevOps and navigate to the Link to existing tab.

You can search for the work item (title or number) and select it.

If you have two-way synchronization on, you’ll have to choose which source should be leading. This is the title and description that we’ll use to overwrite the other.

If you don’t have 2-way sync on, you can still choose to overwrite one of the two sources, and it’s possible to choose to not synchronize them (so the title and description stay the same for both issues). After this initial sync, the title and description will once again be separate.

Note: Synchronization of statuses is separate from this, and when configured will always happen, regardless of whether 2-way sync is on or not.

When you press Link the work item will be linked to the solution, and if you chose to have one source overwrite the other, then this will be done.

5. Security and rights management

We comply with Atlassian’s security requirements: https://developer.atlassian.com/platform/marketplace/security-requirements/



Continue exploring

This article explains how you can add metrics to your journeys.

TheyDo is built to make it easy to share and collaborate your journeys. This article explains the options to help you do so.

Get a personal demo or try for free