n8n-nodes-numeriquai

A custom n8n community node package for Numeriquai data processing tools. This package provides nodes for integrating Numeriquai's rule evaluation services into your n8n workflows.

Features

• Two Operations:
  • Flat Merge: Merge multiple input JSON items into a single streamlined JSON object using deep merge
  • Evaluate Rules: Evaluate rules against data using Numeriquai API (requires API credentials)
• Deep merge functionality for nested object merging
• API integration with Numeriquai's audit service
• Bearer token authentication via credentials
• Error handling with continue on fail option

Installation

Install from npm (Recommended)

1. Go to your n8n instance
2. Navigate to Settings > Community Nodes
3. Click "Install a community node"
4. Enter the package name: n8n-nodes-numeriquai
5. Click "Install"
6. Wait for the installation to complete (you may need to restart n8n)

The package is available on npm: https://www.npmjs.com/package/n8n-nodes-numeriquai

Quick Start

After installation, use the recommended workflow pattern:

1. Connect your input nodes - Connect multiple nodes that provide JSON data
2. Add Numeriquai node (Flat Merge):
   • Set operation to "Flat Merge"
   • Configure number of inputs to match your input nodes
   • Connect all input nodes to this node
3. Add Numeriquai node (Evaluate Rules):
   • Set operation to "Evaluate Rules"
   • Configure credentials: Create a "Numeriquai API" credential with your API key
   • Enter your Guideline ID
   • Connect the Flat Merge node output to this node
4. Execute your workflow

The Flat Merge node will process and format inputs from different nodes, then pass the merged data to the Evaluate Rules node for Numeriquai API evaluation.

Local Development

For developers who want to contribute or test locally:

Prerequisites

• Node.js (version 18.17.0 or higher)
• npm
• n8n instance for testing

Setup

1. Clone the repository:

   git clone https://github.com/numeriquai/n8n-nodes-numeriquai.git
   cd n8n-nodes-numeriquai
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Link for local development:

   # Create npm link
   npm link
   
   # Link to n8n's nodes directory
   cd ~/.n8n/nodes
   npm link n8n-nodes-numeriquai
   

5. Restart n8n to load the linked node

Usage

The Numeriquai node supports two operations that work together in a recommended workflow pattern:

Recommended Workflow Pattern

Use Flat Merge first, then Evaluate Rules:

1. Flat Merge Node: Processes and formats inputs from multiple different nodes
2. Evaluate Rules Node: Receives the merged data and evaluates rules via Numeriquai API

This pattern allows you to combine data from various sources before sending it to Numeriquai for rule evaluation.

Operation 1: Flat Merge

Merge multiple input JSON items into a single streamlined JSON object using deep merge. This operation processes and formats input from different nodes.

Parameters:

• Operation: Select "Flat Merge"
• Number of Inputs: Choose how many input connections to merge (2-10)
  • Use the "+" button on the node to add multiple input connections

Requirements:

• Multiple input connections (2-10)
• Note: Credentials must be configured (the node requires them), but they are not used by the Flat Merge operation

Example:

• Input 1: { "name": "John", "age": 30 }
• Input 2: { "city": "Paris", "country": "France" }
• Output: { "name": "John", "age": 30, "city": "Paris", "country": "France" }

Operation 2: Evaluate Rules

Evaluate rules against data using Numeriquai's API. This operation receives processed data (typically from a Flat Merge node) and sends it to Numeriquai for rule evaluation.

Parameters:

• Operation: Select "Evaluate Rules" (default)
• Guideline ID (required): The unique identifier for the guideline to process

Requirements:

• Numeriquai API credentials (API Key)
• Single input connection with JSON data (typically from a Flat Merge node)

Recommended Workflow:

1. Connect your input data nodes - Connect multiple nodes that provide JSON data (e.g., API calls, database queries, webhooks, etc.)

2. Add the first Numeriquai node (Flat Merge):

   • Operation: "Flat Merge"
   • Number of Inputs: Set to match the number of input nodes you're connecting
   • Credential to connect with: Create/select "Numeriquai API" credential (required but not used)
   • Connect all your input nodes to this Flat Merge node

3. Add the second Numeriquai node (Evaluate Rules):

   • Operation: "Evaluate Rules"
   • Credential to connect with: Use the same "Numeriquai API" credential
     • Enter your API Key
   • Guideline ID: "guideline-123"
   • Connect the Flat Merge node output to this Evaluate Rules node

4. Execute the workflow

5. The Evaluate Rules node will send a POST request to Numeriquai with the merged data:

   {
     "reference": "Test run N8N guidline HH:MM",
     "description": "N8N test",
     "guideline_id": "guideline-123",
     "inputs": {
       "applicantName": "John Doe",
       "applicationType": "standard",
       "priority": "high"
     }
   }
   

   Note: The reference field includes a timestamp (HH:MM format) automatically generated by the node.

6. The API response will be returned as JSON output

API Request Format (Evaluate Rules)

The node sends a POST request with:

• URL: NUMERIQUAI_BACKEND_URL (hardcoded)
• Headers:
  • X-API-Key: {your-api-key}
  • Content-Type: application/json
• Body:

  {
    "reference": "Test run N8N guidline {timestamp}",
    "description": "N8N test",
    "guideline_id": "{guidelineId}",
    "inputs": { /* your input data */ }
  }
  

Error Handling

• If an operation fails, the node will throw an error by default
• Enable "Continue on Fail" in the node settings to return error information instead of stopping the workflow
• Validation errors for missing required parameters (e.g., Guideline ID, credentials) will always stop execution
• For Flat Merge: Errors during merge operations can be handled with "Continue on Fail"
• For Evaluate Rules: API errors (network, authentication, etc.) can be handled with "Continue on Fail"

Testing & Verification

After installing the node, verify it works correctly:

Step 1: Verify Node is Available

1. Start n8n (if not already running):

   n8n start
   

2. Open n8n in your browser (usually http://localhost:5678)

3. Create a new workflow or open an existing one

4. Search for "Numeriquai" in the node palette (click the "+" button or press /)

5. Verify the node appears - You should see:

   • Node name: "Numeriquai"
   • Icon: Numeriquai logo
   • Category: Transform

Step 2: Test Flat Merge Operation

1. Add a Numeriquai node to your workflow

2. Set Operation to "Flat Merge"

3. Configure Number of Inputs (e.g., 2)

4. Connect your input nodes - Connect two or more nodes that provide JSON data:

   • Input Node 1: Should output { "name": "John", "age": 30 }
   • Input Node 2: Should output { "city": "Paris", "country": "France" }

5. Connect your input nodes to the Numeriquai node

6. Execute the workflow (click "Execute Workflow")

7. Verify output: The Numeriquai node should output:

   {
     "name": "John",
     "age": 30,
     "city": "Paris",
     "country": "France"
   }
   

Step 3: Test Complete Workflow (Flat Merge → Evaluate Rules)

1. Connect your input nodes - Connect multiple nodes that provide JSON data

2. Add the first Numeriquai node (Flat Merge):

   • Set Operation to "Flat Merge"
   • Configure Number of Inputs to match your input nodes
   • Configure credentials (required but not used for Flat Merge)

3. Connect your input nodes to the Flat Merge node

4. Add the second Numeriquai node (Evaluate Rules):

   • Set Operation to "Evaluate Rules"
   • Configure credentials:
     • Click on the node
     • Click "Credential to connect with" dropdown
     • Click "Create New Credential" (or select existing)
     • Select "Numeriquai API"
     • Enter your API Key
     • Click "Save"
   • Guideline ID: Enter a valid guideline ID (e.g., "test-guideline-123")

5. Connect the Flat Merge node output to the Evaluate Rules node

6. Execute the workflow

7. Verify the workflow:

   • Check the Flat Merge node output - it should contain merged data from all inputs
   • Check the Evaluate Rules node output - it should contain the API response
   • Check the execution log for any errors
   • Verify the request was sent to: https://api.numeriquai.com/api/v1/audits/

Step 4: Troubleshooting

If the node doesn't appear or doesn't work:

1. Check n8n logs for errors:

   # If running n8n locally, check terminal output
   # Look for errors related to "numeriquai" or "community nodes"
   

2. Verify the build:

   npm run build
   ls -la dist/
   # Should see dist/nodes/Numeriquai/ and dist/credentials/
   

3. Check node installation:

   # Verify the link exists
   ls -la ~/.n8n/nodes/ | grep numeriquai
   

4. Clear n8n cache (if needed):

   • Stop n8n
   • Delete ~/.n8n/.cache/ (if exists)
   • Restart n8n

5. Check n8n version compatibility:

   • Ensure you're using a compatible n8n version
   • Check package.json for peer dependencies

6. Verify credentials (for Evaluate Rules operation):

   • Ensure the Numeriquai API credential type is available
   • Check that credentials can be created and saved
   • Note: Flat Merge operation does not require credentials

Step 5: Verify in Production

For production deployments:

1. Test with real API endpoints
2. Verify error handling (test with invalid credentials/guidelines)
3. Check performance with larger datasets
4. Monitor logs for any runtime errors

Development Commands

# Build the project
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lintfix

# Format code
npm run format

# Watch mode for development
npm run dev

Publishing (For Maintainers)

This package is published to npm. To publish a new version:

Using n8n-node CLI Tool (Recommended)

# 1. Login to npm
npm login

# 2. Release (builds, lints, updates version, publishes)
npx n8n-node release

See N8N_NODE_CLI_GUIDE.md for detailed information.

Manual Publishing

1. Update version:

   npm version patch  # or minor/major
   

2. Build and publish:

   npm run build
   npm publish
   

3. Push tags:

   git push --tags
   git push
   

The package is automatically built before publishing via the prepublishOnly script.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run linting (npm run lint) and fix any issues
5. Build the project (npm run build) to ensure it compiles
6. Commit your changes (git commit -m 'Add some amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Please ensure your code follows the existing style and passes all linting checks.

Links

• npm Package: https://www.npmjs.com/package/n8n-nodes-numeriquai
• GitHub Repository: https://github.com/numeriquai/n8n-nodes-numeriquai
• Numeriquai Website: https://numeriquai.com
• n8n Documentation: https://docs.n8n.io

License

MIT

Support

For issues, questions, or feature requests:

• GitHub Issues: Create an issue
• Numeriquai Support: https://numeriquai.com
• n8n Community: n8n Community Forum