Connectors / Service / Toggl

The simplest time tracker to help you get things done. Ideal for teams, freelancers & agencies. (updated: 1633093467650)

Toggl

The simplest time tracker to help you get things done. Ideal for teams, freelancers & agencies.

Overview

Toggl is a time tracking app that allows you to track your daily activities across different platforms; providing you with detailed insights and an opportunity to optimise your workflow by identifying areas where you can improve.

Authentication

When using the Toggl connector, the first thing you will need to do is go to your Tray.io account page, and select the workflow you wish to work on. Once in the workflow dashboard itself, search and drag the Toggl connector from the connectors panel (on the left hand side) onto your workflow.

With the new Toggl connector step highlighted, in the properties panel on the right, click on 'New Authentication' which is located under the 'Settings' heading.

toggl-auth

This will result in a Tray.io authentication pop-up window, that should look like this:

toggl-popup

As you can see, besides from naming your authentication appropriately and selecting the purpose, you will need your 'API Token'. This can be found within your main Toggl dashboard profile settings.

Head to the bottom of your dashboard, and click on the "More options" button, which will look like your email details and account name. From there, a popup list of further options will appear, one of which is "Profile settings". Once you are on your profile page, scroll to the very bottom to get to the API section. Here You will have your token displayed.

toggl-profile-settings

Copy and paste said token into the Tray.io auth window.

Once you have clicked the 'Add authentication' button, go to back to your authentication field (within the workflow dashboard properties panel from earlier), and select the recently added authentication from the dropdown options now available.

Your connector authentication setup should now be complete.

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Note on Operations usage

Please note some fields on operations on the toggl connector will only be available on the paid plans. Features found in operations that are not available on a non-paid plan are:

  • Tasks

  • Billable projects and time entries

  • Report rounding

Pagination

An additional field, 'Page' exists on this operation which can be used for pagination. Regardless of the time period chosen or how many time entries will be fetched for the report, only 50 items will be returned at a time. This only applies when 'Format' is set to JSON. If requesting CSV or PDF reports, then all items are returned.

When requesting the report as JSON, the property total_count shows how many results in total are to be returned. The output property per_page will always show 50.

For example, if there a total of 200 time entries in the result set, the first call will fetch the first 50. By incrementing the 'Page' field to 2, the next 50 items (items 51-100) can be retrieved.

Retrieving a weekly report

A weekly report of time entries can be retrieved in JSON, CSV or PDF format. This can be selected in the 'Output format' field. Please be aware that choosing CSV or PDF format will result in a file object being returned.

Output format field

If JSON is returned, then this will return the data that will be visible directly in the debug logs (see below, bottom screenshot).

File output for CSV or PDF format
JSON output

Output of JSON is structured by providing lists (arrays) of days. In each list there will be 8 items, for 7 days of the week plus the total for the week. Where no time entries occurred on a certain day, the value will be null.

Weekly time entries JSON example

In the screenshot above, there was a time entry only on one day. The value at the bottom is the total for the week.

The time period that is selectable for weekly reports will always be 7 days. The 'Since' date field can be set to specify when from. If this is left blank it defaults to a week ago from today.

Time entry results can be grouped by project or users in the 'Grouping' field.

The values of time entries can be shown as duration or earnings (earnings only available for billable time entries) by setting the 'Calculate' field.

Results can be filtered by adding the IDs of entities (such as projects or users) to the corresponding input fields.

The 'User IDs' list can be limited or extended by the 'Members of group IDs' and 'All members of group IDs' fields.

'Members of group IDs' will mean that only users that belong to the provided group ID will be returned. If a user ID is provided in 'User IDs' that doesn't belong to a specified group ID in this field, that user will not show in the results.

'All members of group IDs' means returning results for all members (users) that belong to the group IDs specified in this input field, regardless of what is entered in the 'User IDs' field.

'Display hours' only takes effect when retrieving results as CSV format.

Retrieving a detailed report

A detailed report returns a list of time entry items that have more detailed than the summary or weekly reports.

Many of the filtering options are the same as the weekly report operation, with the ability to also set an 'Until' date, which together with the 'Since' date field allows for fetching of data over a custom time period.

Specifying time period using since and until

Example Usage

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the Toggl connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

Below is an example of a way in which you could potentially use the Toggl connector, to get a detailed report on our available projects. We have also added in a create/ list latest time entry section just for the sake of practice.

The steps will be as follows:

  1. Setup a manual trigger and list all available projects.

  2. Create a time entry and get a detailed report of said entry.

  3. List all time entries available (including the newest one).

The final outcome should look like this:

toggl-complete-workflow

1 - Setup trigger & List all Projects

Once you have clicked 'Create new workflow' on your main Tray.io dashboard (and named said new workflow), select the Manual trigger from the trigger options available:

toggl-manual-trigger

Once you have been redirected to the Tray.io workflow dashboard, from the connectors panel on the left, add a Toggl connector to your second step. Set the operation to 'List projects'.

You will need to provide your 'Workspace ID'. To get a workspace ID, open the workspace in your browser and look at the URL in the address bar. ID is the integer after edit/. It should be about 7 numbers in total.

Example: https://www.toggl.com/app/workspaces/edit/{workspaceID}/

Make sure to tick the 'Project state' box option, and 'Project time' if you want to be even more specific about what is returned from your project list.

toggl-step-1

Feel free to re-name your steps as you go along to make things clearer for yourself and other users.

2 - Create a time entry & get Report Details

Add another Toggl conenctor to your workflow and set the operation to 'Create time entry'.

You will notice that both a 'Description', 'Start time' and a 'Duration' are required fields. Make sure to enter your fields appropriately, aka, use the dropdown calendar to make sure your time is in the correct format and that your duration is input in SECONDS.

You will again need your 'Workspace ID', only this time you can have it auto-generated by using the connector-snake to create the jsonpath required.

JSONPATHS: For more information on what jsonpaths are and how to use jsonpaths with Tray.io, please see our Intro page and Data Guide for more details.

CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

toggl-step-2

The third Toggl connector step is very similar to the previous one. Make sure to set the operation to 'Get detailed report', and generate your workspace ID in the same fashion. The required field here is the 'User agent' in question. You will need the individual's email address in this case.

The 'Project ID' is taken from the first project off of the list we created earlier. This is why the connector-snake's output here references the first in the array: [0].

_If you are interested in getting the results from all of the listed projects, you could expand this workflow by adding a 'Loop collection' connector step. For more details please visit the Loop docs page.

toggl-step-3

3 - Get Time Entry

Finally, on your last Toggl connector step, set the operation to 'Get time entry'. Here you will once more use the connector-snake to auto-generate the jsonpath, this time connecting it to the second Toggl connector within the workflow.

toggl-step-4

BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our managing data best practices guide.

All Operations

Latest version:

2.0

List workspace groups

This operation allows you to retrieve a list of groups for a specified workspace.

Get detailed report

This operation allows you to retrieve a report of detailed time entries.

Delete multiple projects

This operation allows you to delete multiple projects.

Create time entry

This operation allows you to create a time entry.

Create project

This operations allows you to create a project.

Delete project

This operation allows you to delete a project.

Get client details

This operation allows you to get a client.

Get project

This operation allows you to get a project by ID.

List workspaces DDL

List client projects

This operation allows to get the projects for one client.

List clients

This operation allows you to get a list of the clients.

List clients DDL

This operation allows you to get a list of the clients.

List time entries DDL

List project users

This operation allows you to get the users for a project.

List time entries

This operation allows you to list all the time entries. If start and end date are specified then it will return the time entries between those dates. If they are not specified, time entries started during the last 9 days are returned

List workspaces

This operation gets data about all the workspaces where the token owner belongs to.

Start time entry

This operation allows you to start a time entry.

Update client

This operation allows you to update the client name and add notes if wanted.

List workspace tasks

This operation allows you to retrieve a list of tasks for a specified workspace.

Delete time entry

This operation allows you to delete a time entry.

Create client

This operation allows you to create a client.

Delete client

This operation allows you to delete a client.

Get time entry

This operation allows you to get the details from a time entry.

List workspace users DDL

Retrieve list of users for a specified workspace

Stop time entry

This operation allows you to stop a time entry.

Update multiple time entries

This operation allows you to update multiple time entries.

Update time entry

This operation allows you to update a time entry

Update project

This operations allows you to update the project data.

List workspace groups DDL

Retrieve list of groups for a specified workspace

List workspace tags DDL

Retrieve list of tags for a specified workspace

List workspace tasks DDL

Retrieve list of tasks for a specified workspace

List projects DDL

This operation allows you to get a list of the projects on the workspace.

Get weekly report

This operation allows you to retrieve the weekly report of time entries. Will return 7 days worths of data beginning from the chosen Since date.

Get project dashboard report

This operation allows you to get dashboard information for a project. Only available with paid Toggl plans.

List workspace tags

This operation allows you to retrieve a list of tags for a specified workspace.

List workspace users

This operation allows you to retrieve a list of users for a specified workspace.

Get summary report

This operation allows you to retrieve a summary report of time entries.

List projects

This operation allows you to get a list of the projects on the workspace.