Skip to main content
A Trigger is a project-scoped rule that says when this kind of event happens in the project, start this Activity Plan. It connects something happening in a project — a task being created, a task status changing, an Activity completing — to the workflow that should run in response. Triggers are the automated counterpart to a manual start. Where a person (or an intake) can kick off an Activity by hand, a Trigger does it for you whenever its event fires and its optional filter matches.

​
What a Trigger Defines

A Trigger answers three questions:
  • What event should it react to? One of the recognized event kinds (task_created, task_status_changed, activity_completed, manual).
  • Which of those events count? An optional eventFilter that must match the event payload. Leave it empty to react to every event of that kind.
  • What should happen? The activityPlanRef of the Activity Plan to start when the Trigger fires.

​
Trigger vs Activity Plan

Triggers live inside a project because what should react to an event is a project decision, even though the Activity Plan they start is an organization-level resource shared across projects. The Activity Plan referenced by activityPlanRef must be bound to the same project before the Trigger can start it — the same intentional cross-scope binding that applies to starting an Activity Plan by hand.

​
Event Kinds

Triggers support these event kinds in v1:
schedule, document_arrived, and data_extracted are planned for a later release and are not accepted yet — creating a Trigger with an unrecognized event kind is rejected.

​
Event Filters

eventFilter is an optional predicate evaluated against the event payload. A Trigger fires only when the filter evaluates truthy; an empty filter ({}) matches every event of its kind. The filter is a JSONata expression. You can supply it as a bare expression string or as an object with an expr field — both forms are equivalent:
The fields available to a filter depend on the event payload for that event kind. Start with an empty filter to fire on every event, then narrow it once you know which events you care about.

​
Basic Shape

A Trigger is authored as project resource configuration and deployed with the rest of your Kodexa project assets.

​
Enabling and Disabling

A Trigger can be turned off without deleting it. The enabled field controls whether the Trigger participates in evaluation, and the API exposes dedicated lifecycle endpoints so you can flip it without sending a full update:
  • POST /api/triggers/{id}/enable
  • POST /api/triggers/{id}/disable
Disabling is the safe way to pause automation — the Trigger keeps its configuration and history, it simply stops firing until re-enabled.

​
Managing Triggers

Triggers are project-scoped resources, so you manage them alongside the project’s other resources (Data Definitions, Data Forms, Activity Plans, and so on):
  • In Studio — from the project’s Resources, where you can create a Trigger, edit its event kind, filter, and Activity Plan binding, enable or disable it, and delete it.
  • Via the API — the Triggers API covers full CRUD plus the enable/disable lifecycle endpoints.
  • With the KDX CLI — Triggers sync as a project-scoped resource (they live in a triggers/ directory in your project), so they can be authored as files and pushed with the rest of your project metadata. See resource operations.