V4 - changeNudgeStepTool

A utility workflow that updates the nudge step tracking for youth entrepreneurs in the SIFA coaching program database. This workflow provides a clean interface for other workflows to modify participant progress tracking without direct database access.

Purpose

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

This workflow serves as a database utility tool that allows other workflows to update the nudge step tracking for participants identified by their phone number. It provides a controlled way to modify participant progress data while ensuring data integrity through proper SQL handling.

How It Works

1. Receives Input: The workflow is triggered by another workflow with a phone number and nudge step value
2. Updates Database: Executes a SQL UPDATE query on the youth entrepreneurs table to set the last nudge step
3. Handles Empty Values: Converts empty nudge step strings to NULL in the database
4. Returns Confirmation: Sends back the updated phone number and nudge step value to confirm the operation

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Update Nudge Step]
    B --> C[Return Result]

    A --> |phoneNumber, nudge_step| B
    B --> |Updated record| C
    C --> |Success confirmation| D[End]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, not run independently. It expects two input parameters: - phoneNumber: The participant's phone number (identifier) - nudge_step: The nudge step value to set (can be empty string to clear)

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflow
PostgreSQL	Update Nudge Step	Updates the participant's nudge step in the database
Code	Return Result	Formats and returns the operation result

External Services & Credentials Required

• PostgreSQL Database: Requires access to the SIFA V4 development database
  • Credential: sifaV4Dev (PostgreSQL connection)
  • Database table: v4_youthEntrepreneurs
  • Required permissions: UPDATE and SELECT on the target table

Environment Variables

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

Data Flow

Input:

{
  "phoneNumber": "string",
  "nudge_step": "string"
}

Output:

{
  "success": true,
  "phoneNumber": "string",
  "nudge_step": "string|null"
}

Database Operation: - Updates last_nudge_step field in v4_youthEntrepreneurs table - Uses phone number as the identifier - Converts empty strings to NULL values - Returns the updated record for confirmation

Error Handling

The workflow has minimal error handling built-in: - SQL errors will cause the workflow to fail and stop execution - The RETURNING clause ensures the update was successful before proceeding - No explicit error catching or retry logic is implemented

Known Limitations

• No input validation on phone number format
• No verification that the phone number exists before attempting update
• Empty string handling is basic (only converts to NULL, doesn't validate meaningful values)
• No logging or audit trail of changes made
• Single record updates only (no batch processing)

Related Workflows

This workflow is designed to be called by other workflows in the SIFA coaching program system. Check for workflows that reference "changeNudgeStepTool" in their configurations.

Setup Instructions

1. Import the Workflow

   • Import the JSON into your n8n instance
   • The workflow will be created with ID ROszvaG1YttsP88O

2. Configure Database Credentials

   • Create a PostgreSQL credential named sifaV4Dev
   • Configure connection to your SIFA V4 database
   • Ensure the credential has UPDATE and SELECT permissions on v4_youthEntrepreneurs table

3. Verify Database Schema

   • Confirm the v4_youthEntrepreneurs table exists
   • Verify it has columns: phoneNumber, last_nudge_step
   • Test the credential connection

4. Activate the Workflow

   • Set the workflow to active status
   • Test by calling it from another workflow with sample data

5. Integration Testing

   • Create a test workflow that calls this one
   • Verify the database updates work correctly
   • Check that return values match expectations