V4 - saveCreditRecordTool

A utility workflow that saves and tracks credit-related data for users in a PostgreSQL database. This workflow handles credit baselines, recovery targets, micro-actions, and maintains historical records of credit management activities.

Purpose

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

This workflow appears to be part of a credit management system that tracks customer credit activities, recovery efforts, and micro-actions taken to manage credit portfolios. It maintains both current state and historical records for analysis and reporting purposes.

How It Works

1. Input Processing: The workflow receives credit tracking data including phone number, credit amounts, customer information, and micro-action details
2. Data Encoding: All input parameters are encoded as Base64 JSON to ensure safe SQL parameter handling and prevent injection attacks
3. Database Operations: Two parallel database operations occur:
   • Credit Record Upsert: Updates or creates a record in the creditTracking table with current credit status
   • History Logging: Records micro-action details in the microActionHistory table for audit purposes
4. Response Generation: Returns a formatted summary of the saved credit information including total locked credit and recovery progress

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[encodeParams]
    B --> C[upsertCreditRecord]
    B --> D[logMicroActionHistory]
    C --> E[setOutput]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows within the same n8n instance. It accepts 18 input parameters related to credit tracking and management.

Nodes Used

Node Name	Type	Purpose
When Executed by Another Workflow	Execute Workflow Trigger	Receives input parameters from calling workflows
encodeParams	Code (JavaScript)	Encodes input data as Base64 JSON for secure SQL operations
upsertCreditRecord	PostgreSQL	Updates or inserts credit tracking records with complex business logic
logMicroActionHistory	PostgreSQL	Records micro-action history for audit and analysis
setOutput	Set	Formats and returns success message with key metrics

External Services & Credentials Required

• PostgreSQL Database: Requires connection credentials for the database containing creditTracking and microActionHistory tables
  • Database host, port, username, password
  • Database name with appropriate schema permissions

Environment Variables

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

Data Flow

Input Parameters

• phoneNumber (string): User's phone number (primary identifier)
• creditCustomersCount (number): Number of credit customers
• totalCreditBaseline (number): Baseline credit amount
• creditCustomerTypes (string): Types of credit customers
• creditTypicalDays (number): Typical credit duration in days
• weeklyRecoveryTarget (number): Target recovery amount per week
• targetCustomers (number): Target number of customers
• creditGivenToday (number): Credit amount given today
• creditRecoveredToday (number): Credit amount recovered today
• microActionType (string): Type of micro-action taken
• microActionScript (string): Script or details of micro-action
• microActionAttempted (boolean): Whether micro-action was attempted
• microActionOutcome (string): Result of micro-action
• amountRecovered (number): Amount recovered from action
• nextAction (string): Planned next action
• creditModuleStage (string): Current stage in credit module
• creditSkipReason (string): Reason for skipping actions
• weekNumber (number): Current week number

Output

• output (string): Formatted message containing:
  • Confirmation of record save
  • Total credit locked amount in KES
  • Weekly recovered amount in KES
  • Current credit module stage

Error Handling

• Input Sanitization: Phone numbers are cleaned to remove non-digit/plus characters
• SQL Injection Prevention: All parameters are Base64 encoded to prevent SQL injection
• Graceful History Logging: The micro-action history logging node is configured to continue on error, ensuring the main credit record is saved even if history logging fails
• Error Workflow: A global error workflow (ID: cuHEGQjAfvuGwIOD) is configured to handle any unhandled errors

Known Limitations

• Workflow is currently inactive ("active": false)
• Requires existing database schema with creditTracking and microActionHistory tables
• Phone number format is restricted to digits and plus signs only
• Micro-action history is only logged when microActionOutcome is provided

Related Workflows

This workflow is designed to be called by other workflows in the system. The caller policy is set to workflowsFromSameOwner, meaning only workflows owned by the same user can execute this workflow.

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Database Connection:
   • Set up PostgreSQL credentials in n8n
   • Ensure database contains required tables: creditTracking and microActionHistory
   • Verify database user has INSERT, UPDATE, and SELECT permissions
3. Database Schema: Ensure the following tables exist with appropriate columns:
   • creditTracking: Main credit tracking table with phone number as primary key
   • microActionHistory: Historical log of micro-actions
4. Test Connection: Verify database connectivity through the PostgreSQL nodes
5. Activate Workflow: Set the workflow to active status
6. Integration: Configure calling workflows to pass the required 18 input parameters
7. Error Handling: Verify the error workflow (cuHEGQjAfvuGwIOD) exists and is properly configured