DocsAutomation

Automation rules

The rule engine behind routing and deadline chasing: seven trigger types, eleven condition operators, seven action types, the run log, and the ten rules seeded by default.

5 min readLast updated September 3, 2026

An automation rule is a trigger, optional conditions, and one or more actions. Rules do the work nobody remembers to do: routing an application to the officer who owns its new stage, creating the task to book a clinic, chasing a passport six months before it expires.

Automation never breaks a write. Rules fire after the operation that triggered them has already committed, outside its transaction, and a failure is caught and recorded rather than propagated. A slow or broken rule cannot hold a database lock or fail a document verification.

Triggers#

Trigger	Fires when	Config it accepts
`APPLICATION_CREATED`	An applicant is endorsed to a position.	—
`STAGE_CHANGED`	An application enters a new stage.	`toStageCode` restricts the rule to one destination stage.
`DOCUMENT_EXPIRING`	The nightly expiry scan finds a verified document approaching its date.	`daysBefore`, and optionally `documentTypeCode` to target one type.
`DOCUMENT_VERIFIED`	A document is verified.	—
`CHECKLIST_OVERDUE`	The daily automation cron finds a stalled application.	`staleDays` — matches at or beyond the threshold.
`PAYMENT_RECEIVED`	A payment is recorded.	—
`DATE_APPROACHING`	The daily cron finds a date field nearing.	`field` (a dotted path such as `application.expectedDepartureAt`) and `daysBefore`.

Threshold triggers fire once, on the day. DOCUMENT_EXPIRING and DATE_APPROACHING match only when the remaining days equal daysBefore exactly. A 30-day rule fires on day 30 and not on the twenty-nine days after it — which is the difference between a useful warning and an ignored one. CHECKLIST_OVERDUE is the exception: it matches at or beyond its staleDays.

Conditions#

Conditions are optional. When present, all of them must hold — they are ANDed. Each names a dotted field path resolved against the trigger context, an operator, and usually a value.

Operator	Test
`eq`, `neq`	Strict equality or inequality.
`in`, `notIn`	Membership in an array value.
`gt`, `gte`, `lt`, `lte`	Numeric comparison.
`contains`	Substring or collection membership.
`isSet`	The field has a value.
`isEmpty`	The field is blank.

A rule with no conditions always proceeds to its actions once the trigger and its config match. A rule whose conditions fail is recorded as SKIPPED with the reason, rather than silently doing nothing.

Actions#

Action	Effect
`ASSIGN_STAGE_OWNER`	Assign the application to the role that owns its current stage. This is what makes a handoff land in someone’s queue.
`ASSIGN_ROLE`	Assign to a named role’s queue.
`ASSIGN_USER`	Assign to a specific user.
`CREATE_TASK`	Create a task with a title, optional description, an assignee role, a due date `dueInDays` out, and a priority of `LOW`, `NORMAL`, `HIGH` or `URGENT`.
`SEND_EMAIL`	Queue a templated email by `templateCode`, optionally addressed to the applicant. Sending is handled by the background worker.
`NOTIFY`	Create an in-app notification with a title and body, optionally scoped to a role.
`SET_CHECKLIST`	Mark a checklist item done or not done by code.

`SET_CHECKLIST` can change gate outcomes. Checklist items are what several stage requirements read. A rule that sets one is, indirectly, deciding whether an application may advance. Use it for genuinely mechanical facts, not to route around a requirement you find inconvenient.

The run log#

Every evaluation writes an AutomationRun row with a status of SUCCESS, SKIPPED or FAILED, plus the context and what was performed. A rule that appears to do nothing can be diagnosed rather than guessed at: either it never matched, or it matched and skipped on conditions, or it failed.

A successful run also increments the rule’s runCount, stamps lastRunAt, and writes automation.fired to the audit trail with the trigger and the actions performed. Note the actor on that audit row is null — it was the system, not a person.

The ten seeded rules#

Every new organization gets these. All of them are editable and can be disabled.

Routing and acknowledgement#

Rule	Trigger	Actions
Route to the owning officer on stage change	`STAGE_CHANGED`	`ASSIGN_STAGE_OWNER` — makes every handoff explicit.
Welcome new applications	`APPLICATION_CREATED`	Email the applicant the `APPLICATION_RECEIVED` template.

Expiry warnings#

Rule	Trigger	Actions
Document expiring within 30 days	`DOCUMENT_EXPIRING`, `daysBefore: 30`	High-priority Document Officer task due in 14 days, plus the `DOCUMENT_EXPIRING` email to the applicant.
Passport expiring within 180 days	`DOCUMENT_EXPIRING`, `daysBefore: 180`, `documentTypeCode: PASSPORT`	High-priority Document Officer task due in 30 days. Fires far earlier than other documents because most destinations require at least six months of passport validity.

Stage-driven work#

Rule	Trigger	Actions
Medical scheduling task on entering Medical	`STAGE_CHANGED`, `toStageCode: MEDICAL`	High-priority Liaison Officer task due in 3 days to book the DOH-accredited clinic, plus the `MEDICAL_SCHEDULE` email.
Chase the worker balance at Payment Status	`STAGE_CHANGED`, `toStageCode: FINANCIAL_CLEARANCE`	High-priority Accounts task due in 5 days to reconcile charges and sign the financial clearance, so ticketing is not held up.
Post-arrival check-in after deployment	`STAGE_CHANGED`, `toStageCode: DEPLOYED`	Three Welfare Officer tasks: day-7 and day-30 at normal priority, day-90 at low.

Departure countdown#

Rule	Trigger	Actions
PDOS reminder 7 days before departure	`DATE_APPROACHING` on `application.expectedDepartureAt`, `daysBefore: 7`	Only when `PDOS_COMPLETED` is not yet true. Creates an urgent Welfare Officer task due in 2 days — the PDOS certificate is a prerequisite for the OEC, so it cannot slip.
Departure briefing 3 days out	`DATE_APPROACHING`, `daysBefore: 3`	The `DEPARTURE_DETAILS` email plus an urgent Welfare Officer task to conduct the pre-departure briefing and confirm airport assistance.

Stall detection#

Rule	Trigger	Actions
Nudge stale applications after 21 days	`CHECKLIST_OVERDUE`, `staleDays: 21`	A normal-priority Recruitment Officer task due in 3 days: review or close the application.

The stale rule is the one that keeps the board honest. An application with no stage movement in three weeks is either blocked on something nobody noticed or should be closed, and both outcomes are better than a card sitting there indefinitely.

When rules run#

Two paths. Write-driven triggers fire inline from the code path that caused them — a stage move fires STAGE_CHANGED immediately after the transaction commits. Date-driven triggers are evaluated by the background worker’s automation cron at 01:30 Asia/Manila, which is also what feeds DOCUMENT_EXPIRING, DATE_APPROACHING and CHECKLIST_OVERDUE. See Notifications and scheduled jobs.

Rules are scoped to your organization and only active rules are considered, so disabling a rule takes effect immediately without deleting its run history.

Rules are configured in the database today. The engine, the seeded rules and the run log are all real. What does not exist is a settings screen for editing them — automation is a writable module for the Owner and System Administrator, but no UI or endpoint exposes it. Changing a rule currently means changing the row.

Was this page helpful?