Workflows & Approvals

Automate approval processes, notifications, and field updates when records are created or updated

Overview

Workflows let you automate multi-step approval processes without writing code. When a record is created or updated, the workflow engine evaluates matching rules and kicks off approval chains, sends notifications, and updates fields automatically.

Examples:

Leave request → HOD approves → Principal approves → status updated to "Approved"
Expense claim → HOD verifies → Finance processes → payment marked "Approved"
Fee concession → Finance reviews → Principal approves → concession applied
Gate pass → Warden approves within 4 hours → student can leave campus
Admission → Counsellor reviews → Head of Admissions enrolls student

How It Works

Record Created/Updated
  ↓
Workflow Engine checks for matching triggers
  ↓
Creates Workflow Instance
  ↓
Assigns Stage 1 to users (by role, manager, or specific user)
  ↓
Assignee sees it in "My Approvals"
  ↓
Approves → advances to Stage 2 (or completes)
Rejects → workflow terminates, field updates applied
  ↓
Notifications sent at each transition

Creating a Workflow

Navigate to Automation > Workflows and click New Workflow.

Name and Trigger

Give the workflow a name (e.g., "Leave Request Approval"). Select the trigger entity (which object triggers this workflow) and the trigger event (CREATE, UPDATE, DELETE, or STATUS_CHANGE). After creation, you're taken to the visual builder.

Configure Trigger

In the builder's Trigger step, set:

Trigger Entity — any of the 41 registered entities (Student, Expense, GatePass, etc.)
Trigger Event — when the workflow fires (Record Created, Record Updated, etc.)
Description — explain the workflow's purpose for other admins

Build Stages

Switch to the Stages step and add approval stages:

Click Add Stage to create a new step in the pipeline
Click any stage to open its configuration panel on the right
Drag stages to reorder them (first stage fires first)

For each stage, configure:

Stage Name — e.g., "HOD Approval", "Finance Review"
Stage Type — Approval, Notification, Auto Action, Parallel Approval, or Conditional
Assignee Type — who should act on this stage (see Assignee Types below)
SLA Hours — how long the assignee has before it shows as overdue
Notify on Entry — which channels to notify the assignee (In-App, Email, SMS)

Activate

Toggle the workflow to Active in the toolbar and click Save. The workflow is now live — any matching record event will trigger it.

Assignee Types

Type	Description	Example
Role	All users with a specific role	"All users with HOD role"
Specific User	A named individual	"John Smith (Principal)"
Reporting Manager	The submitter's manager	"Whoever manages the person who created the record"
Department Head	HOD of the submitter's department	"Head of the submitter's department"
Dynamic Field	User ID from a field on the record	"The user in the `assignedToId` field"

When a role or department head has multiple matching users, all of them receive the assignment. The first to act advances the workflow.

Stage Types

Type	Description
Approval	Requires a human to approve or reject before advancing
Notification	Sends a notification and auto-advances (no human action needed)
Auto Action	Executes field updates automatically and advances
Parallel Approval	Multiple approvers must all approve before advancing
Conditional	Evaluates a condition to decide which path to take

Field Updates on Approve/Reject

Each stage can automatically update fields on the record when approved or rejected. For example:

On Approve at the final stage: set status to "APPROVED"
On Reject at any stage: set status to "REJECTED"

This eliminates manual status updates — the workflow handles it.

My Approvals Inbox

Every user has a My Approvals page (Self Service > My Approvals) showing their pending workflow tasks.

The inbox shows:

Workflow name and trigger event
Entity being approved
Current stage name and type
Assigned date and due date (from SLA)
Overdue badge (red) if past SLA, Due Soon badge (amber) if within 24 hours

Click a row to see the detail panel:

Link to view the entity record
Stage pipeline showing progress
Action history (who approved/rejected/commented and when)
Approve, Reject, and Comment buttons

Approvals Badge

A clipboard icon in the header shows your pending approval count. It updates every 60 seconds.

Pre-built Workflow Templates

OptiCRM ships with 5 ready-to-use workflow templates. Seed them by calling:

POST /api/admin/seed-workflows

Template	Entity	Stages	SLA
Leave Request Approval	LeaveRequest	HOD Review (48h) → Principal Approval (24h)	72h total
Expense Approval	Expense	HOD Approval (48h) → Finance Review (72h)	120h total
Fee Concession Approval	Concession	Finance Review (48h) → Principal Approval (24h)	72h total
Admission Progression	Enquiry	Counsellor Review (24h) → Head of Admissions (48h)	72h total
Hostel Gate Pass	GatePass	Warden Approval (4h)	4h total

Templates are created inactive — review and activate them after verifying the assignee configuration matches your institution's role structure.

Notifications

The workflow engine sends notifications at these points:

Event	Who Gets Notified	Channels
Stage assigned	New assignees	In-App + Email (configurable per stage)
Workflow completed	Initiator	In-App + Email
Workflow rejected	Initiator	In-App + Email

Notifications use the existing notification engine and respect the channels configured on each stage's "Notify on Entry" setting.

Tips

Start with templates — seed the pre-built workflows and customize them rather than building from scratch
Test before activating — create the workflow inactive, verify stages and assignees, then activate
Use SLA wisely — set realistic SLA hours. Overdue items are highlighted red in the inbox
Dynamic fields for flexibility — use "Dynamic Field" assignee type when the approver depends on the record (e.g., the assigned counsellor on an enquiry)
One workflow per trigger — the engine picks the first matching active workflow. Don't create multiple active workflows for the same entity + event
Field updates for automation — use on-approve/reject field updates to automatically change record status, reducing manual work