V4 - WIP - Francis - SalesTrackingAgent

This workflow serves as the main routing hub for the Sifa coaching program, intelligently directing user interactions between onboarding and daily business tracking based on their current status and engagement phase.

Purpose

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

Based on the workflow structure, this appears to be a sales tracking and coaching system that: - Routes users through different engagement phases (onboarding vs. active tracking) - Manages business coaching interactions with context-aware responses - Tracks user progress through various stages of a business development program - Provides AI-powered responses tailored to user's current business situation

How It Works

1. Input Processing: Receives user phone number, query, and communication channel from another workflow
2. Context Retrieval: Fetches comprehensive user session data from PostgreSQL database using a stored procedure
3. Data Processing: Unpacks and formats user data, chat history, business records, and credit information
4. Context Computation: Calculates key business metrics including profit trends, missing data alerts, and current program stage
5. Routing Decision: Determines if user is in onboarding phase or active tracking phase
6. Onboarding Path: For new users, routes to onboarding journey handler with optional AI assistance
7. Daily Tracking Path: For active users, routes to daily tracking system for business monitoring
8. Response Formatting: Standardizes output format with message content, type, and interaction options

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[getSessionContext]
    B --> C[getUserRecord]
    C --> D[chatAndBusinessHistory]
    D --> E[computeContext]
    E --> F[isOnboardingPhase?]
    F --> G[isOnboardingPhase? Route]

    G -->|Onboarding| H[Call V4 - OnboardingJourneyHandler]
    G -->|Active User| I[Call V4 - DailyTrackingRouter]

    H --> J[shouldUseAI?]
    J -->|Use AI| K[callOnboardingAI]
    J -->|No AI| L[onboarding_setOutput]

    K --> M[setOnboardingAIOutput]
    I --> N[daily_setOutput]

    L --> O[Final Output]
    M --> O
    N --> O

Trigger

Execute Workflow Trigger: Activated when called by another workflow with the following inputs: - phoneNumber: User's phone number for identification - query: User's message or query text - channel: Communication channel (e.g., WhatsApp)

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflow
PostgreSQL	getSessionContext	Retrieves user session data using stored procedure
Code	getUserRecord	Unpacks and flattens user data from database result
Code	chatAndBusinessHistory	Formats context data for downstream agents
Code	computeContext	Calculates business metrics and determines user stage
Code	isOnboardingPhase?	Determines if user is in onboarding or active phase
If	isOnboardingPhase? Route	Routes to appropriate handler based on user status
Execute Workflow	Call 'V4 - OnboardingJourneyHandler'	Handles onboarding flow for new users
Execute Workflow	Call 'V4 - DailyTrackingRouter'	Handles daily business tracking for active users
If	shouldUseAI?	Determines if AI assistance is needed for onboarding
Execute Workflow	callOnboardingAI	Provides AI-powered onboarding responses
Set	onboarding_setOutput	Formats onboarding output without AI
Set	setOnboardingAIOutput	Formats AI-generated onboarding output
Set	daily_setOutput	Formats daily tracking output

External Services & Credentials Required

PostgreSQL Database

• Credential Name: sifaV4Dev
• Purpose: Stores user data, chat history, business records, and credit information
• Required Permissions: Execute stored procedure get_session_context_v4

Sub-Workflows

• V4 - OnboardingJourneyHandler (ID: wApuAJrgMmyGdyHJ): Manages user onboarding process
• V4 - DailyTrackingRouter (ID: ZoLUDgEGqwMBkZ3h): Handles daily business tracking
• Onboarding AI Workflow (ID: SuruN1xURUn9I33r): Provides AI-powered onboarding assistance

Environment Variables

No specific environment variables are configured in this workflow. All configuration is handled through: - Database credentials for PostgreSQL connection - Workflow IDs for sub-workflow execution

Data Flow

Input

{
  "phoneNumber": "+254707060397",
  "query": "User message text",
  "channel": "Whatsapp"
}

Output

{
  "output": "Response message text",
  "outputType": "plain|interactive",
  "outputOptions": ["Option 1", "Option 2"]
}

Internal Context Data

The workflow processes extensive user context including: - User profile and onboarding status - Chat history and pending messages - Business records and profit trends - Credit module status and micro-actions - Computed metrics (current day, profit trends, missing data alerts)

Error Handling

• Database Retry: getUserRecord node configured with retry on fail (max 2 attempts)
• Error Workflow: Global error handling via workflow ID cuHEGQjAfvuGwIOD
• Graceful Degradation: chatAndBusinessHistory continues on error with empty data
• Data Validation: Multiple code nodes include null checks and fallback values

Known Limitations

Based on the workflow structure and comments: - Credit collection implementation is incomplete (marked as TODO) - Sales data validation for last 3 working days needs enhancement - Missing data reminders require polite messaging improvements - Some onboarding steps may need refinement for edge cases

Related Workflows

• V4 - OnboardingJourneyHandler: Manages new user onboarding process
• V4 - DailyTrackingRouter: Handles business tracking for active users
• Onboarding AI Assistant: Provides intelligent responses during onboarding
• Error Handler Workflow: Manages workflow-level error processing

Setup Instructions

1. Import Workflow: Import the JSON configuration into your n8n instance

2. Configure Database Connection:

   • Create PostgreSQL credential named sifaV4Dev
   • Ensure database contains the get_session_context_v4 stored procedure
   • Grant appropriate permissions for procedure execution

3. Set Up Sub-Workflows:

   • Import and configure the OnboardingJourneyHandler workflow
   • Import and configure the DailyTrackingRouter workflow
   • Import and configure the Onboarding AI workflow
   • Update workflow IDs in the Execute Workflow nodes if needed

4. Configure Error Handling:

   • Set up the error workflow (ID: cuHEGQjAfvuGwIOD)
   • Test error scenarios to ensure proper fallback behavior

5. Test Integration:

   • Create a test calling workflow to trigger this workflow
   • Verify data flow with sample user data
   • Test both onboarding and daily tracking paths

6. Activate Workflow: Enable the workflow once all dependencies are configured and tested