> For the complete documentation index, see [llms.txt](https://help.timebook.ai/hc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.timebook.ai/hc/integrations/jira.md).

# Jira | Jira PD

## About Jira integration

Currently, Timebook integrates with two Atlassian products:

* **Jira** – allows simultaneous creation, editing, and updating solutions and projects between Timebook and the selected Jira epic/project
* **Jira Product Discovery** – similar to Jira basic, but focuses on synchronizing opportunities and insights

{% hint style="info" icon="lightbulb-gear" %}
Technical-wise, the integration process is the same for both services and requires the same scopes and permissions. Follow below for detailed installation instructions.
{% endhint %}

<div align="left"><figure><img src="/files/ZqVUlpSbjIKQq4dyGKaF" alt="" width="563"><figcaption><p>Jira services in workspace settings</p></figcaption></figure></div>

The integration allows for two types of synchronization:

1. **One-directional synchronization** – updating an object in Timebook also does it in Jira, but not the other way around. Requires authentication with OAuth or an API token.
2. **Bidirectional synchronization** – objects are fully synchronized between both services. Requires authentication with OAuth or an API token and configuring a webhook.

## Requirements

{% hint style="warning" %}
To add the integration, you must:

* create a dedicated service account in Jira with R/W access to the projects that you want to synchronize
* use the account to configure the API token and webhook (for biderectional sync)
* once configured, log out from the service account and use your regular Jira account for work
  {% endhint %}

{% hint style="info" %}
The account's name will be used as the username in Timebook in notifications for synchronization events.
{% endhint %}

### Service account scopes

This is the list of scopes required for the service account to work.

```
Jira
Manage: jira-webhook
View: jira-user, jira-work
Update: jira-work

User
View: account
```

## One-directional synchronization

### Method 1: OAuth

{% stepper %}
{% step %}
Go to **Workplace settings** → **Integrations** and select either **Jira** or **Jira PD**. Select **OAuth** as the access method.
{% endstep %}

{% step %}
Next, accept the request in Atlassian.

{% hint style="warning" %}
Make sure you're logged in to Jira as the dedicated service account.
{% endhint %}

<div align="left"><figure><img src="/files/b8TLvrUGeEIpdNLZ7OMZ" alt="" width="563"><figcaption><p>OAuth access request screen in Atlassian</p></figcaption></figure></div>
{% endstep %}

{% step %}
Once authenticated, paste the URL to your Jira workspace, e.g. `https://company.atlassian.net`
{% endstep %}
{% endstepper %}

### Method 2: Access token

{% stepper %}
{% step %}
Go to **Workplace settings** → **Integrations** and select either **Jira** or **Jira PD**. Select **Access token** as the access method.
{% endstep %}

{% step %}
Fill in the authentication details:

* The URL to your Jira workspace, e.g. `https://company.atlassian.net`
* The email address your Jira account, e.g. `timebook_service@company.com`
* The API token generated in the [Jira user security settings](https://id.atlassian.com/manage-profile/security/api-tokens)

<div align="left"><figure><img src="/files/AidG8JcwxlEEHSqrVToo" alt="" width="563"><figcaption><p>Location of API token creation in Jira</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

## Bidirectional synchronization

Once you authenticate in Jira, you can add a webhook that will allow you to synchronize work items in both ways.

{% stepper %}
{% step %}
Go to the system settings in your Jira workspace and create a webhook with the following scopes:

```
Issue: created, updated, deleted
Comment: created, updated, deleted
Attachment: created, deleted
Issue link: created, deleted
```

{% endstep %}

{% step %}
Generate the secret for the webhook in Jira and paste it back to Timebook.
{% endstep %}

{% step %}
Generate the **webhook URL** in Timebook and paste it back to Jira.

{% hint style="info" %}
Webhook URL syntax: `https://WORKPLACE.timebook.ai/api/pms/webhook/jira/HASH_NUMBER`
{% endhint %}

<div align="left"><figure><img src="/files/ucs6mvlkw8wpH678kMqG" alt="" width="563"><figcaption><p>Webhook configuration details in Jira</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

In the end, your configuration settings in Timebook should look like this:

<div align="left"><figure><img src="/files/r4AZoTIyxoKHiXTU0Csu" alt="" width="375"><figcaption><p>Example of configured Jira integration settings (OAuth)</p></figcaption></figure></div>

## Syncing objects

### Jira

Integrating with Jira allows you to recreate solutions and projects as epics in the selected Jira space together with their child work items.

{% hint style="warning" %}
Please mind you must have admin rights to configure synchronization between services.
{% endhint %}

Instructions:

{% stepper %}
{% step %}
Go to the solution or project that you want to sync.
{% endstep %}

{% step %}
Click the 'Send to delivery' button at the top navi-bar.
{% endstep %}

{% step %}
Select **Jira** as the target software and the team (space) to which you want to deliver your object.
{% endstep %}

{% step %}
Click 'Send' to sync the items.

<figure><img src="/files/eSRp1OwSVyi1tcxtTE7r" alt=""><figcaption><p>Example: sending Timebook solution to Jira</p></figcaption></figure>
{% endstep %}
{% endstepper %}

Once synced, you will notice the Jira icon at the top of the screen together with the URL to the target object. All existing and newly created child items of the object will be automatically recreated in Jira.

{% tabs %}
{% tab title="Timebook" %}

<div align="left"><figure><img src="/files/hz6oa7MGSaNGMy8fYuPu" alt="" width="563"><figcaption><p>Synced solution in Timebook</p></figcaption></figure></div>

{% endtab %}

{% tab title="Jira" %}

<div align="left"><figure><img src="/files/Apg1dHjW5zLOA50EG8sX" alt="" width="563"><figcaption><p>Solution recreated as epic in Jira</p></figcaption></figure></div>

{% endtab %}
{% endtabs %}

### Jira Product Discovery

This integration will let you map Timebook opportunities and insights to Jira PD.

{% hint style="warning" %}
Please mind you must have admin rights to configure synchronization between services.
{% endhint %}

Instructions:

{% stepper %}
{% step %}
Go to the insight or opportunity that you want to sync.
{% endstep %}

{% step %}
Click the 'Sync...' button at the top navi-bar.
{% endstep %}

{% step %}
Select **Jira PD** as the target software and the team (space) with which you want to synchronize your opportunity or insight.
{% endstep %}

{% step %}
Click 'Push' to sync the items.

<figure><img src="/files/2qnwkJG7eP1yYFzAfOHQ" alt=""><figcaption><p>Example: sending Timebook opportunity to Jira PD</p></figcaption></figure>
{% endstep %}
{% endstepper %}

Once synced, you will notice the Jira PD icon at the top of the screen together with the URL to the target object. All insights belonging to the opportunity – existing or new – will be automatically recreated in Jira.

{% tabs %}
{% tab title="Timebook" %}

<div align="left"><figure><img src="/files/XwzXY4hRTHIaQHZfLkZ3" alt="" width="563"><figcaption><p>Synced opportunity in Timebook</p></figcaption></figure></div>
{% endtab %}

{% tab title="Jira PD" %}

<div align="left"><figure><img src="/files/MpTLqL9rhYGCopErUakb" alt="" width="563"><figcaption><p>Opportunity recreated as idea in Jira</p></figcaption></figure></div>
{% endtab %}
{% endtabs %}