V4 - updateUserStatusTool

A utility workflow that updates the onboarding status of youth entrepreneurs in the database and maintains an audit log of all status changes.

Purpose

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

This workflow serves as a centralized tool for updating user onboarding statuses in the youth entrepreneurs database. It validates that users exist before making updates and maintains a complete audit trail of status changes for compliance and tracking purposes.

How It Works

1. Receives Input: The workflow accepts a phone number and new onboarding status from another workflow
2. Validates User Exists: Checks if exactly one user exists with the provided phone number
3. Handles Invalid Users: If the user doesn't exist or multiple records are found, returns an error message
4. Logs Status Change: For valid users, records the previous and new status in an audit log
5. Updates Status: Updates the user's onboarding status in the main database
6. Confirms Success: Returns a confirmation 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 provided phone number
If	If	Validates that exactly one user exists
Set	Edit Fields	Returns error message for invalid users
Postgres	Execute a SQL query1	Retrieves the user ID for the phone number
Postgres	Log Status Change	Records status change in 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 trail)

Environment Variables

No specific environment variables are required beyond the standard n8n database connection configuration.

Data Flow

Input:

{
  "phoneNumber": "string",
  "onboardingStatus": "string"
}

Output (Success):

{
  "output": "User status for phone number [phoneNumber] has been updated"
}

Output (Error):

{
  "output": "Error updating user status"
}

Error Handling

The workflow includes built-in error handling:

• User Validation: If the phone number doesn't match exactly one user record, the workflow returns an error message instead of attempting to update
• Error Workflow: The workflow is configured to use error workflow cuHEGQjAfvuGwIOD for handling unexpected failures
• Graceful Failure: Invalid requests result in a controlled error response rather than workflow failure

Known Limitations

• The workflow only accepts phone numbers as user identifiers
• Updates are limited to the onboardingStatus field only
• No validation is performed on the new status value
• The workflow assumes the calling workflow has already validated the input parameters

Related Workflows

This workflow is designed to be called by other workflows in the system. Check for workflows that reference this workflow ID (7vM1qop37b5jNHCk) in their Execute Workflow nodes.

Setup Instructions

1. Import the Workflow: Import the JSON into your n8n instance
2. Configure Database Connection: Set up PostgreSQL credentials with access to:
   • youthEntrepreneursReal table
   • userStatusLog table
3. Verify Table Schema: Ensure the following columns exist:
   • youthEntrepreneursReal: id, phoneNumber, onboardingStatus
   • userStatusLog: phoneNumber, previousStatus, newStatus
4. Set Error Workflow: Configure error workflow cuHEGQjAfvuGwIOD or update the reference
5. Test the Workflow: Execute with sample data to verify database connectivity
6. Configure Calling Workflows: Update other workflows to call this workflow with the required parameters

The workflow is currently inactive and should be activated once configuration is complete.