KayanOS Automations actions - KayanOS Documentation

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

Read or find the relevant data.
Check the decision condition.
Make one controlled write or response.
Notify the accountable person or team.
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

Start with Record Changes on Permit Applications.
Confirm that the status just became Ready for inspection and that the application contains the required locality and address.
Use Find Records to look for an open inspection case related to the application.
If none exists, use Create Record to create one Inspection Cases record with the source application relationship, locality, status, and accountable unit.
Use Create Task for the field-inspection team and Send Notification to its scoped coordinator.
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

Start with On Form Action when a case is submitted for decision.
Use Wait For Form Signature or Wait For Form Action for the actual approved decision point.
Confirm the accepted decision and the required signed path.
Use Word Template with only the approved fields.
Optionally use Word to PDF, then update the case record with the generated artifact reference.
Notify the accountable service owner inside KayanOS.

Pattern: serve a dashboard response

Start with On Dashboard Widget Call.
Validate its mode and input against the user’s permitted service scope.
Use Find Records to retrieve only the necessary aggregates or records.
Shape the result into the documented JSON schema.
Finish with Return Dashboard Widget Response.

Test each action in the right order

Use one approved non-production record and perform these checks:

Trigger test: verify the source event and expected data.
Read test: verify that lookup actions find the intended record set.
Write test: create or update one clearly identified non-production target.
Wait/execute test: confirm that the exact task, epic, form session, or entity action is correlated correctly.
Notification/response test: verify the recipient or returned payload without using a real citizen, external recipient, or production role scope.
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.

Continue building

Combine triggers and actions in KayanOS Automations recipes.
Test, run, and diagnose a flow in Test, run, and troubleshoot automations.
Review permissions and availability before enabling role or notification actions.

​What an action does

​Before you map an action

​Current action catalog

​Record actions

​Task and grouped-work actions

​Form and entity-action actions

​Flexible-hours approval behavior

​Documents, short links, and dashboard responses

​Governance and internal notification

​How to map actions without surprises

​1. Read before creating

​2. Keep correlation values

​3. Separate machine work from human decisions

​4. Make response actions paired and bounded

​Detailed workflow patterns

​Pattern: intake to inspection without duplicates

​Pattern: wait for a human decision, then produce a document

​Pattern: serve a dashboard response

​Test each action in the right order

​Continue building

What an action does

Before you map an action

Current action catalog

Record actions

Task and grouped-work actions

Form and entity-action actions

Flexible-hours approval behavior

Documents, short links, and dashboard responses

Governance and internal notification

How to map actions without surprises

1. Read before creating

2. Keep correlation values

3. Separate machine work from human decisions

4. Make response actions paired and bounded

Detailed workflow patterns

Pattern: intake to inspection without duplicates

Pattern: wait for a human decision, then produce a document

Pattern: serve a dashboard response

Test each action in the right order

Continue building