Automations

What automations do

Automations let the lab run workflow logic when important events happen. A workflow can start when an order is created, an order status changes, a sample is created or updated, an inventory item changes, a transfer is created, a receipt is posted, a finance transaction changes, an invoice changes, or a payment changes. The workflow can then evaluate conditions and run actions.

Use automations for repeatable operational follow-up, not for decisions that require clinical judgment. Good examples include notifying managers about delayed orders, alerting inventory staff when a transfer changes status, sending internal notifications for high-value finance transactions, or calling a webhook for integration.

Viewing the list requires the automation view permission. Creating, editing, publishing, pausing, resuming, or deleting workflows requires the automation manage permission. The panel also verifies that every workflow belongs to the current lab company.

Workflow state

Each automation has a name, trigger type, status, description, and draft definition. Status can be Draft, Active, or Paused. Draft workflows are editable and not running. Active workflows can execute when their trigger fires. Paused workflows keep their published version but do not run until resumed.

The visual builder stores the definition as nodes and edges. The trigger type is derived from the single trigger node, and status is changed only through Activate, Pause, and Resume. A browser payload cannot activate a draft or select a different trigger independently.

When starter templates are enabled, Create From Template creates a draft only. Applying a template inside the designer replaces unsaved graph changes, so inspect every trigger, condition, recipient, and message before saving.

Every saved draft is assigned from your current lab workspace on the server; the browser cannot choose or replace its lab company. If the workspace session is no longer available, Kashef keeps the draft unsaved and asks you to reopen the lab workspace instead of displaying a database error.

Triggers

Trigger options come from the automation trigger registry. The current catalog includes approved critical results, overdue order-collection SLAs and escalation levels, order created, order status changed, sample CRUD events and status changes, inventory item, warehouse, stock level, transfer, supply request, receipt, transaction, supplier events, finance account, category, transaction, entry, invoice, and payment events.

Choose the most specific trigger you can. For example, use order status changed when the automation depends on a status transition, not order updated. Specific triggers reduce noise and make run history easier to understand.

Critical Result Approved starts only when a critical-low or critical-high result first enters an approved or released state. Its event identity includes the result revision, so saving the same approval again does not deliver the same workflow twice, while an amended and reapproved value receives a new identity. Clinical test and parameter names in this payload use their English result-report names.

Order Collection SLA Overdue starts when an uncollected sample first breaches its deadline and again only when it reaches a new escalation level. Conditions can use the order code and priority, sample barcode, due time, overdue minutes, escalation level, branch, and accountable owner.

Nodes, conditions, and actions

The workflow schema defines allowed node types. Trigger nodes start the flow. Condition nodes branch execution by evaluating payload fields. Action nodes can create in-app notifications, send email, send WhatsApp messages, or call webhooks depending on configured executors and provider availability.

Edges connect nodes. A condition has true and false paths. Action nodes can continue to another node. The execution engine walks the graph from the trigger node, records steps, evaluates conditions, executes supported actions, and stops if a runtime limit is reached.

In-app notifications can target managers in the workflow company or the staff member who created the triggering order. The builder does not offer arbitrary user IDs because that would be difficult to review and could cross company boundaries.

Webhook actions require HTTPS and a host listed in AUTOMATION_WEBHOOK_ALLOWED_HOSTS. Local, private, reserved, credential-bearing, unlisted, and redirect-based targets are blocked. Configure only integration hosts controlled by the lab or a trusted vendor. HTTP can be enabled explicitly for a controlled non-production environment, but should remain disabled in production.

Publishing and versions

Publishing validates the draft definition. If valid, Kashef creates a new workflow version with an incremented version number, checksum, published timestamp, and creator. The workflow becomes Active and stores the current version. If the draft is missing or invalid, publish fails and shows an error.

Pausing changes status to Paused. Resuming requires an existing published version and changes status back to Active. This separation lets admins stop a workflow temporarily without losing the last valid published definition.

Draft and paused workflows can be removed. An active workflow must be paused first. Removal is soft deletion, so published versions and run history remain available for audit and recovery.

Run, retry, and failure history

Open Automation Runs in Admin to review every current-company execution. The dense table shows the workflow, trigger, run state, attempts, timing, next retry, duration, and final error. Use Inspect run to keep the list context while reviewing the immutable version, idempotency key, and each recorded node outcome.

One workflow and event identity create one run record. A retry restarts the same run and replaces its previous step attempt records, preventing duplicate concurrent execution. Failures use bounded backoff. The table shows Retry scheduled between automatic attempts and Retry exhausted after the final attempt. Only a user with automation-manage permission may manually restart an exhausted run, and the request is audited. Completed, queued, running, paused-workflow, or another-company runs cannot be manually retried.

Practical design rules

Keep each automation narrow. One trigger, one clear purpose, and a small number of actions are easier to support than one huge workflow that handles many unrelated cases. Name workflows by outcome, such as Notify manager when transfer is rejected, not by implementation detail.

Use Validate to check the graph, then Test from a saved workflow. Test runs use generated simulation data and record their steps, but they do not send in-app notifications, email, WhatsApp messages, or webhook requests. Confirm the previewed recipients and rendered content, then publish and monitor the first real runs in Activity Logs.

Checklist

• Trigger type matches the event you truly need.
• The draft definition contains a trigger node connected to at least one next node.
• Conditions use payload fields that exist for the selected trigger.
• Actions have complete recipient and message settings.
• Webhook hosts are explicitly allowlisted in the production environment.
• A saved simulation test completes without validation or execution errors.
• Workflow is published before it is expected to run.
• Paused workflows are reviewed so critical notifications are not silently disabled.
• Automation Runs is checked after activation until the first real run completes.
• Retry-scheduled and retry-exhausted runs have an accountable owner and resolution.