V4 - triggerCeaAlertTool - Warenga

This workflow creates and manages alerts for Community Engagement Assistants (CEAs) in the SIFA youth entrepreneurship program. When triggered with youth information and alert details, it logs the alert to the database, identifies the appropriate CEA contact, and sends them a WhatsApp notification to ensure rapid response to youth needs.

Purpose

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

Based on the workflow implementation, this appears to be a critical safety and support system that: - Enables rapid escalation of youth concerns to their assigned Community Engagement Assistants - Handles various alert types including safety, GBV (Gender-Based Violence), distress, and emotional critical situations - Ensures proper documentation and tracking of all alerts through the database - Provides immediate WhatsApp notifications to CEAs for urgent response

How It Works

1. Alert Creation: The workflow receives alert information including phone number, alert type, severity, reason, and context
2. Database Operations: It simultaneously inserts the alert into the alerts table and looks up the appropriate CEA contact based on the youth's recruiter name
3. Notification Preparation: The system prepares a formatted WhatsApp message in both English and Swahili with all relevant alert details
4. Conditional Sending: If a CEA phone number is found, it sends the WhatsApp alert; otherwise, it logs the alert without notification
5. Status Tracking: Successfully sent notifications are marked in the database with delivery confirmation
6. Response: The workflow returns a structured response indicating success status and notification delivery

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Insert Alert & Lookup CEA]
    B --> C[Prepare Notification]
    C --> D{CEA Phone Available?}
    D -->|Yes| E[Send WhatsApp to CEA]
    D -->|No| F[Return Result]
    E --> G[Mark Notification Sent]
    G --> F

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows in the system. It accepts the following input parameters: - phoneNumber: Youth's phone number for identification - alert_type: Type of alert (safety, GBV, distress, emotional_critical, etc.) - severity: Alert severity level (critical, high, medium, low) - reason: Description of the alert reason - context: Additional JSON context data

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflows
Postgres	Insert Alert & Lookup CEA	Inserts alert record and retrieves CEA contact information
Code	Prepare Notification	Formats WhatsApp message and determines routing logic
If	CEA Phone Available?	Checks if CEA has a phone number for notification
Twilio	Send WhatsApp to CEA	Sends WhatsApp message to the CEA
Postgres	Mark Notification Sent	Updates alert record with notification status
Code	Return Result	Formats final response with execution results

External Services & Credentials Required

Twilio WhatsApp API

• Credential Name: Twilio WhatsApp kdp
• Purpose: Send WhatsApp notifications to CEAs
• Required: Twilio Account SID, Auth Token, and verified WhatsApp sender number

PostgreSQL Database

• Credential Name: sifaV4Dev
• Purpose: Store alerts and lookup CEA contacts
• Required: Database host, port, username, password, and database name

Environment Variables

No explicit environment variables are used in this workflow. All configuration is handled through n8n credentials and the workflow input parameters.

Data Flow

Input

{
  "phoneNumber": "string",
  "alert_type": "string",
  "severity": "string", 
  "reason": "string",
  "context": "object"
}

Output

{
  "success": "boolean",
  "alert_id": "number|null",
  "cea_notified": "boolean",
  "cea_name": "string|null",
  "phoneNumber": "string"
}

Database Tables Used

• v4_ceaalerts (write): Stores alert records with notification status
• v4_cea_contacts (read): Contains CEA contact information and active status
• v4_youthEntrepreneurs (read): Youth profile data for alert context

Error Handling

• Continue on Fail: The WhatsApp sending node is configured to continue execution even if message delivery fails
• Missing CEA: If no CEA is found for a youth's recruiter, the alert is still logged but no notification is sent
• No Phone Number: If CEA exists but has no phone number, the alert is logged with appropriate status
• Database Failures: If alert insertion fails, the workflow returns a failure response with diagnostic information

Known Limitations

• CEA lookup depends on exact matching between youth recruiter names and CEA contact records
• WhatsApp delivery confirmation is not tracked beyond Twilio's initial response
• No retry mechanism for failed WhatsApp deliveries
• Alert context is stored as JSON but not validated for structure
• No escalation path if CEA doesn't respond to alerts

Related Workflows

This workflow is designed to be called by other workflows in the SIFA system that need to trigger CEA alerts. Based on the naming convention, it's part of the V4 system architecture.

Setup Instructions

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

2. Configure Database Credential:

   • Create a PostgreSQL credential named sifaV4Dev
   • Configure connection to your SIFA database
   • Ensure access to tables: v4_ceaalerts, v4_cea_contacts, v4_youthEntrepreneurs

3. Configure Twilio Credential:

   • Create a Twilio API credential named Twilio WhatsApp kdp
   • Add your Twilio Account SID and Auth Token
   • Verify your WhatsApp sender number (+254203892316) is approved

4. Database Schema: Ensure the following tables exist with proper structure:

   -- v4_ceaalerts table should include columns:
   -- id, phonenumber, alert_type, severity, reason, context, 
   -- cea_phone, cea_name, status, notification_sent, notification_channel
   
   -- v4_cea_contacts table should include columns:
   -- name, phone, name_normalized, is_active
   
   -- v4_youthEntrepreneurs table should include columns:
   -- firstName, recruiterName, phoneNumber, businessOwned
   

5. Test Execution: Test the workflow by calling it from another workflow or using the manual trigger with sample data

6. Activate Workflow: Activate the workflow to make it available for execution by other workflows