Skip to content

V4 - OnboardingJourneyHandler

This workflow manages the complete onboarding journey for young 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 business coaching system. It handles the entire conversation flow from initial welcome through completion, branching users into specialized paths based on their primary business challenges (credit recovery, profit improvement, or other challenges). The workflow collects essential business data, assigns points for engagement, and prepares users for ongoing daily coaching interactions.

How It Works

The workflow processes user responses through a sophisticated state machine with 39+ distinct conversation steps:

  1. Initial Welcome: Greets new users and explains SIFA's purpose as a free business coaching service
  2. Personal Discovery: Collects the user's personal motivation and business goals
  3. SIFA Introduction: Explains the coaching system, points rewards, and human support options
  4. Business Behavior Collection: Gathers operational details via forms or text input
  5. Pain Point Routing: Identifies primary challenge and routes to specialized branch:
    • Credit Branch: For users with customer debt issues
    • Profit Branch: For users with sales/revenue challenges
    • Other Branch: For users with different business problems
  6. Data Collection: Collects financial data (sales, costs, debts) specific to chosen branch
  7. Testimonial Sharing: Shows relevant success stories based on user's path
  8. Micro-Action Assignment: Provides personalized first action based on business type and challenge
  9. Profile Summary: Reviews collected information with user for accuracy
  10. Points & Rewards: Reveals earned points and redemption options
  11. Support Reinforcement: Reminds users of human support availability
  12. Handover: Explains ongoing daily interaction schedule and completes onboarding

The workflow includes multiple guardrails for welfare concerns, loan requests, and dignity preservation throughout the process.

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 called 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 parent workflows with user input
Code processStep Main logic engine that processes user responses and determines next steps
If isHandledByAI? Routes responses to either AI handling or direct database update
Postgres saveStep Updates user database with conversation progress and collected data
Postgres saveAIData Updates database when response needs AI processing
Set setResponse Formats 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
    • Credential: "Postgres account"
    • Used for: Reading/writing user state, business data, and conversation progress

Environment Variables

No environment variables are explicitly referenced in this workflow. All configuration appears to be handled through the database and hardcoded logic.

Data Flow

Input: - phoneNumber (string): User identifier - query (string): User's message text - user (object): Complete user profile with current onboarding state

Processing: - Analyzes current onboarding step and user response - Applies business logic, guardrails, and routing decisions - Updates database with new state and collected information - Determines appropriate response type (text, interactive buttons, forms)

Output: - handledByAI (boolean): Whether response needs AI processing - output (string): Message text to send to user - outputOptions (array): Interactive button options (if applicable) - outputType (string): Response format (plain, interactive, form_2_1, form_3_1)

Error Handling

The workflow includes several built-in error handling mechanisms:

  • Input Validation: Checks for empty queries and voice notes, redirects appropriately
  • Welfare Guardrails: Detects health/safety concerns and flags for human intervention
  • Dignity Protection: Handles shame/embarrassment around financial disclosure
  • Loan Guardrails: Redirects loan requests to appropriate messaging
  • Scam Concerns: Addresses user suspicions about program legitimacy
  • Data Parsing: Gracefully handles both form submissions and plain text input
  • Fallback Routing: Defaults to AI handling for unrecognized inputs

Known Limitations

Based on the workflow code, several limitations are apparent:

  • Video links are placeholder "[VIDEO LINK - TBD]" and not yet implemented
  • Form handling supports specific Twilio form structures but may not work with other form systems
  • Language support is primarily Swahili with some English, limiting accessibility
  • Points redemption system is described but actual redemption logic is not implemented in this workflow
  • Business type detection relies on keyword matching which may miss edge cases

This workflow is designed to be called by other workflows in the SIFA system, likely including: - Main message routing workflow - User registration workflow - Daily coaching interaction workflows

The workflow references future interactions (morning check-ins, peer tips, evening profit calculations) suggesting integration with scheduled messaging workflows.

Setup Instructions

  1. Import Workflow: Import the JSON workflow definition into your n8n instance

  2. Configure Database Connection:

    • Set up PostgreSQL credential named "Postgres account"
    • Ensure database contains v4_youthEntrepreneurs table with required columns
    • Test database connectivity

  3. Database Schema Requirements: The workflow expects these key columns in the user table:

    • phoneNumber, currentOnboardingStep, onboardingStatus
    • firstName, ceaName, businessOwned
    • Financial fields: day0_sales, day0_costs, day0_profit
    • Credit fields: credit_customers_count, total_credit_baseline
    • Business operation fields: opening_time, closing_time, peak_days
    • Progress tracking: sifa_points, onboarding_branch, primary_pain_point

  4. Integration Setup:

    • Configure calling workflows to pass required parameters
    • Set up response handling for different outputType values
    • Implement form rendering for form_2_1 and form_3_1 types

  5. Testing:

    • Test with sample user data across different onboarding branches
    • Verify database updates occur correctly
    • Test AI handoff functionality
    • Validate form parsing with sample Twilio form submissions

  6. Customization:

    • Update video links when testimonial content is ready
    • Modify business type detection keywords as needed
    • Adjust points values and redemption thresholds
    • Customize messaging for different user segments