V4 - CreditOutcomeHandler - Warenga

This workflow processes the outcomes of credit collection micro-actions for young entrepreneurs in the Warenga program. When a user reports the result of attempting to collect debt from a customer, this workflow provides personalized coaching, awards points for progress, schedules follow-up reminders, and sets the next micro-action to keep the debt collection process moving forward.

Purpose

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

Based on the workflow implementation, this appears to serve young entrepreneurs who are learning debt collection skills through a structured micro-action system. The workflow handles seven different outcome scenarios (C1-C7) ranging from successful payment promises to various barriers like fear, forgetfulness, or lack of time. It provides culturally appropriate coaching in Swahili and maintains momentum through automated follow-ups.

How It Works

1. Receive Input: The workflow receives details about a credit collection attempt, including the phone number, outcome step (C1-C7), user's name, business type, and current micro-action.

2. Get Credit Context: Retrieves the current credit tracking information and any pending follow-ups from the database for the specific phone number.

3. Process Outcome: Based on the outcome step, generates appropriate coaching messages in Swahili, calculates points to award, determines the next micro-action, and creates follow-up reminders if needed.

4. Save Progress: Records the outcome and sets the new micro-action in the system.

5. Award Points: If the outcome warrants it (steps C1-C4, C6), awards 10 points to encourage continued engagement.

6. Schedule Follow-ups: For certain outcomes, creates automated reminders (e.g., checking if promised payments were made, gentle retry attempts after refusals).

7. Return Response: Provides the coaching message back to the user through the chat interface.

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Get Credit Context]
    B --> C[Process Outcome]
    C --> D[Save Microaction]
    D --> E{Points > 0?}
    E -->|Yes| F[Award Points]
    E -->|No| G{Followup Needed?}
    F --> G
    G -->|Yes| H[Schedule Followup]
    G -->|No| I[Return Result]
    H --> I

Trigger

Execute Workflow Trigger: This workflow is called by other workflows in the system when a user reports the outcome of a credit collection micro-action. It expects the following inputs: - phoneNumber: User's phone number - outcomeStep: The outcome code (C1-C7) - firstName: User's first name for personalization - businessOwned: Type of business (for context) - currentMicroAction: The current micro-action being tracked

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflows
Postgres	Get Credit Context	Retrieves credit tracking data and pending follow-ups
Code	Process Outcome	Core logic for handling different outcome scenarios and generating responses
Execute Workflow	Save Microaction	Calls another workflow to record the outcome and set next micro-action
If	Points > 0?	Conditional logic to determine if points should be awarded
Execute Workflow	Award Points	Calls points system to award credit for positive outcomes
If	Followup Needed?	Checks if automated follow-up reminders should be scheduled
Postgres	Schedule Followup	Inserts follow-up reminders into the database
Code	Return Result	Formats the final response message

External Services & Credentials Required

• PostgreSQL Database: Stores credit tracking, follow-up schedules, and user data
  • Credential: sifaV4Dev
  • Tables accessed: v4_creditTracking, v4_creditpathFollowup

Environment Variables

No environment variables are directly used in this workflow. Configuration is handled through the PostgreSQL connection and workflow references.

Data Flow

Input:

{
  "phoneNumber": "string",
  "outcomeStep": "C1|C2|C3|C4|C5|C6|C7",
  "firstName": "string",
  "businessOwned": "string", 
  "currentMicroAction": "string"
}

Output:

{
  "output": "string (Swahili coaching message)",
  "outputType": "plain",
  "outputOptions": []
}

Outcome Steps: - C1: Customer promised to pay → Celebration + follow-up scheduling - C2: Partial payment received → Encouragement + remainder tracking - C3: Full payment received → Celebration + next target suggestion - C4: Customer refused → Empathy + soft reframe script + retry scheduling - C5: User forgot to follow up → Validation + same-day reminder - C6: User afraid to ask → Fear coaching + gentle script - C7: User had no time → Understanding + next-day reminder

Error Handling

The workflow includes basic error handling through: - Default fallback in the outcome processing switch statement - Safe string escaping for SQL queries to prevent injection - Graceful handling of missing credit context data - Conditional execution paths that skip steps when data is unavailable

Known Limitations

• Messages are hardcoded in Swahili and not easily translatable
• Follow-up scheduling assumes East Africa Time (EAT) timezone
• Limited to 7 predefined outcome scenarios
• No validation of input parameters before processing
• Database queries use string interpolation which could be vulnerable if input sanitization fails

Related Workflows

This workflow calls two other workflows: - Microaction Saver (ID: cNnkBA3Cuks1p1wi): Records outcomes and sets next micro-actions - Points System (ID: JmJObsTea34h5bjX): Awards points for positive outcomes

Setup Instructions

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

2. Configure Database Connection:

   • Set up PostgreSQL credential named sifaV4Dev
   • Ensure access to tables: v4_creditTracking, v4_creditpathFollowup

3. Link Related Workflows:

   • Ensure workflow cNnkBA3Cuks1p1wi (Microaction Saver) exists and is accessible
   • Ensure workflow JmJObsTea34h5bjX (Points System) exists and is accessible

4. Database Schema Requirements:

   -- Ensure these tables exist with appropriate columns
   -- v4_creditTracking: phoneNumber, totalCreditLocked, debtorName
   -- v4_creditpathFollowup: phoneNumber, debtorName, followupType, scheduledFollowupAt, followupFired, followupMessage
   

5. Test the Workflow:

   • Execute with sample data for each outcome step (C1-C7)
   • Verify database writes and follow-up scheduling
   • Check that related workflows are called successfully

6. Activate: Set the workflow to active status to enable execution by other workflows