Flow API: automations, reminders and expressions

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

27 min de leitura

Flow API: automations, reminders and expressions

An automation is a rule on an object type: a trigger (when), a condition (if) and actions (what to do). Like a schema or a process, a rule is stored in versions: the draft can be changed, a published version is immutable, and a new publication replaces the previous one. A due date rule — a reminder — is configured separately and can trigger automations. Conditions and computed values are written in the expression language, described at the end of this article.

General API rules — the address, keys, the X-Workspace-Id and Idempotency-Key headers, errors and pagination — are in Flow API: basics. For how rules look in the interface, see Flow: automations.

Methods

Method

Request

Permission

List a type's automations

GET /object-types/{type}/automations

automation.read

Create an automation (draft of version 1)

POST /object-types/{type}/automations

automation.manage

Read an automation

GET /automations/{id}

automation.read

Enable, disable, rename, change the executor

PATCH /automations/{id}

automation.manage

Create the next draft

POST /automations/{id}/versions

automation.manage

Read a version

GET /automation-versions/{id}

automation.read

Replace a draft entirely

PATCH /automation-versions/{id}

automation.manage

Publish a draft

POST /automation-versions/{id}/publish

automation.manage

Run log

GET /automation-runs

automation.read

A run with its actions

GET /automation-runs/{id}

automation.read

Retry a failed run

POST /automation-runs/{id}/retry

automation.execute

A type's reminder rules

GET /object-types/{type}/reminder-rules

automation.read

Create a reminder rule

POST /object-types/{type}/reminder-rules

automation.manage

Update a reminder rule

PATCH /reminder-rules/{id}

automation.manage

Delete a reminder rule

DELETE /reminder-rules/{id}

automation.manage

{type} is the key or id of an object type. Without permission to read the type's automations, the response is 404. All paths are relative to the base address https://flow.sensever.com/v1.

Commands that change a definition (create, PATCH on an automation, draft, publish) accept Prefer: return=minimal. The response is then a compact DefinitionResult (representation: "minimal", resource, id, version, status, href) with the header Preference-Applied: return=minimal. Without the preference you get the full definition if it is no larger than 64 KB, and the same compact result otherwise. Check the representation field; details are in Flow API: basics.

Automation and version

Automation

Field

Type

Description

id

UUID

Automation id

object_type_id

UUID

Object type

key

string

Machine name, ^[a-z][a-z0-9_]*$, up to 64 characters; unique within the type, immutable

name

string

Name, up to 200 characters

enabled

boolean

Whether it is enabled. A disabled automation does not fire

execution_principal_id

UUID

Service executor on whose behalf the actions run

current_version_id, current_version

UUID, AutomationVersion or null

Published version

draft_version_id, draft_version

UUID, AutomationVersion or null

Draft (at most one)

last_run

AutomationRun or null

Last run; only in the type's list

created_by, created_at, updated_at, archived_at


System timestamps

The list GET /object-types/{type}/automations returns {items, execution_principals, can_manage}: up to 200 non-archived automations (oldest first), active service executors ([{id, name}], empty without automation.manage) and a flag showing whether the caller can manage the type's rules.

AutomationVersion

Field

Type

Description

id, definition_id

UUID

The version and its automation

version

integer

Version number, starting from 1

status

string

draft, published or retired (replaced by a newer publication)

trigger_kind

string

Trigger kind, see below

trigger_config

object

Trigger parameters

condition

string or null

Condition expression

actions

array

Actions

created_by, created_at, published_by, published_at


System timestamps

Executor

Actions run on behalf of execution_principal_id — an active service member of the workspace — and with its permissions. When a workspace is created, Flow sets up such a member named "Automations" with the system integration role. Only a member with workspace.manage can set anyone other than themselves as the executor. A person cannot be the executor: 422 VALIDATION_FAILED with the code principal_not_service on the execution_principal_id field (principal_not_found and principal_inactive are the other reasons).

Creating and publishing

POST /object-types/{type}/automations

Field

Type

Required

Description

key

string

yes

Machine name

name

string

yes

Name, 1–200 characters

execution_principal_id

UUID

yes

Service executor

trigger_kind

string

yes

Trigger kind

trigger_config

object

no

Trigger parameters

condition

string or null

no

Condition, up to 4096 bytes; required for condition.became_true

actions

array

yes

1 to 20 actions

enabled

boolean

no

Defaults to true

The response is 201 — the automation with a draft of version 1. On save, the draft is checked only for shape; references to fields, statuses, relations and roles are checked on publish.

curl -X POST https://flow.sensever.com/v1/object-types/task/automations \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Idempotency-Key: automation-notify-overdue-1" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "notify_overdue",
    "name": "Overdue by more than 24 hours",
    "execution_principal_id": "0192a7c4-5b1e-7d3a-9f10-2c4b6d8e0a11",
    "trigger_kind": "condition.became_true",
    "condition": "now > data.due_date + duration('"'"'P1D'"'"') && state.category != '"'"'done'"'"'",
    "actions": [
      {
        "type": "send_notification",
        "recipients": [{"object": "owner"}, {"field": "watchers"}],
        "title": "Task is overdue",
        "body": "The due date passed more than 24 hours ago."
      }
    ]
  }'

POST /automation-versions/{id}/publish

Publishing compiles the condition and the action expressions, validates the trigger parameters, actions and executor, and builds the condition's dependency graph. The previously published version becomes retired, and the new one takes effect immediately for all objects of the type. No request body is needed.

The response is 200 — {version, warnings, fan_out, dependencies}:

Field

Description

version

Published version

warnings

Warnings [{path, code, message}]; they don't block publishing

fan_out

Estimate: how many objects one change to a related object will re-evaluate. Above 1000, re-evaluation runs as a background operation

dependencies

Number of condition dependencies

With Prefer: return=minimal — a compact result with definition_id, the first 50 warnings, warnings_total, fan_out and dependencies.

All definition errors come in a single 422 DEFINITION_INVALID response:

{
  "error": {
    "code": "DEFINITION_INVALID",
    "message": "…",
    "request_id": "0192a7c4-6a00-7c11-8e3f-5a1b2c3d4e5f",
    "details": {
      "errors": [
        {"path": "condition", "code": "UNKNOWN_FIELD", "message": "…", "line": 1, "column": 12},
        {"path": "actions[0].recipients[1].field", "code": "unknown_field", "message": "…"}
      ]
    }
  }
}

path points to the place in the definition (trigger_config.cron, condition, actions[2].url); expression errors also have line and column. Invalid use of now in a condition.became_true rule gets a separate response, 422 EXPRESSION_TIME_PATTERN_UNSUPPORTED.

Changes

  • PATCH /automation-versions/{id} replaces the draft entirely: body {trigger_kind, trigger_config?, condition?, actions}. A published or retired version cannot be changed — 409 DEFINITION_IMMUTABLE.

  • POST /automations/{id}/versions with the same body creates the next draft. If a draft already exists — 422 VALIDATION_FAILED with reason = draft_exists.

  • PATCH /automations/{id} changes only enabled, name and execution_principal_id. A disabled automation does not fire, and its dependencies are removed.

curl -X PATCH https://flow.sensever.com/v1/automations/$AUTOMATION_ID \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Triggers

trigger_kind

When it fires

trigger_config

object.created

an object of the type is created

—

object.updated

the object's data changed

fields — a list of field keys: fires if at least one changed

object.status_changed

the object changed status

to, from, transition — a key or a list of keys

object.archived

the object is archived

—

object.restored

the object is restored

—

condition.became_true

the condition became true (was false, or the object is new)

— ; condition is required

relation.added

a relation is added

relation_type — the relation key, side — from or to (the object's side)

relation.removed

a relation is removed

same

schedule

on a schedule

cron, timezone (both required), query

object.reminder_due

a due date reminder fired

rule, offset — a key or a list of keys

external.event

an external event was received via POST /events

event_type (required), source — a key or a list

process.event

an event of the object's process instance

events, process, step

All trigger_config parameters are optional unless stated otherwise: an empty filter matches any value.

schedule

  • cron — five fields minute hour day_of_month month day_of_week: *, lists, ranges, steps, JAN–DEC, SUN–SAT; or @yearly, @monthly, @weekly, @daily, @hourly. Seconds, L, W and # are not supported. More often than once every 5 minutes is an error, cron_too_frequent.

  • timezone — an IANA time zone, for example Europe/Berlin or UTC. Workspaces have no time zone of their own.

  • query — a {"where": …} filter over objects of the type (the query language, see Flow API: query language and search); {} means all objects. With query, the rule runs for each matching object, and the condition is checked for each one. Without query, there is a single run with no object: the condition is then forbidden, and the only allowed actions are create_object (without link and *_expr), call_webhook, send_notification and send_email.

A slot is a wall-clock time in timezone. A time skipped by the switch to daylight saving time runs once, shifted; a repeated time runs once, at its first occurrence. After downtime, only the last missed slot runs. A slot runs at most once per version and object. The number of objects per slot is limited by the workspace quota automation_schedule_objects_per_slot (10,000 by default).

Error codes: invalid_cron, cron_too_frequent, cron_never_fires, invalid_timezone, required; query errors are the same as in the query language, with the path trigger_config.query.where….

{
  "trigger_kind": "schedule",
  "trigger_config": {
    "cron": "0 9 * * mon-fri",
    "timezone": "Europe/Moscow",
    "query": {"where": {"field": "state.category", "op": "ne", "value": "done"}}
  },
  "condition": "now > data.due_date",
  "actions": [
    {"type": "send_notification", "recipients": [{"object": "owner"}], "title": "Overdue task", "body": "The task's due date has passed."}
  ]
}

external.event and process.event

  • external.event: the triggering object is the object whose id came in the external event's correlation_key; events without such an object are ignored. Expressions can use the event data event.* (source, external_event_id, event_type, correlation_key and the event payload). How to send events is described in Flow API: processes, approvals and external events.

  • process.event: events — any of started, completed, failed, cancelled, step_completed (all by default); process and step are keys. The triggering object is the instance's object; instances without an object don't trigger automations.

object.reminder_due

Fires when a due date reminder from the type's reminder rules comes due. rule and offset narrow the selection (unknown_reminder_rule, unknown_reminder_offset on publish). Event data: {rule_id, rule_key, offset_key, offset_kind, field, fields: {<field>: <due date>}, recipients}.

Condition

condition is an expression that returns true or false, up to 4096 bytes. The condition is checked against the object's current state at the moment of the run. A false condition gives a skipped run with condition_false; an evaluation error gives skipped with expression_error, and the actions don't run.

For condition.became_true, Flow stores the last value of the condition per object and runs the rule only when the value changes from false to true. Flow re-evaluates time comparisons (now > data.due_date) in such a rule on its own, so only the forms from the "Time in reactive rules" section are allowed.

Actions

Each action is an object with a type field and parameters. All actions except for_each_related run on the triggering object. An unknown parameter is an unknown_property error.

type

Parameters

Description

update_field

set: {field: value}, set_expr: {field: expression}, unset: [field] — at least one

Write, compute or clear fields (up to 200)

transition

transition (key), form_values: {}, reason (up to 1000 bytes)

Run a transition, checking guards and constraints

create_object

object_type, title or title_expr, fields: {}, fields_expr: {}, link: {relation, side?}

Create an object; link relates it to the triggering object, side is the new object's side

link, unlink

relation, object_id or object_expr, side (from by default — the triggering object's side)

Add or remove a relation

assign_owner

owner_id or owner_expr

Change the assignee

emit_event

event, payload: {} (up to 16 KB)

Emit a custom.<event> event for webhooks

start_process

process (key of a process of the same type), input: {}

Start a process for the object; the action key serves as start_key, so a retry doesn't create a second instance

call_webhook

url (https), method (POST, PUT, PATCH; POST by default), headers: {name: value}

An HTTPS request to your address

send_notification

recipients (1–100), title (up to 200 bytes), body (up to 4096 bytes), notify_actor

A notification in Sensever chat

send_email

same as send_notification

An email to members, see below

for_each_related

relation, where (optional), actions (1–10 nested)

Run the nested actions on each related object, see below

*_expr values are expressions evaluated on the triggering object; title_expr, object_expr and owner_expr must return a string. object_id and owner_id take a UUID. For object_id/object_expr and owner_id/owner_expr, exactly one of the pair is required.

The contract also lists add_comment. The current version doesn't execute it: publishing returns the error action_type_unsupported.

for_each_related

Iterates over the objects related to the triggering object and runs the nested actions on each of them. Example — when a sprint is closed, move unfinished tasks to the next sprint:

{
  "type": "for_each_related",
  "relation": "tasks",
  "where": "x.state.category != 'done'",
  "actions": [
    {"type": "unlink", "relation": "task_sprint", "object": "trigger"},
    {"type": "link", "relation": "task_sprint", "object_relation": "next_sprint"}
  ]
}

Here the "Sprint" type has a relation field tasks (the sprint's tasks) based on the task_sprint relation type, plus a sprint-to-sprint relation next_sprint ("next sprint", one-to-one). The nested unlink and link run on the task: it is unlinked from the closed sprint and linked to the next one. The rule's trigger is object.status_changed with trigger_config: {"to": "closed"}.

Parameter

Description

relation

A relations.<key> key of the triggering object's type, as in expressions: a relation field key or a relation type key (either side)

where

Optional condition up to 4096 bytes. The related object is x (x.id, x.data.*, x.state.key, x.state.category), and the triggering object's fields are data.*. Checked as relations.<key>.any(x, <where>): nested quantifiers and can_transition are not available in it

actions

1–10 nested actions: update_field, transition, assign_owner, link, unlink. They run on the related object; fields, transitions and *_expr are validated and evaluated against its type

In nested link and unlink, the second object is specified by exactly one of these parameters:

Parameter

Second object

object_id

A specific object

object_expr

An expression over the related object

"object": "trigger"

The triggering object

"object_relation": "<key>"

The single relations.<key> object of the triggering object. If there is none, the item error is TARGET_NOT_FOUND; if there is more than one, TARGET_AMBIGUOUS

side keeps its meaning — the side of the object the action runs on (here, the related object). In a nested assign_owner, you can pass "owner": "trigger" — the triggering object's assignee (if it has none, NO_OWNER).

Publishing errors: an unknown or archived relation — unknown_relation, a related object type without a published schema — type_not_published, a disallowed nested action — action_type_not_allowed. Error paths: actions[i].where, actions[i].actions[j].…. The action is unavailable in process steps and in schedule rules without query (action_type_unsupported, action_requires_object).

Execution:

  • No more than 200 related objects. If there are more, a permanent error RELATED_SET_TOO_LARGE occurs before any changes.

  • Each object is processed at a separate transaction point by regular commands with the rule executor's permissions: guards, constraints, audit and events work as for regular actions.

  • An archived object, an object the executor has no object.read permission for, and an object for which where is false are skipped (object_archived, not_visible, condition_false). An error evaluating where is an item error, EXPRESSION_ERROR.

  • A permanent item error rolls back only that object's changes; the other objects are still processed. If at least one object fails, the action ends as failed with the code FOR_EACH_ITEMS_FAILED, and the changes to successful objects remain. A transient error rolls back the whole action and is retried under the usual rules.

  • A processed object is marked with a key, so retrying the action or POST /automation-runs/{id}/retry doesn't process it a second time (replayed: true).

The action result in GET /automation-runs/{id} (actions[].result):

{
  "relation": "tasks",
  "total": 3,
  "succeeded": 2,
  "skipped": 1,
  "failed": 0,
  "items": [
    {"object_id": "…", "status": "succeeded"},
    {"object_id": "…", "status": "skipped", "reason": "condition_false"},
    {"object_id": "…", "status": "succeeded", "replayed": true}
  ]
}

A failed object in items[] has error: {code, message, details?, action_index} — the number of the nested action.

call_webhook

The address must be https only, up to 2048 bytes, with no username or password and no #fragment; the host is a name or a public IP, and internal network addresses are forbidden. Up to 20 custom headers, each value up to 1024 bytes; Content-Type, Content-Length, Host, Idempotency-Key, User-Agent, X-Flow-Automation and X-Flow-Run are reserved. Flow adds:

Idempotency-Key: <action key>
User-Agent: Sensever-Flow-Automation/1
X-Flow-Automation: <automation id>
X-Flow-Run: <run id>
Content-Type: application/json

Request body:

{
  "automation": {"id": "…", "key": "won_erp_webhook", "version_id": "…"},
  "run_id": "…",
  "action_index": 0,
  "idempotency_key": "…",
  "object_id": "…",
  "tenant_id": "…",
  "correlation_id": "…",
  "trigger": "object.status_changed",
  "event": {}
}

event is the data of the triggering event. A 2xx response means success. The timeout is 10 seconds, and redirects are not followed. 408, 429, 5xx and network errors are retried; other 4xx responses are permanent errors. A webhook may be delivered more than once, so discard duplicates by Idempotency-Key.

send_notification

A recipient in recipients is one of:

Value

Who receives it

"<principal_id>"

A specific member

{"role": "owner"}

Members with a system role: owner, admin, member or viewer

{"role_id": "<uuid>"}

Members with any workspace role

{"field": "watchers"}

People in the object's principal or multi_principal field

{"object": "owner"}

The object's assignee (owner) or author (creator)

Roles and fields are checked on publish and expanded into people before each delivery (no more than 500 people per action). Each recipient must be an active member, have permission to read the object and not have turned off notifications for this category or this automation in their settings; the recipient's quiet hours are respected. The message arrives in Sensever chat, in the "Sensever Flow" conversation; chat adds the link to the object itself, and field values are not included in the notification. If the recipient has enabled the email channel and the automations category in email_categories (see Flow API: workspace, access and notifications), the notification also arrives by email; if their chat channel is off but email is on, it arrives by email only. title and body are plain text; expressions in them are not evaluated.

The person whose action caused the triggering event doesn't get a notification about it. "notify_actor": true removes this exception. Changes made by an automation, a process, a schedule or a reminder have no author.

{
  "type": "send_notification",
  "recipients": [{"object": "creator"}, {"field": "watchers"}],
  "title": "Task completed",
  "body": "The task was moved to \"Done\".",
  "notify_actor": false
}

send_email

An email to workspace members — not to an arbitrary address. Parameters and recipients are the same as for send_notification: recipients (1–100), title (up to 200 bytes), body (up to 4096 bytes), notify_actor. The filters are the same too: the event's author, inactive members, members without permission to read the object, a muted workspace (muted), or the automations category or this automation turned off in personal settings. The email channel in the recipient's notification settings is not required: the rule itself asks for the email. But if the person has turned off notification emails in their personal mail settings (PATCH /me/mail-settings) or unsubscribed via the link in an email, the email is not sent.

The email isn't sent right away: the item joins the person's email queue. One notification email collects everything that arrived during that time and goes out no more than once every 15 minutes and not before the end of the recipient's quiet hours; one email holds up to 40 items, and the rest go in the next one. Before sending, Flow checks again that the person is a workspace member and can read the object. Emails are sent by Sensever Accounts to the account's verified address, and each one has a one-click unsubscribe link. How emails work is described in Flow: email and calendar subscription.

{
  "type": "send_email",
  "recipients": [{"object": "owner"}],
  "title": "Deal won",
  "body": "Prepare the contract and the invoice."
}

The action result in the run log is {channel: "email", recipients, emailed, skipped}: how many recipients there were after expansion, how many were queued for email, and why the rest were skipped (actor, inactive, no_access, muted, opted_out, no_account and others).

Execution and the run log

A run is created for each match between a rule and an event. Actions run in order:

  • actions inside Flow (update_field, transition, create_object, link, unlink, assign_owner, emit_event, start_process, for_each_related) — exactly once: the effect and the completion mark are written in a single transaction (for for_each_related, per object);

  • external actions (call_webhook, send_notification, send_email) — at least once. A retry of send_notification or send_email doesn't create a second message or email item: delivery is idempotent by action key and recipient.

A transient error (timeout, 5xx, unavailability) is retried up to 5 attempts with a delay of min(2^n × 5 s, 10 min) ± 20%, after which the action is dead. A permanent error (a 4xx from the external system other than 408 and 429; a guards or constraints rejection; PERMISSION_DENIED; EXPRESSION_ERROR) immediately gives failed. The run stops at the first failed or dead action.

A rule's actions produce events and can trigger other rules. The chain stops if the rule is already in it (AUTOMATION_CYCLE_DETECTED) or the depth reaches 5 (AUTOMATION_DEPTH_EXCEEDED).

GET /automation-runs

Runs, newest first, paginated (page[size] up to 200, page[cursor]). Query string filters:

Parameter

Description

automation_id

Only runs of this automation

object_type

Only automations of this type (key or id)

status

pending, running, succeeded, failed, skipped

object_id

Only runs for this object

curl "https://flow.sensever.com/v1/automation-runs?object_type=task&status=failed&page[size]=50" \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

The response is {items: [AutomationRun], page: {size, next_cursor}}.

AutomationRun

Field

Description

id, automation_id, version_id

The run, the automation and its version

object_id

The triggering object or null (a schedule without an object)

trigger_event_id, trigger_timer_id

The event or timer that caused the run

run_key

The run's uniqueness key

status

pending, running, succeeded, failed, skipped

skip_reason

For skipped: condition_false, condition_not_became_true, stale, expression_error, automation_disabled, object_not_found, object_archived, version_superseded

depth, correlation_id

Depth of the rule chain and the end-to-end id

error

For failed: {code, message, action_index, action_type, details?}

started_at, finished_at

Times

GET /automation-runs/{id} adds actions — the execution of each action: index, type, status (running, succeeded, failed, dead, skipped), attempts, result, error ({class: transient|permanent, code, message, details?}). For send_notification and send_email, result shows how many were delivered and why some recipients were skipped; for for_each_related, the outcome for each object (see above).

POST /automation-runs/{id}/retry

Resumes a run in failed status with the same run_key: failed and dead actions run again, completed ones don't. The response is the run with its actions. A run in any other status returns 422 RUN_NOT_RETRYABLE.

Due date reminders

A reminder rule is tied to a due date field of the type (date or datetime). For every object that has a due date, is not archived and is not in a status of category done or cancelled, one reminder is scheduled per offset of the rule. Moving the due date moves the reminder; clearing the due date, closing or archiving cancels it. A reminder that fires produces an object.reminder_due event and notifies the recipients once: in chat and, if the person has enabled email for the reminders category, by email.

ReminderRule

Field

Type

Required on create

Description

key

string

yes

Rule key; immutable

name

string

yes

Name, up to 200 characters

field

string

yes

Due date field: a date or datetime field of the current schema

timezone

string

yes

IANA time zone for wall-clock times

offsets

array

yes

1–10 offsets

recipients

object

no

{fields: [...], roles: [...]}

enabled

boolean

no

Whether it is enabled

The response also contains id, object_type_id, revision, created_by, created_at, updated_at and backfill_operation_id — the reminder_backfill background operation that recalculates reminders for existing objects (or null).

Offset (ReminderOffset): key, kind and parameters.

kind

When

Parameters

before

duration before the due date

duration, time

on_due

on the due date

time

overdue

duration after the due date (P0D by default)

duration, time

duration is an ISO 8601 subset P[nW][nD][T[nH][nM]], no more than 366 days. For a date field, only whole days and weeks are allowed; each offset fires at time on its day (09:00 by default), and overdue counts from the day after the due date. For datetime, the before and overdue offsets are exact, and only on_due has time.

Recipients: fields — up to 10 principal/multi_principal fields plus the system $owner and $creator; roles — up to 10 workspace role ids. Only active members who can read the object at the moment the reminder fires are notified; only those who can read the field see the due date value. Without recipients, a reminder only produces an event for automations.

curl -X POST https://flow.sensever.com/v1/object-types/task/reminder-rules \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Idempotency-Key: reminder-due-date-1" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "due_date",
    "name": "Task due date",
    "field": "due_date",
    "timezone": "Europe/Moscow",
    "offsets": [
      {"key": "day_before", "kind": "before", "duration": "P1D", "time": "10:00"},
      {"key": "overdue", "kind": "overdue", "duration": "P1D"}
    ],
    "recipients": {"fields": ["$owner", "watchers"]}
  }'

PATCH /reminder-rules/{id} changes the properties you pass; offsets and recipients are replaced as a whole. DELETE deletes the rule and cancels its future reminders; reminders that already fired stay in the history. The delete response is {id, deleted: true, backfill_operation_id}.

Errors are 422 VALIDATION_FAILED with details.fields[{field, code, messages}]: unknown_field, field_not_date, field_not_principal, unknown_role, required, invalid_timezone, invalid_duration, duration_must_be_days, invalid_time, not_allowed, duplicate_key, key_exists, unknown_property.

Expression language

Expressions define automation conditions, transition conditions (guards), restrictions (constraints), process branches and computed action values. The language is similar to CEL: short formulas without loops, variables or side effects.

data.amount.amount > 0 && data.contract_signed == true
relations.blocked_by.all(t, t.state.category == 'done')
state.key == 'prototype' && can_transition('ready_for_production')
now > data.due_date + duration('P1D')

Names

Name

What it is

In an automation condition

data.<field>

field value after the operation

yes

old.<field>

value before the operation (absent on create)

yes, except condition.became_true and schedule

changed('<field>')

whether the field changed

yes, except condition.became_true and schedule

object.id, object.type, object.title, object.owner, object.created_at, object.version

system attributes

yes

state.key, state.category

current status

yes

actor.id, actor.type

initiator; in an automation, the service executor

yes

actor.has_role('key'), actor.in_team('id')

initiator's role and team

yes

relations.<relation>…

related objects, only through quantifiers

yes

now

transaction time, UTC

yes; in condition.became_true only in the allowed pattern

event.<path>

triggering event data

yes, except condition.became_true and schedule

can_transition('key')

whether the transition is allowed right now

yes

target_state, transition

target status and transition key

guards and constraints only

context.<key>

process data

processes only

Values

Field type

In an expression

Example

string, enum, text, principal

string

data.stage == 'won'

number, integer

exact number

data.qty * 2 > 10

money

.amount — number, .currency — string

data.amount.amount >= 1000

boolean

true / false

data.contract_signed

date, datetime

date, instant (UTC)

data.due_date < now

multi_enum, multi_principal, tags

list of strings

'vip' in data.tags

checklist

summary: total, done, open — item counts, items — the items themselves

data.checklist.open > 0

json

any value

data.meta.priority == 'high'

Literals: 42, -7, 12.50, 1e3, 'string', "string", r'\d+' (raw string), true, false, null, [1, 2, 3]. Numbers are exact: 0.1 + 0.2 == 0.3 is true, and 7 / 2 gives 3.5.

Operators

In descending order of precedence: x.y, x[i], calls; !x, -x; *, /, %; +, - (also string and list concatenation, date ± duration); ==, !=, <, <=, >, >=, in; &&; ||; condition ? a : b. Comparisons can't be chained (1 < x < 10), and a single = is an error.

Functions

Function

Example

size(x)

size(data.tags) >= 2

is_empty(x)

!is_empty(data.lost_reason)

has(field)

has(data.meta.source)

lower(s)

lower(data.city) == 'london'

contains(s, x)

data.title.contains('urgent'), data.tags.contains('vip')

starts_with(s, prefix)

data.sku.starts_with('EU-')

matches(s, pattern)

matches(data.phone, r'^\+7\d{10}$')

duration('ISO 8601')

duration('PT4H'), duration('P1M')

date(...)

date(now) == data.due_date

changed('field')

changed('amount')

can_transition('key')

can_transition('unblock')

Regular expressions use a safe RE2-like set: no backreferences, no lookahead or lookbehind, repetitions up to 1000.

Quantifiers over relations

relations.<relation>.count()
relations.<relation>.exists()
relations.<relation>.any(x, condition)
relations.<relation>.all(x, condition)
relations.<relation>.none(x, condition)

Inside the condition, x.id, x.data.<field>, x.state.key and x.state.category are available. Quantifiers can't be nested. More than 200 related objects gives the error RELATED_SET_TOO_LARGE (except for exists()).

Empty values

An unset field behaves like null: data.x == null is true, data.x > 5 is false, is_empty(data.x) is true. data.flag == false with an unset flag is false — for "not checked", write !data.flag.

Time in condition.became_true

Flow re-evaluates such rules over time on its own, so now is allowed only in the form now <operator> data.<date-field> [± duration('…')] or its mirror, where the operator is <, <=, >, >=, and the field is date, datetime or object.created_at. Such a comparison can be combined with others through &&, ||, !.

Allowed

Not allowed

now > data.due_date + duration('P1D')

now - data.due_date > duration('P1D')

data.starts_at - duration('PT1H') < now

date(now) == data.due_date

now >= data.due_date && state.key != 'done'

now + duration('P1D') > data.due_date

For other time conditions, use the schedule trigger: there you can use now freely.

Errors and limits

Text up to 4 KB, nesting up to 32 levels, cost up to 10,000 units. On publish, all errors are returned at once, with line and column:

Code

Cause

SYNTAX_ERROR

unclosed bracket or string, = instead of ==, chained comparisons

UNKNOWN_IDENTIFIER, UNKNOWN_FIELD, UNKNOWN_RELATION, UNKNOWN_TRANSITION, UNKNOWN_FUNCTION

unknown name

TYPE_ERROR

incompatible types, for example data.amount > 0 for money

INVALID_ARGUMENT

duration('7 days'), changed(data.x)

INVALID_REGEX

invalid pattern

NOT_ALLOWED_IN_MODE

the name isn't available in this kind of rule

NESTED_QUANTIFIER

a quantifier inside a quantifier

SOURCE_TOO_LONG, AST_TOO_DEEP, COST_TOO_HIGH

limits exceeded

EXPRESSION_TIME_PATTERN_UNSUPPORTED

invalid now in condition.became_true

An evaluation error is always safe: for an automation condition, the run is skipped with expression_error; for a guard, the transition isn't allowed; for a constraint, the operation is forbidden.

Common mistakes

Written

Correct

data.amount > 0 (money)

data.amount.amount > 0

data.x = 1

data.x == 1

data.flag == false for "not checked"

!data.flag

data.company.tier == 'gold'

relations.company.any(c, c.data.tier == 'gold')

matches(data.code, '\d+')

matches(data.code, r'\d+')

changed(data.amount)

changed('amount')

Method errors

HTTP

error.code

When

404

NOT_FOUND

The type, automation or run doesn't exist, or you have no permission to read automations

403

PERMISSION_DENIED

No automation.manage, automation.execute, or workspace.manage for someone else as the executor

409

DEFINITION_IMMUTABLE

Changing or republishing a published version

422

VALIDATION_FAILED

Request shape: unknown trigger_kind, condition longer than 4096 bytes, not 1–20 actions, executor isn't a service member, key already taken (key_exists), a second draft (draft_exists)

422

DEFINITION_INVALID

Definition errors on publish, details.errors[{path, code, message}]

422

EXPRESSION_TIME_PATTERN_UNSUPPORTED

Invalid now in condition.became_true

422

RUN_NOT_RETRYABLE

Retrying a run that isn't in failed status

What's next

Comentários

Autores