SIFA Credit Path Test Helper (Form)

A web form interface for SIFA development team members to manage test accounts in the credit path system. This workflow allows authorized users to either add new test accounts or reset existing test data through a simple form submission, streamlining the testing process for the credit followup program.

Purpose

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

This workflow serves as a development tool for the SIFA credit path system, providing a user-friendly way to: - Add new test accounts with predefined debtor scenarios - Reset existing test accounts to their initial state - Validate user permissions before allowing data modifications - Maintain clean test environments for development and QA

The workflow is specifically designed for internal team use during development and testing phases.

How It Works

1. Form Submission: User fills out a web form specifying whether to add a new tester or reset existing test data, along with their phone number and name (if adding)

2. Input Validation: The system validates the phone number format (accepts Kenyan formats like +254..., 254..., or 07...) and ensures required fields are provided

3. Action Routing: Based on the selected action, the workflow branches to either the reset or add flow

4. Reset Flow:

   • Looks up the phone number in the database
   • Verifies the user has admin privileges
   • If authorized, resets all debtor records to original balances and clears conversation history
   • Activates the primary debtor for testing

5. Add Flow:

   • Checks if the phone number already exists in the system
   • If new, creates a youth entrepreneur record with admin privileges
   • Sets up three test debtors (John, Esther, Peter) with different amounts
   • Activates the first debtor for immediate testing

6. Response Generation: Provides clear feedback about the operation result, including current debtor states and next steps

Workflow Diagram

graph TD
    A[On Form Submission] --> B[Validate Input]
    B --> C{Has Error?}
    C -->|Yes| D[Build Validation Error]
    C -->|No| E{Is Reset?}
    E -->|Yes| F[Lookup Phone]
    E -->|No| G[Check Duplicate]
    F --> H{Is Authorized?}
    H -->|Yes| I[Reset Debtors]
    H -->|No| J[Build Reset Denied]
    I --> K[Build Reset Response]
    G --> L{Already Exists?}
    L -->|Yes| M[Build Duplicate Response]
    L -->|No| N[Add Tester]
    N --> O[Build Add Response]

Trigger

Form Trigger: A web form accessible at the path /testing-credit-path that collects: - Action (dropdown): "Reset my test data" or "Add a new tester" - Phone number (required): Accepts various Kenyan phone formats - Name (optional): Required only when adding a new tester

Nodes Used

Node Type	Node Name	Purpose
Form Trigger	On Form Submission	Captures form submissions from the web interface
Code	Validate Input	Normalizes phone numbers and validates form data
If	Has Error?	Routes to error handling if validation fails
Code	Build Validation Error	Creates error response for invalid inputs
If	Is Reset?	Determines whether to reset or add based on action
Postgres	Lookup Phone	Queries user data to verify admin privileges
If	Is Authorized?	Checks if user has permission to reset data
Postgres	Reset Debtors	Resets debtor data and conversation state
Code	Build Reset Response	Creates success response for reset operations
Code	Build Reset Denied	Creates denial response for unauthorized users
Postgres	Check Duplicate	Verifies if phone number already exists
If	Already Exists?	Prevents duplicate account creation
Postgres	Add Tester	Creates new test account with sample debtors
Code	Build Add Response	Creates success response for new accounts
Code	Build Duplicate Response	Creates response for existing accounts

External Services & Credentials Required

PostgreSQL Database

• Credential Name: sifaV4Dev
• Purpose: Access to SIFA development database
• Tables Used:
  • v4_youthEntrepreneurs: User account management
  • v4_creditpathFollowup: Debtor tracking and conversation state
  • v4_creditpathHistory: Conversation history (cleared during reset)

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through the PostgreSQL credentials and hardcoded form settings.

Data Flow

Input

Form submission containing: - Action: "Reset my test data" or "Add a new tester" - Phone number: Various Kenyan formats (+254..., 254..., 07...) - Name: Required for new testers, optional for resets

Output

JSON response with: - status: "ok", "error", "denied", or "duplicate" - title: User-friendly status message - message: Detailed information about the operation result

Sample Responses

Successful Reset:

{
  "status": "ok",
  "title": "✅ Reset done",
  "message": "Reset done for John at +254712345678.\n\nDebtor state:\n- John: KSh 600 (active) ◀ active\n- Esther: KSh 1,200 (active)\n- Peter: KSh 800 (active)\n\nMessage +12402623539 from your phone with \"menu\" to start."
}

New Tester Added:

{
  "status": "ok",
  "title": "✅ Tester added"
}

Error Handling

The workflow includes comprehensive error handling for:

1. Input Validation Errors: Invalid phone formats, missing required fields
2. Authorization Errors: Non-admin users attempting to reset data
3. Duplicate Prevention: Attempting to add existing phone numbers
4. Database Errors: Handled by n8n's built-in PostgreSQL error handling

Each error path provides specific, actionable feedback to help users correct their input or understand why their request was denied.

Known Limitations

• Only supports Kenyan phone number formats
• Requires admin privileges in the database for reset operations
• Creates fixed test debtor scenarios (John: 600 KSh, Esther: 1200 KSh, Peter: 800 KSh)
• Form is publicly accessible but operations are permission-gated
• No audit logging of test account modifications

Related Workflows

This workflow supports testing of the main SIFA credit path conversation system. Users should message +12402623539 with "menu" after using this helper to begin testing the credit followup flow.

Setup Instructions

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

2. Configure Database Credential:

   • Create a PostgreSQL credential named sifaV4Dev
   • Configure connection to your SIFA development database
   • Ensure the credential has read/write access to:
     • v4_youthEntrepreneurs
     • v4_creditpathFollowup
     • v4_creditpathHistory

3. Activate Workflow: Enable the workflow to make the form accessible

4. Access Form: Navigate to https://your-n8n-instance.com/form/testing-credit-path

5. Test Setup:

   • Use the form to add yourself as a tester
   • Verify the database records are created correctly
   • Test the reset functionality to ensure proper state management

6. Integration: Ensure the phone number +12402623539 mentioned in responses corresponds to your SMS gateway for the main credit path workflow