Workflow rules

Workflow rules are how IssuesId does the routine work for you. A defect changes state — a rule notifies a contractor. A defect goes overdue — a rule escalates to the project manager. A new defect is assigned to a trade — a rule sends them the photo pack.

You write the rule once, in plain conditions. The engine runs it every time the matching event happens.

What a rule looks like

Each rule is built from three pieces:

01A trigger — the event that fires the rule.
02A condition — optional filters (e.g. "only when priority is high").
03An action — what to do (notify, assign, escalate, tag).

The four available triggers are:

→`status_changed` — a defect, work order, or RFI moved to a new state.
→`assigned` — a record was assigned to a user or contractor.
→`overdue` — a record passed its due date without progressing.
→`disputed` — a defect entered the dispute state.

Recipient targeting

Notifications can target any combination of:

→Roles — e.g. "all project managers on this project."
→Named users — specific team members.
→Contractors — the assigned trade plus their nominated contacts.
→Freeform email addresses — external stakeholders who don't have accounts.

A single rule can fan out to all four at once.

Immediate or digest

Each rule fires on one of two schedules:

→Immediate — the action runs the moment the trigger event occurs.
→Digest — the action accumulates events over a window and fires on a cron schedule (e.g. daily at 9am, every Monday morning, end of every shift).

Immediate is right for urgent things — disputes, safety issues, blocked work. Digest is right for the steady drumbeat — overnight summaries of yesterday's progress, weekly outstanding-defect counts, end-of-week trade burn-down.

Cycle detection

Workflow rules can chain — one rule's action can become another rule's trigger. The engine detects cycles at evaluation time and refuses to enter an infinite loop. If you accidentally write a rule that would re-trigger itself, the engine logs the cycle, fires the first iteration, and stops.

This means you can write rules without fear of runaway behaviour — but if a rule isn't firing as often as you expect, check the rule log for cycle-stop entries.

Example rules

A few rules teams write on day one:

→High-priority defect → notify project manager immediately. Trigger: status_changed to assigned. Condition: priority = high. Action: notify PM.
→Defect overdue 24h → escalate to company admin. Trigger: overdue by 24h. Action: notify the company admin role and re-flag the defect.
→Trade marks work complete → notify the supervisor for sign-off. Trigger: status_changed to trade_completed. Action: notify the assigning supervisor.
→Daily project digest. Trigger: digest, cron 0 9 * * *. Action: email each PM a roll-up of the prior day's activity on their projects.

Audit and runtime guards

Every rule firing is logged with:

→The trigger event and the record it fired against.
→The recipients notified.
→The action taken and its outcome.
→Any cycle-stop or condition-skip notes.

The log is the source of truth for "did the rule fire?" questions. If a notification didn't arrive, start here.