Workflows and approvals
The eight workflow categories, what a step is, escalations + reminders, and how to customize them.
On this page
A workflow is the sequence of steps a business process moves through — record, verify, approve, post. Every team has slightly different rules ("payments above SAR 10,000 need a director's sign-off"), so the system ships sensible defaults and lets workspace admins customize.
The eight workflow categories
| Category | What it governs |
|---|---|
| Lease offer | Drafting, negotiating, accepting a lease offer |
| Payment verification | Recording → verifying → posting a tenant payment |
| Expense verification | Recording → verifying → posting an expense |
| Deposit payment verification | Recording the initial security deposit |
| Deposit refund verification | Refunding the deposit at contract end |
| Maintenance | Reporting → assigning → resolving → closing |
| Recurring task | Generated instance → working → completing |
| Contract expiry | Approaching contract end → renewal or close |
Each category has a default workflow that works out of the box. You only need to customize if your process is different.
What a "step" is
A workflow is a chain of steps. Each step is either:
- Domain — the core action (e.g. "Record payment", "Mark work complete"). Always one per workflow, always at the start.
- Gate — an approval/verification (e.g. "Manager verifies", "Director approves"). You can have any number of gates after the domain step.
A step has:
- A name ("Manager verification").
- A role that's allowed to act on it (e.g. "Manager", or a custom role).
- Optional rules (e.g. only required when the payment amount exceeds SAR 10,000).
Customizing a workflow
Open Settings → Workflows, pick the category, and edit. The editor lets you:
- Add or remove gate steps.
- Re-order steps (the domain step stays first).
- Change the role assigned to each gate.
- Add conditional rules (gate only triggers above a threshold, etc.).
Save. The next process started will follow the new workflow. In-flight processes keep their existing workflow — changes are not retroactive.
[!warning] A gate step requires action from a member with the matching role. If you assign a gate to a role no one holds, processes will stall there. Always make sure the role has at least one member before saving.
Notifications
Every time a workflow advances, the system notifies the role of the next step. For a payment verification: the recorder submits → the system pings the Manager role → the Manager verifies → the payment posts.
Notifications go to every channel the user opted into (in-app inbox, email, mobile push if installed). Per-role notification overrides live in Settings → Notifications.
Returning and reassigning
If a verifier spots a problem (e.g. wrong tenant, wrong amount), they can Return the item to the previous step. The original recorder gets a notification with the reason and can fix and resubmit. The audit trail records every transition.
A verifier can also Reassign to a different member with the same role (e.g. "out of office — Ahmad will handle this batch").
Escalations and reminders
Workflow steps don't just sit there indefinitely. Each step can carry a deadline, and the engine fires two kinds of nudge around it.
How it works
- Reminder — fires N hours before the deadline. The role currently holding the step gets a notification: "Verify this payment by 5pm tomorrow."
- Escalation — fires when the deadline passes without action. A second role (the escalation role) is notified. If the step is configured with "reassign on escalation," that escalation role also gains the ability to act on the item directly — both the original and the escalation role can now move it forward.
A 5-minute cron checks for overdue items, so escalations land within minutes of the deadline.
Configuration
Escalation settings live on each individual step inside the workflow editor at Settings → Workflows. For each step that has a deadline, an Admin can configure:
- Deadline hours — how long after the step is reached the deadline is.
- Reminder hours — how long before the deadline the reminder fires.
- Escalation role — which role gets pinged when the deadline passes.
- Reassign on escalation — toggle whether the escalation role gains action authority or just visibility.
Workflows ship with sensible defaults. Most teams never touch escalation config; you only need to think about it when a particular step has a hard SLA (e.g. "lease offers must be verified within 24 hours" or "deposit refunds must be approved within 3 business days").
How escalations surface in the UI
- The Tasks page shows due-soon and overdue badges next to each item.
- An item escalated to a second role appears in both roles' task queues — the original member can still complete it, but if they've gone silent, the escalation role can now act.
- The full audit trail records every reminder and escalation event with timestamp.
[!warning] A step configured to escalate to a role with zero members will get stuck. The reminder fires but no one receives the escalation — there's no one to receive it. If you add an escalation, make sure the escalation role has at least one assigned member on the relevant property.
Where to find each workflow's state
- Tasks page shows every workflow item assigned to you across all categories — your action queue.
- Each module's page (Payments, Expenses, etc.) shows items at the workflow step relevant to that module. A "Pending verification" filter shows only the ones waiting for someone to act.
- Each item's detail page shows the full step-by-step history with timestamps and actor names.