PartnerUser

PartnerUser

Overview

The PartnerUser class manages partner application users who operate within partner organizations, providing user account management with multi-partner and multi-venue support.

General Purpose:

Manages partner user creation, updates, and status changes with workflow approval integration
Supports per-partner role assignments allowing users to have different roles at different partners
Handles multi-partner associations where a single user can work for multiple partner organizations
Provides multi-venue access management for location-based permissions
Implements simple enum-based role system (ADMIN, MANAGER, STAFF) independent of the complex RoleManager system
Instance-based architecture where each partner user has a unique instance ID
Streams user data to MongoDB for external synchronization and querying
Designed for phase 1 implementation with authentication and authorization planned for future phases

Data Structure

State Schema

interface PartnerUserState {
  private: {
    user: PartnerUser
  }
  public: object
}

interface PartnerUser {
  id: string
  fullName: string
  email: string
  partners: PartnerAssociation[]    // User can belong to multiple partners
  venues: VenueAssociation[]        // User can access multiple venues
  status: PartnerUserStatus
  createdBy: string
  updatedBy: string
  createdAt: number
  updatedAt: number
}

Enums and Types

enum PartnerUserRole {
  ADMIN = 'admin',      // Full administrative access
  MANAGER = 'manager',  // Management-level access
  STAFF = 'staff'       // Standard staff access
}

enum PartnerUserStatus {
  PENDING = 'pending',   // Awaiting approval
  ACTIVE = 'active',     // Active user account
  INACTIVE = 'inactive'  // Deactivated account
}

enum PartnerUserEvents {
  USER_CREATE = 'user_create',
  USER_UPDATE = 'user_update',
  USER_STATUS_UPDATE = 'user_status_update'
}

Additional Structures

interface PartnerAssociation {
  partnerId: string
  role: PartnerUserRole    // Role specific to this partner
}

interface VenueAssociation {
  partnerId: string
  venueId: string
}

Key Design Points:

Each partner association includes a role, allowing users to have different roles at different partners (e.g., ADMIN at Partner A, STAFF at Partner B)
Venue associations link users to specific locations within partners for location-based access control
Simple enum-based roles eliminate dependency on the complex RoleManager system used by ProgramManagementUser

Core Functionality

Main Feature Groups

User Account Management: Complete CRUD operations for partner user accounts with approval workflow integration
Multi-Partner Support: Users can be associated with multiple partner organizations with per-partner role assignments
Venue Access Control: Granular venue-level access management allowing users to be assigned to specific locations
Status Management: User status lifecycle management (PENDING → ACTIVE → INACTIVE) with approval requirements
Role Information: Client-facing API to retrieve available role options for UI dropdowns and forms
User Discovery: Paginated user listing with filtering by status, partner, and search terms

Workflow Integration

The PartnerUser class extends WorkflowCompatibleStateManager and integrates with the approval workflow system:

Status Transitions: User creation starts with PENDING status and transitions to ACTIVE upon approval
Events: Three main events trigger workflow processing:
- USER_CREATE: Triggered when a new partner user is created
- USER_UPDATE: Triggered when user details (name, email, partners, venues) are modified
- USER_STATUS_UPDATE: Triggered when user status changes
Approval Integration: All workflow events can be configured to require approval through the ApprovalManager
Business Rules: Workflow configuration determines approval requirements and status transitions based on current state and event type

API Methods

User Management

init (INIT) - Create a new partner user account
- Initializes user with PENDING status
- Triggers approval workflow for user creation
- Streams user data to MongoDB
- Input: fullName, email, partners (with roles), venues (optional)
getUser (READ) - Retrieve partner user details
- Returns user profile with partner associations and venue assignments
- Accessible by ProgramManagementUser identity
updateUser (WRITE) - Update partner user information
- Updates fullName, email, partner associations, and venue assignments
- Triggers approval workflow for updates
- All fields are required (no partial updates)
updateStatus (WRITE) - Change user status
- Updates user status (PENDING/ACTIVE/INACTIVE)
- Triggers approval workflow for status changes
- Optional statusReason parameter for audit trail
listPartnerUsers (STATIC) - List all partner users
- Paginated listing with filtering support
- Filter by status, partnerId, or search term (fullName/email)
- Returns users with totalCount, page, limit, and totalPages
- Queries MongoDB for efficient large-scale retrieval

Venue Management

addVenues (WRITE) - Add venues to user
- Assigns additional venues to partner user
- Prevents duplicate venue assignments
- Input: array of venue associations (partnerId + venueId)
removeVenues (WRITE) - Remove venues from user
- Removes venue access from partner user
- Input: array of venueIds to remove
listVenues (READ) - List user's venues
- Returns all venue associations for the partner user

Role Information

getRoles (STATIC) - Get available partner user roles
- Returns all available PartnerUserRole enum values
- Formatted for client-side dropdowns and forms
- Output includes key, value, and human-readable label
- Stateless method requiring no instance

Approval Operations

approveUser (WRITE) - Approve workflow action
- Internal method called by ApprovalManager
- Applies JSON patch updates to user state
- Restricted to ApprovalManager class identity

Key Features

Instance-Based Architecture: Each partner user has a unique instance ID, allowing independent state management and scalability
Multi-Partner Support: Users can be associated with multiple partner organizations simultaneously, each with their own role assignment
Per-Partner Role System: Simple enum-based roles (ADMIN, MANAGER, STAFF) assigned per partner rather than globally, enabling flexible access control
Multi-Venue Access: Granular venue-level assignments allow users to access specific locations within their partner organizations
Workflow Approval Integration: All user creation, updates, and status changes can be configured to require approval through the workflow system
MongoDB Streaming: User data is automatically synchronized to MongoDB for efficient querying and external system integration
Independent Role Management: Deliberately uses simple enum-based roles instead of the complex RoleManager system to simplify partner application architecture
Phase 1 Implementation: Current implementation focuses on user account management; authentication and authorization are planned for future phases
Audit Trail: All state changes are tracked with createdBy, updatedBy, createdAt, and updatedAt timestamps
Scalable Query Support: STATIC listPartnerUsers method leverages MongoDB for efficient pagination and filtering across large user datasets

Keyboard shortcuts

Platinum