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 a 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.

This workflow serves as a state persistence service for youth entrepreneur users, allowing other workflows to update user information such as current stage, progress tracking, business metrics, and engagement status in a consistent manner.

How It Works

1. Receives Input Parameters: The workflow accepts 15 different parameters including phone number, current stage, progress metrics, and business data
2. Updates Database: Executes a PostgreSQL UPDATE query that only modifies fields where new values are provided (using COALESCE to preserve existing values)
3. Calculates Derived Fields: Automatically computes daily fixed costs from monthly costs and business days
4. Returns Confirmation: Provides a formatted output message confirming the state update with key user information

Workflow Diagram

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

    B -.-> D[(PostgreSQL Database<br/>youthEntrepreneursReal)]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, not triggered directly by external events. It accepts the following input parameters:

• phoneNumber (string) - User identifier
• currentStage (string) - Current program stage
• currentDay (number) - Progress day counter
• routingDecision (string) - Routing logic decision
• consecutiveMissedDays (number) - Missed days 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 stock items data
• 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 the database using parameterized query
Set	setOutput	Formats confirmation message with updated user information

External Services & Credentials Required

PostgreSQL Database

• Credential Name: PostgresOnSupabase
• Purpose: Connects to the youth entrepreneurs database to update user state
• Required Permissions: UPDATE access on youthEntrepreneursReal table

Environment Variables

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

Data Flow

Input

The workflow accepts up to 15 optional parameters, with phoneNumber being the key identifier for locating the user record.

Processing

• Uses COALESCE in SQL to only update fields where new values are provided
• Automatically calculates dailyFixedCost 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: - Database connection failures will stop execution - Invalid data types will cause SQL errors - Missing phone numbers will result in no rows updated

No custom error handling or retry logic is implemented.

Known Limitations

• No validation of input parameters before database update
• No rollback mechanism if partial updates fail
• Limited error reporting - only basic SQL errors are surfaced
• Assumes phone number exists in database (no upsert functionality)

Related Workflows

This workflow is designed to be called by other workflows in the youth entrepreneur program system. No specific related workflows are identified in the current documentation.

Setup Instructions

1. Import Workflow

   • Import the workflow JSON into your n8n instance
   • The workflow will be inactive by default

2. Configure Database Credentials

   • Create a PostgreSQL credential named PostgresOnSupabase
   • Configure connection to your youth entrepreneurs database
   • Ensure the credential has UPDATE permissions on youthEntrepreneursReal table

3. Verify Database Schema

   • Ensure the youthEntrepreneursReal table exists with all required columns
   • Verify column data types match the workflow expectations

4. Test the Workflow

   • Create a test workflow that calls this one with sample data
   • Verify database updates are working correctly
   • Check output formatting

5. Activate and Use

   • Activate the workflow once testing is complete
   • Reference this workflow ID in other workflows that need to persist user state