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 is triggered by another workflow and receives 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 parameters using COALESCE to preserve existing values for any null inputs. The query also calculates derived fields like daily fixed costs.

3. Returns Confirmation: Formats and returns a confirmation message showing the updated user's phone number, current stage, day, and onboarding status.

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 15 input parameters related to user state and business metrics.

Nodes Used

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

External Services & Credentials Required

• PostgreSQL Database: Requires connection to Supabase PostgreSQL instance
  • Credential: PostgresOnSupabase (ID: Hw9XWerQ5RNHaVTk)
  • Access needed to youthEntrepreneursReal table with UPDATE permissions

Environment Variables

No environment variables are directly used in this workflow. Database connection details are managed through n8n credentials.

Data Flow

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 days counter
• onboardingStatus (string) - Onboarding progress
• interactionFrequency (string) - How often user interacts
• preferredTime (string) - User's preferred interaction time
• selfInitiated (boolean) - Whether interaction was user-initiated
• monthlyFixedCosts (number) - Monthly business costs
• businessDaysPerMonth (number) - Working days per month
• stockType (string) - Type of stock/inventory
• durableStockItems (string) - Durable inventory items (stored as JSON)
• practiceBaselineAvg (number) - Practice baseline average
• ceaEngagementStatus (string) - CEA engagement status

Output

• output (string) - Formatted confirmation message containing phone number, current stage, current day, and onboarding status

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 at the updateUserState node. No custom error handling or retry logic is implemented.

Known Limitations

• No validation of input parameters before database update
• No error handling for database connection failures
• Assumes the phone number exists in the database (no INSERT capability)
• Limited feedback on which specific fields were updated

Related Workflows

This is a utility workflow designed to be called by other workflows in the system. The calling workflows are not specified in the current configuration.

Setup Instructions

1. Import Workflow: Import the workflow JSON 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 permissions on the youthEntrepreneursReal table

3. Verify Database Schema: Ensure your database has the youthEntrepreneursReal table with the following columns:

   • phoneNumber, currentStage, currentDay, routingDecision
   • consecutiveMissedDays, onboardingStatus, interactionFrequency
   • preferredTime, selfInitiated, monthlyFixedCosts
   • businessDaysPerMonth, dailyFixedCost, stockType
   • durableStockItems, practiceBaselineAvg, ceaEngagementStatus

4. Test the Workflow: Execute from another workflow with sample parameters to verify database connectivity and update functionality

5. Integration: Call this workflow from other workflows using the "Execute Workflow" node, passing the required parameters as input