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

> Design dependable KayanOS workflows: start from a precise event, make the decision explicit, and leave an auditable result.

## What KayanOS Automations does

KayanOS Automations turns a defined KayanOS event into a controlled sequence of internal steps. An automation can read a record, decide whether work is needed, create or update a record, coordinate a task or approval, prepare a document, return a form or dashboard response, or notify the responsible people.

Every released KayanOS Automation trigger and action is used through a selected **KayanOS connection**. The connection is an organization-scoped authorization boundary for the flow, even when the result only changes KayanOS records and does not require an external account. Select, validate, and test that connection before configuring a trigger or mapping data. The public KayanOS catalog for this release contains 12 triggers and 34 supported public actions.

It is most useful when the same hand-off is happening repeatedly and the organization can state all of the following clearly:

* What event starts the work.
* Which records the automation is allowed to touch.
* What condition makes the action appropriate.
* Who remains accountable for reviewing the result.

Automations do not replace service policy or human review. They make an already agreed process repeatable and visible.

## A broad public-service example

A Syrian public-service authority receives building-permit applications, field-inspection requests, public complaints, and internal maintenance requests. Each service has a different intake channel, but the operating pattern is similar:

1. A form action or a new record starts the flow.
2. KayanOS checks the service type, locality, completeness, and current status.
3. It creates the right follow-up record or task only when the request is eligible.
4. The assigned team receives an in-app notification and works the case.
5. A later task action, signature, or record update continues the same flow.
6. When the case is ready, KayanOS generates a review document or returns a controlled response to the originating form.

This pattern can also support licensing, inspections, payroll exceptions, asset maintenance, procurement approvals, and project change requests. The data model and approval rules differ; the design discipline stays the same.

## The workflow model

```mermaid theme={null}
flowchart LR
    A["A precise KayanOS event"] --> B["Read and validate only the needed data"]
    B --> C{"Condition is met?"}
    C -->|No| D["Stop with no side effect"]
    C -->|Yes| E["Create, update, respond, or wait"]
    E --> F["Notify the accountable team"]
    F --> G["Review the recorded outcome"]
```

### 1. Trigger

A trigger is the event that starts the automation. Examples include a new record, a form action, a signed form, a task action, an entity-field action, a dashboard call, or a short-link opening. Choose one event that represents the real start of the process; see [triggers](/build/automations-triggers) for the complete catalog and selection guidance.

### 2. Read, map, and validate

The trigger test output is the source of truth for what arrived. Map only the values an action needs. Before a write action, check that required values exist, that the record is in the expected state, and that the same event has not already been processed.

### 3. Condition

Every consequential action needs a clear reason. A useful condition is specific enough to explain why the automation ran, for example:

* The application is complete **and** its status changed to `Ready for inspection`.
* The complaint's priority is `High` **and** no open escalation task exists.
* The signed form is the approved version **and** the signer is in the required role.

Do not use a broad event such as “record updated” as the only reason to create work. A record can change for many harmless reasons.

### 4. Action

Actions produce the result: find or update records, create a task, wait for an event, execute a controlled action, produce a document, return a response, update roles, or send an in-app notification. Start with a reversible or read-only action where possible, then add writes after the test output is understood. See [actions](/build/automations-actions) for the full action catalog.

### 5. Reviewable outcome

The end of the automation must be easy to find later: a case record, task, document, response, or internal notification with an accountable owner. Avoid flows whose only evidence is an invisible background action.

### Connection-first configuration

Before selecting the trigger, choose the approved organization-owned KayanOS connection. Confirm its owner, purpose, access boundary, and current validity. If an external service is genuinely part of the outcome, its authorization is an additional review concern; it does not replace the required KayanOS connection. A missing, expired, revoked, or incorrectly scoped connection is a configuration failure—not a reason to pick a broader connection or personal account.

## Build an automation step by step

1. **Name the service outcome.** Write a name that says what changes, such as “Create inspection case after permit readiness review,” rather than “Permit flow.”
2. **Describe the decision in one sentence.** For example: “When a complete permit application enters `Ready for inspection`, create one inspection case for its locality.” If this sentence is unclear, the automation is not ready to build.
3. **Select and validate the KayanOS connection.** Use the approved organization-owned connection, confirm its status/owner/scope, and resolve any reconnect or authorization issue before building further.
4. **Choose the narrowest trigger.** Use a form action when the form action is the decision point; use a record-change trigger only when a record change is genuinely the decision point.
5. **Run the trigger test in an approved non-production workspace.** Inspect the event data and record the exact fields that the automation will use.
6. **Add a condition before the first write.** Protect against incomplete data, unrelated updates, retries, and duplicate work.
7. **Map data deliberately.** Prefer stable identifiers, approved status values, and explicit relationship fields. Do not infer ownership from a display name when an ID or member selector is available.
8. **Test one safe outcome.** First retrieve or find a record; then create one clearly identifiable non-production follow-up; finally verify the created record, notification, or response in the relevant KayanOS area.
9. **Enable gradually.** Start with a narrow service scope or a low-risk status, review results, then expand only after the owners confirm that the hand-off is correct.

## Design rules that prevent duplicate or unsafe work

| Risk                                                   | Design response                                                                            |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| A record update arrives more than once                 | Check the status transition or store a processed marker before creating a new follow-up.   |
| An operator changes an unrelated field                 | Watch only the relevant field or filter on the expected old and new state.                 |
| A prior task is still open                             | Find the existing task or case first; update or notify it instead of creating another one. |
| An action needs a human decision                       | Create or wait for a task/form action; do not infer approval from a partial record.        |
| A notification goes to the wrong audience              | Use the narrowest member or member-selector scope and verify it in a non-production run.   |
| The automation needs broader access than the owner has | Stop and review permissions before enabling it.                                            |

## Testing and rollout

Use a non-production workspace and an approved non-production record. Give the record an unambiguous identifier such as `PERMIT-TEST-001`, but do not make that identifier part of the production logic.

For every test, capture four facts in the automation’s operational note or change record:

1. The trigger event and the record used.
2. The condition that evaluated to true or false.
3. The action output, including the ID of any record, task, document, or response created.
4. The reviewer who confirmed the result.

If an action can notify a person, create a document, change roles, or update a production record, test its narrowest allowed scope first. Do not use real citizen data or an external recipient while validating a flow.

## Ownership and permissions

An owner or builder with KayanOS Automations access configures the flow. That does not remove the need for access to the records, forms, tasks, templates, and member scopes used by the automation. Before enabling it, confirm:

* The selected KayanOS connection is valid, organization-owned, appropriate for the flow, and has a named review/reconnection owner.
* The builder can see the source and target data legitimately.
* The automation has no route to private records outside its intended service scope.
* The operational owner knows where to review failures and unexpected results.
* The flow is documented well enough for another authorized builder to understand its trigger, condition, and expected output.

## Guardrails

<Warning>Put a condition before every write, execute, role-update, document-generation, or notification action. If the event is unexpected or the outcome cannot be reviewed, stop the flow rather than guessing.</Warning>

![KayanOS Automations workspace showing a controlled internal workflow.](https://kayanos.app/docs-images/en/build/automations-overview.png)

## Continue building

* Learn how to select and test an event in [KayanOS Automations triggers](/build/automations-triggers).
* Choose and map outcomes in [KayanOS Automations actions](/build/automations-actions).
* Apply the patterns in [KayanOS Automations recipes](/build/automations-recipes).
* Review [permissions and availability](/reference/permissions-and-availability) before widening access.