Skip to content

persistStateTool - Francis

A utility workflow that updates user state information in the youth entrepreneurs database. This workflow serves as a centralized state management tool, allowing other workflows to persist changes to user progress, preferences, and business metrics in a single database operation.

Purpose

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

How It Works

This workflow operates as a simple three-step process:

  1. Receives Input Parameters - Accepts up to 15 different user state parameters including phone number, current stage, day progress, routing decisions, and business metrics
  2. Updates Database - Executes a PostgreSQL UPDATE query that selectively updates only the provided fields, leaving existing data unchanged for any null parameters
  3. Returns Confirmation - Outputs a formatted confirmation message showing the key updated fields for verification

The workflow uses PostgreSQL's COALESCE function to ensure that only non-null input values overwrite existing database fields, making it safe to call with partial updates.

Mermaid Diagram

graph TD
    A[When Executed by Another Workflow] --> B[updateUserState]
    B --> C[setOutput]

Trigger

Execute Workflow Trigger - This workflow is designed to be called by other workflows, not triggered directly. It accepts 15 input parameters:

  • phoneNumber (string) - User identifier
  • currentStage (string) - Current program stage
  • currentDay (number) - Day in current stage
  • routingDecision (string) - Routing logic decision
  • consecutiveMissedDays (number) - Missed day counter
  • onboardingStatus (string) - Onboarding progress
  • interactionFrequency (string) - Communication frequency
  • preferredTime (string) - Preferred contact time
  • selfInitiated (boolean) - Self-initiated flag
  • monthlyFixedCosts (number) - Monthly business costs
  • businessDaysPerMonth (number) - Working days per month
  • stockType (string) - Type of stock/inventory
  • durableStockItems (string) - Durable inventory items
  • practiceBaselineAvg (number) - Practice baseline average
  • ceaEngagementStatus (string) - CEA engagement status

Nodes Used

Node Type Node Name Purpose
Execute Workflow Trigger When Executed by Another Workflow Receives input parameters from calling workflows
PostgreSQL updateUserState Updates user state in youthEntrepreneursReal table
Set setOutput Formats confirmation message with updated values

External Services & Credentials Required

  • PostgreSQL Database (Supabase)
    • Credential: PostgresOnSupabase
    • Access to youthEntrepreneursReal table with UPDATE permissions

Environment Variables

No environment variables are used in this workflow. All configuration is handled through the PostgreSQL credential.

Data Flow

Input: - Up to 15 optional parameters representing various user state fields - phoneNumber is required as the record identifier

Processing: - Constructs a PostgreSQL UPDATE query using COALESCE to preserve existing values - Calculates dailyFixedCost automatically when both monthlyFixedCosts and businessDaysPerMonth are provided - Handles JSON data type conversion for durableStockItems

Output: - Formatted string: "State updated: {phoneNumber} | stage: {currentStage} | day: {currentDay} | onboarding: {onboardingStatus}" - Database returns updated record fields for verification

Error Handling

The workflow relies on PostgreSQL's built-in error handling: - Database constraint violations will cause the workflow to fail - Invalid data type conversions will be caught by PostgreSQL - Missing phoneNumber or non-existent records will result in zero rows updated

No custom error handling nodes are implemented in this workflow.

Known Limitations

  • Requires the calling workflow to provide a valid phoneNumber that exists in the database
  • No validation of input parameter formats or ranges
  • No rollback mechanism if partial updates fail
  • Limited to updating a single user record per execution

This workflow is designed to be called by other workflows in the system. Check for workflows that use "Execute Workflow" nodes targeting this workflow name.

Setup Instructions

  1. Import the Workflow

    • Copy the workflow JSON and import into your n8n instance

  2. Configure Database Credential

    • Create a PostgreSQL credential named PostgresOnSupabase
    • Configure connection to your Supabase/PostgreSQL instance
    • Ensure the credential has UPDATE access to the youthEntrepreneursReal table

  3. Verify Database Schema

    • Confirm the youthEntrepreneursReal table exists with all referenced columns
    • Ensure data types match the workflow expectations (text, int, numeric, boolean, jsonb)

  4. Test the Workflow

    • Create a test workflow that calls this one with sample parameters
    • Verify database updates are applied correctly
    • Check that COALESCE logic preserves existing values for null inputs

  5. Integration

    • Reference this workflow by name in other workflows using "Execute Workflow" nodes
    • Pass required parameters as workflow inputs