KayanOS Automations triggers

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

Write the event statement. State it in plain language: “When a complete permit application is moved to Ready for inspection.”
Select the smallest source scope. Choose the exact table, form, task type, epic type, field key, or entry point that owns the event.
Apply catalog filters. Select the relevant form version, action, signature rule, status transition, record operation, or link metadata where available.
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.
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.
Identify stable inputs. Prefer IDs, status codes, table values, and explicit relationship fields over labels a user could edit.
Add the decision condition. Require the expected state, completeness, and absence of an existing follow-up before a write or notification action.
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:

Trigger on Record Changes for the Permit Applications table and the update operation.
Confirm that the current status is Ready for inspection.
Confirm that the prior status was not already Ready for inspection, or that there is no open inspection case for the application.
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.

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.

Continue building

Map outcomes in KayanOS Automations actions.
See complete workflow patterns in KayanOS Automations recipes.
Learn the expression language used in supported builders in Expressions in the builder.

Build KayanOS apps

What a trigger is

Choose the right trigger first

Current trigger catalog

Record events

Forms, signatures, and entity actions

Tasks and grouped work

Interactive and public-entry events

Configure a trigger safely

Read the trigger output deliberately

Avoid accidental repeat runs

Trigger examples

Route a complete permit application

Continue a signature-controlled decision

Serve a dashboard widget safely

Guardrails

Continue building

​What a trigger is

​Choose the right trigger first

​Current trigger catalog

​Record events

​Forms, signatures, and entity actions

​Tasks and grouped work

​Interactive and public-entry events

​Configure a trigger safely

​Read the trigger output deliberately

​Avoid accidental repeat runs

​Trigger examples

​Route a complete permit application

​Continue a signature-controlled decision

​Serve a dashboard widget safely

​Guardrails

​Continue building

What a trigger is

Choose the right trigger first

Current trigger catalog

Record events

Forms, signatures, and entity actions

Tasks and grouped work

Interactive and public-entry events

Configure a trigger safely

Read the trigger output deliberately

Avoid accidental repeat runs

Trigger examples

Route a complete permit application

Continue a signature-controlled decision

Serve a dashboard widget safely

Guardrails

Continue building