V4 - updateUserStatusTool

A utility workflow that updates the onboarding status of users in the youth entrepreneurs database. This workflow validates user existence, logs status changes for audit purposes, and provides clear success or error feedback.

Purpose

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

How It Works

1. Receives Input: The workflow accepts a phone number and new onboarding status from another workflow
2. Validates User: Checks if exactly one user exists with the provided phone number in the database
3. Branches on Validation:
   • If user exists: Proceeds to update the status
   • If user doesn't exist or multiple users found: Returns an error message
4. Retrieves User ID: Fetches the user's database ID using their phone number
5. Logs Status Change: Records the status change in an audit log before making the update
6. Updates Status: Updates the user's onboarding status in the main table
7. Returns Confirmation: Provides a success message with the updated phone number

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Execute a SQL query]
    B --> C[If]
    C -->|User Found| D[Execute a SQL query1]
    C -->|User Not Found| E[Edit Fields - Error]
    D --> F[Log Status Change]
    D --> G[Insert or update rows in a table]
    G --> H[Edit Fields1 - Success]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, not triggered directly. It expects two input parameters: - phoneNumber: The phone number of the user to update - onboardingStatus: The new status to set for the user

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflow
Postgres	Execute a SQL query	Counts users with the given phone number for validation
If	If	Validates that exactly one user exists with the phone number
Set	Edit Fields	Returns error message when user validation fails
Postgres	Execute a SQL query1	Retrieves the user's ID for the update operation
Postgres	Log Status Change	Records the status change in the audit log
Postgres	Insert or update rows in a table	Updates the user's onboarding status
Set	Edit Fields1	Returns success confirmation message

External Services & Credentials Required

• PostgreSQL Database: Requires connection credentials for the database containing:
  • youthEntrepreneursReal table (main user data)
  • userStatusLog table (audit log for status changes)

Environment Variables

No specific environment variables are configured in this workflow. Database connection details are managed through n8n's credential system.

Data Flow

Input: - phoneNumber (string): Phone number of the user to update - onboardingStatus (string): New onboarding status to set

Output: - Success: "User status for phone number {phoneNumber} has been updated" - Error: "Error updating user status"

Error Handling

The workflow includes validation and error handling:

• User Validation: If the phone number doesn't match exactly one user in the database, the workflow returns an error message instead of attempting an update
• Error Workflow: The workflow is configured with an error workflow (ID: cuHEGQjAfvuGwIOD) to handle any unexpected failures
• Caller Policy: Restricted to workflows from the same owner for security

Known Limitations

• The workflow only updates the onboardingStatus field; other user fields remain unchanged
• No validation is performed on the new status value itself
• The error message is generic and doesn't specify whether the issue was no user found or multiple users found

Related Workflows

• Error handling workflow (ID: cuHEGQjAfvuGwIOD)

Setup Instructions

1. Import the Workflow: Import the JSON into your n8n instance

2. Configure Database Credentials:

   • Set up PostgreSQL credentials in n8n
   • Ensure access to tables: youthEntrepreneursReal and userStatusLog

3. Database Schema Requirements:

   • youthEntrepreneursReal table must have columns: id, phoneNumber, onboardingStatus
   • userStatusLog table must have columns: phoneNumber, previousStatus, newStatus

4. Test the Workflow:

   • Call from another workflow with valid phoneNumber and onboardingStatus parameters
   • Verify the status update in the database
   • Check that the change is logged in userStatusLog

5. Error Workflow (Optional):

   • Configure the referenced error workflow (ID: cuHEGQjAfvuGwIOD) if not already present
   • Or remove the error workflow setting if not needed

The workflow is currently inactive and needs to be activated after configuration is complete.