V4 - logHelpIssueTool

A utility workflow that logs user help requests to a PostgreSQL database and returns a unique reference ID for tracking purposes.

Purpose

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

This workflow serves as a centralized logging mechanism for help requests across different channels. When users encounter issues or need assistance, other workflows can call this tool to create a permanent record in the database with all relevant context information.

How It Works

1. Receives Help Request Data: Another workflow triggers this tool with user information and issue details
2. Stores in Database: The request is inserted into the v4_helprequests table with a timestamp
3. Returns Reference ID: A unique reference ID is generated and returned for tracking the request

The workflow is designed to be called by other workflows rather than running independently, making it a reusable component for help request logging across the system.

Mermaid Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Insert Help Request]
    B --> C[Return Result]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows, not triggered directly by external events.

Required Input Parameters:

• phoneNumber: User's phone number
• channel: Communication channel (e.g., WhatsApp, SMS, web)
• issue_description: Description of the user's issue or help request
• session_snapshot: JSON object containing session context and state information

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflows
PostgreSQL	Insert Help Request	Stores the help request data in the database
Code	Return Result	Formats and returns the success response with reference ID

External Services & Credentials Required

PostgreSQL Database

• Credential Name: sifaV4Dev
• Required Permissions: INSERT access to v4_helprequests table
• Database Schema: Must contain v4_helprequests table with columns:
  • phonenumber (text)
  • channel (text)
  • issue_description (text)
  • session_snapshot (jsonb)
  • created_at (timestamp)
  • id (auto-incrementing primary key)

Environment Variables

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

Data Flow

Input

{
  "phoneNumber": "string",
  "channel": "string", 
  "issue_description": "string",
  "session_snapshot": "object"
}

Output

{
  "success": true,
  "reference_id": "HELP-{id}"
}

The reference ID follows the format HELP- followed by the database-generated ID number.

Error Handling

This workflow has minimal error handling: - Database connection errors will cause the workflow to fail - Invalid JSON in session_snapshot will cause the PostgreSQL insert to fail - If the database insert fails, no reference ID will be returned

The calling workflow should implement appropriate error handling for failed executions.

Known Limitations

• No input validation on required fields
• No duplicate request detection
• Database errors are not gracefully handled
• Reference ID generation assumes successful database insert

Related Workflows

This workflow is designed to be called by other workflows that handle user interactions and need to log help requests. Check for workflows that use the "Execute Workflow" node targeting this workflow.

Setup Instructions

1. Import the Workflow

   • Copy the workflow JSON
   • Import into your n8n instance

2. Configure Database Credentials

   • Create a PostgreSQL credential named sifaV4Dev
   • Ensure connection to database with v4_helprequests table

3. Create Database Table (if not exists)

   CREATE TABLE v4_helprequests (
     id SERIAL PRIMARY KEY,
     phonenumber TEXT,
     channel TEXT,
     issue_description TEXT,
     session_snapshot JSONB,
     created_at TIMESTAMP DEFAULT NOW()
   );
   

4. Test the Workflow

   • Use the "Execute Workflow" node from another workflow
   • Pass test data with all required parameters
   • Verify database insert and reference ID return

5. Activate the Workflow

   • Set the workflow to active status
   • Ensure it's available for other workflows to call