Skip to content

V4 - OnboardingJourneyHandler

This workflow manages the initial onboarding experience for users in a business coaching program, handling their responses to welcome messages and determining whether to continue with automated responses or hand off to AI processing.

Purpose

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

How It Works

  1. Receives User Input: The workflow is triggered by another workflow with user data including phone number, query text, and user profile information
  2. Processes Onboarding Step: Analyzes the user's current onboarding status and their message to determine the appropriate response
  3. Decision Logic: Uses keyword detection to identify yes/no responses, scam concerns, and determines if the interaction should be handled by predefined responses or AI
  4. Database Updates: For non-AI responses, updates the user's onboarding step and relevant timestamps in the database
  5. Response Generation: Returns either a structured response with specific messaging or passes control to AI processing

The workflow handles several key scenarios: - New users receiving their first welcome message - Users declining to participate (pauses onboarding) - Users expressing scam concerns (provides reassurance) - Standard progression through onboarding steps

Workflow Diagram

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

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, not triggered directly by external events.

Nodes Used

Node Type Node Name Purpose
Execute Workflow Trigger When Executed by Another Workflow Receives execution requests from other workflows
Code processStep Contains the main logic for analyzing user input and determining response type
If isHandledByAI? Routes the flow based on whether AI should handle the response
Set setPassthrough Prepares data when handing off to AI processing
Postgres saveStep Updates user onboarding status in the database
Set setResponse Formats the final response for non-AI handled cases

External Services & Credentials Required

  • PostgreSQL Database: Stores user onboarding data and status
    • Credential: "Postgres account" (ID: EJPqF6MDH1ZwAzyv)
    • Required permissions: UPDATE access to youthEntrepreneursReal table

Environment Variables

No environment variables are explicitly referenced in this workflow.

Data Flow

Input Data

The workflow expects an input object containing: - user: User profile object with fields like firstName, currentOnboardingStep, onboardingStatus, ceaName - phoneNumber: User's phone number for database updates - query: The user's message text for analysis

Output Data

The workflow returns one of two response types:

AI Handoff Response: 

1
2
3
{
  "handledByAI": true
}

Direct Response: 

1
2
3
4
5
6
{
  "handledByAI": false,
  "output": "Response message text",
  "outputOptions": ["Option1", "Option2"] | null,
  "outputType": "interactive" | "plain"
}

Error Handling

The workflow includes basic error handling through: - Default fallback to AI processing when no specific conditions are met - Null checks for optional user data fields - Safe string operations with fallback values

No explicit error catching or retry mechanisms are implemented.

Known Limitations

  • The workflow is currently incomplete - Module 1 Step 2 (M1.2) is not yet implemented
  • Keyword detection is limited to predefined word lists and may not catch all variations
  • No handling for multiple languages beyond basic Swahili/English keywords
  • Database operations lack transaction handling or rollback capabilities

This workflow is designed to be called by other workflows in the system, likely including: - Main message processing workflows - User interaction handlers - Onboarding orchestration workflows

Setup Instructions

  1. Import the Workflow

    • Copy the workflow JSON and import it into your n8n instance
    • The workflow will be created in inactive state

  2. Configure Database Connection

    • Set up a PostgreSQL credential named "Postgres account"
    • Ensure the database contains a youthEntrepreneursReal table with required columns:
      • phoneNumber (TEXT)
      • currentOnboardingStep (TEXT)
      • ceaAlertTimestamp (TIMESTAMP)
      • ceaAlertReason (TEXT)
      • ceaEngagementStatus (TEXT)

  3. Test the Workflow

    • Create a test workflow that calls this one with sample data
    • Verify database updates are working correctly
    • Test different user input scenarios (yes/no responses, scam concerns)

  4. Integration

    • Connect this workflow to your main message processing system
    • Ensure proper error handling in calling workflows
    • Monitor database performance with the UPDATE queries

  5. Activate

    • Once testing is complete, activate the workflow
    • Monitor execution logs for any issues