👋 Guides welcome
Jira integration

Jira integration

Setup and start using Jira epics, stories and tasks in your Journey Management.

With the Jira integration, you can sync TheyDo solutions with Jira projects. The two-way synchronization means no more back and forth, no more misalignment but a synchronized roadmap that everyone is ready to collaborate around.

In this article, you will learn how to set up your Jira integration in TheyDo

  1. Installing and authorizing Jira in TheyDo
  2. Setting up 2-way synchronization
  3. Mapping statuses between your Jira projects and TheyDo workspaces
  4. Working with Jira and TheyDo
  5. Security and rights management

1. Installing and authorizing Jira in TheyDo

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

  • URL to your Jira Cloud instance (only works with Jira Cloud)
  • Permission to install a marketplace app in Jira
  • Administrative permissions in TheyDo

1.1 Find the Jira integration in the settings

Start by going to Settings in TheyDo. There you choose Integrations and press on Enable in the Jira product integration line.

1.2. Enter your Jira Cloud details

Enter your Jira Cloud details in the field. You can find this URL when you navigate to your Jira Cloud environment and check the URL bar. Copy the part after https:// and before .atlassian.net


Then click Authorize.

1.3. Install the app in Jira

In Jira, navigate to the Jira Apps marketplace and search for TheyDo.

Install the TheyDo app in your Jira environment (this might take a minute or 2).

Once the app is installed, go back to TheyDo and press Authenticate.

Note: If the app hasn’t finished installing yet, the authentication won’t work. Wait another minute and try it again. If it then still doesn’t work, try to remove and re-install the app in the Jira environment.

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

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

TheyDo can automatically synchronize between solutions in TheyDo and issues in Jira. That means that when you create a solution in TheyDo, you can push it to Jira as an Epic, a Story, a Task or a Bug. Afterwards, when the description changes in Jira, 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 issues in Jira.

For status synchronization see below:

In order to set up 2-way synchronization first choose a default project. This is the main Jira 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 Jira projects and TheyDo workspaces

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

3.1. Choose the project and workspace

  1. Choose the Jira project that you want to connect with.
  2. Choose the TheyDo workspace that connects to that Jira project.

Note: Multiple projects can be linked to one workspace.

3.2. Map the statuses

On the left you see the statuses of the Jira project, on the right, you can link a TheyDo status to those Jira statuses. When an issue changes status in Jira to the status on the left, TheyDo will update the solution status to the linked status.

You don’t need to update every Jira issue status to a TheyDo status, and you can map multiple Jira 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 Selected for Development 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 new issue in Jira.

This story can then be prioritised 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 what to when the solution is implemented and so what the current state of the customer experience is.

4. Working with Jira

Once setup, you can work both ways: from TheyDo to Jira, and the other way around. It’s as simple as pushing new things to Jira, or linking existing Epics, Features or stories to TheyDo solutions.

4.1 Pushing a solution to Jira as a new issue

To push a solution to Jira as a new issue navigate to the solution you want to push and click Link to Jira

You’ll be prompted to select the Jira 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 issue will look like in Jira.

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

4.2 Link a solution to an existing Jira issue

You can also link a solution to an existing Jira issue. To do this once again click on Link to Jira and navigate to the Link to existing tab.

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

If you have enabled two-way synchronization, 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. 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 issue will be linked to the solution, and if you chose to have one source overwrite the other this will be done.

5. Security and rights management

The JIRA integration complies with Atlassian’s 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