Syncing Timebook and Jira items
Reading time: 5 minutes
Last updated
Was this helpful?
Reading time: 5 minutes
Last updated
Was this helpful?
You can configure integration with Jira for your entire Timebook Once enabled, your in Timebook can synchronize 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.
Synchronization between Timebook and Jira is enabled by linking a specific in Timebook with a specific Jira project. This allows 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
Below are the details of how individual attributes are synced:
The Title in Timebook is synced directly with the Summary in Jira.
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 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.
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.
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.
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 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.
Note: Any item type used as a child of another in Timebook will be synced to Jira as a Subtask. This is a known limitation due to how Jira handles item hierarchies.
You can create of any type as parents or children.