Workflow design

Workflow for Enrolment & Disbursement Cycles

PBMS Workflow Design Document

Both Enrolment & Disbursement cycles have a Workflow definition attached to them. The Lists created under these cycles go through the workflow stages for seeking approvals from various stakeholders.

Model Structures

g2p_workflow_stage_definition

Field	Data Type	Constraints	Description
stage_id	String/UUID	Primary Key	Unique identifier for workflow stage
program_id	String/UUID	Index	References program
cycle_type	Enum	ENROLMENT, DISBURSEMENT	Type of cycle workflow
stage_number	Integer		Sequential stage number
stage_name	String		Name of the stage
is_final_stage	Boolean		True if highest stage_number for this program/cycle_type
Roles	String (CSV)		Comma-separated list of roles authorized for this stage
		Unique: (program_id, cycle_type, stage_number)

g2p_beneficiary_list

Field	Data Type	Constraints	Description
list_id	String/UUID	Primary Key	Unique identifier for beneficiary list
cycle_id	String/UUID	Foreign Key	References cycle
list_number	Integer		Sequential integer for list versions (New field)
latest_stage_history_id	String/UUID	Foreign Key	References most recent stage_history record
number_of_beneficiaries	Integer		Total count of beneficiaries
disbursement_quantity	JSON		Disbursement details (Disbursement cycles only)
		Relationship: One cycle → one operating list at any time

g2p_workflow_stage_history

Field	Data Type	Constraints	Description
stage_history_id	String/UUID	Primary Key	Unique identifier for stage history record
list_id	String/UUID	Index, Foreign Key	References beneficiary_list
list_type	Enum	ENROLMENT, DISBURSEMENT	Type of list
stage_id	String/UUID	Foreign Key	References workflow_definition stage
enqueued_at	Timestamp		When list was queued at this stage
status	Enum	PENDING, APPROVED, REJECTED	Current approval status
acted_by	String/UUID		User who performed the action
acted_at	Timestamp		When action was performed
Remarks	Text		Comments or rejection reason
		Unique: (list_id, stage_id)	Each list can only have one record per stage

g2p_workflow_pending_stage

Field	Data Type	Constraints	Description
list_id	String/UUID	Primary Key	References beneficiary_list
current_stage_id	String/UUID	Index, Foreign Key	References workflow_definition stage
enqueued_at	Timestamp		When list entered current stage
stage_status	Enum	PENDING	Status (always PENDING while in this table)

g2p_enrolment_cycle

Field	Data Type	Constraints	Description
cycle_id	String/UUID	Primary Key	Unique identifier for cycle
program_id	String/UUID	Foreign Key	References progra
cycle_number	Integer		Sequence number within program
created_on	Timestamp		When cycle was created
created_by	String/UUID		User who created the cycle
latest_list_id	String/UUID	Foreign Key	References latest beneficiary_list (New field)
number_of_lists	Integer		Count of all list versions

g2p_disbursement_cycle

Field	Data Type	Constraints	Description
cycle_id	String/UUID	Primary Key	Unique identifier for cycle
program_id	String/UUID	Foreign Key	References program
cycle_number	Integer		Sequence number within program
created_on	Timestamp		When cycle was created
created_by	String/UUID		User who created the cycle
latest_list_id	String/UUID	Foreign Key	References latest beneficiary_list (New field)
number_of_lists	Integer		Count of all list versions

g2p_program_metrics (New Model)

Field	Data Type	Constraints	Description
program_id	String/UUID	Primary Key	References program
enrolment_cycle_count	Integer		Total enrolment cycles for program
disbursement_cycle_count	Integer		Total disbursement cycles for program

---

Enrolment Workflow

Flow Overview

1. Create Cycle →

2. Create 1 List that moves to Stage-1

3. List progresses through defined stages (Stage-1, Stage-2, ... Stage-N)

4. At each stage, list is queued for approval by role-based users

5. At each stage: PENDING → (APPROVED or REJECTED)

6. If APPROVED → moves to next stage

7. If REJECTED → user must create a new List version

8. Final stage approval = Cycle approved (no further actions allowed)

Stage Progression

• List has latest_stage_history_id stored within it

• Each stage creates a beneficiary_list_stage_history record

• Workflow is driven by stage definition and role-based approvals

• Once final stage is approved, the entire cycle is locked

Key Rules

• A cycle cannot be modified after approval

• Rejection at any stage requires new list creation

• List versions are tracked as versions in UI (only latest displayed)

• Previous versions accessible in separate tab

---

Disbursement Workflow

Flow Overview

1. Create Cycle

2. Create 1 List that moves to Stage-1

3. List progresses through defined stages with disbursement-specific data

4. At each stage: PENDING → (APPROVED or REJECTED)

5. If APPROVED → moves to next stage with entitlement computation

6. If REJECTED → user must create a new List version

7. Final stage approval = Cycle approved with disbursement locked

Disbursement-Specific Fields

• number_of_beneficiaries

• disbursement_quantity (JSON format, first item displayed)

• Total Entitlements (computed at stage approval)

Bridge & Dispatch Elements (Final Approved List Only)

• Envelopes

• Batches

• Dispatch tracking

Key Rules

• Same stage progression model as Enrolment

• Entitlements computed during approval workflow

• Bridge and dispatch tables only appear for approved disbursement cycles

• Multiple batch control available for envelope distribution

---

Enrolment Cycle View

List of Cycles Display

Columns: Cycle #, Created on, Stage, Status, # of Versions, # of Beneficiaries, Acted on

Data Source: cycle.latest_list_id → latest_list_id.latest_stage_history_id

Cycle Detail View (Single Cycle)

Cycle Section:

• Enrolment (Cycle Type)

• Created on

• Created by

Workflow Section:

• Stage (Current)

• Status (PENDING, APPROVED, REJECTED)

• Queued date

Beneficiaries Section:

• Resolution status

• Number of Beneficiaries

• Search capability

Detail Tabs

1. Statistics: Key metrics

2. Beneficiaries Tab:

   • Search beneficiaries

   • View all beneficiaries in current list

3. Approval History:

   • Stage History of Current Latest List

4. Previous Versions:

   • List of Lists (excluding latest)

   • Stage History of each list (expanded view without context switching)

Status Logic

• If Approved & no further stages → Cycle is fully approved

• If Rejected → User must create new list

• If Pending → Awaiting action

---

Disbursement Cycle View

List of Cycles Display

Columns: Cycle #, Created on, Stage, # of Versions, # of Beneficiaries, Disbursement Amount, Stage Status, Acted on

Data Source: cycle.latest_list_id → latest_list_id.latest_stage_history_id

Cycle Detail View (Single Cycle)

Cycle Section:

• Disbursement (Cycle Type)

• Created on

• Created by

Workflow Section:

• Stage (Current)

• Status (PENDING, APPROVED, REJECTED)

• Queued date

Beneficiaries Section:

• Resolution status

• Number of Beneficiaries

• Search capability

Entitlements Section:

• Computation status

• Total Entitlements

• Product Code: Quantity, Unit

Bridge Section (Approved Cycle Only):

• Dispatch status

• Number of Envelopes

• Number of Batches

Detail Tabs

1. Statistics: Key metrics

2. Beneficiaries Tab:

   • Search beneficiaries

   • View all beneficiaries

3. Approval Log:

   • Stage History of Current Latest List

4. Previous Versions:

   • List of Lists (excluding latest)

   • Stage History of each list (expanded view)

5. Envelopes (Approved Cycle Only):

   • Envelope distribution details

6. Batch Control (Approved Cycle Only):

   • Batch management for approved disbursement

---

Approval Queue View

Queue Filter Logic

1. Retrieve current user's roles

2. Get all workflow stage IDs for those roles

3. Display all beneficiary_list_pending_stage items matching those stage_ids

List Display

Columns: Program Mnemonic, Cycle #, Enrolment/Disbursement, Current Stage, Current Version, Queued Date, # of Beneficiaries

Detail View (From Queue)

Program Section:

• Program Mnemonic

• Program Description

Cycle Section:

• Enrolment/Disbursement (Type)

• Cycle Number

• Created on

• Created by

Workflow Section:

• Version (Current)

• Stage (Current)

• Status (PENDING, APPROVED, REJECTED)

Beneficiaries Section:

• Number of Beneficiaries

• Search capability

Entitlements Section (Disbursement Only):

• Entitlements List

• Product Code: Quantity, Unit

Detail Tabs

1. Statistics: Custom view

2. Beneficiaries: Search and view

3. Approval History:

   • Stage History of Current Latest List

4. Previous Versions:

   • List of Lists (excluding latest)

   • Stage History of each list (expanded)

---

Fundamental Concepts

• A cycle has only 1 operating list at any point in time

• Cycle workflow status is synonymous with the operating list's status

• Lists are treated as versions in the UI

• Only the current operating list is displayed prominently

• Previous lists (versions) are accessible in a separate tab

• Cycle → latest_list_id → List → latest_stage_history_id → Stage History

• This chain allows complete cycle visibility across all states