# Jira

## About Jira integration

Adding the integration will let you simultaneously create, edit, and update items between Timebook teams and the selected Jira epic (project).

The integration allows for two types of synchronization:

1. **One-directional synchronization** – updating a work item in Timebook also does it in Jira, but not the other way around. Requires authentication with OAuth or an API token.
2. **Bidirectional synchronization** – items 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
* 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 switch to the **Jira** tab. 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 switch to the Jira tab. 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 with Jira space (project)

The last part is selecting the space in Jira that will be synchronized with Timebook. Depending on whether you have Teams activated, you can synchronize Jira in two ways:

1. **Team**: all work items in the selected Timebook team
2. **Project**: all work items in the selected Timebook project

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

### Project-level synchronization

{% hint style="info" %}
Synchronizing on the project level will create a new epic in Jira with all work items from the selected Timebook project.
{% endhint %}

{% hint style="success" %}
This method also applies to Timebook solutions.
{% endhint %}

{% stepper %}
{% step %}
Go to the project with the work items you want to sync.
{% endstep %}

{% step %}
Expand project options with `...` , top-right, and click 'Send to Jira'.

<div align="left"><figure><img src="/files/hwMwbaNsJH5Iq6YrGFu1" alt="" width="563"><figcaption><p>Project settings with Jira synchronization option.</p></figcaption></figure></div>
{% endstep %}

{% step %}
Select the space (project) in Jira and click the button to connect both services.
{% endstep %}
{% endstepper %}

### Team-level synchronization

{% hint style="info" %}
Synchronizing on the team level will send updated work items assigned to your Timebook team to the selected Jira space (project).
{% endhint %}

{% stepper %}
{% step %}
Go to the settings of the Timebook team that you want to sync.
{% endstep %}

{% step %}
Switch to **Work Items** → **Jira integration** and select the project in Jira.

<div align="left"><figure><img src="/files/dTMcWko582SYwbHNV4qu" alt="" width="563"><figcaption><p>Selecting Linear team to synchronize in Timebook team settings</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.timebook.ai/hc/integrations/jira.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.