Process Management Entities

1. Overview

Process entities provide a flexible workflow engine for managing multi-step business processes such as event approvals, participant verifications, membership applications, and custom organizational workflows.

Package: za.co.idealogic.event.domain
Repository: event-database
Total Entities: 5

2. Process Definition Entities

2.1. ProcessDefinition

Defines a reusable workflow template with steps and decision points.

Key Relationships:

  • Many-to-one with Organisation (can be global or org-specific)

  • One-to-many with ProcessStep

  • One-to-many with ProcessInstance

Attributes:

  • Process name and description

  • Process category (event, membership, financial, custom)

  • Version number

  • Active/inactive status

  • Scope (global or organisation-specific)

Use Cases:

  • Event approval workflows

  • Membership application processes

  • Participant verification procedures

  • Financial reconciliation workflows

  • Custom approval chains

  • Multi-stage competitions

2.2. ProcessStep

Individual steps within a ProcessDefinition, defining the sequence and logic of the workflow.

Key Relationships:

  • Many-to-one with ProcessDefinition

  • One-to-many with ProcessStepOption

  • Self-referential (next step)

Attributes:

  • Step name and description

  • Step order/sequence

  • Step type (manual, automated, decision, parallel)

  • Required roles/permissions

  • Timeout configuration

  • Notification settings

Step Types:

  • Manual - Requires human action

  • Automated - Executes automatically

  • Decision - Branches based on conditions

  • Parallel - Multiple concurrent steps

  • Wait - Delays until condition met

2.3. ProcessStepOption

Defines possible outcomes/choices for a ProcessStep, enabling conditional branching.

Key Relationships:

  • Many-to-one with ProcessStep

  • References next ProcessStep (for branching)

Attributes:

  • Option label (e.g., "Approve", "Reject", "Request More Info")

  • Option value

  • Next step reference (for branching)

  • Conditions/rules

  • Default option flag

Use Cases:

  • Approval/rejection decisions

  • Conditional routing

  • Multi-path workflows

  • Exception handling

3. Process Execution Entities

3.1. ProcessInstance

A running instance of a ProcessDefinition, tracking the execution of a specific workflow.

Key Relationships:

  • Many-to-one with ProcessDefinition

  • One-to-many with ProcessData

  • References related entity (Event, Membership, Order, etc.)

Attributes:

  • Current step

  • Overall status (pending, in_progress, completed, cancelled, failed)

  • Start timestamp

  • End timestamp

  • Initiating user

  • Related entity type and ID

Lifecycle: 1. Created - Instance initialized 2. In Progress - Steps being executed 3. Awaiting Input - Waiting for user action 4. Completed - All steps finished successfully 5. Cancelled - Workflow terminated 6. Failed - Error occurred

3.2. ProcessData

Stores data collected during process execution, including step inputs, outputs, and decision results.

Key Relationships:

  • Many-to-one with ProcessInstance

  • References ProcessStep

Attributes:

  • Data key

  • Data value (JSON or serialized)

  • Data type

  • Step reference

  • Timestamp

  • User reference (who entered the data)

Use Cases:

  • Form field values

  • Approval comments

  • Decision rationale

  • Uploaded documents

  • Calculation results

  • Audit trail data

4. Entity Relationships

ProcessDefinition
    |
    | 1:N
    |
ProcessStep -------- 1:N --------> ProcessStepOption
    |                                      |
    |                                      | (next step)
    +--------------------------------------+

ProcessDefinition
    |
    | 1:N
    |
ProcessInstance -------- 1:N --------> ProcessData
    |
    | (references)
    |
[Event | Membership | Order | Other Entity]

5. Example Process Definitions

5.1. Example 1: Event Approval Process

ProcessDefinition: "Event Approval Workflow"
  Category: Event
  Scope: Global

  Step 1: "Submit for Approval"
    Type: Manual
    Options:
      - Submit → Step 2

  Step 2: "Director Review"
    Type: Manual
    Required Role: Event Director
    Options:
      - Approve → Step 3
      - Reject → Step 6
      - Request Changes → Step 7

  Step 3: "Financial Review"
    Type: Manual
    Required Role: Finance Manager
    Options:
      - Approve → Step 4
      - Reject → Step 6
      - Request Info → Step 7

  Step 4: "Final Approval"
    Type: Manual
    Required Role: CEO
    Options:
      - Approve → Step 5
      - Reject → Step 6

  Step 5: "Publish Event"
    Type: Automated
    Action: Set event status to "Published"
    → END (Success)

  Step 6: "Rejection Notice"
    Type: Automated
    Action: Notify submitter of rejection
    → END (Rejected)

  Step 7: "Request Revisions"
    Type: Automated
    Action: Send revision request to submitter
    → Step 1 (Re-submit)

5.2. Example 2: Membership Application Process

ProcessDefinition: "Membership Application"
  Category: Membership
  Scope: Organisation

  Step 1: "Application Submission"
    Type: Manual
    Data Required:
      - Personal information
      - Membership type selection
      - Payment
    Options:
      - Submit → Step 2

  Step 2: "Document Verification"
    Type: Manual
    Required Role: Membership Officer
    Data Required:
      - ID verification
      - Qualification check
      - Document review
    Options:
      - Documents OK → Step 3
      - Documents Incomplete → Step 5

  Step 3: "Background Check"
    Type: Automated (if required)
    Conditions: If membership type requires background check
    Options:
      - Pass → Step 4
      - Fail → Step 6

  Step 4: "Approval"
    Type: Automated
    Action: Create membership, send confirmation
    → END (Approved)

  Step 5: "Request Additional Documents"
    Type: Automated
    Action: Notify applicant of missing documents
    → Step 1 (Re-submit)

  Step 6: "Rejection"
    Type: Automated
    Action: Notify applicant, process refund
    → END (Rejected)

5.3. Example 3: Participant Verification Process

ProcessDefinition: "Elite Athlete Verification"
  Category: Event
  Scope: Organisation

  Step 1: "Submit Qualification"
    Type: Manual
    Data Required:
      - Performance time/result
      - Date of performance
      - Event/competition
    Options:
      - Submit → Step 2

  Step 2: "Automated Validation"
    Type: Automated
    Validation:
      - Check against qualification standards
      - Verify within qualification period
      - Verify competition sanctioning
    Options:
      - Meets Standards → Step 4
      - Needs Manual Review → Step 3
      - Does Not Meet Standards → Step 5

  Step 3: "Manual Review"
    Type: Manual
    Required Role: Technical Director
    Options:
      - Approve → Step 4
      - Reject → Step 5

  Step 4: "Grant Elite Status"
    Type: Automated
    Action: Update participant category, send confirmation
    → END (Approved)

  Step 5: "Decline Elite Status"
    Type: Automated
    Action: Notify participant, offer standard entry
    → END (Declined)

6. Common Workflows

6.1. Creating a Process Definition

  1. Define ProcessDefinition (name, category, scope)

  2. Create ProcessSteps in sequence

  3. Define ProcessStepOptions for each step

  4. Link options to next steps (branching)

  5. Configure roles and permissions

  6. Set notification rules

  7. Test with sample ProcessInstance

  8. Activate ProcessDefinition

6.2. Executing a Process Instance

  1. Create ProcessInstance from ProcessDefinition

  2. Link to related entity (Event, Membership, etc.)

  3. Set instance to current step (first step)

  4. User/system executes current step

  5. Store step data in ProcessData

  6. User/system selects ProcessStepOption

  7. Instance advances to next step

  8. Repeat steps 4-7 until completion

  9. Set instance status to completed/cancelled/failed

6.3. Monitoring Process Instances

  1. Query ProcessInstances by status

  2. Identify stuck/delayed instances

  3. Review ProcessData for audit trail

  4. Send notifications for pending actions

  5. Generate reports on completion rates

  6. Identify bottlenecks in ProcessSteps

7. Use Case Scenarios

7.1. Event Management

  • Event approval and publication

  • Permit application workflows

  • Venue booking processes

  • Sponsorship approval chains

  • Safety certification processes

7.2. Membership Management

  • Membership applications

  • Renewal processes

  • Membership upgrades

  • Member verification

  • Disciplinary procedures

7.3. Financial Operations

  • Refund approval workflows

  • Budget approval processes

  • Expense reimbursement

  • Financial reconciliation

  • Payment dispute resolution

7.4. Participant Management

  • Elite status verification

  • Age verification

  • Medical clearance processes

  • Team registration approval

  • Transfer requests

7.5. Custom Workflows

  • Document approval chains

  • Equipment checkout processes

  • Volunteer registration

  • Accreditation processes

  • Complaint handling procedures

8. Multi-Tenancy & Scope

8.1. Global Process Definitions

  • Defined at system level

  • Available to all organisations

  • Standard workflows (e.g., refund process)

  • Maintained by system administrators

8.2. Organisation-Specific Definitions

  • Defined by organisation administrators

  • Only available within the organisation

  • Custom workflows for org requirements

  • Reflect org-specific policies

8.3. Process Instance Execution

  • Always executed within organisation context

  • Uses org-specific or global ProcessDefinition

  • Can reference org-specific or global entities

  • Access control based on org membership

9. Entity Summary

Entity Primary Purpose Relationships

ProcessDefinition

Workflow template

Steps, Instances

ProcessStep

Individual workflow stage

Definition, Options

ProcessStepOption

Step outcomes/branches

Step, Next Step

ProcessInstance

Running workflow

Definition, Data, Entity

ProcessData

Execution data storage

Instance, Step

10. Extension Points

The process management system is designed for extensibility:

  • Custom Step Types - Add new step execution logic

  • Integration Hooks - Trigger external systems

  • Custom Validators - Add business rule validation

  • Notification Templates - Customize communications

  • Reporting Plugins - Generate custom analytics

11. Related Documentation