AppleScript

AppleScript Reference

This page lists everything in Timemator's AppleScript dictionary: each command with its parameters and result, each class with its properties and elements, and each enumeration with its values. It is generated from the dictionary the app ships, so it matches the app.

On this page

Availability
Standard Suite
Commands
Classes
Enumerations
Error codes
Dictionary changelog
- Timemator 3.4.0
Related

If you are new to AppleScript, start with Using AppleScript with Timemator. For ready-made snippets grouped by task, see AppleScript Commands and Examples.

Address the app as tell application "Timemator". If you have several copies of the app, or renamed it, use the bundle identifier instead: tell application id "com.catforce.timemator.macos" for the version from timemator.com, tell application id "com.catforce.timemator-setapp" for the Setapp version. The same dictionary is also available inside Script Editor: choose File → Open Dictionary… and pick Timemator.

Availability#

AppleScript support is part of Timemator for Mac starting with Timemator 3.4.0. It needs macOS 12 or later, like the app itself. The dictionary is not available on iPhone, iPad, Apple Watch or Apple Vision Pro.

The dictionary has a version of its own, scripting version of the application, which is 1 in Timemator 3.4.0 and goes up whenever a term is added or changed (see the changelog). A script that needs a newer term can check scripting version ≥ 2 before using it. version of application "Timemator" is the app's version, not the dictionary's.

The version from timemator.com and the version from Setapp ship the same dictionary. Every command, class and property on this page works the same in both.

Reading never needs a license. Writing does: when a trial has expired, Timemator is in read-only mode and every command or property that would change your data fails with error 10001. Scripts can check the application's read only property before they write. The Setapp version has no trial and is never read-only.

Timemator must be running. tell application "Timemator" launches it when it is not; a script that wants to avoid that can check application "Timemator" is running first.

Standard Suite#

Every scriptable Mac app shares the Standard Suite, which macOS provides. Timemator binds three of its commands, make, delete and set, to its own folders, tasks and time entries, and delete to activity records; they are described in full below. count, exists, get, open and quit work as in any app. The remaining standard commands apply to documents and windows, which Timemator does not script, so they are of no use here.

Command	What it does in Timemator
`open`	Opens Timemator. Rarely needed: `tell application "Timemator"` launches it.
`close`	Not used. Timemator has no scriptable documents or windows to close.
`save`	Not used. Timemator saves every change itself.
`print`	Not used.
`quit`	Quits Timemator. A running timer keeps running: the app continues it on the next launch.
`count`	Counts elements: `count of tasks`, `count of time entries of task "Design"`, `count of (every task whose archived is true)`, `count of activity records`.
`duplicate`	Not used.
`exists`	Tests whether an object exists: `exists task "Design"`, `exists task id "…"`, `exists current task`, `exists activity record id "…"`.
`move`	Not used. Move a task or a folder by setting its `parent folder` or `position`; move a time entry by setting its `task`.
`delete`	Deletes a folder (with everything in it), a task (with its time entries), a time entry or an activity record. See below.
`make`	Creates a folder, a task or a time entry. See below.
`set`	Changes a writable property, or several at once with `set properties of … to {…}`. See below.

Command: `delete`#

Delete an object.

delete specifier

Parameters

Name	Type	Required	Description
direct parameter	`specifier`	yes	The object(s) to delete.

Result: none.

Since: Timemator 3.4.0

Errors: 10001, 10002, 10006, 10012, 10013

Example: Delete a task, Delete a time entry, Delete yesterday's activity records of an app

Command: `make`#

Create a new object.

make new type [at location specifier] [with data any] [with properties record]  → specifier

Parameters

Name	Type	Required	Description
`new`	`type`	yes	The class of the new object.
`at`	`location specifier`	no	The location at which to insert the object.
`with data`	`any`	no	The initial contents of the object.
`with properties`	`record`	no	The initial values for properties of the object.

Result: specifier. The new object.

Since: Timemator 3.4.0

Errors: 10001, 10005, 10011, 10012, 10014

Example: Create a folder, Create a time entry

Command: `set`#

Sets the value of the specified object(s). (Not shown in the dictionary viewer: set is built into AppleScript.)

set specifier to any

Parameters

Name	Type	Required	Description
direct parameter	`specifier`	yes
`to`	`any`	yes	The new value.

Result: none.

Since: Timemator 3.4.0

Errors: 10001, 10005, 10007, 10008, 10010, 10011, 10012, 10014

Example: Rename or edit a task, Edit a time entry, Mark time entries as billed

Standard classes#

The Standard Suite also defines the application class, which the Timemator Suite extends (see application below), and the document and window classes. Timemator has no scriptable documents; its windows are the standard Cocoa windows with name, bounds, visible, miniaturized and zoomed, which are of little use for time tracking. The standard application properties name, frontmost and version work: version of application "Timemator" tells you which version is installed.

application: Extended by the Timemator Suite, see below.
document: Not used. Timemator has no scriptable documents.
window: The app's windows with the standard properties (name, bounds, visible, …). To open or switch windows use show and open reports instead.

Commands#

The commands of the Timemator Suite, alphabetically. Every command runs inside a tell application "Timemator" block. A parameter in square brackets is optional; the text says what happens without it.

Command: `archive`#

Archives folders and tasks, like the task list's Archive: a folder's folders and tasks are archived with it. One undoable step.

archive node | list of node [moving to root boolean]

Parameters

Name	Type	Required	Description
direct parameter	`node` or list of `node`	yes	The folder or task, or a list of them.
`moving to root`	`boolean`	no	Move them to the top level too, where the task list's Archive puts them. False without it: they stay in their folders.

Result: none.

Since: Timemator 3.4.0

Errors: 10001, 10002, 10011

Example: Archive a task

Command: `clear timer`#

Forgets the current task and the current time entry: the timer goes idle. A running entry is paused first.

clear timer

Result: none.

Since: Timemator 3.4.0

Errors: 10001

Example: Clear the timer

Command: `create task`#

Creates a task by its path, like the Create Task shortcut: Clients/Acme/Design makes the folders Clients and Acme where they are missing and the task Design in Acme. Folders along the path are reused, and so is an active task of that name in the last folder, so a script can run again and get the same task; an archived task of the name is not reused. Names are compared exactly.

create task named text [in folder]  → task

Parameters

Name	Type	Required	Description
`named`	`text`	yes	The task's name, or folder names and the task's name separated by /.
`in`	`folder`	no	The folder the path starts in. The top level without it.

Result: task. The task, new or reused.

Since: Timemator 3.4.0

Errors: 10001, 10011

Example: Create a task

Command: `create time entry`#

Logs a time entry on a task. With replacing existing, the task's entries overlapping the range are deleted first, as one undoable step with the creation, so a calendar import can run again.

create time entry from date to date in task [with notes text] [billing status billing status] [replacing existing boolean]  → time entry

Parameters

Name	Type	Required	Description
`from`	`date`	yes	When it began.
`to`	`date`	yes	When it ended; must be after from.
`in`	`task`	yes	The task to log it on.
`with notes`	`text`	no	Its notes.
`billing status`	`billing status`	no	Its billing status; unbilled without one.
`replacing existing`	`boolean`	no	Delete the task's time entries that overlap the range first. False without it.

Result: time entry. The new time entry.

Since: Timemator 3.4.0

Errors: 10001, 10002, 10005, 10011

Example: Create a time entry, Import calendar events as time entries

Command: `export time entries`#

Writes the time entries that overlap a range to a CSV or PDF file, the file the Export window writes for the same settings. The entries are the ones find time entries answers for the same from, to, in, with billing status and including archived. Options of the other format are ignored.

export time entries from date to date to file file as export format [in list of node] [with billing status list of billing status] [including archived boolean] [group by grouping] [duration format duration format] [including notes boolean] [including revenue boolean] [including roundings boolean] [delimiter delimiter] [marking as billed boolean]  → file

Parameters

Name	Type	Required	Description
`from`	`date`	yes	The start of the range.
`to`	`date`	yes	The end of the range; must be after from.
`to file`	`file`	yes	The file to write; it is replaced when it exists.
`as`	`export format`	yes	CSV or PDF.
`in`	list of `node`	no	The folders and tasks to export; a folder stands for every task beneath it. The whole library without it.
`with billing status`	list of `billing status`	no	Only entries with one of these billing statuses. Any status without it.
`including archived`	`boolean`	no	Include the entries of archived tasks. False without it.
`group by`	`grouping`	no	PDF: none, date or task. By date without it.
`duration format`	`duration format`	no	PDF: hours and minutes or decimal. Hours and minutes without it.
`including notes`	`boolean`	no	CSV and PDF: a notes column. True without it.
`including revenue`	`boolean`	no	CSV and PDF: the revenue columns. True without it.
`including roundings`	`boolean`	no	CSV: the rounding columns. True without it.
`delimiter`	`delimiter`	no	CSV: comma, semicolon, colon or tab character. Semicolon without it.
`marking as billed`	`boolean`	no	Set the exported entries to billed once the file is written, like the Export window's option. One undoable step. False without it.

Result: file. The file written.

Since: Timemator 3.4.0

Errors: 10001, 10005, 10009

Example: Export time entries as CSV, Export a PDF report

Command: `find activity records`#

The activity records that overlap a date range, by begin date. The record being recorded counts when it began before to. Fetches only what it returns.

find activity records from date to date [with bundle identifier list of text]  → list of activity record

Parameters

Name	Type	Required	Description
`from`	`date`	yes	The start of the range.
`to`	`date`	yes	The end of the range; must be after from.
`with bundle identifier`	list of `text`	no	Only the records of this app, or of these apps: a bundle identifier or a list of them, compared exactly. Every app without it.

Result: list of activity record. The matching activity records, by begin date.

Since: Timemator 3.4.0

Errors: 10005

Example: Find activity records, Delete yesterday's activity records of an app

Command: `find time entries`#

The time entries that overlap a date range, by begin date. The running entry counts when it began before to. Fetches only what it returns.

find time entries from date to date [in list of node] [with billing status list of billing status] [including archived boolean]  → list of time entry

Parameters

Name	Type	Required	Description
`from`	`date`	yes	The start of the range.
`to`	`date`	yes	The end of the range; must be after from.
`in`	list of `node`	no	The folders and tasks to look in; a folder stands for every task beneath it. The whole library without it.
`with billing status`	list of `billing status`	no	Only entries with one of these billing statuses. Any status without it.
`including archived`	`boolean`	no	Include the entries of archived tasks. False without it.

Result: list of time entry. The matching time entries, by begin date.

Since: Timemator 3.4.0

Errors: 10005

Example: Find time entries for today, Find time entries in a date range

Command: `get time summary`#

A period's total duration, revenue and time entry count with each task's part, from the Reports window's calculation. Either a scope with a date in the period (the Reports window's day, week, month or year, the week from the first weekday of Preferences), or custom from one date to another. The time entries are the ones find time entries answers for the period and the same in, with billing status and including archived.

get time summary [scope report scope] [on date] [from date] [to date] [in list of node] [with billing status list of billing status] [including archived boolean]  → time summary

Parameters

Name	Type	Required	Description
`scope`	`report scope`	no	daily, weekly, monthly, yearly or custom. Custom without it.
`on`	`date`	no	daily, weekly, monthly, yearly: a date in the period; now without it.
`from`	`date`	no	custom: the start of the period. Custom needs it, the other scopes refuse it.
`to`	`date`	no	custom: the end of the period; must be after from. Custom needs it, the other scopes refuse it.
`in`	list of `node`	no	The folders and tasks to sum; a folder stands for every task beneath it. The whole library without it.
`with billing status`	list of `billing status`	no	Only entries with one of these billing statuses. Any status without it.
`including archived`	`boolean`	no	Include the entries of archived tasks. False without it.

Result: time summary. The period and its totals, as a record.

Since: Timemator 3.4.0

Errors: 10005

Example: Get today's total, Get a weekly summary per task

Command: `merge time entries`#

Merges time entries into one, like the merge panel: it begins at the earliest begin date and lasts their durations added up, their notes joined. The running entry can't be merged; pause first. One undoable step.

merge time entries list of time entry [into task] [filling gaps boolean]  → time entry

Parameters

Name	Type	Required	Description
direct parameter	list of `time entry`	yes	Two time entries or more.
`into`	`task`	no	The task of the merged entry. Their task without it; entries on different tasks need it.
`filling gaps`	`boolean`	no	Fill the time between them: the merged entry runs from the earliest begin date to the latest end. False without it.

Result: time entry. The merged time entry.

Since: Timemator 3.4.0

Errors: 10001, 10006, 10011

Example: Merge time entries

Command: `open reports`#

Opens the Reports window on a period: the day, week, month or year that contains a date. Timemator stays where it is among the apps; activate brings it to the front.

open reports scope report scope [on date]

Parameters

Name	Type	Required	Description
`scope`	`report scope`	yes	daily, weekly, monthly or yearly.
`on`	`date`	no	A date in the period; now without it.

Result: none.

Since: Timemator 3.4.0

Errors: 10011

Example: Open the Reports window

Command: `pause timer`#

Pauses the timer: the running time entry ends. An entry shorter than the drop threshold is discarded, as it is in the app. Nothing running is no error.

pause timer [at date]  → boolean

Parameters

Name	Type	Required	Description
`at`	`date`	no	When the entry ends; now without it. Must be after its begin date.

Result: boolean. Whether a time entry was running.

Since: Timemator 3.4.0

Errors: 10001, 10005

Example: Pause the timer

Command: `show`#

Brings the main window forward on Tracking with a folder, a task or a time entry selected. Timemator stays where it is among the apps; activate brings it to the front.

show node | time entry

Parameters

Name	Type	Required	Description
direct parameter	`node` or `time entry`	yes	The folder, task or time entry.

Result: none.

Since: Timemator 3.4.0

Errors: 10002

Example: Show an item in the main window

Command: `start timer`#

Starts tracking a task. Without for, the current task is continued; with no current task the command fails rather than creating one. A time entry running on another task is paused first. On the task already running it starts nothing and returns the running entry, like the Start Timer shortcut.

start timer [for task] [at date] [with notes text]  → time entry

Parameters

Name	Type	Required	Description
`for`	`task`	no	The task to track. The current task without it. An archived task is refused.
`at`	`date`	no	When the new entry begins; now without it. Not in the future.
`with notes`	`text`	no	The new entry's notes.

Result: time entry. The time entry being tracked.

Since: Timemator 3.4.0

Errors: 10001, 10003, 10004, 10005

Example: Start a timer, Continue the current task, Start a timer in the past

Command: `toggle timer`#

Pauses the timer when it runs, continues the current task when it does not. With no current task the command fails.

toggle timer  → boolean

Result: boolean. Whether the timer is running now.

Since: Timemator 3.4.0

Errors: 10001, 10004

Example: Toggle the timer

Command: `unarchive`#

Takes folders and tasks out of the archive, a folder's folders and tasks with it. One undoable step.

unarchive node | list of node [moving to root boolean]

Parameters

Name	Type	Required	Description
direct parameter	`node` or list of `node`	yes	The folder or task, or a list of them.
`moving to root`	`boolean`	no	Move them to the top level too, where the task list's Unarchive puts them. False without it.

Result: none.

Since: Timemator 3.4.0

Errors: 10001, 10002, 10011

Example: Archive a task

Classes#

Objects are addressed by reference: task "Design", task id "…", item 3 of root items, or the result of a command. A reference stays valid while the object exists, across statements and across launches. The id is the same on every Mac that syncs the library through iCloud.

Write access: a property marked r/w can be set with set … to …. Several properties of one object can be set at once with set properties of … to {name:"…", color:teal}, which Timemator saves as one change. Every change a script makes is one step on the Edit → Undo menu in Timemator and syncs like a change made in the app, except deleting activity records, which cannot be undone and stay on this Mac, as in the app.

Class: `application`#

Timemator's top-level scripting object.

Extends: the Standard Suite's application

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`root items`	list of `node`	r/o	The folders and tasks at the top level, in the order the task list shows them; the active ones first, then the archived ones.
`current task`	`task` or `missing value`	r/o	The task the timer is on, tracked, paused or merely selected; missing value when there is none. Read-only: start timer for t is the way to change it.
`current time entry`	`time entry` or `missing value`	r/o	The time entry the timer is tracking or has paused; missing value when there is none.
`timer state`	`timer state`	r/o	What the timer is doing.
`timer running`	`boolean`	r/o	Is a time entry being tracked right now?
`read only`	`boolean`	r/o	Is the app in read-only mode? With an expired trial it is, and nothing can be changed by script either.
`scripting version`	`integer`	r/o	The version of this dictionary, 1 for the first one. It goes up when a term is added or changed, so a script can check for what it needs; version of the application is the app's version.
`auto tracking enabled`	`boolean`	r/w	Is auto-tracking switched on? The switch of Preferences › Auto-tracking; setting it switches auto-tracking on or off. Auto-tracking also needs the Accessibility permission.
`selected item`	`node` or `time entry` or `missing value`	r/o	The time entry selected in the main window, else the folder or task selected there; missing value when nothing is selected or the window is closed.

Elements

folders (folder), by name, index, id, range, whose filter. Every folder, at any depth. Address one by id or by name, or filter with whose.
tasks (task), by name, index, id, range, whose filter. Every task, at any depth. Address one by id or by name, or filter with whose.
time entries (time entry), by index, id, range, whose filter. Every time entry of the library, by begin date. Address one by id; for a date range use find time entries, which fetches only what it returns, where a whose clause here walks every entry ever tracked.
rule sets (rule set), by index, id, range, whose filter. The rule set of every task that has one, for rule set id. A task's own is rule set of the task. Read-only.
rules (rule), by index, id, range, whose filter. Every auto-tracking rule of every rule set, a combination's rules included, for rule id. Read-only.
activity records (activity record), by index, id, range, whose filter. Every record of the activity log, by begin date. Address one by id; for a date range use find activity records, which fetches only what it returns, where a whose clause here walks every record ever recorded. Deleting records cannot be undone.

Responds to: count, exists, make, open, quit

Example: Read what is running, List folders and tasks, Check the dictionary version

Class: `node`#

A folder or a task. The abstract class of both; what a mixed list holds.

Plural: nodes

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id`	`text`	r/o	Its identifier, the same on every synced device.
`name`	`text`	r/w	Its name.
`path`	`text`	r/o	Where it lives: its folders and its name, joined with ›.
`parent folder`	`folder` or `missing value`	r/w	The folder it is in; missing value at the top level. Set it to move the item.
`position`	`integer`	r/w	Its place among its siblings, from 1. Set it to reorder.
`color`	`item color`	r/w	Its color. A folder's color is given to its tasks.
`archived`	`boolean`	r/o	Is it archived? Archiving goes through the archive command.
`billing`	`billing setting`	r/w	Its billing setting: its own, or inherited from its parent folder.
`billable`	`boolean`	r/o	Is it billable, once the inherited setting is resolved?
`hourly rate setting`	`real` or `missing value`	r/w	Its own hourly rate; missing value when it inherits its parent folder's.
`hourly rate`	`real`	r/o	The hourly rate that applies, once the inherited setting is resolved.
`total duration`	`real`	r/o	The tracked time in seconds, the running time entry included.
`last tracked`	`date` or `missing value`	r/o	When tracking on it last began; missing value when never.

Responds to: count, exists, set, archive, export time entries, find time entries, get time summary, show, unarchive

Example: List folders and tasks

Class: `folder`#

A folder of the task list.

Plural: folders · Inherits from: node

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id` (from `node`)	`text`	r/o	Its identifier, the same on every synced device.
`name` (from `node`)	`text`	r/w	Its name.
`path` (from `node`)	`text`	r/o	Where it lives: its folders and its name, joined with ›.
`parent folder` (from `node`)	`folder` or `missing value`	r/w	The folder it is in; missing value at the top level. Set it to move the item.
`position` (from `node`)	`integer`	r/w	Its place among its siblings, from 1. Set it to reorder.
`color` (from `node`)	`item color`	r/w	Its color. A folder's color is given to its tasks.
`archived` (from `node`)	`boolean`	r/o	Is it archived? Archiving goes through the archive command.
`billing` (from `node`)	`billing setting`	r/w	Its billing setting: its own, or inherited from its parent folder.
`billable` (from `node`)	`boolean`	r/o	Is it billable, once the inherited setting is resolved?
`hourly rate setting` (from `node`)	`real` or `missing value`	r/w	Its own hourly rate; missing value when it inherits its parent folder's.
`hourly rate` (from `node`)	`real`	r/o	The hourly rate that applies, once the inherited setting is resolved.
`total duration` (from `node`)	`real`	r/o	The tracked time in seconds, the running time entry included.
`last tracked` (from `node`)	`date` or `missing value`	r/o	When tracking on it last began; missing value when never.

Elements

folders (folder), by name, index, id, range, whose filter. Its folders, in the order the task list shows them.
tasks (task), by name, index, id, range, whose filter. Its tasks, in the order the task list shows them.
nodes (node), by name, index, id, range, whose filter. Its folders and tasks, in the order the task list shows them. Read-only.

Responds to: count, exists, make, delete, set, archive, create task, export time entries, find time entries, get time summary, show, unarchive

Example: Create a folder, Move a task into a folder

Class: `task`#

A task of the task list; what the timer tracks.

Plural: tasks · Inherits from: node

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id` (from `node`)	`text`	r/o	Its identifier, the same on every synced device.
`name` (from `node`)	`text`	r/w	Its name.
`path` (from `node`)	`text`	r/o	Where it lives: its folders and its name, joined with ›.
`parent folder` (from `node`)	`folder` or `missing value`	r/w	The folder it is in; missing value at the top level. Set it to move the item.
`position` (from `node`)	`integer`	r/w	Its place among its siblings, from 1. Set it to reorder.
`color` (from `node`)	`item color`	r/w	Its color. A folder's color is given to its tasks.
`archived` (from `node`)	`boolean`	r/o	Is it archived? Archiving goes through the archive command.
`billing` (from `node`)	`billing setting`	r/w	Its billing setting: its own, or inherited from its parent folder.
`billable` (from `node`)	`boolean`	r/o	Is it billable, once the inherited setting is resolved?
`hourly rate setting` (from `node`)	`real` or `missing value`	r/w	Its own hourly rate; missing value when it inherits its parent folder's.
`hourly rate` (from `node`)	`real`	r/o	The hourly rate that applies, once the inherited setting is resolved.
`total duration` (from `node`)	`real`	r/o	The tracked time in seconds, the running time entry included.
`last tracked` (from `node`)	`date` or `missing value`	r/o	When tracking on it last began; missing value when never.
`notes`	`text` or `missing value`	r/w	Its notes; missing value when it has none.
`being tracked`	`boolean`	r/o	Is the timer tracking it right now?
`auto tracking`	`boolean`	r/w	Are its auto-tracking rules on? Setting it on a task without rules is an error.
`rule set`	`rule set` or `missing value`	r/o	Its auto-tracking rules; missing value when it has none. Read-only: rules are edited in Timemator, and auto tracking switches them on and off.

Elements

time entries (time entry), by index, id, range, whose filter. Its time entries, by begin date, the running one included.

Responds to: count, exists, make, delete, set, archive, create time entry, export time entries, find time entries, get time summary, merge time entries, show, start timer, unarchive

Example: Create a task, Rename or edit a task, Set billing and hourly rate

Class: `time entry`#

A tracked span of time on a task. Make one with make new time entry with properties {begin date:d1, end date:d2} at end of time entries of task t, or with create time entry.

Plural: time entries

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id`	`text`	r/o	Its identifier, the same on every synced device.
`task`	`task`	r/w	The task it is on. Set it to move the entry to another task.
`begin date`	`date`	r/w	When it began. Must stay before the end date; on the running entry, not after now.
`end date`	`date` or `missing value`	r/w	When it ended; missing value while it is running. Setting it on the running entry pauses the timer at that date. It cannot be set to missing value: resuming goes through the start timer command. (Not end: AppleScript keeps that word for the end of a list.)
`duration`	`real`	r/o	Its length in seconds; counts up while it is running.
`original end date`	`date` or `missing value`	r/o	The end before rounding was applied; missing value when it was never rounded.
`being tracked`	`boolean`	r/o	Is it the time entry the timer is tracking right now?
`notes`	`text` or `missing value`	r/w	Its notes; missing value when it has none.
`billing status`	`billing status`	r/w	unbilled, billed or paid. Set it on a list of entries to mark a batch in one statement.
`billable`	`boolean`	r/o	Is it billable? Follows the task while unbilled, frozen once billed or paid.
`hourly rate`	`real`	r/o	Its hourly rate. Follows the task while unbilled, frozen once billed or paid.
`revenue`	`real`	r/o	Its revenue in currency units: the hourly rate times the duration, 0 when not billable.
`autotracked`	`boolean`	r/o	Was it started by auto-tracking?

Responds to: count, exists, make, delete, set, merge time entries, show

Example: List a task's time entries, Edit a time entry, Move a time entry to another task

Class: `rule set`#

The auto-tracking rules of a task and what they do. Read-only.

Plural: rule sets

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id`	`text`	r/o	Its identifier, the same on every synced device.
`active`	`boolean`	r/o	Are the rules on? The same switch as auto tracking of the task.
`start behavior`	`start behavior`	r/o	What happens when a rule matches: notify or start automatically.
`start delay`	`tracking delay`	r/o	How long a rule must match before that happens.
`pause behavior`	`pause behavior`	r/o	What happens when no rule matches any more: never, notify or pause automatically.
`pause delay`	`tracking delay`	r/o	How long no rule must match before that happens.

Elements

rules (rule), by index, id, range, whose filter. Its rules, in the order the rules window shows them; a combination is one rule with rules of its own. Read-only.

Responds to: count, exists

Example: Read a task's auto-tracking rules

Class: `rule`#

An auto-tracking rule, or a combination of rules that must all match (kind combination). A property that does not apply to the rule's kind is missing value. Read-only.

Plural: rules

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id`	`text`	r/o	Its identifier, the same on every synced device.
`active`	`boolean`	r/o	Is the rule on?
`kind`	`rule kind` or `missing value`	r/o	What it watches, or combination for a combination of rules.
`application path`	`text` or `missing value`	r/o	The application of an application rule.
`file path`	`text` or `missing value`	r/o	The file of a document rule, the folder of a folder rule.
`website url`	`text` or `missing value`	r/o	The address of a website rule.
`text`	`text` or `missing value`	r/o	What a window title, Slack or Skype rule looks for; the name or path pattern of a document rule.
`match`	`match mode` or `missing value`	r/o	How it compares: for a document rule path exactly, name containing, path containing, name matches regex or path matches regex; for a window title, website, Slack or Skype rule exactly, containing, starting with or ending with. missing value for an application or folder rule.
`in active window`	`boolean` or `missing value`	r/o	Does it look at the front window only?

Elements

rules (rule), by index, id, range, whose filter. The rules of a combination, in order; none for a plain rule. Read-only.

Responds to: count, exists

Example: Read a task's auto-tracking rules

Class: `time summary`#

What get time summary answers: a period's totals, as the Reports window shows them, and each task's part. A record, returned by value; it belongs to nothing and has no id.

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`scope`	`report scope`	r/o	daily, weekly, monthly, yearly or custom.
`begin date`	`date`	r/o	When the period begins: from for custom, else the start of the day, week, month or year. (Not from: AppleScript keeps that word.)
`end date`	`date`	r/o	When the period ends: to for custom, else the end of the day, week, month or year. (Not to: AppleScript keeps that word.)
`total duration`	`real`	r/o	The tracked time in the period in seconds, the running time entry included; an entry that overlaps an end counts with its part inside.
`total revenue`	`real`	r/o	The revenue of the billable time in the period, in currency units.
`time entry count`	`integer`	r/o	How many time entries the totals are made of.
`task totals`	list of `record`	r/o	One record per task with time in the period, in the order the task list shows them: {task:a reference to the task, duration:seconds, revenue:currency units}.

Example: Get a weekly summary per task

Class: `activity record`#

A record of the activity log: which app was in front, from when to when, with its window title and, for a browser or a document app, the website or the file. Read-only; delete removes records, and that cannot be undone.

Plural: activity records

Since: Timemator 3.4.0

Properties

Name	Type	Access	Description
`id`	`text`	r/o	Its identifier on this Mac. It stays the same across launches and changes when the activity log is rebuilt, by restoring a backup.
`begin date`	`date`	r/o	When it began.
`end date`	`date` or `missing value`	r/o	When it ended; missing value while it is being recorded.
`duration`	`real`	r/o	Its length in seconds; counts up while it is being recorded.
`recording`	`boolean`	r/o	Is it being recorded right now?
`bundle identifier`	`text`	r/o	The bundle identifier of the app, com.apple.Safari say.
`application name`	`text`	r/o	The app's name as the timeline shows it; the bundle identifier when the app is not installed.
`title`	`text` or `missing value`	r/o	The title of the front window; missing value when there was none.
`website url`	`text` or `missing value`	r/o	The address a browser showed; missing value for any other app.
`file path`	`text` or `missing value`	r/o	The path of the document a document app showed; missing value for any other app.

Responds to: count, exists, delete

Example: Find activity records, Delete yesterday's activity records of an app

Enumerations#

Enumeration values are written as bare words in a script, without quotes: set color of task "Design" to teal, if timer state is paused then ….

Enum: `timer state`#

What the timer is doing.

Since: Timemator 3.4.0

Value	Description
`idle`	No current task and no current time entry.
`idle with task`	A current task, but nothing is tracked.
`paused`	The current time entry is paused.
`running manually`	A time entry is being tracked; it was started by hand.
`running autotracked`	A time entry is being tracked; it was started by auto-tracking.

Enum: `billing setting`#

How a folder or a task is billed.

Since: Timemator 3.4.0

Value	Description
`inherited`	Billed like its parent folder.
`always billable`	Billable, whatever the parent folder is.
`never billable`	Not billable, whatever the parent folder is.

Enum: `billing status`#

Whether a time entry has been billed.

Since: Timemator 3.4.0

Value	Description
`unbilled`	Not billed yet; billable and hourly rate follow the task.
`billed`	Billed; billable and hourly rate are frozen.
`paid`	Billed and paid; billable and hourly rate are frozen.

Enum: `item color`#

The colors of the app's color set, by their names.

Since: Timemator 3.4.0

Value	Description
`white`
`gray`
`red`
`brown`
`orange`
`green2`
`green`
`teal`
`blue`
`violett`
`lightPink`
`indigo`
`lightRed`
`pink`
`yellow`
`lightGreen`
`cyan`
`lightBlue`
`lightViolett`
`lightIndigo`

Enum: `export format`#

The formats export time entries writes, the Export window's.

Since: Timemator 3.4.0

Value	Description
`CSV`	Comma-separated values, one row per time entry.
`PDF`	A time-tracking report: totals, a task summary and the time entries.

Enum: `grouping`#

How a PDF export groups its time entries.

Since: Timemator 3.4.0

Value	Description
`none`	One list, by begin date.
`date`	By day, each with its total.
`task`	By task, each with its total and notes.

Enum: `duration format`#

How a PDF export writes durations.

Since: Timemator 3.4.0

Value	Description
`hours and minutes`	Hours and minutes, 1:30.
`decimal`	Decimal hours, 1.50.

Enum: `delimiter`#

What separates the columns of a CSV export.

Since: Timemator 3.4.0

Value	Description
`comma`
`semicolon`
`colon`
`tab character`	A tab. (Not tab: AppleScript keeps that word for the tab text.)

Enum: `report scope`#

The period of a report, as the Reports window offers it.

Since: Timemator 3.4.0

Value	Description
`daily`	The day.
`weekly`	The week, starting on the first weekday of Preferences.
`monthly`	The month.
`yearly`	The year.
`custom`	A range of its own.

Enum: `start behavior`#

What auto-tracking does when a rule matches and the timer is not on the task.

Since: Timemator 3.4.0

Value	Description
`notify`	Ask first.
`start automatically`	Start the timer on the task.

Enum: `pause behavior`#

What auto-tracking does when no rule matches any more and the timer is on the task.

Since: Timemator 3.4.0

Value	Description
`never`	Keep tracking.
`notify`	Ask first.
`pause automatically`	Pause the timer.

Enum: `tracking delay`#

How long the rules must match, or must not match, before auto-tracking starts or pauses.

Since: Timemator 3.4.0

Value	Description
`immediately`	At once. A start delay only.
`ten seconds`	10 seconds. (A term can't begin with a number.)
`thirty seconds`	30 seconds.
`one minute`	1 minute.
`three minutes`	3 minutes.
`five minutes`	5 minutes.

Enum: `rule kind`#

What an auto-tracking rule watches.

Since: Timemator 3.4.0

Value	Description
`launched application`	An application is running, or is in front. (Not application: that is a class.)
`opened document`	A document is open. (Not document: that is a class.)
`opened folder`	A document in a folder is open. (Not folder: that is a class.)
`window title`	The title of a window.
`website`	The address a browser shows.
`slack`	A Slack workspace or channel.
`skype`	A Skype call or chat.
`combination`	A combination of rules that must all match; its rules are its rule elements.

Enum: `match mode`#

How a rule compares its text, or a document rule its file.

Since: Timemator 3.4.0

Value	Description
`exactly`	The text is the rule's text. (Not is: that is AppleScript's comparison.)
`containing`	The text contains the rule's text.
`starting with`	The text starts with the rule's text.
`ending with`	The text ends with the rule's text.
`path exactly`	The document's path is the rule's file path.
`name containing`	The document's name contains the rule's text.
`path containing`	The document's path contains the rule's text.
`name matches regex`	The document's name matches the rule's text as a regular expression.
`path matches regex`	The document's path matches the rule's text as a regular expression.

Error codes#

Timemator reports its own errors with numbers from 10001 to 10999 and a message in the app's language. Catch them with try … on error errorMessage number errorNumber and compare the number; the message is for people. Negative numbers come from AppleScript or macOS. See Error handling for a worked example.

Code	Message	Meaning	How to fix
10001	Timemator is in read-only mode. Open Timemator to continue tracking.	The trial has expired and Timemator is in read-only mode. Nothing can be changed, by script or in the app.	Activate a license, or restrict the script to reading. Check `read only` before writing.
10002	No folder, task or time entry has this id.	A reference by id names an object that is not in the library, for example a task that was deleted on another Mac, or an activity record id that is not one, or no longer is after a backup restore.	Look the object up again by name, or test with `exists task id "…"` first.
10003	This task is archived. Please select another task	`start timer for` was given an archived task.	`unarchive` the task first, or pick an active one (`whose archived is false`).
10004	The timer has no current task.	`start timer` without `for`, or `toggle timer`, found no current task to continue.	Name a task: `start timer for task "…"`.
10005	The date range is invalid: the end must be after the start.	A `to` that is not after `from`, an end date that is not after the begin date, a start date in the future (`start timer at`, or the `begin date` of the running time entry), or a `get time summary` without a usable period.	Check the dates; `current date` arithmetic with `days` and `hours` is the safest way to build them.
10006	The running time entry can't be deleted. Pause the timer first.	`delete` or `merge time entries` was given the time entry the timer is tracking.	`pause timer` first.
10007	A time entry can't be resumed by setting a property. Use the start timer command.	A script set `end date` of a time entry to `missing value`.	Use `start timer for (task of theEntry)` to track the task again.
10008	This task has no auto-tracking rules.	`auto tracking` was set on a task that has no auto-tracking rules.	Create rules for the task in Timemator first (Tracking → Edit Rules…).
10009	The export failed.	The exporter could not write the file; the reason follows the message (a missing folder, no permission, a disk that is full).	Check the path and the folder's permissions, then try again.
10010	archived can't be set. Archiving goes through the archive command.	A script set the `archived` property.	Use the `archive` or `unarchive` command.
10011	The change could not be saved.	Timemator refused or could not save the change; the reason follows the message (an empty name, a merge of fewer than two entries, `open reports` with scope `custom`, a time entry passed to `archive`).	Read the rest of the message; it names what was wrong.
10012	Auto-tracking rules can't be changed by script. Edit them in Timemator; auto tracking of the task switches them on and off.	A script tried to set, make or delete an auto-tracking rule set or rule.	Edit rules in Timemator. The `auto tracking` property of a task switches its rules on and off.
10013	The activity record being recorded right now can't be deleted.	`delete` was given the activity record that activity tracking is recording right now, the one whose `recording` is true.	Leave it out: add `recording is false` to the `whose` clause, or skip it in the loop. Once you switch to another app it ends and can be deleted.
10014	Activity records can't be changed by script. A script can read and delete them.	A script tried to set a property of an activity record, or to make one.	Activity records can only be read and deleted. They are recorded by activity tracking.

Errors that come from macOS rather than from Timemator:

Code	Message	Meaning	How to fix
-1743	Not authorized to send Apple events to Timemator.	macOS has not allowed the app that runs the script (Script Editor, Shortcuts, Terminal, …) to control Timemator, or you clicked Don't Allow.	Open System Settings → Privacy & Security → Automation and switch on Timemator under that app. See Permissions.
-1728	Can't get task "…".	A reference by name or index found nothing, for example a task of that name does not exist.	Check the spelling; use `exists task "…"` or a `whose` clause that may return an empty list.
-1712	AppleEvent timed out.	Timemator did not answer within the time limit, usually two minutes, or macOS is still waiting for you to answer the Automation permission dialog.	Answer the dialog. For long exports wrap the call in `with timeout of 600 seconds … end timeout`.
-1708	Timemator got an error: … doesn't understand the … message.	A command was sent to an object that cannot take it, for example `archive` on a time entry, or a term from another app's dictionary.	Check the command's parameters on this page.
-10006	Can't set … to ….	The property is read-only, or the script set a property on a list of references at once.	Check the Access column of the class; set the entries of a list one by one in a `repeat` loop.

Dictionary changelog#

Timemator 3.4.0#

First release of the Timemator Suite; scripting version is 1.
Classes application (extended), node, folder, task, time entry, rule set, rule, time summary and activity record.
Commands start timer, pause timer, toggle timer, clear timer, create task, create time entry, find time entries, archive, unarchive, merge time entries, show, open reports, export time entries, get time summary and find activity records; the Standard Suite's make, delete and set bound to folders, tasks and time entries, and delete to activity records.
Enumerations timer state, billing setting, billing status, item color, export format, grouping, duration format, delimiter, report scope, start behavior, pause behavior, tracking delay, rule kind and match mode.
Error numbers 10001 to 10014.

AppleScript Reference

Availability#

Standard Suite#

Command: delete#

Command: make#

Command: set#

Standard classes#

Commands#

Command: archive#

Command: clear timer#

Command: create task#

Command: create time entry#

Command: export time entries#

Command: find activity records#

Command: find time entries#

Command: get time summary#

Command: merge time entries#

Command: open reports#

Command: pause timer#

Command: show#

Command: start timer#

Command: toggle timer#

Command: unarchive#

Classes#

Class: application#

Class: node#

Class: folder#

Class: task#

Class: time entry#

Class: rule set#

Class: rule#

Class: time summary#

Class: activity record#

Enumerations#

Enum: timer state#

Enum: billing setting#

Enum: billing status#

Enum: item color#

Enum: export format#

Enum: grouping#

Enum: duration format#

Enum: delimiter#

Enum: report scope#

Enum: start behavior#

Enum: pause behavior#

Enum: tracking delay#

Enum: rule kind#

Enum: match mode#

Error codes#

Dictionary changelog#

Timemator 3.4.0#

Related#

Command: `delete`#

Command: `make`#

Command: `set`#

Command: `archive`#

Command: `clear timer`#

Command: `create task`#

Command: `create time entry`#

Command: `export time entries`#

Command: `find activity records`#

Command: `find time entries`#

Command: `get time summary`#

Command: `merge time entries`#

Command: `open reports`#

Command: `pause timer`#

Command: `show`#

Command: `start timer`#

Command: `toggle timer`#

Command: `unarchive`#

Class: `application`#

Class: `node`#

Class: `folder`#

Class: `task`#

Class: `time entry`#

Class: `rule set`#

Class: `rule`#

Class: `time summary`#

Class: `activity record`#

Enum: `timer state`#

Enum: `billing setting`#

Enum: `billing status`#

Enum: `item color`#

Enum: `export format`#

Enum: `grouping`#

Enum: `duration format`#

Enum: `delimiter`#

Enum: `report scope`#

Enum: `start behavior`#

Enum: `pause behavior`#

Enum: `tracking delay`#

Enum: `rule kind`#

Enum: `match mode`#