/toggl-to-jira

:clock3: :arrows_counterclockwise: Console application for synchronizing time entries from Toggl to Jira.

Primary LanguagePHPMIT LicenseMIT

Toggl to Jira

Console application for synchronizing time entries from Toggl into Jira.

Toggl to 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
  1. 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
--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.