Skip to content

V4 - OnboardingJourneyHandler

This workflow manages the complete onboarding journey for youth entrepreneurs in the SIFA coaching program, guiding them through a structured conversation flow that collects business information, identifies pain points, and sets up their first micro-actions for business improvement.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

This workflow serves as the core onboarding engine for new users entering the SIFA system. It handles the entire conversation flow from initial welcome through completion, branching users into different paths based on their primary business challenges (credit recovery, profit improvement, or other issues). The workflow collects essential business data, assigns points for engagement, and prepares users for ongoing daily coaching interactions.

How It Works

The workflow follows a multi-stage onboarding process:

  1. Initial Welcome (M1): Greets new users, explains SIFA's purpose, collects personal motivation and business goals, introduces the points system, and provides human support contact information.

  2. Business Information Collection (M2): Gathers business behavior data through forms (opening hours, peak days, etc.) and routes users to specialized branches based on their primary pain point.

  3. Branch-Specific Data Collection (M3):

    • Credit Branch (3A): Collects information about outstanding debts from customers
    • Profit Branch (3B): Focuses on sales and expense tracking
    • Other Branch (3C): Handles custom challenges through AI assistance

  4. Micro-Action Assignment (M4): Assigns personalized first actions based on the user's business type and chosen branch, with follow-up scheduling.

  5. Summary and Completion (M5): Reviews collected information, reveals earned points with redemption options, reinforces human support availability, and completes the onboarding process.

The workflow includes multiple guardrails for welfare concerns, loan requests, and dignity preservation, along with intelligent routing between branches based on user responses.

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[processStep]
    B --> C{isHandledByAI?}
    C -->|Yes| D[saveAIData]
    C -->|No| E[saveStep]
    D --> F[setPassthrough]
    E --> G[setResponse]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#e8f5e8
    style F fill:#fff9c4
    style G fill:#fff9c4

Trigger

Execute Workflow Trigger: This workflow is triggered by other workflows in the system, receiving three input parameters: - phoneNumber: User's phone number for identification - query: User's message/response text - user: Complete user object with current state and profile data

Nodes Used

Node Type Node Name Purpose
Execute Workflow Trigger When Executed by Another Workflow Receives calls from other workflows with user input
Code processStep Main logic engine that processes user responses and determines next steps
If isHandledByAI? Routes flow based on whether AI should handle the response
Postgres saveStep Updates user database with deterministic responses and state changes
Postgres saveAIData Updates user database when AI will handle the response
Set setResponse Formats the final response for deterministic replies
Set setPassthrough Passes through AI-handled responses unchanged

External Services & Credentials Required

  • PostgreSQL Database: Stores user profiles and onboarding progress in the v4_youthEntrepreneurs table
  • Twilio (implied): For form-based data collection (forms 2_1 and 3_1)

Required credentials: - PostgreSQL connection credentials for database access - Twilio credentials for form delivery (if using form output types)

Environment Variables

No specific environment variables are referenced in this workflow. Database connection details are handled through n8n's credential system.

Data Flow

Input: - phoneNumber: String - User identifier - query: String - User's message or response - user: Object - Complete user profile with current onboarding state

Output: - handledByAI: Boolean - Whether AI should process this response - output: String - Message to send to user (for deterministic responses) - outputOptions: Array - Interactive button options (optional) - outputType: String - Response format ('plain', 'interactive', 'form_2_1', 'form_3_1')

Database Updates: The workflow updates numerous fields in the user profile including onboarding step, business data, pain points, micro-actions, and SIFA points balance.

Error Handling

The workflow includes several built-in error handling mechanisms:

  • Input Validation: Checks for valid numeric inputs and re-prompts when needed
  • Dignity Guardrails: Handles sensitive topics (shame about debt) with supportive responses
  • Welfare Flagging: Detects emergency situations and routes to human support
  • Fallback Routing: Unrecognized inputs default to AI handling or re-prompting
  • Database Safety: Uses COALESCE and NULLIF functions to prevent data corruption

Known Limitations

  • Video links are placeholder text ("[VIDEO LINK - TBD]") and need to be replaced with actual content
  • Form handling assumes specific Twilio form structure and field names
  • Points redemption system references specific rewards but doesn't include actual redemption logic
  • Toll-free number (0800 723 611) may need verification for different regions

This workflow is designed to be called by other workflows in the SIFA system, likely including: - Message routing workflows that determine when to trigger onboarding - AI processing workflows that handle the responses marked as handledByAI: true - Daily engagement workflows that follow up on assigned micro-actions

Setup Instructions

  1. Import the Workflow: Copy the JSON and import into your n8n instance

  2. Configure Database Connection:

    • Set up PostgreSQL credentials in n8n
    • Ensure the v4_youthEntrepreneurs table exists with all required columns
    • Test database connectivity

  3. Set Up Twilio Integration (if using forms):

    • Configure Twilio credentials for form delivery
    • Create form templates for form_2_1 (business behavior) and form_3_1 (sales info)

  4. Update Placeholder Content:

    • Replace "[VIDEO LINK - TBD]" with actual video URLs
    • Verify the toll-free number (0800 723 611) for your region
    • Customize points redemption options and values

  5. Test the Workflow:

    • Create test user records in the database
    • Execute with sample inputs to verify all branches work correctly
    • Test database updates and state transitions

  6. Connect to Calling Workflows:

    • Ensure other workflows can properly call this one with required parameters
    • Set up proper error handling in calling workflows for AI responses