V4 - OnboardingJourneyHandler

This workflow manages the complete onboarding journey for young entrepreneurs in the SIFA coaching program, handling deterministic conversation flows and routing complex interactions to AI when needed. It processes user responses through a structured 5-module onboarding sequence, collecting business data, assigning micro-actions, and transitioning users from "new" to "active" status.

Purpose

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

This workflow serves as the core onboarding engine for young entrepreneurs joining the SIFA business coaching program. It guides users through a comprehensive intake process that:

• Establishes rapport and explains the SIFA coaching model
• Collects detailed business information (operating hours, pain points, financial data)
• Routes users into specialized coaching branches based on their primary challenges (credit recovery, profit optimization, or other business issues)
• Assigns personalized micro-actions to drive immediate business improvements
• Awards points for engagement and offers redemption opportunities
• Completes the onboarding with human support reinforcement

The workflow is designed to handle both simple acknowledgments deterministically and complex queries through AI integration, ensuring users receive appropriate responses while maintaining conversation flow.

How It Works

The workflow operates as a state machine processing user inputs through five main modules:

Module 1 (M1) - Introduction & Foundation - Welcomes new users and introduces SIFA - Collects personal motivation and business goals - Explains the points system and human support options - Gathers basic business behavior data through forms

Module 2 (M2) - Business Profiling - Confirms business operation details - Identifies primary pain points (credit issues, low profits, or other challenges) - Routes users into specialized coaching branches

Module 3 (M3) - Branch-Specific Data Collection - Branch A (Credit): Focuses on debt recovery and customer credit management - Branch B (Profit): Emphasizes sales optimization and profit analysis - Branch C (Other): Handles miscellaneous business challenges - Collects financial data (sales, expenses, monthly costs) through forms - Calculates true profit including fixed cost allocation

Module 4 (M4) - Insight & Action Assignment - Presents personalized business insights based on collected data - Assigns specific micro-actions tailored to the user's business type and branch - Captures any additional challenges the user wants to address

Module 5 (M5) - Completion & Activation - Summarizes the user's profile for confirmation - Reveals accumulated points and offers redemption options - Reinforces human support availability - Completes onboarding and activates the user for ongoing coaching

Throughout the process, the workflow awards points for engagement, handles welfare concerns by flagging users for human intervention, and maintains detailed conversation logs.

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[logChatHistory]
    G --> H[setResponse]

    F -.->|AI Processing| I[External AI Handler]
    H --> J[Response to User]

Trigger

Execute Workflow Trigger - This workflow is called by other workflows with three required inputs: - 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 inputs from calling workflows
Code	processStep	Main logic engine - processes user input and determines response
If	isHandledByAI?	Routes flow based on whether AI processing is needed
Postgres	saveStep	Updates user data for deterministic responses
Postgres	saveAIData	Updates user data for AI-handled responses
Postgres	logChatHistory	Records conversation history
Set	setPassthrough	Prepares AI passthrough response
Set	setResponse	Formats final response for deterministic flows

External Services & Credentials Required

PostgreSQL Database (Credential: "sifaV4Dev") - Stores user profiles in v4_youthEntrepreneurs table - Logs conversations in v4_chatLog table - Requires read/write access for user state management

AI Integration (External) - Handles complex queries that fall outside deterministic rules - Processes natural language understanding for ambiguous responses - Returns structured responses for workflow continuation

Environment Variables

No explicit environment variables are configured in this workflow. Database connection details are managed through n8n credentials.

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 deterministic rules for common responses - Routes complex queries to AI processing - Updates user state and awards points - Generates appropriate response content

Output: - handledByAI: Boolean - Whether AI processing is needed - output: String - Response message text (null for AI routing) - outputOptions: Array - Interactive button options - outputType: String - Response format (plain, interactive, form templates)

Error Handling

The workflow includes several error handling mechanisms:

• Welfare Detection: Automatically flags users mentioning health/safety concerns for human intervention
• Scam Concerns: Provides reassurance and human contact information for users expressing fraud worries
• Invalid Input Handling: Gracefully handles malformed form data and missing responses
• AI Fallback: Routes unexpected or complex queries to AI when deterministic rules don't apply
• SQL Injection Protection: Escapes user input in database queries using the esc() function

Known Limitations

Based on the workflow implementation:

• Form parsing relies on specific JSON structure and may not handle all form variations
• Points system thresholds are hardcoded and not easily configurable
• Language support is primarily Swahili with some English fallbacks
• Business type detection for micro-actions uses simple keyword matching
• No explicit timeout handling for long conversations
• Welfare flagging uses basic keyword detection which may miss nuanced concerns

Related Workflows

This workflow is designed to be called by other workflows in the SIFA system, likely including: - Message routing workflows that determine when onboarding is needed - AI processing workflows that handle complex query resolution - Follow-up workflows that manage post-onboarding engagement

Setup Instructions

1. Import the Workflow

   • Import the JSON configuration into your n8n instance
   • Ensure all node types are available in your n8n version

2. Configure Database Credentials

   • Create a PostgreSQL credential named "sifaV4Dev"
   • Ensure connection to database with v4_youthEntrepreneurs and v4_chatLog tables
   • Verify the database user has INSERT, UPDATE, and SELECT permissions

3. Set Up Database Schema

   • Create the required tables with all fields referenced in the SQL queries
   • Ensure proper data types for numeric fields (NUMERIC for financial data, INTEGER for counts)
   • Set up appropriate indexes for phone number lookups

4. Configure AI Integration

   • Set up the external AI processing workflow or service
   • Ensure it can handle the passthrough data structure
   • Test AI responses return in the expected format

5. Test the Workflow

   • Create test user records in the database
   • Test various onboarding scenarios and edge cases
   • Verify form parsing works with your form submission format
   • Confirm points system calculations are accurate

6. Deploy and Monitor

   • Activate the workflow for production use
   • Monitor conversation logs for unexpected AI routing
   • Track completion rates through the onboarding funnel
   • Review welfare flagging accuracy and response times