SIFA Update Phone

This workflow provides a secure API endpoint for updating youth entrepreneur phone numbers in the SIFA system. It validates the new phone number isn't already in use, performs the update with proper normalization, and maintains an audit trail of all changes.

Purpose

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

This workflow serves as a data management API for updating phone number records in what appears to be a youth entrepreneur database system. It ensures data integrity by preventing duplicate phone numbers and maintains accountability through change logging.

How It Works

1. Receive Update Request: A POST request comes in with old phone number, new phone number, and recruiter information
2. Normalize Phone Numbers: Both phone numbers are standardized to international format (+254 for Kenya)
3. Check for Conflicts: Verify the new phone number isn't already registered to another youth
4. Prevent Duplicates: If the new number exists, return an error immediately
5. Update Record: Change the phone number for the youth with the old number
6. Verify Success: Check if any record was actually updated
7. Log the Change: Record the phone number change in an audit log with recruiter details
8. Confirm Success: Return success message with the youth's name

Workflow Diagram

graph TD
    A[Webhook] --> B[Normalize Phones]
    B --> C[Check New Phone Exists]
    C --> D{New Phone Taken?}
    D -->|Yes| E[Respond Conflict]
    D -->|No| F[Update Phone Number]
    F --> G[Check Update Result]
    G --> H{Was Updated?}
    H -->|Yes| I[Log Phone Change]
    H -->|No| J[Respond Not Found]
    I --> K[Respond Updated]

Trigger

Webhook: POST request to /sifa-update-phone

Expected payload:

{
  "oldPhoneNumber": "0712345678",
  "newPhoneNumber": "0787654321",
  "recruiterName": "John Doe"
}

Nodes Used

Node Type	Node Name	Purpose
Webhook	Webhook	Receives HTTP POST requests with phone update data
Code	Normalize Phones	Standardizes phone numbers to international format (+254)
Postgres	Check New Phone Exists	Queries database to see if new phone number is already registered
If	New Phone Taken?	Branches workflow based on whether new number exists
Respond to Webhook	Respond Conflict	Returns error if new phone number is already taken
Postgres	Update Phone Number	Updates the phone number in the youth database
Code	Check Update Result	Processes update result to determine if any record was changed
If	Was Updated?	Branches based on whether the update was successful
Postgres	Log Phone Change	Records the change in the audit log table
Respond to Webhook	Respond Updated	Returns success message with youth's name
Respond to Webhook	Respond Not Found	Returns error if no youth found with old phone number

External Services & Credentials Required

• PostgreSQL Database: Stores youth entrepreneur records and change logs
  • Credential ID: EJPqF6MDH1ZwAzyv (named "Postgres account")
  • Required tables: youthEntrepreneursReal, changeLogs

Environment Variables

No environment variables are used in this workflow. All configuration is handled through node parameters and database credentials.

Data Flow

Input (via webhook):

{
  "oldPhoneNumber": "string",
  "newPhoneNumber": "string", 
  "recruiterName": "string"
}

Output (success):

{
  "status": "success",
  "firstName": "string",
  "message": "Phone number successfully updated for [firstName]"
}

Output (conflict error):

{
  "status": "error",
  "message": "The new phone number [number] is already registered to another youth."
}

Output (not found error):

{
  "status": "error",
  "message": "No youth found with the old phone number. Please search again."
}

Error Handling

The workflow includes comprehensive error handling:

1. Duplicate Phone Number: If the new phone number already exists in the database, the workflow stops and returns a conflict error without making any changes.

2. Youth Not Found: If no youth is found with the provided old phone number, the workflow returns a "not found" error.

3. CORS Headers: All responses include Access-Control-Allow-Origin: * headers for cross-origin requests.

4. Phone Number Normalization: Handles various phone number formats by converting them to international format before processing.

Known Limitations

• Phone number normalization is specifically designed for Kenyan numbers (+254)
• No validation for phone number format beyond basic normalization
• No authentication or authorization checks on the webhook endpoint
• No rate limiting implemented

Related Workflows

No related workflows identified from the provided information.

Setup Instructions

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

2. Configure PostgreSQL Credential:

   • Create a PostgreSQL credential named "Postgres account"
   • Ensure connection to database with tables: youthEntrepreneursReal and changeLogs

3. Database Schema Requirements:

   -- youthEntrepreneursReal table needs:
   -- id, firstName, secondName, phoneNumber columns
   
   -- changeLogs table needs:
   -- recruiterName, recruiterRole, changeType, youthFirstName, youthSecondName, oldPhoneNumber, newPhoneNumber columns
   

4. Activate the Workflow: Enable the workflow to start the webhook listener

5. Test the Endpoint: Send a POST request to the webhook URL with the required payload structure

6. Verify CORS: Ensure your frontend application can make requests to the webhook endpoint (CORS is enabled for all origins)