Workflows and Statuses

A workflow is the directed graph of statuses and transitions that drives everything: sessions, invoices, clients, and payroll. Build your own by adding statuses and connecting them with transitions.

Statuses

Default statuses

FoxCLM ships with default statuses per entity type:

Type	Default statuses
Sessions (c)	Scheduled, Commencing, Occurred, Cancelled, Pending
Invoices (i)	Draft, Sent, Pending Payment, Paid, Overdue, Cancelled
Payroll (p)	Draft, Approved, Rejected, Paid
Clients (cl)	Lead, Active, Inactive, Churned

Adding a status

1. Go to Settings -> Workflows & Statuses (or click the Workflow link in the sidebar).
2. Pick the entity type (Sessions / Invoices / Payroll / Clients).
3. Click + Add Status.
4. Enter:
   • Name (required) - e.g. "Submitted for Approval"
   • Description (optional)
   • Colour - shown as a badge throughout the UI
   • Auto-advance - toggle on if this status should be checked by the auto-advance cron
5. Save.

Editing and removing statuses

Click any status node on the flowchart to edit or delete it. Deleting a status prompts you to reassign entities currently in that status.

Transitions

A transition is an arrow from one status to another. It represents a state change.

Adding a transition

1. On the flowchart, drag from one status to another (or click + Add Transition).
2. Pick:
   • From status and To status
   • Label - the button text on the entity (e.g. "Approve", "Send")
   • Condition (optional) - see below
3. Save.

Sort order

Transitions from the same status are evaluated in sort_order - lower numbers first. This matters when multiple transitions match from the same status (e.g. "Sent -> Paid" and "Sent -> Overdue" both valid).

Drag transitions up and down in the list to reorder.

Conditions

A condition is a rule that must be true before a transition fires. Only the first matching transition (by sort order) is taken.

Supported operators

Operator	Meaning
eq	Equal
neq	Not equal
gt	Greater than
lt	Less than
gte	Greater or equal
lte	Less or equal
is_null	Value is empty
is_not_null	Value is set
contains	Substring match (case-insensitive)

Value types

• Static - compare to a literal value (e.g. status = "Active")
• Column - compare to another field on the same entity (e.g. paid_at < due_date)

Special values

• $NOW - current datetime
• $TODAY - current date (midnight)

Example: simple condition

"Only move invoice to Overdue if due date is past."

field: due_date
op: lt
value: $NOW
value_type: static

Example: column comparison

"Mark invoice as Late Paid if payment came after due date."

field: paid_at
op: gt
value: due_date
value_type: column

Compound conditions

Combine multiple rules with and/or:

logic: and
rules:
  - field: amount
    op: gte
    value: 500
  - field: status_text
    op: eq
    value: Sent

The transition fires only if both rules are true.

Auto-advance

Transitions with conditions are evaluated by a cron job that runs every few minutes. Per type, it evaluates the date columns:

Entity	Date column used
Session	start_date / end_date
Invoice	due_date
Payroll	period_end
Client	updated_at

When a condition becomes true for a row, the transition fires. Actions are queued.

Actions

See Workflow Actions for the 25 action types.

Testing a workflow

Click Test Workflow on the Workflows page to run a dry-run:

• All transitions are enumerated
• Mock entities are created that satisfy each condition
• Failed conditions are flagged
• Full paths (Start -> End) are shown

Use this after making changes to catch broken condition logic before entities get stuck.

Next steps

• Workflow Actions - what fires when a transition runs
• Webhooks & API - hook into external systems on transitions
• Automation Settings - global toggles