V4 - CreditPathHandler (followup only)

A specialized credit recovery follow-up workflow that guides young entrepreneurs through a structured 7-outcome conversation flow after they've attempted to collect debts from their customers. This deterministic state machine handles daily follow-ups, captures outcomes, and provides appropriate coaching based on the results.

Purpose

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

This workflow serves as a focused follow-up handler for credit recovery activities. It processes user responses to daily check-ins about debt collection attempts, categorizing outcomes into 7 specific scenarios (promised payment, partial payment, full payment, refusal, forgot, fear, no time) and providing tailored guidance for each situation. The system tracks progress, schedules appropriate follow-ups, and awards points for engagement.

How It Works

1. Trigger Reception: The workflow is executed by another workflow (typically a scheduled morning nudge system) that passes user data and their response to a follow-up question.

2. Input Processing: The system extracts user information, phone number, query text, and current step from the incoming data. It also performs safety checks for threatening language.

3. Safety Override: If aggressive or threatening language is detected, the workflow immediately pauses the recovery process, alerts the Community Engagement Advisor (CEA), and ends the conversation.

4. State Machine Processing: Based on the user's current step in the credit path, the system processes their response through one of several conversation flows:

   • Outcome Selection (cfu_outcome_pending): User selects from 7 possible outcomes
   • Promise Flow (C1): Captures relationship and commitment date
   • Partial Payment Flow (C2): Records amount and remaining balance
   • Full Payment Flow (C3): Generates thank-you message and offers next target
   • Refusal Flow (C4): Provides softer approach based on relationship
   • Forgot Flow (C5): Offers reminder scheduling
   • Fear Flow (C6): Provides coaching and support
   • No Time Flow (C7): Offers flexible scheduling options

5. AI Integration: Certain steps trigger AI-generated responses for personalized coaching, thank-you messages, or softer recovery scripts.

6. Data Persistence: User progress, outcomes, and scheduling preferences are saved to the database with appropriate point awards.

7. Response Generation: The system outputs either a direct response or passes control to AI for dynamic content generation.

Mermaid 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]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, typically scheduled follow-up systems that send daily check-ins to users about their credit recovery activities.

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives execution requests from other workflows with user data
Code	processStep	Main state machine logic that processes user responses and determines next steps
If	isHandledByAI?	Routes flow based on whether AI generation is needed
Postgres	saveAIData	Updates database when AI processing is required
Postgres	saveStep	Updates database for direct responses
Set	setPassthrough	Prepares data for AI processing
Set	setResponse	Formats final response for direct replies

External Services & Credentials Required

• PostgreSQL Database: Requires connection to sifaV4Dev database for user data storage and updates
• Database Tables: Uses v4_youthEntrepreneurs table with extensive credit tracking columns

Environment Variables

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

Data Flow

Input: - user: User object containing profile and progress data - phoneNumber: User's phone number for identification - query: User's text response to follow-up questions

Output: - handledByAI: Boolean indicating if AI processing is needed - output: Direct response text (for non-AI responses) - outputOptions: Array of interactive options (if applicable) - outputType: Response format ('plain' or 'interactive') - ai_intent: Type of AI processing needed (for AI responses) - ai_context: Context data for AI generation (for AI responses)

Database Updates: - Progress tracking through currentCreditPathStep - Payment amounts and relationship data - Scheduling preferences and follow-up timing - Point awards for engagement - Safety alerts and CEA notifications

Error Handling

The workflow includes several error handling mechanisms:

• Safety Override: Detects threatening language and immediately pauses the process
• Input Validation: Checks for valid numeric inputs when capturing amounts
• Fallback Responses: Provides default outcome selection prompt when user input is unclear
• Database Error Resilience: Uses conditional SQL updates to prevent null value issues

Known Limitations

Based on the workflow documentation:

• Followup Only: This is a stripped-down version that only handles follow-up conversations, not initial onboarding
• Single Language: Primarily designed for Swahili/English mixed communication
• Manual Scheduling: Follow-up scheduling relies on external systems to trigger at appropriate times
• Limited AI Context: AI responses are generated with minimal context about user history

Related Workflows

• Unified Credit Path Handler: A more comprehensive version (v4_creditPathHandler.json) that includes both onboarding and follow-up functionality
• Morning Nudge Workflow: Likely triggers this workflow with daily check-ins
• AI Response Generation: Workflows that handle the AI-generated content for coaching and scripts

Setup Instructions

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

2. Database Setup: Ensure PostgreSQL connection is configured with credential ID KG6Iw6AZuiJwopGr pointing to your sifaV4Dev database

3. Database Schema: Verify the v4_youthEntrepreneurs table includes all required columns:

   • currentCreditPathStep, target_debtor_name, target_debtor_amount
   • target_debtor_relationship, target_debtor_balance
   • next_open_debtor_name, next_open_debtor_amount, next_open_debtor_days
   • committed_date_raw, commitment_captured
   • partial_payment_amount, partial_payment_received
   • full_recovery_complete, full_recovery_amount
   • refusal_received, action_forgotten
   • fear_barrier_acknowledged, fear_description
   • credit_followup_scheduled_for, next_target_assigned
   • first_micro_action, sifa_points
   • ceaAlertReason, ceaAlertTimestamp

4. Calling Workflow Setup: Configure your trigger workflow to call this workflow with the required data structure

5. AI Integration: Set up downstream workflows to handle AI-generated responses when handledByAI is true

6. Testing: Test with sample user data to ensure state transitions work correctly

7. Monitoring: Set up monitoring for CEA alerts and safety overrides to ensure user safety