Skip to content

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 (contains processId, provinceId, context, notes).
  • Logic:
    1. The system looks up the active WorkflowProcess for that processId + provinceId.
    2. It parses the CONFIGURATION JSON.
    3. It finds the Trigger Node.
    4. It creates a new Workflow Instance.

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":

  1. System Status (STATUSID in WORKFLOW table)

    • Controlled by Java code (WorkflowProcessingService).
    • 1: Standard Processing
    • 2: Update Database Step (System automated step)
  2. 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 (likely LIST_ITEM or similar generic list management in cis-api).
  3. 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

  1. Submission -> triggerTask API.
  2. System reads WORKFLOWPROCESS JSON -> Creates WORKFLOW (Status X) -> Creates WORKFLOWACTION (Task for User A).
  3. User A completes Task -> processTask API.
  4. System checks JSON for "Next Node" -> Updates WORKFLOW Status to Y -> Creates new WORKFLOWACTION (Task for User B).
  5. 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_ITEM table has a row where ITEMID = 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.