@traien/n8n-nodes-espocrm

This is a community node for n8n that enables seamless integration with EspoCRM, a powerful open-source CRM platform. With this node, you can automate your CRM operations and integrate EspoCRM with other services in your n8n workflows.

n8n is a fair-code licensed workflow automation platform.

Features

The EspoCRM node provides comprehensive access to EspoCRM's API functionality:

• Entity Operations

  • Create new records (Leads, Contacts, Accounts, etc.)
  • Retrieve entity details
  • Update records (full or partial updates)
  • Delete records
  • List/search entities with advanced filtering
  • Supported core entities: Account, Contact, Lead, Meeting, Task, Call, Opportunity, Case

• Dynamic Entity Support

  • Work with any entity type in your EspoCRM instance
  • Automatic field detection and validation
  • Custom field support

• Advanced Filtering

  • Complex search queries
  • Date-based filtering
  • Relationship filters
  • Array field operations
  • Custom boolean filters

• Performance Optimizations

  • Pagination support
  • Selective field loading
  • Skip total count for large datasets
  • Duplicate checking control

Prerequisites

• Active EspoCRM instance (v6.0 or later recommended)
• API access enabled in EspoCRM
• API user with appropriate permissions
• n8n installation (v0.170.0 or later)

Installation

Follow these steps to install this package in your n8n instance:

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Select "Install"
4. Enter @traien/n8n-nodes-espocrm
5. Click "Install"

For a manual installation, you can use:

npm install @traien/n8n-nodes-espocrm

Or if you have installed n8n globally:

npm install -g @traien/n8n-nodes-espocrm

Configuration

API Authentication

1. In EspoCRM:

   • Navigate to Administration > API Users
   • Create a new API User
   • Generate an API Key
   • Note down the API Key and API Secret

2. In n8n:

   • Add new credentials of type 'EspoCRM API'
   • Enter your EspoCRM instance URL
   • Input the API Key and API Secret
   • Save the credentials

Usage Examples

Creating a Contact

Create a new contact record with customized field values:

1. Add an "EspoCRM" node to your workflow
2. Select "Contact" as the Resource
3. Choose "Create" as the Operation
4. Fill in the required fields:
   • First Name
   • Last Name
   • Email Address
5. Add any additional fields as needed
6. Connect to other nodes in your workflow

Creating a Meeting

1. Add an "EspoCRM" node to your workflow
2. Select Meeting as the Resource
3. Choose Create as the Operation
4. Fill in the required fields:

• Name
• Start Date

5. Optionally set End Date, Status, Assigned User ID, or parent (parentType + parentId)
6. Execute to create the meeting in EspoCRM

Working with Dynamic Entities

The Dynamic resource allows you to work with any entity type in your EspoCRM system:

1. Add an "EspoCRM" node to your workflow
2. Select "Dynamic" as the Resource
3. Choose your desired Operation (Create, Update, Get, etc.)
4. Select the Entity Type from the dropdown
5. The available fields will be automatically loaded based on the entity type
6. Complete the required fields and connect to your workflow

Advanced Filtering Example

{
  "operation": "getAll",
  "entityType": "Lead",
  "filterOptions": {
    "where": [
      {
        "type": "and",
        "value": [
          {
            "type": "equals",
            "field": "status",
            "value": "New"
          },
          {
            "type": "greaterThan",
            "field": "createdAt",
            "value": "2024-01-01"
          }
        ]
      }
    ],
    "orderBy": "createdAt",
    "order": "desc",
    "maxSize": 50
  }
}

Attachments & Documents

You can upload files to EspoCRM as Attachment records and then create a Document that references the uploaded file. You can also download attachments to binary output in n8n.

1. Upload an Attachment

• Add an EspoCRM node
• Resource: Attachment
• Operation: Upload
• Fields:
  • Binary Property: name of the binary key on the incoming item (default data)
  • Related Type: usually Document (but can be any entity supported by your instance)
  • Field: usually file for Document’s File field
  • Role: defaults to Attachment (other roles: Inline Attachment)
• The node derives name, type, and size from the binary; you can override name and type in Additional Fields
• Output contains the created Attachment id

2. Create a Document linked to the uploaded file

• Add a second EspoCRM node
• Resource: Document
• Operation: Create
• Fields:
  • Name: document name
  • File ID: reference the Attachment id (from the previous step)
  • Optional: Publish Date (date only is expected; we normalize inputs), Status, File Name, Folder ID, Description, Assigned User ID

3. Download an Attachment

• Add an EspoCRM node
• Resource: Attachment
• Operation: Download
• Fields:
  • Attachment ID: the Attachment record ID
  • Binary Property: output key to store the file (default data)
• Output: one item with binary[Binary Property] populated, including fileName and mimeType

Notes:

• EspoCRM may restrict allowed file types by extension/MIME. If you receive 403 Not allowed file type, verify your instance settings and the file’s extension/MIME.
• For attachment-multiple fields (e.g., Note.attachments), upload first, then create/update the parent entity with attachmentsIds including the returned attachment ID (remember to include existing IDs when updating to avoid unlinking).

Resources

• EspoCRM API Documentation
• n8n Community Nodes Documentation

Support

• For EspoCRM-specific issues: EspoCRM Forum
• For node-specific issues: Create an issue in the GitHub repository
• For n8n-related questions: n8n Community

Development

To run a local version of n8n with this node for development, you can use the following Docker command. Make sure to replace /path/to/your/local/n8n-espocrm with the absolute path to this repository on your machine.

docker run -it --rm \\
 --name n8n \\
 -p 5678:5678 \\
 -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \\
 -e N8N_RUNNERS_ENABLED=true \\
 -e N8N_LOG_LEVEL=debug -v n8n_data:/home/node/.n8n \\
 -v /path/to/your/local/n8n-espocrm:/home/node/.n8n/custom/n8n-espocrm

License

MIT