Toggl to Jira

Console application for synchronizing time entries from Toggl into Jira.

Usage

To synchronize your Toggl entries into Jira simply run:

$ 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, all yesterday's time entries will be synchronized. Check available options for further details.

Getting Started

Please follow these instructions to get a local copy and set it up.

System Requirements

• Git
• Docker
• Make

Installation

1. Clone the repository and install the application

$ git clone https://github.com/68publishers/toggl-to-jira.git
$ cd toggl-to-jira
$ make

2. Open the .env file and set up your credentials

Variable	Type	Description
APP_DEBUG	Boolean	Enables debug mode for Tracy
TOGGL_API_TOKEN	String	Auth token for your Toggl account
JIRA_USERNAME	String	Username (email) of your Jira account
JIRA_API_TOKEN	String	Auth token for your Jira account
JIRA_WEBSITE_URL	String	URL of your Jira website

Synchronization

Synchronization is started with:

$ docker exec -it t2j-app bin/console sync --start <START_DATE> --end <END_DATE> [--group-by-day] [--rounding <ROUNDING>] [--filter <FILTER_NAME=FILTER_VALUE>] [--dry-run] [--no-interaction]

Available Options

Option	Type	Description
--start	String	Accepts datetime strings - absolute or relative, default: yesterday
--end	String	Accepts datetime strings - absolute or relative, default: yesterday
--group-by-day	Boolean	Group all daily entries into one (per issue)
--append	Boolean	All entries will be added without creating a diff. Will cause duplicates if the command is run multiple times on the same day
--prune	Boolean	All entries will be synchronized by default, however existing entries in JIRA for issues that do not exist in Toggl will be removed. This option can not be combined with the --append option
--rounding	Integer	All entries will be rounded to up the given minutes [2-60]
--filter	String	Filter in the format "filterName=filterValue" that entries must meet for synchronization. Multiple values can be declared, between filters with the same name is OR, between filters with different names is AND.
--dry-run	Boolean	Displays only change set and summary tables but do not synchronize anything
-n, --no-interaction	Boolean	Do not ask any interactive question, suitable for scheduled commands, etc.

Description format

Descriptions of time entries in Toggl must follow the following pattern:

<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

Supported filters

• issueCode
• workspaceId
• workspaceName
• projectId
• projectName

Filters example

Entries must be in the project "Demo" or "Demo2":

--filter "projectName=Demo" --filter="projectName=Demo2"

Entries must be in the workspace "My company" and must have the issue code "PROJ-123":

--filter "workspaceName=My company" --filter="issueCode=PROJ-123"

Limitations

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

Featured

See the How to Sync Toggl Entries to Jira article on Medium.

License

The package is distributed under the MIT License. See LICENSE for more information.