From 18c65831c777d23ab1005b4cac789da711fc38ce Mon Sep 17 00:00:00 2001 From: Lukas Bindreiter Date: Wed, 15 Jul 2026 15:58:26 +0200 Subject: [PATCH] Update cron schedule documentation --- .../go/workflows/Clusters.Create.mdx | 17 ++- api-reference/go/workflows/Clusters.Get.mdx | 2 +- api-reference/go/workflows/Clusters.List.mdx | 2 +- .../go/workflows/Clusters.Update.mdx | 47 ++++++++ .../go/workflows/Workflows.PublishRelease.mdx | 2 +- .../go/workflows/Workflows.Update.mdx | 47 ++++++++ .../python/tilebox.workflows/Client.mdx | 7 ++ .../tilebox.workflows/ClusterClient.all.mdx | 2 +- .../ClusterClient.create.mdx | 22 +++- .../tilebox.workflows/ClusterClient.find.mdx | 2 +- .../ClusterClient.update.mdx | 40 +++++++ .../tilebox.workflows/JobClient.query.mdx | 5 + .../tilebox.workflows/WorkflowClient.all.mdx | 20 ++++ .../WorkflowClient.create.mdx | 32 ++++++ .../WorkflowClient.delete.mdx | 22 ++++ .../WorkflowClient.deploy_release.mdx | 40 +++++++ .../tilebox.workflows/WorkflowClient.find.mdx | 26 +++++ .../WorkflowClient.undeploy_release.mdx | 40 +++++++ .../WorkflowClient.unpublish_release.mdx | 28 +++++ .../WorkflowClient.update.mdx | 40 +++++++ docs.json | 11 ++ workflows/automations/cron.mdx | 107 ++++++++++++------ 22 files changed, 514 insertions(+), 47 deletions(-) create mode 100644 api-reference/go/workflows/Clusters.Update.mdx create mode 100644 api-reference/go/workflows/Workflows.Update.mdx create mode 100644 api-reference/python/tilebox.workflows/ClusterClient.update.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.all.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.create.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.delete.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.deploy_release.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.find.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.undeploy_release.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.unpublish_release.mdx create mode 100644 api-reference/python/tilebox.workflows/WorkflowClient.update.mdx diff --git a/api-reference/go/workflows/Clusters.Create.mdx b/api-reference/go/workflows/Clusters.Create.mdx index ff38145..1465657 100644 --- a/api-reference/go/workflows/Clusters.Create.mdx +++ b/api-reference/go/workflows/Clusters.Create.mdx @@ -8,6 +8,7 @@ icon: circle-nodes func (*ClusterClient) Create( ctx context.Context, name string, + options ...cluster.CreateOption, ) (*workflows.Cluster, error) ``` @@ -16,17 +17,25 @@ Create a cluster. ## Parameters - A display name for the cluster + A display name for the cluster. + + + Optional cluster description. + + + Optional cluster slug. If omitted, Tilebox generates a slug from the cluster name. ## Returns -The created cluster object. +The created cluster object, including its slug, name, description, whether it can be deleted, and deployed workflows. ```go Go -cluster, err := client.Clusters.Create(ctx, - "My cluster" +createdCluster, err := client.Clusters.Create(ctx, + "My cluster", + cluster.WithDescription("Development workloads"), + cluster.WithSlug("dev"), ) ``` diff --git a/api-reference/go/workflows/Clusters.Get.mdx b/api-reference/go/workflows/Clusters.Get.mdx index 099c540..066531c 100644 --- a/api-reference/go/workflows/Clusters.Get.mdx +++ b/api-reference/go/workflows/Clusters.Get.mdx @@ -21,7 +21,7 @@ Get a cluster by its slug. ## Returns -A cluster object. +A cluster object, including its slug, name, description, whether it can be deleted, and deployed workflows. ```go Go diff --git a/api-reference/go/workflows/Clusters.List.mdx b/api-reference/go/workflows/Clusters.List.mdx index d010df8..a98c512 100644 --- a/api-reference/go/workflows/Clusters.List.mdx +++ b/api-reference/go/workflows/Clusters.List.mdx @@ -12,7 +12,7 @@ Fetch all available clusters. ## Returns -A list of all available clusters. +A list of all available clusters. Each cluster includes its slug, name, description, whether it can be deleted, and deployed workflows. ```go Go diff --git a/api-reference/go/workflows/Clusters.Update.mdx b/api-reference/go/workflows/Clusters.Update.mdx new file mode 100644 index 0000000..a3b6214 --- /dev/null +++ b/api-reference/go/workflows/Clusters.Update.mdx @@ -0,0 +1,47 @@ +--- +title: Clusters.Update +sidebarTitle: Clusters.Update +icon: circle-nodes +--- + +```go +func (*ClusterClient) Update( + ctx context.Context, + slug string, + options ...cluster.UpdateOption, +) (*workflows.Cluster, error) +``` + +Update a cluster. + +## Parameters + + + The slug of the cluster to update. + + + Optional new display name for the cluster. + + + Optional new cluster description. Pass an empty string to clear the description. + + +## Returns + +The updated cluster object, including its slug, name, description, whether it can be deleted, and deployed workflows. + + +```go Go +updatedCluster, err := client.Clusters.Update(ctx, + "dev", + cluster.WithName("Development"), + cluster.WithDescription("Development workloads"), +) +``` + + +## Errors + + + The specified cluster does not exist. + diff --git a/api-reference/go/workflows/Workflows.PublishRelease.mdx b/api-reference/go/workflows/Workflows.PublishRelease.mdx index 43fb88e..d528222 100644 --- a/api-reference/go/workflows/Workflows.PublishRelease.mdx +++ b/api-reference/go/workflows/Workflows.PublishRelease.mdx @@ -29,7 +29,7 @@ Publish an immutable release for a workflow. ## Returns -The published workflow release. +The published workflow release, including any clusters where the release is deployed. ```go Go diff --git a/api-reference/go/workflows/Workflows.Update.mdx b/api-reference/go/workflows/Workflows.Update.mdx new file mode 100644 index 0000000..7016508 --- /dev/null +++ b/api-reference/go/workflows/Workflows.Update.mdx @@ -0,0 +1,47 @@ +--- +title: Workflows.Update +sidebarTitle: Workflows.Update +icon: diagram-project +--- + +```go +func (workflowClient) Update( + ctx context.Context, + slug string, + options ...workflow.UpdateOption, +) (*workflows.Workflow, error) +``` + +Update a workflow. + +## Parameters + + + The workflow slug. + + + Optional new display name for the workflow. + + + Optional new workflow description. Pass an empty string to clear the description. + + +## Returns + +The updated workflow object. + + +```go Go +updatedWorkflow, err := client.Workflows.Update(ctx, + "scene-processing", + workflow.WithName("Scene processing"), + workflow.WithDescription("Process new scenes into analysis-ready outputs."), +) +``` + + +## Errors + + + The specified workflow does not exist. + diff --git a/api-reference/python/tilebox.workflows/Client.mdx b/api-reference/python/tilebox.workflows/Client.mdx index 8ec93c4..2aed70f 100644 --- a/api-reference/python/tilebox.workflows/Client.mdx +++ b/api-reference/python/tilebox.workflows/Client.mdx @@ -54,6 +54,12 @@ def Client.clusters() -> ClusterClient A client for managing clusters. +```python +def Client.workflows() -> WorkflowClient +``` + +A client for managing workflows and workflow release deployments. + ```python def Client.automations() -> AutomationClient ``` @@ -96,6 +102,7 @@ client = Client( # access sub clients job_client = client.jobs() cluster_client = client.clusters() +workflow_client = client.workflows() automation_client = client.automations() # or instantiate a runner diff --git a/api-reference/python/tilebox.workflows/ClusterClient.all.mdx b/api-reference/python/tilebox.workflows/ClusterClient.all.mdx index 2a3a92b..ea004c1 100644 --- a/api-reference/python/tilebox.workflows/ClusterClient.all.mdx +++ b/api-reference/python/tilebox.workflows/ClusterClient.all.mdx @@ -11,7 +11,7 @@ List all available clusters. ## Returns -A list of all available clusters. +A list of all available clusters. Each cluster includes its slug, display name, description, whether it can be deleted, and deployed workflows. ```python Python diff --git a/api-reference/python/tilebox.workflows/ClusterClient.create.mdx b/api-reference/python/tilebox.workflows/ClusterClient.create.mdx index daccfdb..d3fe869 100644 --- a/api-reference/python/tilebox.workflows/ClusterClient.create.mdx +++ b/api-reference/python/tilebox.workflows/ClusterClient.create.mdx @@ -4,7 +4,11 @@ icon: circle-nodes --- ```python -def ClusterClient.create(name: str): Cluster +def ClusterClient.create( + name: str, + description: str | None = None, + slug: str | None = None, +) -> Cluster ``` Create a cluster. @@ -12,15 +16,25 @@ Create a cluster. ## Parameters - A display name for the cluster + A display name for the cluster. + + + Optional cluster description. + + + Optional cluster slug. If omitted, Tilebox generates a slug from the cluster name. ## Returns -The created cluster object. +The created cluster object, including its slug, display name, description, whether it can be deleted, and deployed workflows. ```python Python -cluster = cluster_client.create("My cluster") +cluster = cluster_client.create( + "My cluster", + description="Development workloads", + slug="dev", +) ``` diff --git a/api-reference/python/tilebox.workflows/ClusterClient.find.mdx b/api-reference/python/tilebox.workflows/ClusterClient.find.mdx index b442fd8..922ec67 100644 --- a/api-reference/python/tilebox.workflows/ClusterClient.find.mdx +++ b/api-reference/python/tilebox.workflows/ClusterClient.find.mdx @@ -17,7 +17,7 @@ Get a cluster by its slug. ## Returns -A cluster object. +A cluster object, including its slug, display name, description, whether it can be deleted, and deployed workflows. ```python Python diff --git a/api-reference/python/tilebox.workflows/ClusterClient.update.mdx b/api-reference/python/tilebox.workflows/ClusterClient.update.mdx new file mode 100644 index 0000000..7af9cad --- /dev/null +++ b/api-reference/python/tilebox.workflows/ClusterClient.update.mdx @@ -0,0 +1,40 @@ +--- +title: ClusterClient.update +icon: circle-nodes +--- + +```python +def ClusterClient.update( + cluster_or_slug: Cluster | str, + name: str | None = None, + description: str | None = None, +) -> Cluster +``` + +Update a cluster. + +## Parameters + + + The cluster or cluster slug to update. + + + Optional new display name for the cluster. If omitted, the display name is unchanged. + + + Optional new cluster description. Pass an empty string to clear the description. If omitted, the description is unchanged. + + +## Returns + +The updated cluster object, including its slug, display name, description, whether it can be deleted, and deployed workflows. + + +```python Python +cluster = cluster_client.update( + "dev", + name="Development", + description="Development workloads", +) +``` + diff --git a/api-reference/python/tilebox.workflows/JobClient.query.mdx b/api-reference/python/tilebox.workflows/JobClient.query.mdx index 83de44e..55b40e0 100644 --- a/api-reference/python/tilebox.workflows/JobClient.query.mdx +++ b/api-reference/python/tilebox.workflows/JobClient.query.mdx @@ -10,6 +10,7 @@ def JobClient.query( job_states: JobState | list[JobState] | None = None, name: str | None = None, task_states: TaskState | list[TaskState] | None = None, + clusters: Cluster | str | list[Cluster | str] | None = None, ) -> list[Job] ``` @@ -42,6 +43,9 @@ Query jobs in the specified interval. A task state or list of task states to filter jobs by. If specified, only jobs that have at least one task in any of the given states are returned. Useful for finding jobs with [optional](/workflows/concepts/tasks#optional-tasks) task failures, e.g. `task_states=TaskState.FAILED_OPTIONAL`. + + A cluster or list of clusters to filter jobs by. Pass actual cluster slugs or cluster objects. `None` and `[]` apply no cluster filter. Empty string cluster slugs are not accepted. + ## Returns @@ -50,5 +54,6 @@ A list of jobs. ```python Python jobs = job_client.query(("2025-01-01", "2025-02-01")) +jobs_on_cluster = job_client.query(("2025-01-01", "2025-02-01"), clusters="production") ``` diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.all.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.all.mdx new file mode 100644 index 0000000..8c2126b --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.all.mdx @@ -0,0 +1,20 @@ +--- +title: WorkflowClient.all +icon: diagram-project +--- + +```python +def WorkflowClient.all() -> list[Workflow] +``` + +List all workflows. + +## Returns + +A list of workflow objects. + + +```python Python +workflows = workflow_client.all() +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.create.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.create.mdx new file mode 100644 index 0000000..d950304 --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.create.mdx @@ -0,0 +1,32 @@ +--- +title: WorkflowClient.create +icon: diagram-project +--- + +```python +def WorkflowClient.create(name: str, description: str = "") -> Workflow +``` + +Create a workflow. + +## Parameters + + + The workflow display name. + + + Optional workflow description. + + +## Returns + +The created workflow object. + + +```python Python +workflow = workflow_client.create( + "Scene processing", + description="Process new scenes into analysis-ready outputs.", +) +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.delete.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.delete.mdx new file mode 100644 index 0000000..412b7ad --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.delete.mdx @@ -0,0 +1,22 @@ +--- +title: WorkflowClient.delete +icon: diagram-project +--- + +```python +def WorkflowClient.delete(workflow_or_slug: Workflow | str) -> None +``` + +Delete a workflow. + +## Parameters + + + The workflow or workflow slug to delete. + + + +```python Python +workflow_client.delete("scene-processing") +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.deploy_release.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.deploy_release.mdx new file mode 100644 index 0000000..6045a81 --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.deploy_release.mdx @@ -0,0 +1,40 @@ +--- +title: WorkflowClient.deploy_release +icon: diagram-project +--- + +```python +def WorkflowClient.deploy_release( + workflow_or_slug: Workflow | str, + release_or_id: WorkflowRelease | UUID | str, + clusters: Cluster | str | list[Cluster | str] | None = None, +) -> WorkflowReleaseDeployment +``` + +Deploy a workflow release to one or more clusters. + +## Parameters + + + The workflow or workflow slug containing the release to deploy. + + + The workflow release or release ID to deploy. + + + The cluster or clusters to deploy the release to. If omitted, the API uses the default cluster. + + +## Returns + +The deployment result, including the release and affected clusters. + + +```python Python +deployment = workflow_client.deploy_release( + workflow, + release.id, + clusters="production", +) +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.find.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.find.mdx new file mode 100644 index 0000000..b944886 --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.find.mdx @@ -0,0 +1,26 @@ +--- +title: WorkflowClient.find +icon: diagram-project +--- + +```python +def WorkflowClient.find(workflow_or_slug: Workflow | str) -> Workflow +``` + +Get a workflow by slug. + +## Parameters + + + The workflow or workflow slug to get. + + +## Returns + +A workflow object. + + +```python Python +workflow = workflow_client.find("scene-processing") +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.undeploy_release.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.undeploy_release.mdx new file mode 100644 index 0000000..900e555 --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.undeploy_release.mdx @@ -0,0 +1,40 @@ +--- +title: WorkflowClient.undeploy_release +icon: diagram-project +--- + +```python +def WorkflowClient.undeploy_release( + workflow_or_slug: Workflow | str, + release_or_id: WorkflowRelease | UUID | str, + clusters: Cluster | str | list[Cluster | str] | None = None, +) -> WorkflowReleaseDeployment +``` + +Remove a workflow release from one or more clusters. + +## Parameters + + + The workflow or workflow slug containing the release to remove from clusters. + + + The workflow release or release ID to remove from clusters. + + + The cluster or clusters to remove the release from. If omitted, the API uses the default cluster. + + +## Returns + +The result, including the release and affected clusters. + + +```python Python +deployment = workflow_client.undeploy_release( + workflow, + release.id, + clusters="production", +) +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.unpublish_release.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.unpublish_release.mdx new file mode 100644 index 0000000..1ad8bfe --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.unpublish_release.mdx @@ -0,0 +1,28 @@ +--- +title: WorkflowClient.unpublish_release +icon: diagram-project +--- + +```python +def WorkflowClient.unpublish_release( + workflow_or_slug: Workflow | str, + release_or_id: WorkflowRelease | UUID | str, +) -> None +``` + +Remove a workflow release from the set of published releases. + +## Parameters + + + The workflow or workflow slug containing the release to remove. + + + The workflow release or release ID to remove. + + + +```python Python +workflow_client.unpublish_release(workflow, release.id) +``` + diff --git a/api-reference/python/tilebox.workflows/WorkflowClient.update.mdx b/api-reference/python/tilebox.workflows/WorkflowClient.update.mdx new file mode 100644 index 0000000..9718205 --- /dev/null +++ b/api-reference/python/tilebox.workflows/WorkflowClient.update.mdx @@ -0,0 +1,40 @@ +--- +title: WorkflowClient.update +icon: diagram-project +--- + +```python +def WorkflowClient.update( + workflow_or_slug: Workflow | str, + name: str | None = None, + description: str | None = None, +) -> Workflow +``` + +Update a workflow. + +## Parameters + + + The workflow or workflow slug to update. + + + Optional new display name for the workflow. If omitted, the display name is unchanged. + + + Optional new workflow description. Pass an empty string to clear the description. If omitted, the description is unchanged. + + +## Returns + +The updated workflow object. + + +```python Python +workflow = workflow_client.update( + "scene-processing", + name="Scene processing", + description="Process new scenes into analysis-ready outputs.", +) +``` + diff --git a/docs.json b/docs.json index 6fb061b..c312721 100644 --- a/docs.json +++ b/docs.json @@ -256,9 +256,18 @@ "api-reference/python/tilebox.workflows/ProgressUpdate.add", "api-reference/python/tilebox.workflows/ProgressUpdate.done", "api-reference/python/tilebox.workflows/ClusterClient.create", + "api-reference/python/tilebox.workflows/ClusterClient.update", "api-reference/python/tilebox.workflows/ClusterClient.find", "api-reference/python/tilebox.workflows/ClusterClient.delete", "api-reference/python/tilebox.workflows/ClusterClient.all", + "api-reference/python/tilebox.workflows/WorkflowClient.create", + "api-reference/python/tilebox.workflows/WorkflowClient.all", + "api-reference/python/tilebox.workflows/WorkflowClient.find", + "api-reference/python/tilebox.workflows/WorkflowClient.update", + "api-reference/python/tilebox.workflows/WorkflowClient.delete", + "api-reference/python/tilebox.workflows/WorkflowClient.unpublish_release", + "api-reference/python/tilebox.workflows/WorkflowClient.deploy_release", + "api-reference/python/tilebox.workflows/WorkflowClient.undeploy_release", "api-reference/python/tilebox.workflows/AutomationClient.storage_locations", "api-reference/python/tilebox.workflows/AutomationClient.all", "api-reference/python/tilebox.workflows/AutomationClient.find", @@ -342,12 +351,14 @@ "api-reference/go/workflows/PollingTaskRunner.HasActiveTask", "api-reference/go/workflows/PollingTaskRunner.InterruptActiveTask", "api-reference/go/workflows/Clusters.Create", + "api-reference/go/workflows/Clusters.Update", "api-reference/go/workflows/Clusters.Get", "api-reference/go/workflows/Clusters.Delete", "api-reference/go/workflows/Clusters.List", "api-reference/go/workflows/Workflows.Create", "api-reference/go/workflows/Workflows.List", "api-reference/go/workflows/Workflows.Get", + "api-reference/go/workflows/Workflows.Update", "api-reference/go/workflows/Workflows.PublishRelease", "api-reference/go/workflows/Workflows.DeployRelease", "api-reference/go/workflows/Workflows.UndeployRelease", diff --git a/workflows/automations/cron.mdx b/workflows/automations/cron.mdx index 3d11b87..d5ba80d 100644 --- a/workflows/automations/cron.mdx +++ b/workflows/automations/cron.mdx @@ -6,8 +6,7 @@ icon: clock ## Creating Cron tasks -Cron tasks run repeatedly on a specified [cron](https://en.wikipedia.org/wiki/Cron) schedule. -In Python, use `tilebox.workflows.automations.CronTask` as your task base class instead of the regular `tilebox.workflows.Task`. In Go, register an executable task with the same task identifier as the automation prototype. +Cron tasks run repeatedly on a specified [cron](https://en.wikipedia.org/wiki/Cron) schedule. Define the task that the automation submits, then register its implementation with a runner. ```python Python @@ -39,10 +38,9 @@ func (t *MyCronTask) Execute(ctx context.Context) error { ``` -## Registering a Cron trigger +## Registering a cron trigger -After implementing a Cron task, register it to be triggered according to a Cron schedule. The Python SDK provides a registration helper, and you can also register cron automations from the Tilebox Console. -When the Cron expression matches, a new job is submitted consisting of a single task instance derived from the Cron task prototype. +After implementing a cron task, register it with one or more schedules. The Python SDK provides a registration helper, and you can also register cron automations from the Tilebox Console. Each matching schedule submits a new job containing one task instance derived from the cron task prototype. ```python Python from tilebox.workflows import Client @@ -53,24 +51,85 @@ cron_automation = automations.create_cron_automation( "my-cron-automation", # name of the cron automation MyCronTask(message="World"), # the task (and its input parameters) to run repeatedly cron_schedules=[ - "12 * * * *", # run every hour at minute 12 - "45 18 * * *", # run every day at 18:45 - "30 13 * * 3", # run every Wednesday at 13:30 + "*/15 * * * 1-5", # every 15 minutes on weekdays in UTC + "CRON_TZ=Europe/Vienna 0 9 * * 1-5", # 09:00 on weekdays in Vienna + "@daily", # every day at midnight UTC + "CRON_TZ=Europe/Vienna @daily", # every day at midnight in Vienna ], ) ``` - The syntax for specifying the cron triggers is a [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression). - A helpful tool to test your cron expressions is [crontab.guru](https://crontab.guru/). + Use [crontab.guru](https://crontab.guru/) to check standard five-field expressions. Remove any `CRON_TZ=...` prefix before entering an expression there. -## Starting a Cron runner +## Cron schedule syntax -With the Cron automation registered, a job is submitted whenever the Cron expression matches. But unless a [runner](/workflows/concepts/runners) is available to execute the Cron task the submitted jobs remain in a task queue. -Once an [eligible runner](/workflows/concepts/runners#task-selection) becomes available, all jobs in the queue are executed. +Cron triggers accept standard five-field expressions. The fields specify the minute, hour, day of the month, month, and day of the week in that order. + +```text +┌───────────── minute (0–59) +│ ┌─────────── hour (0–23) +│ │ ┌───────── day of month (1–31) +│ │ │ ┌─────── month (1–12 or JAN–DEC) +│ │ │ │ ┌───── day of week (0–6 or SUN–SAT; 0 is Sunday) +│ │ │ │ │ +* * * * * +``` + +Use `*` for every value, `,` for a list, `-` for a range, and `/` for a step. For example, `*/15 * * * *` runs every 15 minutes, while `0 9-17 * * 1-5` runs hourly from 09:00 through 17:00 on weekdays. + +If both day of month and day of week contain specific values, a trigger runs when either field matches. For example, `0 9 1 * MON` runs at 09:00 on the first day of every month and on every Monday. + +Schedules without an explicit timezone use UTC. Prefix a schedule with `CRON_TZ=` to interpret it in an [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones): + +```text +CRON_TZ=Europe/Vienna 0 9 * * 1-5 +``` + +This expression runs at 09:00 Vienna local time on weekdays. The corresponding UTC time changes automatically when Vienna enters or leaves daylight saving time. + + + Timezone schedules follow traditional cron behavior during daylight saving transitions. A local time skipped when clocks move forward does not trigger. A local time that occurs twice when clocks move backward triggers twice. + + +### Schedule helpers + +You can replace a five-field expression with one of these helpers. Helpers use UTC unless you add a `CRON_TZ` prefix. + +| Helper | Cron expression | Meaning | +| --- | --- | --- | +| `@yearly` or `@annually` | `0 0 1 1 *` | At midnight on January 1 | +| `@monthly` | `0 0 1 * *` | At midnight on the first day of each month | +| `@weekly` | `0 0 * * 0` | At midnight every Sunday | +| `@daily` or `@midnight` | `0 0 * * *` | At midnight every day | +| `@hourly` | `0 * * * *` | At the start of every hour | + +Timezone prefixes also work with helpers: + +```text +CRON_TZ=Europe/Vienna @daily +``` + +This schedule runs every day at midnight in Vienna. + +### Schedule examples + +| Schedule | Meaning | +| --- | --- | +| `0 * * * *` | At the start of every hour in UTC | +| `*/15 * * * *` | Every 15 minutes in UTC | +| `30 13 * * 3` | Every Wednesday at 13:30 UTC | +| `0 9 1 * MON` | At 09:00 UTC on every Monday and every first day of the month | +| `CRON_TZ=Europe/Vienna 0 9 * * 1-5` | At 09:00 Vienna time on weekdays | +| `@daily` | Every day at midnight UTC | +| `CRON_TZ=Europe/Vienna @daily` | Every day at midnight in Vienna | +| `@weekly` | Every Sunday at midnight UTC | + +## Starting a cron runner + +Cron tasks run on any regular [runner](/workflows/concepts/runners) that has the task registered. Keep at least one such runner available to execute jobs submitted by the automation. - ```python Python from tilebox.workflows import Client, Runner @@ -78,26 +137,6 @@ client = Client() runner = Runner(tasks=[MyCronTask]) runner.connect_to(client).run_forever() ``` -```go Go -ctx := context.Background() -client := workflows.NewClient() - -runner, err := client.NewTaskRunner(ctx) -if err != nil { - slog.ErrorContext(ctx, "failed to create task runner", slog.Any("error", err)) - return -} - -if err := runner.RegisterTasks(&MyCronTask{}); err != nil { - slog.ErrorContext(ctx, "failed to register tasks", slog.Any("error", err)) - return -} - -if err := runner.RunForever(ctx); err != nil { - slog.ErrorContext(ctx, "task runner stopped", slog.Any("error", err)) -} -``` - If this runner runs continuously, its logs may resemble the following: