Centralized_Reporting_Backend/src/integrations/n8n

n8n Integration Module

Overview

This module provides a unified interface to call n8n workflows for fetching data from multiple providers (Zoho, Salesforce, QuickBooks, etc.) with minimal backend code.

Directory Structure

n8n/
├── client.js      # n8n webhook client
├── handler.js     # Handler for processing requests
├── mapper.js      # Module name mappings and validation
└── README.md      # This file

Files

client.js

• N8nClient class
• Handles HTTP communication with n8n webhook
• Methods:
  • callWebhook(payload) - Generic webhook caller
  • fetchZohoData(service, module, accessToken, query)
  • fetchSalesforceData(service, module, accessToken, instanceUrl, query)
  • fetchIntuitData(service, module, accessToken, query)

handler.js

• N8nHandler class
• Manages token retrieval and request orchestration
• Methods:
  • getServiceTokens(serviceName) - Gets decrypted tokens from DB
  • fetchZohoData(service, module, options)
  • fetchSalesforceData(service, module, options)
  • normalizeResponse(response) - Standardizes responses

mapper.js

• N8nMapper class (static methods)
• Validates and maps module names
• Methods:
  • mapZohoModule(service, module)
  • mapSalesforceModule(service, module)
  • getSupportedModules(provider, service)
  • isSupported(provider, service, module)

Usage Example

const N8nHandler = require('./integrations/n8n/handler');

// Create handler for a user
const handler = new N8nHandler(userId);

// Fetch Zoho CRM Leads
const leads = await handler.fetchZohoData('crm', 'leads', {
  limit: 100,
  page: 1
});

// Fetch Salesforce Accounts
const accounts = await handler.fetchSalesforceData('crm', 'accounts', {
  limit: 50,
  offset: 0
});

Configuration

Set these environment variables:

N8N_WEBHOOK_URL=http://localhost:5678
N8N_WEBHOOK_ID=04e677f5-ec57-4772-bf12-96f2610d4b9c

Webhook Payload Format

The client sends this payload to n8n:

{
  "body": {
    "provider": "zoho",
    "service": "crm",
    "module": "leads",
    "acces_token": "1000.xxxxx",
    "instance_url": null
  },
  "query": {
    "per_page": 200,
    "page": 1
  }
}

Response Format

n8n returns data which is normalized to:

{
  "success": true,
  "data": [...],
  "count": 10,
  "metadata": {}
}

Error Handling

All errors are logged and thrown with descriptive messages:

• Token not found
• Unsupported provider/service/module
• n8n webhook timeout
• Provider API errors

Extending

To add a new provider:

1. Update n8n workflow with new provider switch
2. Add modules to mapper.js:

   static getSupportedModules(provider, service) {
     const modules = {
       ...existing,
       newprovider: {
         service1: ['module1', 'module2']
       }
     };
   }
   

3. Add fetch method to client.js (optional)
4. No other changes needed!

Testing

// Test with a user who has authenticated
const handler = new N8nHandler('user-uuid-here');

// Test Zoho
const zohoData = await handler.fetchZohoData('crm', 'leads', { limit: 10 });
console.log('Zoho Leads:', zohoData.count);

// Test Salesforce
const sfData = await handler.fetchSalesforceData('crm', 'accounts', { limit: 10 });
console.log('SF Accounts:', sfData.count);

Dependencies

• axios - HTTP client
• ../../utils/logger - Logging utility
• ../../utils/crypto - Token encryption/decryption
• ../../data/repositories/userAuthTokenRepository - Token storage