laxmanhalaki/Centralized_Reporting_Backend

yashwin-foxy c8eedf73ad n8n flow integrated fro sales force integration

2025-10-10 12:10:33 +05:30

14 KiB

Raw Blame History

🚀 n8n Integration - Complete Implementation

📋 What's Been Created

A complete low-code n8n integration that allows you to fetch data from multiple providers (Zoho, Salesforce, QuickBooks) through a single unified webhook.

✅ Created Files

src/
├── integrations/
│   └── n8n/
│       ├── client.js          # n8n webhook HTTP client
│       ├── handler.js          # Request orchestration & token management
│       ├── mapper.js           # Module validation & mapping
│       └── README.md           # Module documentation
│
├── services/
│   └── n8nService.js          # Business logic layer
│
├── api/
│   ├── controllers/
│   │   └── n8nController.js   # HTTP request handlers
│   └── routes/
│       └── n8nRoutes.js        # API route definitions
│
└── app.js                      # Updated with n8n routes

docs/
├── N8N_INTEGRATION.md          # Complete integration guide
└── N8N_SETUP_EXAMPLE.md        # Quick start examples

README_N8N.md                   # This file

🏗️ Architecture

┌─────────────┐
│   Client    │
│  (Frontend) │
└──────┬──────┘
       │ HTTP Request
       ↓
┌─────────────────────────────────────────────┐
│           Backend API                        │
│  ┌────────────────────────────────────┐    │
│  │  GET /api/v1/n8n/zoho/crm/leads    │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      n8nController                  │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      n8nService                     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      N8nHandler                     │    │
│  │   • Gets user's access token       │    │
│  │   • Decrypts token                 │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      N8nClient                      │    │
│  │   • Calls n8n webhook              │    │
│  └──────────────┬─────────────────────┘    │
└─────────────────┼──────────────────────────┘
                  │
                  │ HTTP POST
                  ↓
┌─────────────────────────────────────────────┐
│              n8n Workflow                    │
│  ┌────────────────────────────────────┐    │
│  │  Webhook (receives request)         │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Provider Switch (zoho/salesforce)  │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Service Switch (crm/books/etc)     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Module Switch (leads/contacts)     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  HTTP Request to Provider API       │    │
│  └──────────────┬─────────────────────┘    │
└─────────────────┼──────────────────────────┘
                  │
                  ↓
          ┌───────────────┐
          │   Zoho API    │
          │ Salesforce API│
          │ QuickBooks API│
          └───────────────┘

🚀 Quick Start

Step 1: Environment Setup

Add to .env:

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

Step 2: Import n8n Workflow

Open n8n at http://localhost:5678
Import My_workflow_3 (1).json
Activate the workflow

Step 3: User Authentication

Users must authenticate with providers first:

GET /api/v1/users/oauth/callback?
    authorization_code=ABC123&
    user_uuid=550e8400-e29b-41d4-a716-446655440000&
    service_name=zoho

Step 4: Fetch Data

GET /api/v1/n8n/zoho/crm/leads?limit=100
Authorization: Bearer <jwt_token>

📡 API Endpoints

Get Supported Providers

GET /api/v1/n8n/providers

Generic Endpoint (Any Provider)

GET /api/v1/n8n/data/:provider/:service/:module

Examples:

GET /api/v1/n8n/data/zoho/crm/leads
GET /api/v1/n8n/data/salesforce/crm/accounts
GET /api/v1/n8n/data/zoho/people/employees

Zoho Shorthand

GET /api/v1/n8n/zoho/:service/:module

Examples:

GET /api/v1/n8n/zoho/crm/leads
GET /api/v1/n8n/zoho/books/invoices
GET /api/v1/n8n/zoho/people/employees
GET /api/v1/n8n/zoho/projects/portals

Salesforce Shorthand

GET /api/v1/n8n/salesforce/:service/:module

Examples:

GET /api/v1/n8n/salesforce/crm/leads
GET /api/v1/n8n/salesforce/crm/accounts
GET /api/v1/n8n/salesforce/crm/opportunities

🎯 Supported Providers & Modules

Zoho

CRM: leads, contacts, accounts, deals, tasks, invoices, purchase_orders, sales_orders

Books: organizations, contacts, customers, vendors, accounts, invoices, bills, expenses, purchase_orders, sales_orders

People: employees, departments, timesheets, leaves, attendence, attendence_entries, attendence_report, leave_tracker, leaves_data, goals_data, performance_data

Projects: portals, projects, tasks, all_tasks, tasklists, all_tasklists, issues, phases

Salesforce

CRM: leads, accounts, tasks, opportunities, events, reports

📝 Usage Examples

JavaScript/Node.js

const axios = require('axios');

const API_URL = 'http://localhost:3000/api/v1';
const token = 'your_jwt_token';

// Fetch Zoho Leads
async function getZohoLeads() {
  const response = await axios.get(
    `${API_URL}/n8n/zoho/crm/leads?limit=100`,
    { headers: { Authorization: `Bearer ${token}` }}
  );
  return response.data;
}

// Fetch Salesforce Accounts
async function getSalesforceAccounts() {
  const response = await axios.get(
    `${API_URL}/n8n/salesforce/crm/accounts?limit=50`,
    { headers: { Authorization: `Bearer ${token}` }}
  );
  return response.data;
}

// Fetch multiple sources
async function getDashboardData() {
  const [leads, employees, opportunities] = await Promise.all([
    axios.get(`${API_URL}/n8n/zoho/crm/leads`, 
      { headers: { Authorization: `Bearer ${token}` }}),
    axios.get(`${API_URL}/n8n/zoho/people/employees`, 
      { headers: { Authorization: `Bearer ${token}` }}),
    axios.get(`${API_URL}/n8n/salesforce/crm/opportunities`, 
      { headers: { Authorization: `Bearer ${token}` }})
  ]);

  return {
    leads: leads.data,
    employees: employees.data,
    opportunities: opportunities.data
  };
}

cURL

# Get JWT token
TOKEN="your_jwt_token"

# Fetch Zoho CRM Leads
curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=100" \
  -H "Authorization: Bearer $TOKEN"

# Fetch Salesforce Accounts
curl -X GET "http://localhost:3000/api/v1/n8n/salesforce/crm/accounts" \
  -H "Authorization: Bearer $TOKEN"

# Get supported providers
curl -X GET "http://localhost:3000/api/v1/n8n/providers" \
  -H "Authorization: Bearer $TOKEN"

🔄 Response Format

{
  "status": "success",
  "message": "zoho crm leads data fetched successfully",
  "data": {
    "success": true,
    "data": [
      {
        "id": "123",
        "First_Name": "John",
        "Last_Name": "Doe",
        "Email": "john@example.com",
        "Company": "Acme Corp"
      }
    ],
    "count": 1,
    "metadata": {}
  },
  "timestamp": "2025-10-09T12:00:00.000Z"
}

✨ Key Features

✅ Benefits

Low-code Approach: Most logic in visual n8n workflows
Single Webhook: One webhook handles all providers
Easy Maintenance: Add new providers in n8n without backend changes
Token Management: Automatic token retrieval and decryption
Error Handling: Comprehensive error handling and logging
Type Safety: Module validation before API calls
Unified API: Consistent endpoint structure across providers
Scalable: n8n workflows can be scaled horizontally

🎨 Design Patterns Used

Facade Pattern: N8nService provides simple interface
Strategy Pattern: Different handlers for each provider
Factory Pattern: N8nHandler creates appropriate clients
Repository Pattern: Token management through repositories

🛠️ Development

Adding a New Provider

Update n8n workflow:

- Add switch case in "Provider Switch"
- Add service switches
- Add module switches
- Add HTTP request nodes

Update mapper:

// src/integrations/n8n/mapper.js
static getSupportedModules(provider, service) {
  const modules = {
    newprovider: {
      api: ['resource1', 'resource2']
    }
  };
}

Done! No other backend changes needed.

Adding a New Module

Update n8n workflow:
- Add switch case in appropriate module switch
- Add HTTP request node

Update mapper:

crm: ['leads', 'contacts', 'new_module']

🧪 Testing

Manual Testing

Authenticate user with provider
Get JWT token

Call endpoint:

curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads" \
  -H "Authorization: Bearer $TOKEN"

Integration Testing

const request = require('supertest');
const app = require('./src/app');

describe('n8n Integration', () => {
  it('should fetch Zoho leads', async () => {
    const response = await request(app)
      .get('/api/v1/n8n/zoho/crm/leads')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.status).toBe('success');
    expect(response.body.data.data).toBeInstanceOf(Array);
  });
});

📊 Monitoring

All requests are logged with:

User ID
Provider
Service
Module
Query parameters
Execution time
Errors

Check logs in your logging system.

🔒 Security

✅ JWT authentication required
✅ Tokens encrypted in database
✅ Rate limiting applied
✅ Module validation prevents unauthorized access
✅ No tokens in logs

📚 Documentation

docs/N8N_INTEGRATION.md - Complete integration guide
docs/N8N_SETUP_EXAMPLE.md - Quick start examples
docs/SALESFORCE_PAGINATION.md - Salesforce pagination guide
src/integrations/n8n/README.md - Module documentation

🐛 Troubleshooting

"n8n workflow execution failed"

Check if n8n is running
Verify webhook URL in .env
Check n8n logs

"Authentication not found"

User must authenticate via OAuth first
Check if tokens are in database

"Unsupported combination"

Check /api/v1/n8n/providers for supported modules
Verify spelling of provider/service/module

🎉 Success!

You now have a complete n8n integration that:

✅ Supports multiple providers (Zoho, Salesforce)
✅ Uses a single webhook endpoint
✅ Requires minimal backend code
✅ Is easy to extend with new providers
✅ Includes comprehensive documentation
✅ Has proper error handling
✅ Manages tokens automatically

📞 Next Steps

Import the n8n workflow
Test with Zoho CRM
Test with Salesforce
Add to your dashboard/UI
Monitor logs for issues
Add more providers as needed

Happy coding! 🚀

14 KiB Raw Blame History

🚀 n8n Integration - Complete Implementation

📋 What's Been Created

✅ Created Files

🏗️ Architecture

🚀 Quick Start

Step 1: Environment Setup

Step 2: Import n8n Workflow

Step 3: User Authentication

Step 4: Fetch Data

📡 API Endpoints

Get Supported Providers

Generic Endpoint (Any Provider)

Zoho Shorthand

Salesforce Shorthand

🎯 Supported Providers & Modules

Zoho

Salesforce

📝 Usage Examples

JavaScript/Node.js

cURL

🔄 Response Format

✨ Key Features

✅ Benefits

🎨 Design Patterns Used

🛠️ Development

Adding a New Provider

Adding a New Module

🧪 Testing

Manual Testing

Integration Testing

📊 Monitoring

🔒 Security

📚 Documentation

🐛 Troubleshooting

"n8n workflow execution failed"

"Authentication not found"

"Unsupported combination"

🎉 Success!

📞 Next Steps

14 KiB

Raw Blame History