SA.Automate.Clockify

Clockify connection types and actions for Umbraco Automate. Start and stop timers, or log a completed time entry by duration or explicit dates, as part of an automation workflow.

What is Clockify?

Clockify is a time tracking service. This package uses its REST API, authenticated with a single API key, to log time entries.

What can this be used for?

This package is useful when you want time-tracking data inside an Umbraco Automate workflow, for example:

• Live tracking: start a timer when a workflow begins (e.g. "content editing started") and stop it when a later workflow finishes, letting Clockify compute the duration.
• Auto-logging by duration: log a completed entry whenever a workflow runs, allocating a number of seconds against a task, either a predefined/fixed duration or a value bound from a node property (e.g. a timeSpentInSeconds field the editor fills in before saving).
• Backfilling: log a completed entry for a fully-known historical time range, e.g. when importing or reconciling past work.

Installation

dotnet add package SA.Automate.Clockify

No further setup required. The composer registers itself automatically via Umbraco's IComposer discovery.

Connection types

This package registers a single Clockify connection type:

• API Key: required. The Clockify API key used by this connection.

Setup

1. Get an API key

Get your API key from Clockify's profile settings.

2. Store the key in appsettings.json (optional)

The connection's API Key field is marked sensitive, so instead of entering the key directly in the backoffice you can store it in appsettings.json and reference it using Umbraco Automate's configuration reference syntax:

{
  "Umbraco": {
    "Automate": {
      "Secrets": {
        "ClockifyApiKey": "your-api-key"
      }
    }
  }
}

The API Key field already defaults to $Umbraco:Automate:Secrets:ClockifyApiKey, so once this is set you can leave the field as-is when creating the connection below; no need to paste the reference in manually.

3. Create the connection in the backoffice

1. Go to Automate → Connections and create a new Clockify connection.
2. Give the connection a name and enter your API Key: either the key itself, or, if you stored it in appsettings.json above, the reference $Umbraco:Automate:Secrets:ClockifyApiKey (the field's default value).
3. Click Test connection to verify. This requests the current user to confirm the API key is valid.

Usage

All actions resolve the current user's active workspace automatically via the Clockify API, so there's no workspace or user ID to configure.

Project ID and required fields: Clockify workspaces can be configured to require a project (and/or task, tag, description) before any time entry can be saved. See Workspace Settings → Time Tracking → "Do not allow saving time without". If you leave Project ID blank on any of the actions below and get an error like "Project is either required field or given project is archived", either supply a valid, non-archived project ID or turn that workspace setting off. This is a Clockify workspace setting, not something these actions enforce.

Start Timer

Starts a running timer (a time entry with no end time) at the moment the step runs. Add the Start Timer action to any automation and select the connection to use. If you need to delay when it starts, use a delay/wait action earlier in the workflow; this action always starts now. Available fields:

Field	Description
Description	A description of the work being started. Supports ${ binding } expressions.
Project ID	Optional. The Clockify project ID to log the timer against. Supports ${ binding } expressions. See the note above if your workspace requires one.

The action outputs the following, which can be referenced via bindings in later workflow steps:

Output	Description
Id	The started time entry's unique ID.
Description	The time entry's description.
ProjectId	The Clockify project ID the timer was started against, if any.
Start	When the timer started.
RawResponse	The full, unprocessed JSON response returned by the Clockify API.

Stop Timer

Stops the current user's running timer at the moment the step runs. Clockify only allows one running timer per user, so there's no entry ID, project, description, or end time to supply; it takes no configuration and just acts on whatever's currently running, right now. Add the Stop Timer action to any automation and select the connection to use. If you need to delay when it stops, use a delay/wait action earlier in the workflow.

The action outputs the following, which can be referenced via bindings in later workflow steps:

Output	Description
Id	The stopped time entry's unique ID.
Description	The time entry's description.
ProjectId	The Clockify project ID the timer was logged against, if any.
Start	When the timer started.
End	When the timer ended.
DurationSeconds	The duration of the timer in seconds.
RawResponse	The full, unprocessed JSON response returned by the Clockify API.

If nothing is currently running, Clockify rejects the request and the action fails with Clockify's error message.

Create Time Entry by Duration

Logs a completed time entry from a known duration rather than an explicit start time. The entry always runs from (now - Duration) to now. Useful when you know how long something took but not its exact timestamps, e.g. allocating 5 minutes against a blog post whenever it's saved, even though the save event itself fires in under a second. Add the Create Time Entry by Duration action to any automation and select the connection to use. Available fields:

Field	Description
Description	A description of the work being logged. Supports ${ binding } expressions.
Duration (seconds)	How long the work took, in seconds. Supports ${ binding } expressions.
Project ID	Optional. The Clockify project ID to log the time entry against. Supports ${ binding } expressions. See the note above if your workspace requires one.

The action outputs the following, which can be referenced via bindings in later workflow steps:

Output	Description
Id	The created time entry's unique ID.
Description	The time entry's description.
ProjectId	The Clockify project ID the time entry was logged against, if any.
Start	When the time entry started.
End	When the time entry ended.
DurationSeconds	The duration of the time entry in seconds.
RawResponse	The full, unprocessed JSON response returned by the Clockify API.

Create Time Entry by Date

Logs a completed time entry from an explicit start and end date/time. Useful for backfilling or importing work whose timing is already fully known. Add the Create Time Entry by Date action to any automation and select the connection to use. Available fields:

Field	Description
Description	A description of the work being logged. Supports ${ binding } expressions.
Start	When the time entry starts. Format: yyyy-MM-dd HH:mm:ss. Defaults to now. Supports ${ binding } expressions.
End	When the time entry ends. Format: yyyy-MM-dd HH:mm:ss. Defaults to five minutes from now. Supports ${ binding } expressions.
Project ID	Optional. The Clockify project ID to log the time entry against. Supports ${ binding } expressions. See the note above if your workspace requires one.

The action outputs the following, which can be referenced via bindings in later workflow steps:

Output	Description
Id	The created time entry's unique ID.
Description	The time entry's description.
ProjectId	The Clockify project ID the time entry was logged against, if any.
Start	When the time entry started.
End	When the time entry ended.
DurationSeconds	The duration of the time entry in seconds.
RawResponse	The full, unprocessed JSON response returned by the Clockify API.

Compatibility

Package version	Umbraco Automate	Umbraco CMS
1.x	17.x – 18.x	17.x – 18.x

Links

• Source code
• Report an issue
• Clockify API documentation