> ## 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 actions > Use KayanOS actions to read data, make controlled changes, coordinate work, return responses, create documents, and notify the right people. ## What an action does An action is the outcome of an automation step. It can retrieve information, create or update a record, wait for a later event, coordinate a task or approval, prepare a document, return a request/response result, notify people internally, or update role assignments. Every released action runs through the selected organization-scoped [KayanOS connection](/build/automations-connections). Validate that connection before mapping inputs; an internal KayanOS outcome does not remove this required authorization boundary. Choose an action because it produces a necessary, reviewable result—not because it is available in the catalog. The safest order is usually: 1. Read or find the relevant data. 2. Check the decision condition. 3. Make one controlled write or response. 4. Notify the accountable person or team. 5. Record enough information for a reviewer to find the result. ## Before you map an action For every action, answer these questions before saving it: | Question | What a good answer looks like | | -------------------------------------- | ------------------------------------------------------------------------------------------------ | | What is the source of each input? | A tested trigger field, a prior action output, or an explicitly selected configuration value. | | What is the smallest permitted target? | One table, record, task type, form session, template, role scope, or recipient group. | | What condition protects the action? | A clear state transition, required fields, and an absence-of-duplicate check where relevant. | | What visible result proves success? | A record ID, task, document, in-app notification, or returned response that an owner can review. | | What happens if data is missing? | The flow stops for review or follows a documented non-destructive path. | Do not map a display label when the trigger output supplies a stable ID or relationship value. IDs and scoped selectors are less likely to change unexpectedly. ## Current action catalog The tables below preserve the visible KayanOS action names and required inputs in the current catalog. The editor may present additional optional fields; use them to narrow scope and make the result easier to audit. ### Record actions | Action | Required inputs | What it is for | Safe use | | ---------------------------- | ------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create Record** | `Table Name`; `Records` | Create one or more mapped records in a selected table. | Check for an existing open record first when retries or repeated events are possible. Give the new record an owner, status, and source relationship. | | **Delete Record(s)** | `Table Name`; `Records IDs` | Delete selected records. | Treat as irreversible. Use only for an approved lifecycle rule, never as a shortcut for hiding a failed automation result. | | **Update Record** | `Table Name`; `Values` | Change explicit values on a selected record. | Update only the fields owned by the flow. Do not overwrite staff-entered notes, decisions, or fields from another process. | | **Get Record** | `Table Name`; `Record ID` | Read a known record before a decision. | Use it when the target ID is already known and you need current data. | | **Find Records** | `Table Name` | Look up records before deciding whether to create, update, or notify. | Narrow the search by stable relationship, status, or identifier. Handle zero, one, and multiple matching records deliberately. | | **Wait for Record Change** | `Table Name`; `Record ID`; `Watched Fields` | Pause until a specified record changes in a relevant field. | Watch only fields that represent a real hand-off. Record why the flow is waiting and what state should resume it. | | **Wait for Record Creation** | `Table Name`; `Field`; `Value` | Pause until a matching record is created. | Use a unique correlation value, such as the source request ID, so an unrelated new record cannot resume the flow. | ### Task and grouped-work actions | Action | Required inputs | What it is for | Safe use | | -------------------------- | -------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create Task** | `Task` | Start a governed follow-up task. | Include the source record, accountable team, due context, and the next human decision. | | **Create Epic** | `Epic` | Start grouped work with a shared lifecycle. | Use when several tasks or stages need one accountable umbrella; do not create an epic for a one-step notification. | | **Update Task** | `Epic` | Change a selected task in the current catalog. | Confirm the selected target in the editor. The current UI shows the input label `Epic`; treat that as a visible label and verify the actual target before enabling. | | **Update Epic** | `Epic` | Change an existing grouped-work item. | Limit updates to the lifecycle fields owned by the automation. | | **Respond To Task Action** | `Action ID` | Respond to a pending task action by its action ID. | Use only when the prior step produced or identified the correct pending action. | | **Respond To Epic Action** | `Action ID` | Respond to a pending grouped-work action. | Preserve the relationship between the source case and the pending action. | | **Wait For Task Action** | `Task ID` | Pause until an action is available or completed for a task. | Use a task ID from the same case; do not wait on a generic task type. | | **Wait For Epic Action** | `Epic ID` | Pause until an action is available or completed for grouped work. | Pair it with a documented timeout or operational review procedure. | | **Execute Task Action** | `Task Type`; `Task ID`; `Action` | Invoke a named action for an existing task. | Confirm that the selected action is permitted for the current status and that a human approval is not being bypassed. | | **Execute Epic Action** | `Epic Type`; `Epic ID`; `Action` | Invoke a named action for an existing grouped-work item. | Use a precise epic ID and an approved action; avoid broad status jumps. | ### Form and entity-action actions | Action | Required inputs | What it is for | Safe use | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Update Form Session Values** | `Session ID`; `Values` | Populate or correct selected values in a form session. | Update only values the automation owns; preserve participant-entered information unless policy explicitly permits a change. | | **Create Record: Attendance Schedule Adjustments** | Select the `Attendance Schedule Adjustments` table, then enter `Member`, `Assignment`, `Start Day`, and `Adjustment Type`. Optional: `End Day`, `Note`, `Source Submission`. | Apply approved fixed or flex-window hours without crediting worked time, then recalculate attendance. Position and shift are derived from the assignment. | The existing **Create Record** action shows only fields for the selected adjustment type. Every submitted record is approved automatically. Assignment is filtered by Member. Source Submission falls back to the flow-run ID. Never overlap another active adjustment for the member-day. | | **Respond To Form Action** | `Session ID`; `Action ID` | Respond to a pending action in a form session. | Use the exact session and action IDs produced by the relevant process. | | **Respond To Entity Action** | `Table Name`; `Field Key`; `Action ID` | Respond to a pending entity-field action. | Verify that the field key and action ID refer to the same record lifecycle. | | **Wait For Form Action** | `Form`; `Form Session ID` | Pause until a later action is taken on a selected form session. | Use for a real human hand-off, such as a reviewer deciding to approve or return a submission. | | **Wait For Form Signature** | `Form`; `Form Session ID` | Pause for a signature event on the selected form session. | Ensure the form version and signature path are the intended one before waiting. | | **Wait For Entity Action** | `Table Name`; `Field Key` | Pause for an action configured on an entity field. | Keep the watched field narrow and document who is expected to perform the action. | | **Execute Form Action** | `Session ID` | Invoke an available action in the selected form session. | Use only after validating the session state and required approvals. | | **Execute Entity Action** | `Table Name`; `Record ID`; `Field Key`; `Action` | Invoke an action on a specific entity field. | Verify table, record, field, and action together; a correct field key on the wrong record is still unsafe. | | **Return Form Response** | `JSON Body` | Return a JSON response to an **On Form Call** flow. | Return the smallest documented response schema and no private fields. Test both success and validation-failure responses. | ### Flexible-hours approval behavior An **Attendance Schedule Adjustments** record created with the existing **Create Record** action is a schedule decision, not a time claim. It never creates a work-time entry. Actual closed punches remain the only source of productive minutes; an open punch can anchor arrival but contributes no worked minutes until it has a valid checkout. The record has no Decision or approval-status input. Every submitted adjustment is treated as approved. `Note` is the only optional free-text field. Revision, approval provenance, position, shift, schedule snapshot, and retroactive status are system-managed and never entered in Create Record. `Source Submission` is optional because the server uses the automation flow-run ID when it is blank. Use a stable source submission when a later run should update the same adjustment; the ledger increments its internal revision automatically. Create Record presents schedule details as typed fields instead of a JSON object. **Adjustment Type** controls visibility: * **Fixed Times:** **Start Time** and **End Time**. * **Shift Offset:** **Offset Minutes** (positive moves later; negative moves earlier). * **Flex Window:** optional **Window Start Time** and required **Window End Time**. Audit-only values—including the normalized adjustment JSON, derived mode, shift snapshot, revision default, actor, recomputation job, and retroactive marker—are maintained by the system and cannot be edited as ledger fields. `Shift Snapshot` is captured by the server from the selected assignment's shift and is never entered manually. `Retroactive` is also server-derived: it is `true` when the affected dates already have an approved salary slip. Such a change requires locked-period correction permission; it preserves locked attendance/payroll and uses the existing next-period adjustment behavior. * **Fixed times** accepts an explicit start/end pair only when it preserves the base shift span. **Shift offset** is the equivalent signed-minute form. Every work range and configured break moves by the same offset. * **Flex window** clamps the first check-in to the approved window. Before the window uses the window start, inside the window uses the actual arrival, and after the cap uses the cap; arrival after the cap is late by the excess. * With no check-in, the base schedule remains effective and no minutes are granted. A missing checkout can still establish lateness, but it produces no worked minutes, last-out, early-leave, or overtime until corrected. * Required productive duration and scheduled-break allowance do not change. Early leave is measured against the adjusted end. Overtime is productive punch coverage after the adjusted end, not early arrival or a skipped break. * Example: base `08:00–16:00`, flex window `08:00–10:00`, first check-in `09:17` gives `09:17–17:17`; a `10:20` arrival is anchored at `10:00` and is 20 minutes late. * The range is limited to 366 days. One approved adjustment may exist per member-day. A higher revision replaces the same adjustment and recalculates its affected range. Locked attendance is not rewritten—existing payroll adjustment behavior applies. ### Documents, short links, and dashboard responses | Action | Required inputs | What it is for | Safe use | | ------------------------------------ | -------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Excel Template** | `Template`; `Values` | Generate a spreadsheet from an approved template and mapped values. | Keep the template version controlled and inspect the generated file for absent or mis-mapped values. | | **Word Template** | `Template`; `Values` | Generate a text document from an approved template and mapped values. | Use only templates approved for the service; omit data the recipient does not need. | | **Excel to PDF** | `File` | Convert an approved spreadsheet file to PDF. | Confirm that the source file is the intended generated artifact before converting. | | **Word to PDF** | `File` | Convert an approved Word file to PDF. | Review pagination, signatures, and sensitive fields in the resulting PDF. | | **Create Short Link** | `Target URL` | Create a link for an approved destination. | Use a destination that has been reviewed; do not use a short link to bypass access controls. | | **Return Dashboard Widget Response** | `JSON Body` | Return a JSON response to an **On Dashboard Widget Call** flow. | Return only the data the widget needs and validate any input-derived filter before querying records. | ### Governance and internal notification | Action | Required inputs | What it is for | Safe use | | --------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Send Notification** | `Type`, and `Member ID` or `Member Selectors` | Send an internal KayanOS notification to a specific member or scoped group. | Use the narrowest recipient scope. Test the title, body, priority, and recipient resolution with non-production members first. | | **Update Roles** | `Scope`; `Role ID`; `Operation`; `Entity ID`; `Selectors` | Change role assignments within an explicit scope. | Treat as high risk. Make the scope, selector, target entity, and operation independently reviewable; never use a broad selector as a convenience. | ## How to map actions without surprises ### 1. Read before creating When the flow could be retried, begin with **Get Record** or **Find Records**. For the permit example, find an open `Inspection Cases` record whose source application ID matches the permit. If one exists, update or notify that case. If none exists and the decision condition is true, create exactly one new case. ### 2. Keep correlation values When one action creates a record, task, epic, form session, file, or response that a later action must use, retain its returned ID and relate it to the source case. That relationship is what makes a wait, update, or response action safe later. ### 3. Separate machine work from human decisions Use an action to assemble data, create a task, or wait for a form action. Do not use **Execute Task Action**, **Execute Epic Action**, **Execute Form Action**, or **Execute Entity Action** to skip a decision that policy assigns to a person or role. ### 4. Make response actions paired and bounded **Return Form Response** belongs with **On Form Call**; **Return Dashboard Widget Response** belongs with **On Dashboard Widget Call**. Define the expected JSON fields before building, return only that schema, and test missing input, no-result, and error cases separately. ## Detailed workflow patterns ### Pattern: intake to inspection without duplicates 1. Start with **Record Changes** on `Permit Applications`. 2. Confirm that the status just became `Ready for inspection` and that the application contains the required locality and address. 3. Use **Find Records** to look for an open inspection case related to the application. 4. If none exists, use **Create Record** to create one `Inspection Cases` record with the source application relationship, locality, status, and accountable unit. 5. Use **Create Task** for the field-inspection team and **Send Notification** to its scoped coordinator. 6. Store or expose the created case ID so a reviewer can trace the result from the application. ### Pattern: wait for a human decision, then produce a document 1. Start with **On Form Action** when a case is submitted for decision. 2. Use **Wait For Form Signature** or **Wait For Form Action** for the actual approved decision point. 3. Confirm the accepted decision and the required signed path. 4. Use **Word Template** with only the approved fields. 5. Optionally use **Word to PDF**, then update the case record with the generated artifact reference. 6. Notify the accountable service owner inside KayanOS. ### Pattern: serve a dashboard response 1. Start with **On Dashboard Widget Call**. 2. Validate its mode and input against the user's permitted service scope. 3. Use **Find Records** to retrieve only the necessary aggregates or records. 4. Shape the result into the documented JSON schema. 5. Finish with **Return Dashboard Widget Response**. ## Test each action in the right order Use one approved non-production record and perform these checks: 1. Trigger test: verify the source event and expected data. 2. Read test: verify that lookup actions find the intended record set. 3. Write test: create or update one clearly identified non-production target. 4. Wait/execute test: confirm that the exact task, epic, form session, or entity action is correlated correctly. 5. Notification/response test: verify the recipient or returned payload without using a real citizen, external recipient, or production role scope. 6. Review: locate the result in KayanOS and record its ID, owner, and outcome. Do not put a write, execution, role-update, document-generation, or notification action directly after an unfiltered event. Make the condition and the resulting target explicit first. ![KayanOS Automations action configuration for a controlled internal follow-up.](https://kayanos.app/docs-images/en/build/automations-actions.png) ## Continue building * Combine triggers and actions in [KayanOS Automations recipes](/build/automations-recipes). * Test, run, and diagnose a flow in [Test, run, and troubleshoot automations](/build/automations-test-run-and-troubleshoot). * Review [permissions and availability](/reference/permissions-and-availability) before enabling role or notification actions.