Approval Workflow#

Some actions in the system need approval before they take effect. For example, creating a new part or submitting a purchase order might need a manager’s sign-off.

The Idea#

Think of it like a permission slip:

You want to do something (create a part, edit a price)
The system checks: “Does this need approval?”
If yes: Your request goes into a queue, and the right people get notified
An approver reviews it and says “approved” or “rejected”
If approved: The change actually happens
If rejected: Nothing changes, and you’re told why

The Three Key Pieces#

1. Change Matrix (The Rules)#

A ChangeMatrix defines who needs to approve what.

Example: “When someone creates a Part, it needs approval from the Procurement Team first, then the Finance Manager.”

{
  "level_1": {
    "role": ["procurement_team"],
    "user": []
  },
  "level_2": {
    "role": ["finance_manager"],
    "user": ["ceo@atomberg.com"]
  }
}

How levels work:

Level 1 must approve before Level 2 even sees it
At each level, ANY person in the listed roles OR listed users can approve
If a level has empty roles AND empty users, it’s auto-approved (skip)

2. Change Request (The Pending Change)#

When you try to do something that needs approval, a ChangeRequest is created:

What’s being changed (which entity, which action)
What the new values would be (stored as JSON)
Who requested it (your user)
Status: pending → approved or rejected

The actual change doesn’t happen yet — it’s just a record of what you want to do.

3. Approval (The Decision)#

Each level in the matrix creates an Approval task:

Which request it belongs to
Which level (1, 2, 3…)
Status: pending → approved or rejected
Who acted and when

Step-by-Step Flow#

You: "I want to create Part SCREW-M5"
  ↓
System checks ChangeMatrix for (Part, "create")
  ↓
Found! 2-level approval required.
  ↓
Creates ChangeRequest (status: pending)
Creates Approval for Level 1 (status: pending)
  ↓
Procurement Team member sees it in their task list
  ↓
They approve it ✅
  ↓
Level 1 done. System creates Approval for Level 2.
  ↓
Finance Manager sees it in their task list
  ↓
They approve it ✅
  ↓
All levels done! System commits the change.
  ↓
Part SCREW-M5 is now created in the database. 🎉

What if someone rejects?

Finance Manager rejects it ❌
  ↓
ChangeRequest status → "rejected"
  ↓
Part is NOT created.
You see the rejection reason in the request details.

When There’s No Matrix#

If no ChangeMatrix exists for an action, the change happens immediately — no approval needed. This is the default for most simple edits.

API Usage#

Check your pending tasks:

GET /api/webapis/approvals/tasks/

Approve a task:

POST /api/webapis/approvals/tasks/<sqid>/act/
{
  "action": "approved",
  "comment": "Looks good."
}

Reject a task:

POST /api/webapis/approvals/tasks/<sqid>/act/
{
  "action": "rejected",
  "comment": "Price seems too high, please renegotiate."
}

Common Approval Scenarios#

Scenario	Typical Matrix
Creating a new Part	Procurement → Finance
Editing an existing Part	Procurement
Submitting a Purchase Order	Procurement Lead → Finance
Changing supplier pricing	Category Manager
Adding a new Supplier	Procurement → Admin

Tips#

Approvers see tasks in order — Level 2 doesn’t get notified until Level 1 approves
Anyone in the role can approve — it’s not assigned to a specific person
The audit trail records everything — who approved, when, and their comments
Matrices can be per-model or per-instance — you can set different rules for different Parts