SIGNALS Documentation
API Reference

Workflow Triggers & Conditions

Trigger types and the condition schema the delivered workflow engine publishes and validates.

Trigger types

A published workflow pins one trigger key on its immutable snapshot. The delivered engine recognises four keys.

Key How a run starts Source
manual An authorised operator or API caller starts the published version. The envelope records trigger: manual and an idempotency key prefixed manual:. A workflow may require a subject or refuse one. Declared input_schema fields are validated before start. WorkflowTriggerEnvelope::fromManual()
schedule The scheduler dispatches due occurrences. The envelope records trigger: schedule. Publication canonicalises the schedule through WorkflowTimingContractValidator whenever the trigger key is schedule. WorkflowScheduleDispatchContext, WorkflowTimingContractValidator::trigger()
domain_event A registered workflow-visible domain event matches the published version. Conditions may read trigger.payload.{field} from that event's payload schema. WorkflowTriggerMatcher, WorkflowConditionSchemaValidator
inbound A signed integration request is accepted at POST /api/v1/workflows/{workflow}/inbound/{credentialKey}. The envelope records trigger: inbound and an idempotency key prefixed inbound:. WorkflowTriggerEnvelope inbound factory, WorkflowInboundRunStartService

Plugin-owned trigger extensions register through the workflow trigger registry and are matched only when the snapshot key is not domain_event. Core does not invent additional trigger keys beyond the four above.

Schedule configuration

When the trigger key is schedule, the published config must be exactly:

  • expression — a valid canonical five-field cron expression
  • timezone — an IANA timezone identifier
  • misfire_policy — latest, all, or skip (WorkflowMisfirePolicy)
  • catch_up_selection — newest or oldest

subject_selection, when present, must be an array and is validated by WorkflowScheduleSubjectSelectorRegistry. Catch-up is bounded to 100 occurrences (WorkflowScheduleConfiguration::MaxCatchUpOccurrences).

Condition schema

Conditions are optional on a trigger. WorkflowConditionSchemaValidator accepts either a list of rules (implicit combinator and) or an object with:

  • combinator — and or or (ConditionCombinator)
  • conditions or rules — a list of rule objects

Each core rule is exactly { path, operator, value }. Paths must match \A[a-zA-Z][a-zA-Z0-9_.-]{0,119}\z. Operators are eq, not_eq, lt, lteq, gt, gteq, in, not_in, null, not_null, true, and false (ConditionOperator). in / not_in require a list value. null / not_null require a null value. true / false require a boolean value and a boolean path schema.

A plugin condition is a single-key object { condition: { type, plugin, plugin_version, condition_id, condition_version, arguments } } with type equal to plugin and object arguments. Conditions receive allowlisted sanitized context and cannot query or mutate application state.

Paths available to conditions

These static paths are always in the immutable trigger context (WorkflowConditionSchemaValidator::staticSchemas()):

Path Types Nullable
trigger.event.name string no
trigger.event.id string yes
trigger.idempotency_key string no
trigger.occurred_at string no
trigger.payload_version integer no
trigger.causal_metadata.correlation_id string no
trigger.causal_metadata.causation_id string no
trigger.causal_metadata.causal_depth integer no
subject.type string no
subject.id string no
originator.type string no
originator.id string yes
originator.label string yes
workflow.id string no
workflow.version_id string no
workflow.version integer no
workflow.service_principal.type string no
workflow.service_principal.id string no
workflow.service_principal.label string yes

Additional paths:

  • trigger.input.{field} — only when the trigger key is manual and the field is declared on input_schema as a single string, integer, or boolean type
  • trigger.payload.{field} — only when the trigger key is domain_event and the named event declares that property on its payload schema. Nested payload paths are not available

A path that is not in that allowlist is rejected as not available in the immutable trigger context.

External continuation

An awaiting run that parked on an external correlation is resumed by POST /api/v1/workflow-resumes (api.v1.workflow-resumes.store). See Workflow Operations.