Workflow & Approval System

Overview

The CNPERP Workflow System provides a flexible, role-based approval mechanism for critical business transactions.

Key Benefits

IFRS Compliance - Proper authorization controls as required by international standards
Segregation of Duties - No user can approve their own transactions
Multi-Level Approvals - Escalation based on materiality thresholds
Complete Audit Trail - Every action logged with timestamps and comments

System Features

State Machine	Configurable states per workflow
Role-Based	Actions restricted by user role
Threshold Escalation	Auto-routing based on amount
Notifications	Real-time in-app alerts
Documentation	Required comments/attachments

Getting Started

Quick Setup: Follow these steps to enable workflow approvals in your system.

Step 1: Seed Phase 1 Workflows

Navigate to Settings → Workflow & Approvals and click "Seed Phase 1 Workflows" or use the API:

POST /api/v1/workflows/seed/phase1

Step 2: Configure Approval Thresholds

In Settings → Workflow & Approvals, set your approval thresholds:

Manager Approval Limit (default: $25,000)
Finance Manager Limit (default: $50,000)
CFO Approval Limit (default: $250,000)
CEO Approval Limit (default: $500,000)

Step 3: Assign User Roles

Ensure users have appropriate roles assigned in Settings → Users:

manager finance_manager cfo ceo

Step 4: Enable Notifications

Configure notification preferences in Settings to receive alerts for pending approvals.

Role Hierarchy

Level	Role	Code	Typical Authority
L0	Any User	`*`	Create drafts, submit
L1	Supervisor	`supervisor`	Up to $5,000
L2	Manager	`manager`	$5,001 - $25,000
L3	Finance Manager	`finance_manager`	$25,001 - $50,000
L4	CFO	`cfo`	$50,001 - $500,000
L5	CEO	`ceo`	Above $500,000
L5+	Board	`board`	Material items, policy changes

Phase 1 Workflows (Critical)

Phase 1 implements the five most critical approval workflows required for IFRS compliance.

1. Journal Entry Approval IAS 8

┌─────────┐ ┌───────────┐ ┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ │ Draft │───▶│ Submitted │───▶│ Manager │───▶│ Finance │───▶│ CFO │ │ │ │ │ │ Review │ │ Controller │ │ Approval │ └─────────┘ └───────────┘ └─────────────┘ └──────────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Rejected │ │ Posted │ │ Posted │ └─────────────┘ │ (< $50k) │ │ (> $50k) │ └─────────────┘ └─────────────┘

Critical Controls:

✅ No self-approval permitted
✅ All manual journals require approval
✅ Entries > $50,000 require CFO approval
✅ Year-end adjustments require CFO approval

2. Vendor Payment Approval IAS 7, IFRS 9

┌─────────┐ ┌───────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Draft │───▶│ Scheduled │───▶│ Finance │───▶│ CFO │───▶│ CEO │ │ │ │ │ │ Review │ │ Approval │ │ Approval │ └─────────┘ └───────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌────────────────┐ ┌─────────────┐ ┌─────────────┐ │ Approved │◀─│ Approved │◀───│ Approved │ │ (< $50k) │ │ ($50k-$250k)│ │ (> $250k) │ └────────────────┘ └─────────────┘ └─────────────┘

Amount	Required Approval
< $50,000	Finance Manager
$50,000 - $250,000	CFO
> $250,000	CEO

3. Sales Credit Note Approval IFRS 15

Critical: ALL credit notes require approval (revenue reduction risk)

✅ Submission requires justification comment
✅ Credit > $5,000 requires CFO
✅ Full invoice reversal requires CFO approval

4. Bad Debt Write-off Approval IFRS 9

Amount	Required Approval
< $10,000	Finance Manager
$10,000 - $100,000	CFO
> $100,000	Board (CEO as representative)

Requirements:

✅ Requires documented collection efforts
✅ Submission requires comment AND attachment

5. Period Close Approval IAS 1

Period Type	Required Approval
Month-End	Finance Manager
Quarter-End	CFO
Year-End	CFO + External Audit

Controls:

✅ Soft close prevents new postings to period
✅ Period reopen requires CFO approval and justification

Workflow States

Status	Code	Description	Terminal?
Draft	`draft`	Initial state, editable	No
Submitted	`submitted`	Awaiting routing	No
Pending Approval	`pending_approval`	Awaiting approver action	No
Approved	`approved`	Approved, awaiting completion	No
Completed	`completed`	Fully processed	Yes
Rejected	`rejected`	Declined by approver	Yes

Available Actions

Submit - Send for approval
Approve - Accept and advance
Reject - Decline with reason
Cancel - Cancel workflow

Reassign - Transfer to another user
Revise - Return for changes
Hold - Pause workflow
Resume - Resume from hold

Approval Thresholds

Configure thresholds in Settings → Workflow & Approvals:

Setting	Default Value	Description
Manager Approval Limit	$25,000	Maximum amount manager can approve
Finance Manager Limit	$50,000	Maximum amount finance manager can approve
CFO Approval Limit	$250,000	Maximum amount CFO can approve
CEO Approval Limit	$500,000	Maximum amount CEO can approve alone
Auto-Submit Threshold	$1,000	Items below this skip workflow

Notifications

Notification Types

Approval Pending	Item assigned to you for approval
Approved	Your item was approved
Rejected	Your item was rejected
Status Update	General status change

Notification Channels

In-App Toast - Appears on page load if pending approvals exist
Notification Bell - Badge counter shows unread notifications
Notifications Page - Full list at /static/notifications.html

Using Approvals

For Submitters

Create your document (journal entry, payment, etc.)
Click Submit for Approval
Add required comments if prompted
Track status in the Notifications page

For Approvers

Check the notification bell for pending items
Click the notification to view the item
Review the details and history
Click Approve or Reject
Add comments (required for rejections)

Important: You cannot approve your own submissions. The system enforces segregation of duties.

API Reference

Workflow Definitions

GET /api/v1/workflows/definitions - List all workflow definitions

GET /api/v1/workflows/definitions/{id} - Get single workflow definition

POST /api/v1/workflows/seed/phase1 - Seed Phase 1 workflows

Workflow Instances

GET /api/v1/workflows/instances - List workflow instances

POST /api/v1/workflows/instances/{id}/approve - Approve item

POST /api/v1/workflows/instances/{id}/reject - Reject item

Dashboard & User Endpoints

GET /api/v1/workflows/my-pending-approvals - Get user's pending items

GET /api/v1/workflows/dashboard - Get workflow dashboard stats

GET /api/v1/workflows/entity-types - Get all entity type definitions

Supported Entity Types (36 Total)

Procurement

purchase_requisition
purchase_order
goods_receipt
vendor_payment

Sales

sales_quotation
sales_order
sales_invoice
sales_credit_note
customer_credit_limit

Inventory

inventory_adjustment
stock_writeoff
stock_transfer
inventory_revaluation

Accounting

journal_entry
accrual
bad_debt_writeoff
period_close
coa_change
intercompany

Fixed Assets

asset_acquisition
asset_disposal
asset_impairment
depreciation_policy

Banking

bank_recon_adj
cash_transfer
petty_cash

Configuration

Settings Location

Navigate to Settings → Workflow & Approvals to configure:

Global workflow enable/disable
Approval thresholds by role
Auto-submit settings
Notification preferences
Escalation settings
Module-specific toggles
Documentation requirements

Seeding Workflows via Python

from app.database.seed_workflows import seed_phase1_workflows
from app.core.database import SessionLocal

db = SessionLocal()
seed_phase1_workflows(db)
db.close()

Troubleshooting

Solution: Check that the user's role_id is in the state's allowed_roles array. Verify role assignment in Settings → Users.

Solution: Use GET /api/v1/workflows/instances/{id}/available-actions to see valid transitions. Check if required approvers are assigned.

Solution: Verify notified_roles are configured for the target state. Check notification settings in Settings → Workflow & Approvals.

This is expected behavior. The system enforces segregation of duties - users cannot approve their own transactions. Another authorized user must approve.

Debug Endpoints

GET /api/v1/workflows/definitions/{id} - Get workflow with all states/transitions

GET /api/v1/workflows/instances/{id}/history - Get full action history

Implementation Phases

Phase	Entity Types	Status
Phase 1	journal_entry, vendor_payment, sales_credit_note, bad_debt_writeoff, period_close	✅ Complete
Phase 2	purchase_order, inventory_adjustment, stock_writeoff, asset_acquisition, asset_disposal	📋 Planned
Phase 3	sales_order, production_order, bom_change, expense_claim, payroll_run	📋 Planned
Phase 4	purchase_requisition, sales_quotation, stock_transfer, bank_recon_adj, budget_transfer	📋 Planned

Contents