Update User Status Tool

This workflow provides a centralized service for updating user onboarding status in the youth entrepreneurs database. It validates user existence, updates their status, logs the change for audit purposes, and returns appropriate success or error messages to calling workflows.

Purpose

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

This workflow serves as a utility tool for other workflows that need to update user onboarding status. It ensures data integrity by validating user existence before making changes and maintains an audit trail of all status updates through comprehensive logging.

How It Works

1. Receive Input: The workflow accepts a phone number and new onboarding status from another workflow
2. Validate User: Checks if exactly one user exists with the provided phone number in the database
3. Branch Logic: If user exists, proceeds with update; if not, returns an error message
4. Get User ID: Retrieves the user's database ID using their phone number
5. Log Change: Records the status change in the audit log before making the update
6. Update Status: Updates the user's onboarding status in the main table
7. Return Result: Sends back a success message with the phone number, or an error message if the user wasn't found

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 user's phone number to identify them - 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 workflows
Postgres	Execute a SQL query	Counts users with the given phone number for validation
If	If	Checks if exactly one user exists (count = 1)
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 Fields	Returns error message when user is not found
Set	Edit Fields1	Returns success message after successful update

External Services & Credentials Required

• PostgreSQL Database: Requires connection to the main database containing user records
  • Credential: "Postgres account" (ID: EJPqF6MDH1ZwAzyv)
  • Tables accessed:
    • youthEntrepreneursReal: Main user table
    • userStatusLog: Audit log table

Environment Variables

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

Data Flow

Input:

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

Success Output:

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

Error Output:

{
  "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 in the database, the workflow returns an error message instead of attempting the update
• Database Integrity: Uses the user's ID for updates to ensure accuracy and prevent accidental modifications

Known Limitations

• Only updates users that exist exactly once in the database (prevents updates when there are duplicate phone numbers)
• No validation of the new status value - any string can be set as the onboarding status
• Error messages are generic and don't specify the exact reason for failure (e.g., user not found vs. multiple users found)

Related Workflows

This workflow is designed to be called by other workflows that need to update user status. Check for workflows that use the "Execute Workflow" node pointing to this workflow.

Setup Instructions

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

2. Configure Database Credentials:

   • Set up a PostgreSQL credential named "Postgres account"
   • Ensure it has read/write access to the youthEntrepreneursReal and userStatusLog tables

3. Database Schema Requirements:

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

4. Test the Workflow:

   • Use the pinned test data or create your own test execution
   • Verify the workflow can connect to your database
   • Test both success and error scenarios

5. Integration:

   • Call this workflow from other workflows using the "Execute Workflow" node
   • Pass the required phoneNumber and onboardingStatus parameters

6. Activate: Enable the workflow so it can be called by other workflows