CleverFlow Node for n8n

A custom n8n node for integrating with CleverFlow, allowing you to create and retrieve Runs directly from your n8n workflows with dynamic workspace, workflow, and field selection.

Features

• Dynamic Workspace Selection: Choose from available workspaces in your CleverFlow account
• Dynamic Workflow Selection: Select workflows within the chosen workspace
• Dynamic Field Selection: Automatically fetch available fields in the workflow
• Multiple Run Retrieval Methods: Get runs by UID+workspace or directly by numeric run ID
• Efficient Caching: Reduces API calls by caching workspaces, workflows, and fields
• Run Naming: Name your runs for better tracking

Getting Started

Prerequisites

• n8n installed (version 0.152.0 or later recommended)
• CleverFlow API token

Installation

1. Clone this repository:

   git clone https://github.com/your-organization/n8n-nodes-cleverflow.git
   cd n8n-nodes-cleverflow
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Link to your n8n installation:

   npm link
   

4. In your n8n custom extension directory (typically ~/.n8n/custom/):

   npm link n8n-nodes-cleverflow
   

5. Restart n8n:

   n8n restart
   

Usage

Setting Up Credentials

1. In n8n, add a new "CleverFlow" node to your workflow
2. When prompted for credentials, click "Create New"
3. Enter your CleverFlow API token (without the "Token " prefix)
4. The default API Base URL is set to https://api.cleverflow.com
5. Save the credentials

Configuration Options

Operations

• Create: Create a new run in CleverFlow
• Get: Retrieve a run by its identifier

Create Operation Options

• Workspace: Select from available workspaces in your account
• Workflow: Select from the workflows available in the chosen workspace
• Run Name: Optionally provide a name for the run
• Data Fields: Add field values based on the selected workflow's available fields

Get Operation Options

• Run Identifier Type:
  • Run UID (Requires Workspace): Identify run by UID within a workspace (e.g., PL-1)
    • Workspace: Select from available workspaces
    • Run UID: Enter the unique identifier for the run
  • Run ID: Identify run directly by numeric ID without specifying a workspace
    • Run ID: Enter the numeric run identifier (e.g., 110796)

Technical Implementation

API Integration

The node integrates with several CleverFlow API endpoints:

1. Workspace List: /workspace

   • Used to fetch available workspaces
   • Maps workspace names to IDs for subsequent requests

2. Workflow List: /workspace/{workspaceId}/workflows/?version=v6

   • Fetches workflows within a workspace
   • Maps workflow keys to IDs for field fetching

3. Create Run: /public/create_run

   • Creates a new run with the configured parameters

4. Get Run by UID: /workspaces/{workspace}/runs/{runUid}

   • Retrieves details for a specific run within a workspace

5. Get Run by ID: /runs/{runId}

   • Retrieves details for a specific run directly by its numeric ID

Caching Mechanism

To optimize performance and reduce API calls, the node implements a three-tier caching system:

1. Workspace Cache: Stores workspaces by API token

   • Refreshed when a different API token is used
   • Used to quickly populate workspace dropdowns

2. Workflow Cache: Stores workflows by workspace name

   • Refreshed when a different workspace is selected
   • Used to quickly populate workflow dropdowns

3. Field Cache: Stores fields by workflow key

   • Refreshed when a different workflow is selected
   • Used to quickly populate field dropdowns

Workspace Slug Handling

The node automatically converts workspace names to slugs for API requests, ensuring proper formatting for CleverFlow's API:

$parameter.workspaceId.toLowerCase().replace(/[^a-z0-9]/g, "-")

This handles spaces, special characters, and capitalization that might be present in the workspace name displayed to the user.

Troubleshooting

Common Issues

1. 404 Errors: Ensure your API token has access to the specified workspaces and runs.

2. Authentication Errors: Verify that you've entered the API token correctly without the "Token " prefix.

3. Missing Fields: If fields aren't showing up, try refreshing the node or selecting the workflow again.

Development

Building

npm run build

Linting

npm run lint

Fixing Lint Issues

npm run lintfix

License

This project is licensed under the MIT License - see the LICENSE.md file for details.