Workflow Lifecycle & Status Analysis¶
1. Workflow Definition (The "Blueprint")¶
Workflows are not hardcoded but are data-driven. They are defined in the Workflow Studio (frontend) and saved into the database as a JSON configuration.
- Table:
WORKFLOWPROCESS - Key Columns:
PROCESSID: Unique ID of the workflow definition.CONFIGURATION: A JSON blob containing the entire logic (Nodes, Links, Roles, Statuses).PROVINCEID: Links the workflow to a specific province.ITEMID_MODULE: Links the workflow to a module (e.g., Lodgement, Maintenance).
Configuration JSON Structure¶
The JSON controls the status lifecycle. Each step is a Node, and transitions are Outlinks.
{
"Node": [
{
"NodeID": 101,
"NodeType": "Trigger",
"OutLink": [
{
"NextNodeID": 102,
"Action": "Submit",
"StatusInternal": "15", // The Internal Status whenever this path is taken
"StatusExternal": "20" // The External Status visible to users
}
]
},
{
"NodeID": 102,
"Role": "123", // Role ID responsible for this step
"ActionRequired": "Approve"
}
]
}
2. Triggering a Workflow¶
When a submission comes in (e.g., propert maintenance request), the backend triggers a specific workflow based on the Process Type and Province.
- API:
POST /via RoutingController/triggerTask - Request:
TriggerRequest(containsprocessId,provinceId,context,notes). - Logic:
- The system looks up the active
WorkflowProcessfor thatprocessId+provinceId. - It parses the
CONFIGURATIONJSON. - It finds the Trigger Node.
- It creates a new Workflow Instance.
- The system looks up the active
3. Workflow Objects & Tables (Runtime)¶
Once running, the state is tracked across these four key tables:
A. WORKFLOW (The "Instance")¶
Represents the overall running process.
* Table: WORKFLOW
* Key Columns:
* WORKFLOWID: Unique ID for this specific run.
* PROCESSID: Links back to the definition.
* REFERENCE_NO: The unique reference number (e.g., "GP-2023-...").
* INTERNAL_STATUS_ID / EXTERNAL_STATUS_ID: Dynamic. Updates as the workflow moves from node to node, based on the JSON configuration of the path taken.
* STATUSID: System Status (Hardcoded logic: 1 = Active, 2 = UpdateDatabase specific state).
B. WORKFLOWACTION (The "Task")¶
Represents the current pending task for a user.
* Table: WORKFLOW_ACTION
* Key Columns:
* ACTIONID: Unique Task ID.
* WORKFLOWID: Links to parent workflow.
* USERID: The user assigned to this task.
* NODEID: The step in the JSON config this task corresponds to.
* ACTED_ON: Timestamp when completed (Null if pending).
C. TRANSACTIONS (The "History")¶
Audit trail of every move.
* Table: TRANSACTIONS
* Key Columns:
* TRANSACTIONID: Unique ID.
* SUMMARY: Context/Description.
* COMMENTS: User notes.
* USERID: Who performed the action.
D. NOTIFICATION (The "Alerts")¶
Records of system notifications generated.
* Table: NOTIFICATIONS
* Linkage: Linked to WORKFLOWID and TRANSACTIONID.
4. Status Lifecycle & States¶
There are three layers of "Status":
-
System Status (
STATUSIDinWORKFLOWtable)- Controlled by Java code (
WorkflowProcessingService). - 1: Standard Processing
- 2: Update Database Step (System automated step)
- Controlled by Java code (
-
Workflow Statuses (
INTERNAL_&EXTERNAL_STATUS_ID)- Dynamic: Defined in the JSON configuration per outcome.
- Internal: Visible to internal officers (e.g., "Pending QA", "Referred for Correction").
- External: Visible to the applicant (e.g., "In Progress", "Awaiting Payment").
- Values: These are integers (e.g.,
15,20) that often map to a Lookup Table (likelyLIST_ITEMor similar generic list management incis-api).
-
Process Types (Enum:
ProcessType.java)- Defines the category of workflow.
- Examples:
EXCISION_REQUEST(366)LODGEMENT_REQUEST(278)RESERVATION_REQUEST(229)AMENDMENTS_REQUEST(906)
5. Summary of Flow¶
- Submission ->
triggerTaskAPI. - System reads
WORKFLOWPROCESSJSON -> CreatesWORKFLOW(Status X) -> CreatesWORKFLOWACTION(Task for User A). - User A completes Task ->
processTaskAPI. - System checks JSON for "Next Node" -> Updates
WORKFLOWStatus to Y -> Creates newWORKFLOWACTION(Task for User B). - Repeat until End Node.
6. List Management (The "Lookup Data")¶
The values used for Statuses, Process Types, Maintenance Reasons, and Document Types are not random integers. They are keys to a powerful generic lookup system stored in two tables:
A. M_LIST_MASTER (Categories)¶
Defines the types of lists available.
* Table: M_LIST_MASTER
* Key Column: LISTCODE (e.g., 50 might be "Workflow Statuses", 101 might be "Maintenance Reasons").
* Columns: CAPTION, ISSTATIC.
B. M_LIST_ITEM (Values)¶
Defines the specific options within a category.
* Table: M_LIST_ITEM
* Key Column: ITEMID (This is the ID used in Java Enums and JSON Config).
* Columns:
* ITEMCODE: Unique code (e.g., REAS001).
* LISTCODE: Links to the parent category.
* CAPTION: The text shown to the user (e.g., "Pending QA", "Excision", "Approved").
Example Mapping¶
- Enum:
MaintenanceReason.EXCISION(2486L) - Database:
M_LIST_ITEMtable has a row whereITEMID = 2486.CAPTION= "Excision".LISTCODE= [Some ID representing Maintenance Reasons].
Why this matters?¶
When configuring a workflow in Workflow Studio:
1. Statuses: You pick "Pending QA" from a dropdown. The system saves ID 15. This corresponds to LIST_ITEM 15.
2. Reasons: You pick "Excision". The system saves ID 2486.
3. Code: Java Enums (like ProcessType.java) must manually match these DB IDs. If you create a new List Item in the DB, you must update the Java Enum to match.