How to Sync Toggl Entries to Jira?

Fast, simple, clear.

TLDR;

Using CLI tool 68publishers/toggl-to-jira. Run it locally or in a scheduled pipeline.

Why you may need Toggl's time entries in Jira

As a developer working on several projects, especially for more than one client you're probably using some time tracking tool. Toggl is one of my favorites. I use it for monthly reports, invoicing, or just personal use.
When participating in a larger project, some other tools for project management are required. Most of them include time tracking. That’s where the problem arises — you don't want to use multiple tools for the same thing when you already have one.

And here comes the 68publishers/toggl-to-jira CLI tool to save you. Any time you can sync Toggl's entry directly to Jira's issue. All you need are your credentials, API tokens, Docker or a working copy of toggle-to-Jira's tool, and to follow the description convention of entries in Toggl.

Description format

It's pretty easy — the description has to start with Jira's issue code and everything else is optional. The pattern is:

<IssueCode> [<IssueName>] [<Comment>]

For example, if the issue in Jira has code PROJ-123 and the name of the issue is UX improvements, then the following examples are acceptable:

• PROJ-123 - the entry is imported with an empty comment
• PROJ-123 UX improvements - the entry is imported with an empty comment
• PROJ-123 UX improvements Fixed footer on small devices - the entry is imported with a comment Fixed footer on small devices
• PROJ-123 Fixed footer on small devices - the entry is imported with a comment Fixed footer on small devices

Entries with different formats will be skipped and unknown issue codes will also be ignored.

Prerequisites

• Docker
• Toggl API token, get yours on Profile settings
• Jira API token, create one on Atlassian account — Security settings — API Tokens
• Jira website URL, such as my-organization.atlassian.net
• Jira username/e-mail

Usage

$ docker run --rm \
    -e TOGGL_API_TOKEN=<toggl_api_token> \
    -e JIRA_API_TOKEN=<jira_api_token> \
    -e JIRA_WEBSITE_URL=<jira_website_url> \
    -e JIRA_USERNAME=<jira_username> \
    68publishers/toggl-to-jira:latest \
    bin/console sync \
    --no-interaction

By default, it synchronizes all of your records for the previous day.

To synchronize a larger period of time, use the start and end options

Available options

The sync command has multiple options. The ones you might be interested in:

1. --start defines the beginning from which the time entries will be synchronized. It accepts datetime strings — absolute (Y-m-d) or relative, default: yesterday
2. --end defines the end of the synchronization
3. --dry-run displays only change set and summary tables without synchronization.
4. --group-by-date is useful when you have multiple entries per issue in one day. The log description will be composed of all Toggl's entries.
5. --rounding regarding the group-by-day option rounds the total time to a given number of minutes.

For further details check the README file.

Limitations

Depending on the range of the synchronization interval (start/end), you may run into the limits of one of the APIs. Therefore it's recommended running synchronization e.g. every day/sprint/month, etc.

At the time of writing this article, the tool supports synchronization with one Jira at a time. To sync Toggl with multiple Jira organizations, you may configure multiple jobs with different Jira configurations. The issue code has to be unique across all your Jiras.

Conclusion

Since Jira Sync in Toggl is a premium feature, the 68publishers/toggl-to-jira can be comfortably synced with all handy features like dry-run, group-by-day, or even rounding which you’ll appreciate when you’re not very meticulous about tracking time.
Setting up a scheduled pipeline e.g. in GitLab will give you an out-of-the-box solution for the price of no more than a coffee.

Another advantage is that you keep all historical data and can look at it retrospectively, independent of your client or the used software.