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

> Build complete, reviewable KayanOS workflows for intake, inspection, escalation, decision documents, and controlled responses.

## How to use these recipes

Each recipe is a design pattern, not a workflow to enable unchanged. Adapt the table, status names, owners, form versions, action names, and permission scopes to your organization. Build it in an approved non-production workspace first, verify every output, then move through a controlled rollout.

Every recipe follows the same safe shape:

```mermaid theme={null}
flowchart LR
    A["Specific event"] --> B["Validate data and state"]
    B --> C["Find related work"]
    C --> D{"Already handled?"}
    D -->|Yes| E["Update or stop"]
    D -->|No| F["Create controlled follow-up"]
    F --> G["Notify accountable team"]
    G --> H["Record and review outcome"]
```

## Recipe 1: route a service request to the right case queue

**Use when:** A public-service request must become an accountable internal case without creating duplicates.

| Design decision        | Recommended implementation                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Source event           | **New Record Created** on the intake table, or **On Form Action** when a controlled submission action is the real intake point. |
| Required source values | Service category, locality, request identifier, contact/relationship reference where permitted, and an initial status.          |
| Guard condition        | The request is complete, its service category is supported, and it has not already been routed.                                 |
| Duplicate check        | **Find Records** for an open case with the same source request relationship or source identifier.                               |
| Follow-up              | **Create Record** in the service-case table; map the source request, category, locality, owner unit, and status `New`.          |
| Human hand-off         | **Create Task** for the queue owner and **Send Notification** to the narrow internal coordinator scope.                         |
| Proof of success       | The request points to one case, the case points back to the request, and the queue owner can see the task or notification.      |

### Build it step by step

1. Test the intake event with a non-production request such as `REQUEST-TEST-001`.
2. Inspect the trigger output and identify the exact source ID and category fields.
3. Find existing open cases for that source ID.
4. If one exists, stop or update the existing case according to the service policy.
5. If none exists, create a single case with a clear source relationship and a queue-owned status.
6. Create a task only after the case is created successfully, so the task always has a reviewable target.
7. Notify only the queue owner or a constrained member selector—not a broad organization-wide audience.

**Common extension:** Add a category-to-unit lookup after the duplicate check. Keep the fallback explicit: if no unit is found, create a review task for a central triage team instead of guessing the owner.

## Recipe 2: prepare and track a field inspection

**Use when:** A case must be scheduled or prepared for a field team after an eligibility decision.

| Design decision | Recommended implementation                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| Source event    | **Record Changes** on the application or case table, observing updates.                                   |
| Guard condition | Status changed to `Ready for inspection`; locality and address are complete; no active inspection exists. |
| Read step       | **Get Record** for current data and **Find Records** for an active inspection linked to the source case.  |
| Follow-up       | **Create Record** in `Inspection Cases`, then **Create Task** for the responsible field unit.             |
| Optional pause  | **Wait for Record Change** on the inspection case's `Outcome` or `Status` field.                          |
| Resume result   | Update the source case, create a decision task, or prepare the approved inspection document.              |

### Why the status transition matters

Do not trigger on every update to an application. An address correction, attachment upload, or note change should not schedule another inspection. Require the expected old/new state or an equivalent explicit eligibility marker, and record which inspection case was created.

### Test cases to run

* Eligible application with no prior inspection: creates exactly one inspection case and task.
* Eligible application with an existing open inspection: creates no duplicate; updates or flags the existing case according to policy.
* Incomplete address: creates no inspection; creates a review task only if that is the approved exception path.
* Unrelated update: produces no action.

## Recipe 3: escalate an aging service case

**Use when:** A case needs attention after a defined service-level threshold, while avoiding repeated alerts.

| Design decision | Recommended implementation                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| Source event    | A controlled record-change event, task action, or scheduled operational hand-off available to your service design. |
| Guard condition | The case is still open, has exceeded the agreed threshold, and has no unresolved escalation task.                  |
| Read step       | **Find Records** for the existing escalation task or case marker.                                                  |
| Follow-up       | **Create Task** for the escalation role, then **Send Notification** to the specific accountable coordinator.       |
| Prevent repeats | Store a visible escalation status, timestamp, or related escalation-task ID on the case.                           |
| Resolution      | Use **Wait For Task Action** or a task-action trigger to continue only after the accountable role responds.        |

### Make the escalation useful

An escalation should carry the information needed to act: source case ID, current queue, age, responsible unit, next expected decision, and link or relationship to the case. Avoid sending a generic alert that requires the recipient to search for context.

## Recipe 4: produce a decision document after approval

**Use when:** An approved form or decision must create a controlled document that can be attached to the case.

| Design decision | Recommended implementation                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| Source event    | **On Form Signature Signed** or **On Form Action** at the approved decision point.                         |
| Guard condition | The form version, signature path, resolution, and source case are all the expected ones.                   |
| Human boundary  | Use **Wait For Form Signature** or **Wait For Form Action** when a later human decision is required.       |
| Document step   | **Word Template** or **Excel Template** with an approved template and a deliberately mapped value set.     |
| Final artifact  | **Word to PDF** or **Excel to PDF** where a PDF is required by policy.                                     |
| Recordkeeping   | **Update Record** with the approved document reference and a status that accurately reflects the decision. |

### Document controls

Treat the template as part of the service policy. Test it with empty optional values, long text, Arabic content, and each allowed decision outcome. Verify that the generated artifact has the right headings, signatory information, date, and attachments before using it in a live process.

## Recipe 5: provide a controlled dashboard or form response

**Use when:** A dashboard widget or form must receive calculated data without exposing records outside the user's permitted scope.

| Design decision  | Recommended implementation                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| Source event     | **On Dashboard Widget Call** or **On Form Call**.                                                            |
| Guard condition  | The request mode, input shape, and requested service scope are valid.                                        |
| Read step        | **Find Records** with the narrowest allowed criteria.                                                        |
| Response step    | Shape a minimal JSON body, then use **Return Dashboard Widget Response** or **Return Form Response**.        |
| Error path       | Return a documented empty, validation, or error response without leaking private data.                       |
| Proof of success | The widget or form shows the expected result for an authorized request and no result for a disallowed scope. |

### Response design checklist

* Define the JSON fields, types, and empty-state behavior before building.
* Return identifiers and summaries only when the interface needs them.
* Do not return private notes, internal-only fields, or broad record lists merely because the automation can query them.
* Test malformed input, zero matching records, multiple matching records, and a request outside the intended scope.

## Recipe 6: close the loop after a reviewed task action

**Use when:** An accountable role completes a task action and the source case needs a consistent follow-up.

1. Start with **On Task Action** for the exact task type.
2. Narrow it to the approved old/new status transition where available.
3. Read the source case through the task's stored relationship or known ID.
4. Confirm that the task action is the expected approved outcome.
5. Update the source case with the decision and next status.
6. If policy requires a new hand-off, create the next task or notification only after the case update succeeds.
7. Keep the completed task, case, and any generated document linked so the decision trail can be reviewed.

## Rollout checklist for every recipe

1. Build with an approved non-production record and non-production recipients only.
2. Verify the trigger payload, condition, every read, every write, and final result.
3. Run each negative case: missing data, unrelated update, duplicate attempt, wrong status, and unauthorized scope.
4. Have the service owner review the created record, task, document, or response—not just the automation editor output.
5. Enable the smallest service scope first.
6. Monitor the first live results and retain a clear path to disable the flow if results differ from the approved design.

<Warning>Never copy a recipe directly into a live service. Each one requires the organization's own data model, access rules, approval boundaries, and accountable owner.</Warning>

![KayanOS Automations recipe for a controlled service escalation.](https://kayanos.app/docs-images/en/build/automations-recipes.png)

## Continue building

* Inspect the available [KayanOS Automations triggers](/build/automations-triggers) and [actions](/build/automations-actions).
* Use [Test, run, and troubleshoot automations](/build/automations-test-run-and-troubleshoot) before enabling any recipe.
* Review [permissions and availability](/reference/permissions-and-availability) before expanding the service scope.