Skip to content

Latest commit

 

History

History
119 lines (84 loc) · 5.74 KB

README.md

File metadata and controls

119 lines (84 loc) · 5.74 KB
Raw

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.