persistStateTool - Francis

A utility workflow that updates user state information in the youth entrepreneurs database. This workflow accepts various user parameters and persists them to the PostgreSQL database, providing a centralized way to maintain user progress and configuration data.

Purpose

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

How It Works

1. Receives Input Parameters: The workflow accepts 15 different parameters including phone number, current stage, day tracking, routing decisions, and various business metrics
2. Updates Database: Executes a PostgreSQL UPDATE query that selectively updates only the provided fields using COALESCE to preserve existing values
3. Returns Confirmation: Outputs a formatted confirmation message showing the updated state information

Workflow 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 the following input parameters:

• phoneNumber (string) - User identifier
• currentStage (string) - Current program stage
• currentDay (number) - Day counter
• routingDecision (string) - Routing logic result
• consecutiveMissedDays (number) - Missed day tracking
• onboardingStatus (string) - Onboarding progress
• interactionFrequency (string) - Communication frequency
• preferredTime (string) - Preferred contact time
• selfInitiated (boolean) - Self-initiated flag
• monthlyFixedCosts (number) - Monthly cost data
• businessDaysPerMonth (number) - Business day calculation
• stockType (string) - Stock classification
• durableStockItems (string) - Durable stock data
• practiceBaselineAvg (number) - Practice baseline metric
• ceaEngagementStatus (string) - CEA engagement status

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives parameters from calling workflows
Postgres	updateUserState	Updates user state in the database
Set	setOutput	Formats confirmation message

External Services & Credentials Required

PostgreSQL Database

• Credential Name: PostgresOnSupabase
• Purpose: Updates the youthEntrepreneursReal table
• Required Permissions: UPDATE access on the target table

Environment Variables

No environment variables are used in this workflow.

Data Flow

Input

The workflow accepts up to 15 parameters, all optional except phoneNumber which is used as the WHERE clause identifier.

Processing

• Uses COALESCE in the SQL query to only update fields that have non-null values
• Calculates dailyFixedCost automatically when both monthlyFixedCosts and businessDaysPerMonth are provided
• Handles JSON data type conversion for durableStockItems

Output

Returns a formatted string containing: - Phone number - Updated current stage - Updated current day - Updated onboarding status

Example output: "State updated: +1234567890 | stage: practice | day: 15 | onboarding: completed"

Error Handling

The workflow uses basic PostgreSQL error handling. If the UPDATE query fails (e.g., due to invalid phone number or database connectivity issues), the workflow will stop execution and return an error.

Known Limitations

• No input validation on parameter values
• Assumes the phone number exists in the database (no INSERT capability)
• Limited error reporting - doesn't distinguish between different failure types
• No rollback mechanism for partial updates

Related Workflows

This is a utility workflow designed to be called by other workflows in the system. Check for workflows that execute this one by searching for references to "persistStateTool - Francis".

Setup Instructions

1. Import the Workflow

   • Copy the workflow JSON
   • Import into your n8n instance

2. Configure Database Credentials

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

3. Database Schema Requirements

   • Ensure the youthEntrepreneursReal table exists with all referenced columns
   • The table should have a phoneNumber column as the primary identifier
   • All other columns should match the parameter names in the workflow

4. Test the Workflow

   • Create a test workflow that calls this one
   • Provide sample parameters to verify database updates work correctly
   • Check that the output message formats correctly

5. Integration

   • Reference this workflow from other workflows using the "Execute Workflow" node
   • Pass the required parameters based on your business logic needs