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

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

The account's name will be used as the username in Timebook in notifications for synchronization events.

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

1

Go to Workplace settings → Integrations and switch to the Jira tab. Select OAuth as the access method.

2

Next, accept the request in Atlassian.

Make sure you're logged in to Jira as the dedicated service account.

OAuth access request screen in Atlassian

3

Once authenticated, paste the URL to your Jira workspace, e.g. https://company.atlassian.net

Method 2: Access token

1

Go to Workplace settings → Integrations and switch to the Jira tab. Select Access token as the access method.

2

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. [email protected]

• The API token generated in the Jira user security settings

Location of API token creation in Jira

Bidirectional synchronization

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

1

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

2

Generate the secret for the webhook in Jira and paste it back to Timebook.

3

Generate the webhook URL in Timebook and paste it back to Jira.

Webhook URL syntax: https://WORKPLACE.timebook.ai/api/pms/webhook/jira/HASH_NUMBER

Webhook configuration details in Jira

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

Example of configured Jira integration settings (OAuth)

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

Please mind you must have admin rights to configure synchronization between services.

Project-level synchronization

Synchronizing on the project level will create a new epic in Jira with all work items from the selected Timebook project.

This method also applies to Timebook solutions.

1

Go to the project with the work items you want to sync.

2

Expand project options with ... , top-right, and click 'Send to Jira'.

Project settings with Jira synchronization option.

3

Select the space (project) in Jira and click the button to connect both services.

Team-level synchronization

Synchronizing on the team level will send updated work items assigned to your Timebook team to the selected Jira space (project).

1

Go to the settings of the Timebook team that you want to sync.

2

Switch to Work Items → Jira integration and select the project in Jira.

Selecting Linear team to synchronize in Timebook team settings