updateUserStatusTool

A utility workflow that updates the onboarding status of youth entrepreneurs in the database. This workflow validates user existence by phone number and safely updates their status, providing clear feedback on success or failure.

Purpose

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

This workflow serves as a data management tool for updating user onboarding statuses in what appears to be a youth entrepreneurship program. It ensures data integrity by validating user existence before making updates and provides clear feedback on the operation's success or failure.

How It Works

1. Input Validation: The workflow receives a phone number and new onboarding status from another workflow
2. User Verification: Queries the database to check if exactly one user exists with the provided phone number
3. Conditional Processing:
   • If user exists: Retrieves their ID and updates their onboarding status
   • If user doesn't exist or multiple users found: Returns an error message
4. Status Update: Uses an upsert operation to update the user's onboarding status in the database
5. Success Confirmation: 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[Insert or update rows in a table]
    F --> G[Edit Fields1 - Success]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows and 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
If	If	Validates that exactly one user exists
Postgres	Execute a SQL query1	Retrieves the user ID for the valid user
Postgres	Insert or update rows in a table	Updates the user's onboarding status
Set	Edit Fields	Returns error message for invalid users
Set	Edit Fields1	Returns success confirmation message

External Services & Credentials Required

• PostgreSQL Database: Requires connection to a Supabase PostgreSQL instance
  • Credential: PostgresOnSupabase (ID: Hw9XWerQ5RNHaVTk)
  • Access needed to the youthEntrepreneursReal table

Environment Variables

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

Data Flow

Input:

{
  "phoneNumber": "+254728309545",
  "onboardingStatus": "active"
}

Output (Success):

{
  "output": "User status for phone number +254728309545 has been updated"
}

Output (Error):

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

Error Handling

The workflow includes built-in error handling:

• User Validation: Checks if exactly one user exists with the provided phone number
• Conditional Branching: Routes to error path if user count is not equal to 1
• Error Messages: Provides clear feedback when updates cannot be performed
• Safe Updates: Uses upsert operation to prevent data conflicts

Known Limitations

• Only updates the onboardingStatus field; other user fields remain unchanged
• Requires exact phone number match (case-sensitive)
• No validation of the onboarding status value itself
• Error message is generic and doesn't specify the exact reason for failure (user not found vs. multiple users found)

Related Workflows

This workflow is designed to be called by other workflows in the system. Based on the naming convention and functionality, it likely integrates with user management or onboarding workflows.

Setup Instructions

1. Import the Workflow: Import this workflow into your n8n instance

2. Configure Database Credentials:

   • Create a PostgreSQL credential named PostgresOnSupabase
   • Configure connection to your Supabase instance
   • Ensure access to the youthEntrepreneursReal table

3. Database Schema: Ensure your database has the youthEntrepreneursReal table with at least these columns:

   • id (number, primary key)
   • phoneNumber (string)
   • onboardingStatus (string)

4. Test the Workflow:

   • Use the pinned test data or create your own
   • Verify database connectivity
   • Test both success and error scenarios

5. Integration: Call this workflow from other workflows using the Execute Workflow node with the required parameters:

   • phoneNumber: Valid phone number string
   • onboardingStatus: Desired status value

6. Permissions: Ensure the database user has SELECT and UPDATE permissions on the youthEntrepreneursReal table