> ## Documentation Index > Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt > Use this file to discover all available pages before exploring further. # KayanOS Automations triggers > Select, narrow, test, and document the exact KayanOS event that is allowed to start a workflow. ## What a trigger is A trigger is the KayanOS event that starts an automation. It is not a general subscription to everything that happens in the organization. A good trigger answers one precise question: **what happened, to which object, and why is this the moment to begin this workflow?** Before selecting a trigger, choose and validate the approved organization-scoped [KayanOS connection](/build/automations-connections). The connection is required for the released catalog even when the trigger and its later action only work with internal KayanOS data. For a permit service, “a record was updated” is usually too broad. “A permit application moved from `Completeness review` to `Ready for inspection`” is a useful start because it describes a specific, reviewable change. ## Choose the right trigger first | If the workflow should start when… | Prefer this trigger | Why | | ------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | | A new record is first created | **New Record Created** | It reacts once at creation time and is appropriate for intake routing. | | Any change to a record matters | **Record Updated** | Use only when every relevant update needs attention; otherwise narrow it with a condition. | | Only particular record operations matter | **Record Changes** | It lets you choose the operations to observe and is safer for a mixed record lifecycle. | | A controlled form button/action is taken | **On Form Action** | The user deliberately performed the form action, so it is a better decision point than a draft update. | | A signature outcome is available | **On Form Signature Signed** | It ties the flow to the signing step rather than an unrelated form edit. | | A task or grouped-work action is performed | **On Task Action** or **On Epic Action** | It continues a governed work lifecycle. | | A record-field action is performed | **On Entity Action** | It scopes the event to the selected entity field and action. | | A dashboard needs calculated data | **On Dashboard Widget Call** | It starts a request/response flow for the widget. | | A form needs a controlled response | **On Form Call** | It starts a request/response flow for the form. | | A public entry link is opened | **Short Link Opened** | It is suitable for an intentional public entry point, not for sensitive internal decisions. | If two triggers appear possible, choose the one that carries the strongest business meaning. A form action such as `Submit for review` is more reliable than watching a dozen form-field updates. ## Current trigger catalog The table preserves the visible trigger names and required inputs in the current KayanOS catalog. Optional filters refine the event; use them whenever they prevent unrelated runs. ### Record events | Trigger | Required configuration | Use it for | Design notes | | ---------------------- | -------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **New Record Created** | `Table Name` | Creating an intake, case, request, asset, or inspection record. | Add a condition if only one category of new record should continue. A new record can be incomplete at creation time. | | **Record Updated** | `Table Name` | Reacting when updates need review. | Do not create work on every update. Compare the relevant status or watched value in the condition. | | **Record Deleted** | `Table Name` | Recording a controlled deletion follow-up. | Use cautiously: the record may no longer be available for later lookups. Preserve only the allowed audit context. | | **Record Changes** | `Table Name`; `Operations` | Watching selected create, update, or delete operations in one flow. | Choose only the operations the workflow understands. A separate flow is often clearer when create and delete require different decisions. | ### Forms, signatures, and entity actions | Trigger | Required configuration | Use it for | Optional narrowing available in the catalog | | ---------------------------- | ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **On Form Action** | `Form` | Submitting, routing, requesting review, or another named form action. | `Form Versions` and `Actions` let you keep the flow aligned with the intended form and action. | | **On Form Signature Signed** | `Form` | Starting a downstream step after a reviewed signing outcome. | `Signatures`, `Rules`, and `Resolutions` distinguish the relevant signing route. | | **On Entity Action** | `Table Name`; `Field Key` | Responding to an action configured on an entity field. | Confirm the entity field and the action’s permitted users before enabling the flow. | ### Tasks and grouped work | Trigger | Required configuration | Use it for | Optional narrowing available in the catalog | | ------------------ | ---------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | **On Task Action** | `Task Type` | Continuing an approval, inspection, assignment, or escalation task. | `Old Status` and `New Status` make the transition explicit. | | **On Epic Action** | `Epic Type` | Continuing a grouped-work or multi-step service lifecycle. | `Old Status` and `New Status` help prevent actions on unrelated progress updates. | ### Interactive and public-entry events | Trigger | Required configuration | Use it for | Pair it with | | ---------------------------- | ---------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | **On Dashboard Widget Call** | `Mode`; `Input` | Returning calculated, permission-aware data to a dashboard widget. | **Return Dashboard Widget Response**. | | **On Form Call** | `Mode`; `Input` | Returning a controlled result to a form integration point. | **Return Form Response**. | | **Short Link Opened** | No required field | Measuring or routing an explicitly designed public entry point. | Optional `Metadata Filter` and `Open Type` can narrow the event. Do not use it as proof of identity or approval. | ## Configure a trigger safely 1. **Write the event statement.** State it in plain language: “When a complete permit application is moved to `Ready for inspection`.” 2. **Select the smallest source scope.** Choose the exact table, form, task type, epic type, field key, or entry point that owns the event. 3. **Apply catalog filters.** Select the relevant form version, action, signature rule, status transition, record operation, or link metadata where available. 4. **Run the trigger test with one approved non-production record.** Use a recognisable record such as `PERMIT-TEST-001`; never use real citizen or staff data for this step. 5. **Inspect the output before adding actions.** For a tested record event, KayanOS returned `action`, `oldData`, `data`, and `changedFields`. Treat the actual test output as authoritative: different event types can expose different context. 6. **Identify stable inputs.** Prefer IDs, status codes, table values, and explicit relationship fields over labels a user could edit. 7. **Add the decision condition.** Require the expected state, completeness, and absence of an existing follow-up before a write or notification action. 8. **Record the expected result.** Note what downstream record, task, response, or notification should appear and who will confirm it. ## Read the trigger output deliberately The test panel is not just a connectivity check. It shows the data your automation will receive. Review it field by field: | Output to inspect | Why it matters | Example question | | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `data` | The current event or record values. | Does it include the service category, locality, requester relationship, and current status needed by the next action? | | `oldData` | The prior values when the event includes a change context. | Did the status actually move from `Completeness review` to `Ready for inspection`? | | `changedFields` | The fields that caused an update context. | Was the relevant status changed, or did someone merely correct a phone number? | | `action` | The selected form, task, epic, or entity action context when available. | Is this the exact approved action that should start the process? | Never assume a field is present because it appears on the screen. Inspect the test result, then map only the values the next step truly needs. ## Avoid accidental repeat runs Record and task events may legitimately happen more than once. Design the trigger and its first condition so that a retry or unrelated change does not create duplicate cases, tasks, notifications, or documents. For example, an inspection-routing flow can use this sequence: 1. Trigger on **Record Changes** for the `Permit Applications` table and the `update` operation. 2. Confirm that the current status is `Ready for inspection`. 3. Confirm that the prior status was not already `Ready for inspection`, or that there is no open inspection case for the application. 4. Only then create the inspection case and notify the assigned locality team. If an existing open case is found, update it or stop with a review note. Do not create another case simply because an editor saved the record again. ## Trigger examples ### Route a complete permit application * **Business event:** A permit application passes completeness review. * **Trigger:** `Record Changes` on `Permit Applications`, observing updates. * **Condition:** Current status is `Ready for inspection`; required address and locality values are present; no open inspection case exists. * **Next action:** Create one `Inspection Cases` record and notify the appropriate internal team. ### Continue a signature-controlled decision * **Business event:** The required decision signature is completed. * **Trigger:** `On Form Signature Signed` for the selected decision form. * **Filter:** Select the approved form version, signature, rule, and resolution where those options are available. * **Next action:** Create or update the decision record, then create a task for the next accountable role. ### Serve a dashboard widget safely * **Business event:** A dashboard widget requests its data. * **Trigger:** `On Dashboard Widget Call` with the intended mode and input. * **Condition:** Validate that the input belongs to the permitted service scope. * **Next action:** Find only the permitted records and use **Return Dashboard Widget Response** with a minimal JSON body. ## Guardrails A trigger tells you that an event occurred. It does not prove that a write, notification, role change, or external consequence is appropriate. Test the exact event, add a condition, and stop when the context is incomplete or unexpected. ![KayanOS Automations trigger selection for a controlled service workflow.](https://kayanos.app/docs-images/en/build/automations-triggers.png) ## Continue building * Map outcomes in [KayanOS Automations actions](/build/automations-actions). * See complete workflow patterns in [KayanOS Automations recipes](/build/automations-recipes). * Learn the expression language used in supported builders in [Expressions in the builder](/build/expressions-in-builder).