Custom component that integrates basics of Toggl Track API with Home Assistant
GPL-3.0 License
NOTE: This is still a work in progress but it's functional enough for my needs. I'll be adding more features as I need them. Feel free to open an issue or PR if you have any suggestions.
This is a custom component for Home Assistant that integrates with Toggl Track. This repo is mostly the glue code between the lib-toggl library and Home Assistant. Any issues with the Toggl API should be reported to the lib-toggl repo.
Note As of now
lib-toggl
can't be safely installed into Home Assistant via HACS. See issue #1 for details on how to install it manually if you're so inclined.
Add this repo to HACS as a custom repository and then the integration can be installed from the HACS UI.
You can click the button below to open this repository in HACS or you can manually add it via the HACS UI.
This repo may eventually be added to the default HACS repository list but only once it's more stable. Until then, you'll need to add it as a custom repository using the instructions above.
Copy the custom_components/toggl_track
folder into your custom_components
folder and restart Home Assistant.
If everything worked, you should see a message like this in your Home Assistant logs:
WARNING (SyncWorker_2) [homeassistant.loader] We found a custom integration toggl_track which has not been tested by Home Assistant. This component might cause stability problems, be sure to disable it if you experience issues with Home Assistant
You can then add the integration via the UI.
After installing the integration, you'll need to add and configure it via the UI.
You will need to provide an API token and can optionally change how often the integration polls the Toggl Track API. The default is 60 seconds and should be fine for most people but can be adjusted as needed.
Assuming your API token works, you'll be shown a list of workspaces. Unless you're a premium user, you'll only have one workspace.
For each workspace that you select, a sensor will be created.
Note The icon for the integration will be the generic
icon not available
icon this is merged.
Note Each sensor requires POLLING the Toggl Track API. The default polling interval is 60 seconds. This means you may see a delay of up to ~60 seconds between when you start/stop a time entry and when the sensor updates to reflect the change.
This delay does not impact the create/stop services
The sensor will have the name/description for the current time entry for the account. This means that you may have multiple sensors - one for each workspace - but only one of them will have a value at any given time. (Note: Not quite correct; see issue #4)
The sensor's state
will be the description on the current time entry.
The attributes
will contain the rest of the time entry data.
There are two services for creating a new Time Entry and for stopping the current Time Entry. Both services can take either a workspace/Time Entry sensor entity ID or manually specified values.
toggl_track.new_time_entry
This service will create a new Time Entry.
You can either manually specify the workspace_id
or you can specify a workspace/Time Entry sensor entity ID in the workspace_id_entity_id
field.
service: toggl_track.new_time_entry
data:
description: Home Assistant Toggl Track Time Entry
tags:
- HomeAssistant
- Example
- For
- Screenshot
created_with: ha-toggl-track
workspace_id_entity_id: sensor.your_toggl_acc_name_here_workspace
If the workspace_id_entity_id
field is specified, the sensor must have a valid workspace_id
in it's attributes.
As of right now this is only possible when there is ALREADY a running time entry.
This is a known bug / should be addressed in the future.
If the time entry is created successfully, you'll get a response like this:
id: 1234567890
workspace_id: 7654321
project_id: null
task_id: null
user_id: 1234567
billable: false
created_with: lib-toggl
start: "2023-12-25T20:26:14Z"
stop: null
duration: -1
description: Home Assistant Toggl Track Time Entry
tag_action: add
tags:
- HomeAssistant
- Example
- For
- Screenshot
tag_ids:
- 12345727
- 12345728
- 12345729
- 12345730
And using another Toggl Track client, you'll see the new time entry
toggl_track.stop_time_entry
Docs for this service are coming soon; operates similar to the create time entry service, though.
toggl_track.edit_time_entry
Similar to new_time_entry
but meant for editing an existing time entry.
Internally, the Toggle API allows editing virtually every aspect of a time entry but I've chosen to only expose the description
and tags
fields for now as my use case doesn't require anything else.
This service will create tags if they do not yet exist in the workspace so you're free to add new tags as needed and not worry about creating them first.
This service will remove tags if needed but it will not delete them.
service: toggl_track.edit_time_entry
data:
description: Cleaning the house
tags: tag1,tag2,tag3
workspace_id_entity_id: sensor.your_toggl_track_workspace_name
workspace_id: 1234567
time_entry_id: 1234567