> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# automation
> sift/automation/v1/automation.proto
## Services
*RPC methods exposed by this API.*
### AutomationService
AutomationService manages Canvas Scheduler automation triggers. An
automation trigger fires when a producer (v1: RunService.StopRun)
observes a Run whose metadata matches the trigger's match filter; the
resulting automation\_triggered\_events row is dispatched by the
automation worker after a bounded wait, currently by calling
CanvasService.EvaluateCanvas.
| Method | Request | Response | Description |
| :---------------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetAutomationTrigger | [GetAutomationTriggerRequest](#getautomationtriggerrequest) | [GetAutomationTriggerResponse](#getautomationtriggerresponse) | Retrieve an automation trigger by ID. |
| CreateAutomationTrigger | [CreateAutomationTriggerRequest](#createautomationtriggerrequest) | [CreateAutomationTriggerResponse](#createautomationtriggerresponse) | Create an automation trigger. |
| UpdateAutomationTrigger | [UpdateAutomationTriggerRequest](#updateautomationtriggerrequest) | [UpdateAutomationTriggerResponse](#updateautomationtriggerresponse) | Update select fields of an existing automation trigger. To enable or disable a trigger set the `is_enabled` field and include `is_enabled` in the update mask. |
| ListAutomationTriggers | [ListAutomationTriggersRequest](#listautomationtriggersrequest) | [ListAutomationTriggersResponse](#listautomationtriggersresponse) | Retrieve and optionally filter a list of automation triggers. |
| DeleteAutomationTrigger | [DeleteAutomationTriggerRequest](#deleteautomationtriggerrequest) | [DeleteAutomationTriggerResponse](#deleteautomationtriggerresponse) | Delete an automation trigger. Soft-delete: sets `archived_date` and hides the trigger from further producer matches. Historical `automation_triggered_events` rows survive for the retention window so past dispatches can still be inspected. |
| ListAutomationTriggeredEvents | [ListAutomationTriggeredEventsRequest](#listautomationtriggeredeventsrequest) | [ListAutomationTriggeredEventsResponse](#listautomationtriggeredeventsresponse) | Retrieve and optionally filter a list of automation triggered events (per-trigger dispatch history). Filter by `automation_trigger_id` to power the canvas trigger history sidebar, or by `state == FAILED` for the manage jobs automation errors tab. Match/config and dispatch failures set `last_error`. |
## Messages
*Data models used across requests/responses.*
### AutomationTrigger
| Field | Type | Label | Description |
| :------------------------------ | :-------------------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| automation\_trigger\_id | string | | |
| organization\_id | string | | |
| canvas\_id | string | | |
| name | string | | |
| match\_filter | [AutomationTriggerMatchFilter](#automationtriggermatchfilter) | | |
| user\_id | string | | Impersonation user materialized at create time. Recheck happens at dispatch when the automation worker impersonates this user for the EvaluateCanvas call. |
| action\_kind | [AutomationTriggerActionKind](#automationtriggeractionkind) | | |
| action\_params | [AutomationTriggerActionParams](#automationtriggeractionparams) | | Typed template action params. Must agree with `action_kind` (e.g. CANVAS\_EVALUATION requires `action_params.canvas_evaluation`). The match job resolves wildcards into automation\_triggered\_events.action\_params\_snapshot; the automation worker pass-throughs that snapshot to EvaluateCanvas. |
| is\_enabled | bool | | |
| archived\_date | google.protobuf.Timestamp | optional | |
| is\_archived | bool | | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| created\_by\_user\_id | string | | |
| modified\_by\_user\_id | string | | |
| email\_notifications\_enabled | bool | | When true, dispatches also send an email to notification\_recipient\_emails. The in-app notification to the trigger's creator is always created. Defaults to true. |
| notification\_recipient\_emails | string | repeated | Addresses emailed when this trigger dispatches. Plain addresses rather than user ids, so reports can reach shared inboxes, ticket bots and distribution lists. Empty falls back to the creator's address. |
### AutomationTriggerActionParams
AutomationTriggerActionParams is the public action\_params shape. oneof by
action kind so future dispatch types (webhook, email, ...) don't fall back
to google.protobuf.Struct.
| Field | Type | Label | Description |
| :----------------------------- | :------------------------------------------------------------ | :---- | :---------- |
| oneof kind. canvas\_evaluation | [CanvasEvaluationActionParams](#canvasevaluationactionparams) | | |
### AutomationTriggerMatchFilter
AutomationTriggerMatchFilter is the selector evaluated asynchronously
after StopRun. StopRun inserts an automation\_source\_event (RUN\_STOP); the
automation\_worker then pages through the org's enabled, non-archived
automation\_triggers and enqueues a row for each trigger whose
match\_filter accepts the run (the trigger's canvas\_id identifies which
canvas to evaluate later — runs themselves have no canvas association).
Empty asset\_ids matches any asset; absent name\_match matches any name;
empty metadata\_matches matches any metadata. Dimensions are AND'd.
Name matching for STARTS\_WITH / ENDS\_WITH / CONTAINS is case-insensitive;
REGEX uses Go regexp semantics (add (?i) for case-insensitive patterns).
| Field | Type | Label | Description |
| :---------------- | :---------------------------------------------------------------- | :------- | :---------- |
| asset\_ids | string | repeated | |
| name\_match | [AutomationTriggerRunNameMatch](#automationtriggerrunnamematch) | optional | |
| metadata\_matches | [AutomationTriggerMetadataMatch](#automationtriggermetadatamatch) | repeated | |
### AutomationTriggerMetadataMatch
AutomationTriggerMetadataMatch is an equality filter against a run's
entity-metadata key/value. Key names are case-sensitive. Values are
compared as strings (numbers/booleans are stringified with Go's default
formatting). All listed matches are AND'd together.
| Field | Type | Label | Description |
| :---- | :----- | :---- | :---------- |
| key | string | | |
| value | string | | |
### AutomationTriggerParamValue
AutomationTriggerParamValue is one canvas param: a JSON literal or a
run-scoped wildcard source. Prefer this over ad-hoc `{"source":"..."}`
objects in a free-form Struct.
| Field | Type | Label | Description |
| :------------------- | :------------------------------------------------------------ | :---- | :---------- |
| oneof value. literal | google.protobuf.Value | | |
| oneof value. source | [AutomationTriggerParamSource](#automationtriggerparamsource) | | |
### AutomationTriggerRunNameMatch
AutomationTriggerRunNameMatch expresses a filter against runs.name.
| Field | Type | Label | Description |
| :---- | :---------------------------------------------------------------------- | :---- | :---------- |
| kind | [AutomationTriggerRunNameMatchKind](#automationtriggerrunnamematchkind) | | |
| value | string | | |
### AutomationTriggeredEvent
AutomationTriggeredEvent is one (automation\_trigger, run) match. When
dispatch succeeds, `canvas_execution_id` points at the resulting
canvas\_executions row (and published report, when publish=true).
| Field | Type | Label | Description |
| :------------------------------- | :-------------------------------------------------------------- | :------- | :---------- |
| automation\_triggered\_event\_id | string | | |
| organization\_id | string | | |
| automation\_trigger\_id | string | | |
| run\_id | string | | |
| state | [AutomationTriggeredEventState](#automationtriggeredeventstate) | | |
| dispatch\_after | google.protobuf.Timestamp | | |
| canvas\_execution\_id | string | optional | |
| attempt\_count | int32 | | |
| last\_error | string | optional | |
| terminal\_date | google.protobuf.Timestamp | optional | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| created\_by\_user\_id | string | | |
| modified\_by\_user\_id | string | | |
### CanvasEvaluationActionParams
CanvasEvaluationActionParams is the typed template for
AUTOMATION\_TRIGGER\_ACTION\_KIND\_CANVAS\_EVALUATION. Wildcards in param\_json
are resolved into automation\_triggered\_events.action\_params\_snapshot;
the automation worker pass-throughs that snapshot to EvaluateCanvas.
| Field | Type | Label | Description |
| :------------------ | :------------------------------------------------------------------------------------------ | :------- | :---------- |
| canvas\_version\_id | string | | |
| param\_json | [CanvasEvaluationActionParams.ParamJsonEntry](#canvasevaluationactionparams-paramjsonentry) | repeated | |
### CanvasEvaluationActionParams.ParamJsonEntry
| Field | Type | Label | Description |
| :---- | :---------------------------------------------------------- | :---- | :---------- |
| key | string | | |
| value | [AutomationTriggerParamValue](#automationtriggerparamvalue) | | |
### CreateAutomationTriggerRequest
The request for a call to `AutomationService_CreateAutomationTrigger`.
| Field | Type | Label | Description |
| :------------------------------ | :-------------------------------------------------------------- | :------- | :-------------------------------------------------- |
| canvas\_id | string | | |
| name | string | | |
| match\_filter | [AutomationTriggerMatchFilter](#automationtriggermatchfilter) | | |
| action\_kind | [AutomationTriggerActionKind](#automationtriggeractionkind) | | |
| action\_params | [AutomationTriggerActionParams](#automationtriggeractionparams) | | |
| is\_enabled | bool | optional | |
| email\_notifications\_enabled | bool | optional | Defaults to true when unset. |
| notification\_recipient\_emails | string | repeated | Defaults to the creating user's address when empty. |
### CreateAutomationTriggerResponse
The response of a call to `AutomationService_CreateAutomationTrigger`.
| Field | Type | Label | Description |
| :------------------ | :-------------------------------------- | :---- | :---------- |
| automation\_trigger | [AutomationTrigger](#automationtrigger) | | |
### DeleteAutomationTriggerRequest
The request for a call to `AutomationService_DeleteAutomationTrigger`.
Soft-deletes by setting archived\_date.
| Field | Type | Label | Description |
| :---------------------- | :----- | :---- | :---------- |
| automation\_trigger\_id | string | | |
### DeleteAutomationTriggerResponse
The response of a call to `AutomationService_DeleteAutomationTrigger`.
*This message has no fields.*
### GetAutomationTriggerRequest
The request for a call to `AutomationService_GetAutomationTrigger`.
| Field | Type | Label | Description |
| :---------------------- | :----- | :---- | :---------- |
| automation\_trigger\_id | string | | |
### GetAutomationTriggerResponse
The response of a call to `AutomationService_GetAutomationTrigger`.
| Field | Type | Label | Description |
| :------------------ | :-------------------------------------- | :---- | :---------- |
| automation\_trigger | [AutomationTrigger](#automationtrigger) | | |
### ListAutomationTriggeredEventsRequest
The request for a call to `AutomationService_ListAutomationTriggeredEvents`.
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| page\_size | uint32 | | |
| page\_token | string | | |
| filter | string | | CEL filter. Available fields: `automation_triggered_event_id`, `automation_trigger_id`, `automation_trigger_name`, `run_id`, `run_name`, `state`. |
| order\_by | string | | Order-by. Available fields: `created_date`, `dispatch_after`. Default: `created_date desc`. |
### ListAutomationTriggeredEventsResponse
The response of a call to `AutomationService_ListAutomationTriggeredEvents`.
| Field | Type | Label | Description |
| :---------------------------- | :---------------------------------------------------- | :------- | :---------- |
| automation\_triggered\_events | [AutomationTriggeredEvent](#automationtriggeredevent) | repeated | |
| next\_page\_token | string | | |
### ListAutomationTriggersRequest
The request for a call to `AutomationService_ListAutomationTriggers`.
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | |
| page\_token | string | | |
| filter | string | | CEL filter. Available fields: `automation_trigger_id`, `canvas_id`, `name`, `action_kind`, `is_enabled`, `is_archived`, `archived_date`. |
| order\_by | string | | Order-by. Available fields: `created_date`, `modified_date`, `name`. Default: `created_date desc`. |
### ListAutomationTriggersResponse
The response of a call to `AutomationService_ListAutomationTriggers`.
| Field | Type | Label | Description |
| :------------------- | :-------------------------------------- | :------- | :---------- |
| automation\_triggers | [AutomationTrigger](#automationtrigger) | repeated | |
| next\_page\_token | string | | |
### UpdateAutomationTriggerRequest
The request for a call to `AutomationService_UpdateAutomationTrigger`.
The trigger's `automation_trigger_id` is used to identify the row; every
other field is applied only when named in `update_mask`.
| Field | Type | Label | Description |
| :------------------ | :------------------------------------------------------ | :---- | :---------- |
| automation\_trigger | [AutomationTrigger](#automationtrigger) | | |
| update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | |
### UpdateAutomationTriggerResponse
The response of a call to `AutomationService_UpdateAutomationTrigger`.
To archive a trigger, include `archived_date` in the mask and set the
field. To unarchive, include `archived_date` in the mask and clear it.
| Field | Type | Label | Description |
| :------------------ | :-------------------------------------- | :---- | :---------- |
| automation\_trigger | [AutomationTrigger](#automationtrigger) | | |
## Enums
*Allowed constant values used in message fields.*
### AutomationTriggerActionKind
AutomationTriggerActionKind is what an automation trigger does when it fires.
v1 supports `AUTOMATION_TRIGGER_ACTION_KIND_CANVAS_EVALUATION` only; the
enum is kept so future dispatch types (webhook, email, ...) can be added
without a breaking change.
| Name | Number | Description |
| :---------------------------------------------------- | :----- | :---------- |
| AUTOMATION\_TRIGGER\_ACTION\_KIND\_UNSPECIFIED | 0 | |
| AUTOMATION\_TRIGGER\_ACTION\_KIND\_CANVAS\_EVALUATION | 1 | |
### AutomationTriggerParamSource
AutomationTriggerParamSource is a wildcard resolved against the triggering
run when the match job builds action\_params\_snapshot.
| Name | Number | Description |
| :---------------------------------------------------------- | :----- | :---------------------------------------------------------- |
| AUTOMATION\_TRIGGER\_PARAM\_SOURCE\_UNSPECIFIED | 0 | |
| AUTOMATION\_TRIGGER\_PARAM\_SOURCE\_TRIGGERING\_RUN | 1 | Resolves to the triggering run's run\_id (string). |
| AUTOMATION\_TRIGGER\_PARAM\_SOURCE\_TRIGGERING\_RUN\_ASSETS | 2 | Resolves to the triggering run's asset\_ids (string array). |
### AutomationTriggerRunNameMatchKind
AutomationTriggerRunNameMatchKind is the operator on runs.name in an
automation trigger match filter.
| Name | Number | Description |
| :-------------------------------------------------------- | :----- | :---------- |
| AUTOMATION\_TRIGGER\_RUN\_NAME\_MATCH\_KIND\_UNSPECIFIED | 0 | |
| AUTOMATION\_TRIGGER\_RUN\_NAME\_MATCH\_KIND\_STARTS\_WITH | 1 | |
| AUTOMATION\_TRIGGER\_RUN\_NAME\_MATCH\_KIND\_ENDS\_WITH | 2 | |
| AUTOMATION\_TRIGGER\_RUN\_NAME\_MATCH\_KIND\_CONTAINS | 3 | |
| AUTOMATION\_TRIGGER\_RUN\_NAME\_MATCH\_KIND\_REGEX | 4 | |
### AutomationTriggeredEventState
AutomationTriggeredEventState is the lifecycle of a single
(automation\_trigger, run) match / dispatch attempt.
| Name | Number | Description |
| :----------------------------------------------- | :----- | :---------- |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_UNSPECIFIED | 0 | |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_WAITING | 1 | |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_DISPATCHING | 2 | |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_DONE | 3 | |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_FAILED | 4 | |
| AUTOMATION\_TRIGGERED\_EVENT\_STATE\_CANCELLED | 5 | |