Onboarding Management

The Onboarding Management submodule handles project onboarding workflows, typeform response processing, and client setup coordination within the admin projects system.

🎯 Overview

This submodule manages the complete onboarding lifecycle for project services, including typeform integration, onboarding status tracking, notification management, and client communication coordination.

🔧 Service Methods

Core Onboarding Operations

updateOrderOnboardingService()

Updates project order onboarding information and status with comprehensive validation.

Parameters:

• orderId - Target order identifier
• onboardingData - Onboarding information updates
• userId - Administrative user performing update
• dashclicks - User role and permission context

Features:

• Order validation and authorization checks
• Onboarding data processing and updates
• Activity logging for audit trails
• Role-based access control validation

resendOnboarding()

Resends onboarding forms and notifications to clients for incomplete submissions.

Parameters:

• orderId - Order requiring onboarding resend
• dashclicks - Administrative user context
• userId - User performing the resend operation

Features:

• Duplicate submission prevention
• Notification queue management
• Email template processing
• Typeform integration

updateOnboardingStatus()

Updates the onboarding status and progression state for project orders.

Parameters:

• orderId - Target order identifier
• status - New onboarding status
• dashclicks - User authorization context
• requestingUserId - User making the update

Features:

• Status validation and progression rules
• Workload reassignment when needed
• Activity tracking and notifications
• Integration with project workflows

getOrderOnboarding()

Retrieves comprehensive onboarding information and responses for project orders.

Parameters:

• orderIds - Array of order identifiers
• dashclicks - User permission context

Features:

• Multi-order aggregation queries
• Typeform response integration
• Comprehensive onboarding data retrieval
• Role-based data filtering

🔐 Authorization Framework

Role Requirements

All onboarding operations require appropriate PROJECT_ROLES permissions:

• Admin: Full onboarding management access
• Account Manager: Account-specific onboarding oversight
• Fulfillment Specialist: Onboarding execution and updates
• Team Lead: Team-based onboarding coordination

Permission Validation

• Order Access: Validates user access to specific project orders
• Status Updates: Ensures proper authorization for status changes
• Data Access: Role-based filtering of onboarding information
• Notification Rights: Validates resend and communication permissions

🏗️ Technical Architecture

Typeform Integration

• Response Processing: Automated typeform response collection and parsing
• Field Mapping: Dynamic field mapping using TYPEFORM_VALUE_KEYS_MAP
• Data Validation: Response validation and sanitization
• Error Handling: Comprehensive error handling for external API integration

Database Collections

• onboarding-typeform-response: Typeform response storage and tracking
• notification-queue: Notification scheduling and delivery management
• store-order: Order information and onboarding status tracking
• activity: Comprehensive activity logging and audit trails

Workflow Integration

• Activity Logging: Uses createActivity utility for audit trails
• Workload Management: Integration with reassignUserWorkloadUtil
• Domain Management: Active domain resolution for communication
• Contact Integration: Contact information management and updates

📊 Data Processing

Response Handling

The service processes various typeform field types:

const TYPEFORM_VALUE_KEYS_MAP = {
  short_text: 'text',
  long_text: 'text',
  email: 'email',
  phone_number: 'phone_number',
  website: 'url',
  number: 'number',
  yes_no: 'boolean',
  file_upload: 'file_url',
  // ... additional mappings
};

Onboarding Workflows

• Status Progression: Managed onboarding status transitions
• Notification Triggers: Automated notification based on status changes
• Validation Rules: Business rule validation for onboarding data
• Error Recovery: Automated error handling and recovery processes

🔄 Integration Points

External Systems

• Typeform API: Form response collection and processing
• Email System: Notification and communication management
• Activity System: Comprehensive audit trail integration
• Contact System: Client contact information management

Internal Services

• Order Management: Integration with store order system
• User Management: Role and permission validation
• Notification System: Queue-based notification delivery
• Workload System: Automated workload reassignment

📈 Business Logic

Onboarding Flow

1. Initial Setup: Order creation triggers onboarding initialization
2. Form Distribution: Typeform deployment and client notification
3. Response Collection: Automated response processing and validation
4. Status Tracking: Progressive status updates and milestone tracking
5. Completion Processing: Final validation and project launch preparation

Error Handling

• Authorization Errors: Comprehensive role and permission validation
• Data Validation: Input sanitization and business rule enforcement
• External API Errors: Robust handling of typeform and email service failures
• Workflow Errors: Automated error recovery and notification processes

🛡️ Security Features

Data Protection

• Input Validation: Comprehensive input sanitization and validation
• Role-based Access: Granular permission checking for all operations
• Audit Logging: Complete audit trails for compliance and tracking
• Error Logging: Detailed error logging for security monitoring

Authorization Checks

• Order Access: Validates user access to specific project orders
• Role Validation: Ensures appropriate permissions for onboarding operations
• Data Filtering: Role-based filtering of sensitive onboarding information
• Operation Logging: Comprehensive logging of all administrative actions

📝 Usage Examples

Updating Onboarding Status

await updateOnboardingStatus({
  orderId: 'order_123',
  status: 'completed',
  dashclicks: userRoles,
  requestingUserId: 'user_456',
});

Resending Onboarding Forms

await resendOnboarding({
  orderId: 'order_123',
  dashclicks: userRoles,
  userId: 'admin_789',
});

Retrieving Onboarding Data

const onboardingData = await getOrderOnboarding({
  orderIds: ['order_1', 'order_2'],
  dashclicks: userRoles,
});

⚠️ Important Notes

• Typeform Integration: Requires proper API configuration and error handling
• Status Progression: Onboarding status updates must follow defined workflow rules
• Workload Impact: Status changes may trigger automatic workload reassignment
• Notification Dependencies: Onboarding operations depend on notification queue system
• Role Requirements: All operations require appropriate PROJECT_ROLES permissions
• Audit Compliance: All onboarding operations generate audit trail entries