Syncing Timebook and Jira items

Reading time: 5 minutes

How Timebook syncs with Jira

You can configure integration with Jira for your entire Timebook Workplace. Once enabled, your Teams in Timebook can synchronize Work Items with Jira issues. This article explains which Work Item attributes can be mapped between the two systems.

Mapping, in this context, means connecting specific fields in Timebook Work Items with their counterparts in Jira issues. Once synced, any changes made to these fields in one of the apps are reflected in the other.

Some solutions that exist in Jira aren’t used in Timebook because the two tools are built with different philosophies. This means not everything can sync perfectly.

Continue reading to see how the Timebook-Jira integration handles these differences.

---

What gets synced

Synchronization between Timebook and Jira is enabled by linking a specific Team in Timebook with a specific Jira project. This allows Work Items in the Team to sync with Jira issues. The synchronization is two-way, meaning changes made in one tool can be reflected in the other.

The following Timebook Work Item attributes are mapped to Jira issue attributes:

• Title (Summary in Jira)

• Description

• Item type (Issue type in Jira)

• Parent/child relationships

• Status

• Priority

Attributes based on type selection—such as Status, Issue Type, and Priority—are generally mapped by name and are case-insensitive. This means that as long as the names match, capitalization doesn’t matter.

Syncing details

Below are the details of how individual attributes are synced:

If you’re not looking for the full context or technical details about how Jira and Timebook handle item attributes, feel free to skip ahead to the Configuration Recommendations at the end of each section.

These callouts highlight best practices that can help you avoid common issues when setting up your Timebook–Jira integration.

Title

• The Title in Timebook is synced directly with the Summary in Jira.

---

Description

• Timebook uses a JSON-based format called 'plate.js' for rich text descriptions. Jira uses the Atlassian Document Format for its descriptions.

Due to the difference explained above, limited mapping is supported between these formats.

This means that some formatting may be lost or displayed incorrectly when syncing descriptions.

---

Priority

• Priority fields are mapped by name.

• Jira allows customization of priority fields, enabling teams to define their own sets of values. In Timebook, the priority set is predefined and not customizable.

• Jira does not allow an empty priority value, while Timebook does. If a Work Item in Timebook is set to "No priority", the change won’t be reflected in Jira.

Configuration recommendations:

• Define priorities in Jira as Low, Medium, High, and Urgent so that Timebook values can be synced properly.

• Ensure that the Priority field is enabled for the relevant issue types in Jira.

---

Status

• The Status field is mapped by name.

• Both Timebook and Jira allow customizable status configurations. In Timebook, statuses are defined at the Team level.

• Jira supports workflows that control allowed transitions between statuses. For example, you might not be able to move directly from "To do" to "Done" unless a workflow allows it. Timebook, on the other hand, imposes no restrictions on changing statuses. As a result, a status change in Timebook may not sync with Jira if there is no valid transition defined in the Jira workflow.

• Consider this example of a potential limitation: Suppose the Jira workflow allows the following transitions: To do → In progress → In test → Done. If you change a Work Item in Timebook directly from "To do" to "In test", the corresponding Jira issue will remain in "To do" because the transition is not permitted.

Configuration recommendations:

• Use the same set of statuses in both Jira and the connected Timebook Team.

• Apply the same status set across all Jira issue types.

• Avoid configuring Jira workflows that block status transitions.

---

Item types

• Item type (issue type in Jira) is mapped by name.

• However, when syncing hierarchical relationships, Jira may override issue types to preserve its hierarchy rules, even if an exact name match exists.

• If an item type cannot be matched (considering Jira’s hierarchy constraints), the first applicable issue type will be used instead.

• Consider the following examples:

  • In Timebook, you can create an Epic that has another Epic as its parent. In Jira, this isn’t allowed; child items of Epics must be Stories, Bugs, or Tasks. Jira will therefore assign one of these types.

  • In Timebook, you can create a Bug with another Bug as its parent. In Jira, Bugs can only have Subtasks as children. Jira will automatically assign the Subtask type.

Configuration recommendations:

• Define identical sets of item types in Jira and Timebook.

• Avoid using item types that cannot be matched in the other system.

• To maintain the importance and structure of Epics, use only Stories, Bugs, and Tasks as their child items.

• Note: Any item type used as a child of another Work Item in Timebook will be synced to Jira as a Subtask. This is a known limitation due to how Jira handles item hierarchies.

---

Parent/child relationships

• Timebook does its best to maintain parent-child relationships when syncing with Jira. If both parent and child items can be synced, the relationship is preserved.

• Jira defines issue hierarchies with these levels:

  • Level 1: Epics

  • Level 0: Stories, Bugs, Tasks

  • Level -1: Subtasks

• As a result, in Jira:

  • Epics can only have Stories, Bugs, or Tasks as their child items.

  • Stories, Bugs, and Tasks can only have Subtasks as their child items.

  • Subtasks must always have a parent and cannot have their own child items.

• Timebook does not support these structural constraints. In Timebook:

  • You can create Work Items of any type as parents or children.

  • You cannot define that a Work Item type must have a parent.

  • You cannot prevent a Work Item from having sub-items.

• Considering all the above, these are the supported relationships in Timebook-Jira integration:

  • Epics can have child items of the Story, Bug, or Task type; these relationships sync correctly.

  • Stories, Bugs, and Tasks can have Subtasks; these relationships will also sync.

  • The type of the parent of a Subtask can be changed between Story, Bug, or Task.

  • Issue types can be changed as long as hierarchy rules are followed. For instance, we can’t sync changing of the issue type to Epic if its parent is also an Epic. But if the issue is detached from the parent Epic, it can be converted to Epic without any issues.

Configuration recommendations:

There is no configurable setting for parent/child synchronization. Instead, keep the limitations in mind and design your hierarchies accordingly.

---

Related articles

Workplace integrations

Work settings

Work Item