Test, run, and troubleshoot automations

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:

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

Automation: <name and version>
Run time: <time and timezone>
Source event: <trigger and non-production record ID>
Expected condition: <true/false and why>
Actual payload fields used: <field names only if data is sensitive>
Last successful step: <trigger/read/action>
Failed step and error: <exact safe error message>
Affected target: <record/task/document ID, if any>
Duplicate or external effect: <yes/no>
Reviewer and next decision: <name/role and action>

This makes it possible to distinguish a configuration issue from a permission, data, or lifecycle issue without exposing unnecessary personal or service data.

Recovery after an unsafe or duplicate run

Disable the automation if it can repeat the same effect.
Identify every target created or changed by the run using the source relationship, run output, and timestamp.
Do not delete records just to hide the problem; follow the approved correction or cancellation procedure.
Correct the trigger, condition, duplicate guard, or target mapping in the non-production workspace.
Repeat the positive and negative tests.
Obtain owner review before re-enabling the flow.

Do not treat a successful test-panel response as completion. The test is complete only when the accountable reviewer can locate and verify the intended KayanOS result with no duplicate or unintended side effect.

KayanOS Automations test-run history for a controlled workflow.

Continue building

Review KayanOS Automations triggers and actions when correcting a flow.
Apply the KayanOS Automations recipes in an approved non-production scope.
Review permissions and availability before widening access.

​What a successful test proves

​Test protocol

​1. Define the expected path before running

​2. Test the trigger in isolation

​3. Test the condition both ways

​4. Add and verify one action at a time

​5. Verify the complete audit trail

​6. Roll out in stages

​Diagnose failures in the right order

​Known input-validation patterns

​A repeatable failure-report template

​Recovery after an unsafe or duplicate run

​Continue building

What a successful test proves

Test protocol

1. Define the expected path before running

2. Test the trigger in isolation

3. Test the condition both ways

4. Add and verify one action at a time

5. Verify the complete audit trail

6. Roll out in stages

Diagnose failures in the right order

Known input-validation patterns

A repeatable failure-report template

Recovery after an unsafe or duplicate run

Continue building