> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Triggers are project-scoped rules that start an Activity Plan when a matching event — a task created, a task status change, an activity completing, or a manual fire — occurs in the project.

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.

```mermaid theme={null}
flowchart LR
    Event["Project event<br/>(task_created, task_status_changed, …)"] --> Trigger
    Trigger["Trigger<br/>event kind + filter"] -->|filter matches| Plan["Activity Plan<br/>(activityPlanRef)"]
    Plan --> Activity["Activity run"]
```

## 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                                                                          |

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:

| 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 |

<Note>
  `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.
</Note>

## 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:

```json theme={null}
{ "expr": "taskTemplate.ref = \"invoice-review\"" }
```

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.

```json theme={null}
{
  "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](#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}/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](/studio/project/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](/api-reference/triggers/get-triggers) 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](/guides/kdx-cli/resource-operations).

## Related reading

* [Activity Plans](/guides/activity-plans/index) — the workflows a Trigger starts
* [Task Templates](/guides/task-templates/index) — the work whose creation and status changes drive `task_created` and `task_status_changed`
* [Event Activity in Studio](/studio/project/event-activity) — the real-time log of events flowing through a project
* [Triggers API reference](/api-reference/triggers/get-triggers) — CRUD and enable/disable endpoints