Workflow

• Workflow
  • Overview
  • Data Structure
    • State Schema
    • Workflow Configuration
    • Workflow Rules
    • Conditions
    • Supported Classes
  • Core Functionality
    • Workflow Execution
    • Status Transitions
    • Condition Evaluation
    • Approval Integration
  • Architecture
    • Workflow Executer
    • State Manager Integration
    • Cross-Class Communication
  • API Methods
    • Configuration Management
    • State Management
  • Key Features

Overview

The Workflow class is a service that manages state transitions and approval workflows for various entities in the system. It provides a centralized workflow engine that coordinates status changes based on events, conditions, and approval requirements.

General Purpose:

• Centralized workflow management for system entities
• Integration with approval management system
• Configurable workflow rules for different entity types
• Automatic status updates based on business rules

Data Structure

State Schema

The Workflow class maintains workflow configurations for different entities:

interface WorkflowState {
  private: {
    workflowConfig: WorkflowConfig<WorkflowRule>
  }
  public: object
}

Workflow Configuration

Each workflow configuration contains:

interface WorkflowConfig {
  id: string                    // Unique identifier (class name)
  classId: WorkflowSupportedClass  // Target entity class
  rules: WorkflowRule[]         // Array of workflow rules
}

Workflow Rules

Individual workflow rules define state transitions:

interface WorkflowRule {
  event: string | number           // Triggering event
  currentStatus: Status | '*'      // Current entity status (* = wildcard)
  targetStatus: Status | '*'       // Target status after transition
  conditions: WorkflowRuleCondition[]  // Conditions to evaluate
  approvers: string[]             // Required approver roles (empty = auto-approve)
}

Conditions

Workflow conditions provide flexible rule evaluation:

interface WorkflowRuleCondition {
  dataSource: 'entity' | 'actor'     // Data source for evaluation
  key: string                         // Field to evaluate
  value: any                          // Expected value
  operator: 'equal' | 'not_equal' | 'in' | 'not_in' |
           'less_than' | 'greater_than' | 'less_than_equal' | 'greater_than_equal'
}

Data Sources:

• entity: Evaluate fields from the target entity
• actor: Evaluate fields from the user performing the action

Supported Operators:

• Equality: equal, not_equal
• Set operations: in, not_in
• Comparisons: less_than, greater_than, less_than_equal, greater_than_equal

Core Functionality

Workflow Execution

The workflow engine processes events through these steps:

1. Event Trigger: An event occurs on an entity (e.g., user creation, status change)
2. Rule Matching: Find applicable rules based on event and current status
3. Condition Evaluation: Check if all conditions are satisfied
4. Status Transition: Update entity status to target status
5. Approval Creation: Create approval record if required
6. Auto-Approval: Automatically approve and execute if no manual approval needed

Status Transitions

• Wildcard Support: Rules can apply to any status using * wildcard
• Conditional Logic: Multiple conditions can be combined for complex rules
• Flexible Operators: Support for equality, comparison, and set operations

Condition Evaluation

The workflow engine evaluates conditions to determine if a rule should be applied:

• Multiple Conditions: All conditions in a rule must be satisfied
• Data Source Flexibility: Can evaluate both entity and actor properties
• Type-Aware Operations: Supports different data types with appropriate operators

Approval Integration

The workflow system integrates with ApprovalManager:

• Auto-Approval: Rules without approvers are automatically approved
• Manual Approval: Rules with approvers require manual approval
• Async Processing: Supports both synchronous and asynchronous approval callbacks
• JSON Patch: Tracks state changes for approval records
• Simulated Approved State: For auto-approved async operations, returns simulated approved state by applying jsonPatch to current state snapshot

Architecture

Workflow Executer

The WorkflowExecuter class (workflow.executer.ts) is the core engine that processes workflow rules:

Key Features:

• Rule Matching: Filters rules based on event and current status
• Condition Evaluation: Processes complex conditional logic
• State Management: Integrates with WorkflowCompatibleStateManager
• Approval Coordination: Creates and manages approval records
• Error Handling: Provides specific error types for different failure scenarios
• Simulated Approved State Response: Returns simulated approved state for auto-approved async operations

Return Value: The run() method returns:

• isApproved - Boolean indicating if approval is complete
• approvalRecord - The created approval record
• simulatedApprovedState - Optional state snapshot with jsonPatch applied (only for auto-approved async callbacks)

Error Types:

• WorkflowClassIdDoesNotMatchError - Class ID mismatch between config and state manager
• WorkflowUnhandledFlow - No matching rules found for event/status combination
• WorkflowMultipleFlowsMatched - Multiple rules match (should be unique)
• WorkflowUnexpectedErrorWhileFinalizingApproval - Approval callback execution failed

State Manager Integration

Classes that use workflows must extend WorkflowCompatibleStateManager:

abstract class WorkflowCompatibleStateManager<State> extends StateManager<State> {
  abstract updateStatus<T extends string | number>(id: string, status: T): Promise<void>
  getStateSnapshot(): State  // Returns cloned state for safe external use
}

Integration Examples:

• Member - Member registration and lifecycle workflows
• ProgramManagementUser - Administrative user management workflows
• Company - Company lifecycle and approval workflows
• Tier - Tier management workflows

Cross-Class Communication

The workflow system facilitates communication between classes:

• Configuration Storage: Workflow configurations stored in RDK database
• Utility Access: Classes access workflow configs via getWorkflowConfiguration()
• Async Callbacks: Support for delayed approval processing via task queues
• Event Synchronization: Coordinates status changes across related entities

API Methods

Configuration Management

• updateWorkflowConfiguration (WRITE) - Update workflow rules
  • Updates workflow configuration for a specific entity class
  • Validates class ID matches existing configuration
  • Syncs configuration to RDK database

State Management

• setState (WRITE) - Set workflow state from Rio console

• getState (READ) - Retrieve current workflow state

• init (INIT) - Initialize workflow for a specific class

  • Creates initial workflow configuration structure

Key Features

1. Event-Driven Architecture: Responds to entity events with configurable rules
2. Conditional Logic: Supports complex business rules with multiple conditions
3. Approval Integration: Integrates with approval management system
4. Wildcard Support: Flexible rule matching with status wildcards
5. Error Recovery: Comprehensive error handling for edge cases
6. Cross-Class Coordination: Enables workflow communication between different entity types
7. Database Persistence: Workflow configurations persisted in RDK database
8. Type Safety: Full TypeScript support with generic type constraints