Help /

Escalation & Notification Processing

This page provides administrative controls for running the approval system's two background processes: escalation processing (detecting and escalating overdue drafts) and email notification sending (dispatching queued notification emails to approvers and submitters).

The page also displays a Current Escalation Risk dashboard showing all pending drafts and their proximity to escalation deadlines.

Execution Modes

The escalation and notification processors can be triggered in three ways:

Mode	How It Works
Web (Manual)	Click the buttons on this page to run processing immediately.
Web (Auto)	Access the page URL with `?auto` query parameter to trigger both processors in one request.
CLI (Cron)	Run `php /path/to/admin/approval_cron.php` from the command line (e.g., via cron job). The script bootstraps without a browser session, connects to company 0, runs both processors, and exits.

Cron Setup

The page displays the recommended cron command for your server:

*/30 * * * * php /full/path/to/admin/approval_cron.php

This runs the processors every 30 minutes. Adjust the schedule as needed for your organisation.

Action Buttons

Button	Action
Process Escalations	Scans all pending drafts for overdue items and escalates them according to their level configuration.
Send Pending Emails	Processes the notification queue and sends any unsent email notifications to users.
Process All	Runs both escalation processing and email notification sending in one step.

---

Escalation Processing

How Escalation Works

The system queries all pending drafts where the number of days at the current approval level meets or exceeds the level's Escalation Days threshold.
Days at level is calculated from the date of the most recent submit, approve, or escalate action at the current level — or from the submission date if no such action exists.
For each overdue draft, the system checks a double-escalation guard: if the last escalation was less than 24 hours ago, the draft is skipped (to prevent rapid repeated escalation).
If the level has an Escalate To Level configured, the draft advances to that specific level. Otherwise, it advances to the next sequential level (current + 1).
If the draft is already at the maximum level in the workflow, it cannot advance further. Instead, a reminder is sent to the current-level approvers.
Each escalation creates an action record with user_id = 0 (indicating a system-generated action) and action type escalate.
Notifications are sent to the new-level approvers and the original submitter.

Escalation Results Table

After processing, a results table is displayed:

Metric	Description
Drafts Processed	Total number of overdue drafts examined
Escalated to Next Level	Number of drafts successfully moved to a higher level
Reminders Sent (At Max Level)	Number of drafts at the maximum level that received reminder notifications
Skipped (Recently Escalated)	Number of drafts skipped because they were escalated less than 24 hours ago

Escalation Details Table

A detailed log is shown with one row per processed draft:

Status — colour-coded: escalated (orange, bold), reminded (blue), skipped (gray)
Message — descriptive text (e.g., "Escalated DRF-0023 from Level 1 to Level 2")

---

Email Notification Processing

How Notifications Work

The approval system uses a two-phase notification model:

Phase 1 — Queuing: Whenever an approval action occurs (submit, approve, reject, escalate, delegate), an in-app notification record is created in the approval_notifications table for each relevant user.
Phase 2 — Sending: The email processor reads the queue, builds email messages, and sends them. Each notification is then marked as sent.

Notification Types and Email Subjects

Notification Type	Email Subject Format	Recipients
Pending	`[Approval Required] Purchase Order DRF-0001`	Approvers at the current level
Approved	`[Approved] Purchase Order DRF-0001`	Original submitter
Rejected	`[Rejected] Purchase Order DRF-0001`	Original submitter
Escalated	`[Escalated] Purchase Order DRF-0001`	New-level approvers and submitter
Delegated	`[Delegated] Purchase Order DRF-0001`	Delegate (the user receiving the delegation)

Email Body Structure

Each email contains:

Greeting (Dear [UserName],)
Context message explaining the action (e.g., "A new purchase order requires your approval")
Draft summary text
Transaction amount
Prompt to log in and take action

Email Sending

Emails are processed in batches (up to 100 in web mode, 50 in CLI mode).
The sender name and address are taken from the company settings (company name + company email). If no company email is configured, noreply@<hostname> is used.
Users without an email address in their user profile are skipped.

Email Results Table

Metric	Description
Emails Sent	Total number of notification emails dispatched in this batch

---

Current Escalation Risk Dashboard

The bottom section of the page shows a real-time view of all pending drafts that have escalation configured, sorted by urgency (most overdue first):

Column	Description
Reference	Draft reference (e.g., DRF-0001)
Workflow	Workflow name
Level	Current approval level
Days at Level	Number of days the draft has been at the current level
Escalation After	Number of days configured for escalation at this level
Days Remaining	Days until the escalation deadline. Negative = overdue.
Status	Colour-coded badge: OVERDUE (red), At Risk (yellow, ≤ 1 day remaining), Normal (green)
Amount	Transaction amount

Tips

Set up the cron job to run every 30 minutes for timely escalation. Without the cron job or manual triggering, overdue drafts will not be escalated and emails will not be sent.
Monitor the Current Escalation Risk table regularly to identify drafts that are approaching their escalation deadline.
If a draft is being repeatedly escalated and skipped, check whether the approvers at the target level have the correct security role assigned.
Ensure all approver users have a valid email address in their user profile for email notifications to work.

Escalation & Notification Processing