SIFA Quick Onboard Youth

This workflow provides a streamlined API endpoint for quickly onboarding youth entrepreneurs into the SIFA coaching program. It handles both new registrations and updates to existing profiles, automatically calculating business metrics and setting up participants for the coaching journey.

Purpose

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

How It Works

1. Receives Registration Data: A POST request is made to the webhook endpoint with youth registration information including personal details, business information, and coaching preferences.

2. Normalizes Phone Number: The phone number is standardized to Kenyan format (+254) to ensure consistency across the database.

3. Checks for Existing Youth: The system queries the database to see if someone with this phone number is already registered.

4. Processes Business Metrics: Calculates key business metrics including daily fixed costs, practice baseline averages from profit data, and determines interaction frequency based on preferred coaching times.

5. Updates or Creates Record: If the youth exists, their profile is updated with new information and status set to "active". If they're new, a complete profile is created.

6. Logs the Action: All onboarding activities are recorded in the change log for audit purposes, tracking who performed the action and what type of change occurred.

7. Returns Success Response: Confirms the onboarding with appropriate messaging based on whether it was an update or new registration.

Workflow Diagram

graph TD
    A[Webhook] --> B[Normalize Phone]
    B --> C[Check If Exists]
    C --> D[Compute Fields]
    D --> E{Youth Exists?}
    E -->|Yes| F[Update Youth]
    E -->|No| G[Insert Youth]
    F --> H[Log Update]
    G --> I[Log Insert]
    H --> J[Respond Update Success]
    I --> K[Respond Insert Success]

Trigger

Webhook: POST request to /sifa-quick-onboard

The webhook accepts form data or JSON with youth registration information and responds with CORS headers enabled for web application integration.

Nodes Used

Node Type	Purpose
Webhook	Receives POST requests with registration data
Code (Normalize Phone)	Standardizes phone numbers to +254 format
Postgres (Check If Exists)	Queries database for existing youth by phone number
Code (Compute Fields)	Calculates business metrics and processes registration data
If (Youth Exists?)	Routes to update or insert based on existing records
Postgres (Update Youth)	Updates existing youth profile with new information
Postgres (Insert Youth)	Creates new youth profile in database
Postgres (Log Update)	Records update action in change log
Postgres (Log Insert)	Records creation action in change log
Respond to Webhook (Update)	Returns success response for updates
Respond to Webhook (Insert)	Returns success response for new registrations

External Services & Credentials Required

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

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through n8n's credential system and direct node parameters.

Data Flow

Input (Webhook Body)

{
  "firstName": "string",
  "secondName": "string", 
  "phoneNumber": "string",
  "gender": "string",
  "age": "number",
  "county": "string",
  "ward": "string",
  "youthWard": "string",
  "businessOwned": "string",
  "recruiterName": "string",
  "preferredLanguage": "string",
  "channel": "string",
  "phoneType": "string",
  "monthlyFixedCosts": "number",
  "businessDaysPerMonth": "number",
  "stockType": "string",
  "durableStockItems": "array",
  "preferredTime": "string",
  "profitDay1": "number",
  "profitDay2": "number",
  "profitDay3": "number"
}

Output (Success Response)

{
  "status": "success",
  "action": "updated|created",
  "message": "Youth name has been onboarded successfully!"
}

Calculated Fields

• dailyFixedCost: Monthly fixed costs divided by business days per month
• practiceBaselineAvg: Average of three practice profit days
• interactionFrequency: Coaching frequency based on preferred time (daily_7pm, daily_3pm, daily_12pm, daily_5am)
• durableStockSql: JSON formatted durable stock items for database storage

Error Handling

The workflow uses alwaysOutputData: true on the existence check to handle cases where no matching youth is found. This prevents the workflow from failing and allows it to proceed with creating a new record.

No explicit error handling nodes are present, so database errors or validation failures will cause the workflow to stop and return an error response.

Known Limitations

• No input validation is performed on the webhook data
• Database errors are not gracefully handled with user-friendly messages
• No duplicate prevention beyond phone number matching
• Durable stock items processing assumes a specific JSON structure without validation

Related Workflows

No related workflows are specified in the current context.

Setup Instructions

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

2. Configure Database Credentials:

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

3. Database Schema Requirements:

   • youthEntrepreneursReal table with all fields referenced in the INSERT/UPDATE queries
   • changeLogs table for audit trail with fields: recruiterName, recruiterRole, changeType, youthFirstName, youthSecondName, youthPhoneNumber, details

4. Activate the Workflow: Enable the workflow to make the webhook endpoint available

5. Test the Endpoint: Send a POST request to the webhook URL with sample youth data

6. Configure CORS: The workflow includes CORS headers for web integration - adjust the Access-Control-Allow-Origin value if needed for your domain

The webhook will be available at: https://your-n8n-instance.com/webhook/sifa-quick-onboard