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
| Concept | Scope | What it means |
|---|
| Trigger | Project | A project-scoped rule: when an event of a given kind fires in the project (and the filter matches), start the referenced Activity Plan |
| Activity Plan | Organization | The reusable workflow definition the Trigger starts |
| Activity | Project | One run of that Activity Plan, created when the Trigger fires |
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:
| Event kind | Fires when |
|---|
task_created | A task is created in the project |
task_status_changed | A task moves to a new status |
activity_completed | An Activity in the project finishes |
manual | The Trigger is fired explicitly rather than by a platform event |
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:
{ "expr": "taskTemplate.ref = \"invoice-review\"" }
Basic Shape
A Trigger is authored as project resource configuration and deployed with the rest of your Kodexa project assets.
{
"name": "Start invoice review when an intake task is created",
"slug": "start-invoice-review",
"eventKind": "task_created",
"eventFilter": {},
"activityPlanRef": "activity-plan://acme/invoice-intake",
"enabled": true
}
| Field | Meaning |
|---|
slug | Stable identifier, unique within the project |
name | Human-readable label |
eventKind | The event the Trigger reacts to (see Event Kinds) |
eventFilter | Optional JSONata predicate over the event payload; empty fires on every event of that kind |
activityPlanRef | URI of the Activity Plan to start, in the form activity-plan://orgSlug/planSlug |
enabled | Whether the Trigger is active (defaults to true) |
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}/enablePOST /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.
