> ## 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. # Test, run, and troubleshoot automations > Validate each KayanOS automation with a controlled non-production run, then diagnose the trigger, condition, action, scope, and resulting record in order. ## What a successful test proves A successful test proves more than “the flow ran.” It proves that the intended event supplied the intended data, the condition made the right decision, the action affected only the approved target, and a reviewer can locate the result. Use an approved non-production workspace, an isolated record such as `PERMIT_TEST_001`, and non-production members. Never validate a new automation with real citizen data, a production role scope, or an external recipient. ## Test protocol ### 1. Define the expected path before running Write down the following before opening the test panel: | Step | Record before testing | | --------------------- | -------------------------------------------------------------------------------- | | Trigger | The exact event, source table/form/task, and record identifier. | | Condition | The values that should make it true and one variation that should make it false. | | Reads | The record or record set that should be found. | | Writes | The exact table/record/task/document that may be created or changed. | | Notification/response | The intended internal recipient or minimal response schema. | | Reviewer | The person who will locate the final outcome and confirm it. | If you cannot describe the expected path, do not enable the automation yet. ### 2. Test the trigger in isolation Use one source record. Cause the precise event: submit the intended form action, change the intended status, complete the intended task action, or call the intended dashboard/form interface. Inspect the resulting payload before mapping downstream fields. For a record event, KayanOS can expose values such as `data`, `oldData`, `changedFields`, and `action`. Check that the event is the one you expected—not simply an update that happened to occur on the same record. ### 3. Test the condition both ways Run one case that should continue and one that should stop. For an inspection-routing flow, the positive case might move a complete application to `Ready for inspection`; the negative case might update a note or leave out the locality. The negative case must create no case, task, notification, document, or role change. ### 4. Add and verify one action at a time Start with a read or lookup action. Then add one write, wait, response, document, or notification action and run the test again. After every run, locate the result in KayanOS rather than relying only on the automation output. ### 5. Verify the complete audit trail For a successful run, confirm all of the following: * The source record has the expected relationship or status. * The created/updated target has the expected ID, values, and owner. * No duplicate record, task, notification, or document exists. * No unrelated record changed. * The notification reached only the intended internal member or scope. * A reviewer can trace the outcome from the source to the target and back. ### 6. Roll out in stages Enable the smallest service scope first. Monitor the first approved live runs, compare them with the expected design, and keep a documented owner and disable path. Expand only after the service owner confirms that the hand-off is correct. ## Diagnose failures in the right order | Symptom | Check first | Typical correction | | -------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | The automation never starts | Trigger scope, source event, form/task/action filter, and whether the record actually caused the event. | Narrow or correct the trigger; rerun the exact source event. | | The trigger starts but the flow stops | Condition inputs and the actual test payload. | Compare current/old values, required fields, and field keys; make the condition explicit. | | A lookup finds nothing | Table, ID, relationship, filter values, and access to the target table. | Test **Get Record** with a known ID, then narrow **Find Records** with stable values. | | A write is rejected | Required action inputs, target table, field values, and role scope. | Map the exact required fields and test one minimal valid target. | | A duplicate is created | Retry behavior, broad update triggers, and missing existing-record check. | Add a status-transition guard and a **Find Records** check before **Create Record** or **Create Task**. | | The flow waits forever | Correlation ID, watched field, form session, task ID, or epic ID. | Confirm that the later event belongs to the same source case and is able to satisfy the wait condition. | | A task/action execution is denied | Task/epic/form/entity state, action name, and role permissions. | Use a permitted status/action path; do not try to automate around a required human decision. | | A response is invalid | Request input and JSON body shape. | Document the response schema, validate required fields, and test empty/no-result paths. | | A document is wrong | Template version, mapped values, and source artifact. | Test with optional values empty, long text, Arabic content, and each decision outcome. | | A notification is missing or misrouted | Member ID/member selector values, type, and recipient scope. | Use one recipient mechanism deliberately and verify the resolved audience in a non-production run. | | A role update is too broad | Scope, selector, target entity, and operation. | Stop the flow and reduce scope; obtain a permission review before retesting. | ## Known input-validation patterns These validation patterns are useful when interpreting an action error: 1. **Send Notification:** when you target a specific `Member ID`, leave `Member Selectors` empty unless the action is intentionally configured to use selectors. Supplying an unrelated text value in the optional selector control can cause a validation rejection. 2. **Create Record IDs:** use the identifier format accepted by the target table. In a verified non-production run, letters, numbers, and underscores were accepted, while a table-prefixed value containing a colon was rejected. Use a neutral ID such as `PERMIT_TEST_001`; do not copy an internal-only naming convention into production logic. The exact error output from the run is the primary evidence. Record the trigger, mapped inputs, error message, and the smallest change that resolves it. ## A repeatable failure-report template When a flow fails, capture this before changing anything: ```text theme={null} Automation: Run time: