Mendix n8n Integration

A Java Action for Mendix Studio Pro that enables seamless integration with n8n webhooks. This library provides a simple, drag-and-drop solution for calling n8n workflows from Mendix applications.

🚀 Features

✅ Easy Integration: Simple Java Action for Mendix Studio Pro
✅ Webhook Support: Call n8n webhooks with custom payloads
✅ Optional Authentication: Support for secured webhooks with API keys
✅ Extended Timeouts: Configurable timeouts (up to 60 minutes) for long-running workflows
✅ Multiple Content Types: Support for JSON, XML, plain text, and custom content types
✅ Error Handling: Comprehensive validation and error messages
✅ Session Support: Session ID required for n8n Simple Memory feature
✅ Zero Dependencies: Pure Java implementation using built-in HTTP client
✅ Lightweight: Small JAR file (~7KB) with no external dependencies

📋 Requirements

Java 11+
Mendix Studio Pro
n8n Instance (self-hosted or cloud)

🛠️ Installation

1. Build the JAR

./gradlew shadowJar

This creates build/libs/n8n-1.0.0-mendix.jar

2. Deploy to Mendix Project

Option A: Manual Copy

cp build/libs/n8n-1.0.0-mendix.jar /path/to/your/mendix/project/userlib/

Option B: Automated Deployment (Windows)

# Edit deploy-to-mendix.ps1 to set your Mendix project path
.\deploy-to-mendix.ps1

Option C: Quick Deploy (Windows)

quick-deploy.bat

3. Refresh Mendix Project

Refresh your Mendix project in Studio Pro to recognize the new JAR file.

🔧 Usage in Mendix Studio Pro

Create Java Action

Right-click on a module → Add → Java Action
Name: CallN8nWebhook (or your preferred name)
Add Parameters:
- apiKey (String) - Your n8n API key (optional for public webhooks)
- webhookEndpoint (String) - Complete n8n webhook URL
- inputData (String) - JSON payload to send to n8n
- sessionId (String) - Session ID for conversation continuity (required)
Set Return Type: String

Java Code:

// BEGIN USER CODE
return com.company.mendix.n8n.N8nAction.execute(apiKey, webhookEndpoint, inputData, sessionId);
// END USER CODE

Use in Microflows

Drag the CallN8nWebhook Java Action into your microflow
Set the input parameters:
- apiKey: Your n8n API key (leave empty for public webhooks)
- webhookEndpoint: Your n8n webhook URL (e.g., https://your-n8n.com/webhook/workflow-id)
- inputData: JSON string with your data (e.g., {"user": "john", "action": "process"})
- sessionId: Session ID for conversation continuity (required for n8n Simple Memory)
Use the returned string in your application logic

📚 API Reference

Main Method (requires session ID)

N8nAction.execute(String apiKey, String webhookEndpoint, String inputData, String sessionId)

Session + Content Type Method

N8nAction.execute(String apiKey, String webhookEndpoint, String inputData, String sessionId, String contentType)

Session + Timeout Method

N8nAction.executeWithTimeout(String apiKey, String webhookEndpoint, String inputData, String sessionId, int timeoutMinutes)

Full Control with Session Method

N8nAction.execute(String apiKey, String webhookEndpoint, String inputData, String sessionId, String contentType, int timeoutMinutes)

🧠 Session Support for n8n Simple Memory

The library supports session IDs for n8n's Simple Memory feature, enabling conversation continuity across multiple webhook calls.

How Session IDs Work

Session Creation: Generate a unique session ID for each conversation/user
Session Continuity: Use the same session ID across related webhook calls
Memory Access: n8n Simple Memory uses the session ID to maintain conversation context

Session ID Examples

// Generate unique session ID
String sessionId = "user-" + userId + "-" + System.currentTimeMillis();

// Or use existing user/conversation identifier
String sessionId = "conversation-" + conversationId;

// First interaction
String response1 = N8nAction.execute(apiKey, webhookUrl, 
    "{\"message\": \"Hello, my name is John\"}", sessionId);

// Follow-up interaction (n8n remembers the name)
String response2 = N8nAction.execute(apiKey, webhookUrl, 
    "{\"message\": \"What's my name?\"}", sessionId);

Session ID Best Practices

Unique per conversation: Each conversation should have its own session ID
Consistent format: Use a consistent naming pattern (e.g., user-{id}-{timestamp})
Meaningful identifiers: Include user/conversation identifiers when possible
Session management: Consider session cleanup and expiration in your application

⏱️ Timeout Configuration

Use Case	Recommended Timeout	Method
Simple webhook calls	10 minutes (default)	`execute()`
Data processing workflows	15-20 minutes	`executeWithTimeout()`
File processing	20-30 minutes	`executeWithTimeout()`
Large data workflows	30+ minutes	`executeWithTimeout()`

🔗 Webhook Integration

Request Format

The library sends HTTP POST requests to n8n webhooks with your custom payload:

{
    "user": "john_doe",
    "action": "process_order",
    "order_id": 12345,
    "items": ["item1", "item2"]
}

Headers

Content-Type: application/json (or custom)
Authorization: Bearer your-api-key-here (if provided)
x-session-id: your-session-id-here (if provided)

Response Processing

The library automatically processes n8n webhook responses:

Searches for structured response in common fields like result, data, message, response
Returns raw response if no structured data found
Handles various content types returned by n8n

🛡️ Error Handling

The library provides comprehensive validation:

Endpoint Validation: "Webhook endpoint is required and cannot be empty"
URL Validation: "Webhook endpoint must be a valid URL"
HTTP Errors: "Webhook request failed with status code: XXX"
Timeout Errors: "Request timeout after X minutes"

🧪 Building

Build the JAR

./gradlew shadowJar

This creates build/libs/n8n-1.0.0-mendix.jar

📁 Project Structure

src/
└── main/java/com/company/mendix/n8n/
    └── N8nAction.java                   # Main implementation

deploy-to-mendix.ps1                     # Automated deployment script
quick-deploy.bat                         # Quick deployment batch file
build.gradle                             # Build configuration

🚀 Quick Start Examples

Example 1: Basic Webhook Call with Session

// In your Mendix Java Action
String apiKey = null; // No authentication needed
String webhookEndpoint = "https://your-n8n.com/webhook/simple-workflow";
String inputData = "{\"message\": \"Hello from Mendix!\", \"user\": \"john\"}";
String sessionId = "user-session-" + System.currentTimeMillis();

String result = N8nAction.execute(apiKey, webhookEndpoint, inputData, sessionId);

Example 2: Authenticated Webhook with Session

String apiKey = "your-n8n-api-key";
String webhookEndpoint = "https://your-n8n.com/webhook/secure-workflow";
String inputData = "{\"action\": \"process_order\", \"order_id\": 12345}";
String sessionId = "order-session-" + orderId;

String result = N8nAction.execute(apiKey, webhookEndpoint, inputData, sessionId);

Example 3: Custom Timeout for Long Workflows

String sessionId = "long-task-" + System.currentTimeMillis();
String result = N8nAction.executeWithTimeout(apiKey, webhookEndpoint, inputData, sessionId, 20);

Example 4: Session Support for n8n Simple Memory

String sessionId = "user-session-" + System.currentTimeMillis();

// First message in conversation
String result1 = N8nAction.execute(apiKey, webhookEndpoint, 
    "{\"message\": \"Hello, I need help\"}", sessionId);

// Second message in same conversation
String result2 = N8nAction.execute(apiKey, webhookEndpoint, 
    "{\"message\": \"Can you remember what I asked?\"}", sessionId);

Example 5: Custom Content Type

String xmlData = "<?xml version=\"1.0\"?><order><id>123</id></order>";
String result = N8nAction.execute(apiKey, webhookEndpoint, xmlData, "application/xml");

🔧 Development

Build Commands

# Compile only
./gradlew compileJava

# Build JAR
./gradlew shadowJar

# Clean build
./gradlew clean build

Deployment Scripts

PowerShell: deploy-to-mendix.ps1 - Full deployment with verification
Batch: quick-deploy.bat - Quick rebuild and deploy

🐛 Troubleshooting

Common Issues

"Class not found" in Mendix
- Ensure JAR is in userlib folder
- Refresh Mendix Studio Pro
Timeout errors
- Increase timeout using executeWithTimeout()
- Check n8n workflow performance
Connection errors
- Verify n8n instance is running and accessible
- Check webhook URL and API key (if required)
- Confirm network connectivity
Authentication errors
- Verify API key is correct
- Check if webhook requires authentication
- Ensure webhook is published and active

Debug Output

The library outputs debug information to help with troubleshooting:

Executing n8n webhook call to endpoint: https://your-n8n.com/webhook/...
Input data length: 45 characters
Request payload: {"message":"Hello from Mendix!"}
API request sent, waiting for n8n response (timeout: 10 minutes)...
Response status code: 200

📊 n8n Workflow Examples

Example Workflow 1: Data Processing

{
  "trigger": "webhook",
  "nodes": [
    {
      "name": "Webhook",
      "type": "webhook",
      "parameters": {
        "path": "process-data"
      }
    },
    {
      "name": "Process Data",
      "type": "function",
      "parameters": {
        "code": "return [{ json: { result: 'processed', data: items[0].json } }];"
      }
    },
    {
      "name": "Return Response",
      "type": "respond",
      "parameters": {
        "response": "{{ $json.result }}"
      }
    }
  ]
}

Example Workflow 2: Email Notification

{
  "trigger": "webhook",
  "nodes": [
    {
      "name": "Webhook",
      "type": "webhook",
      "parameters": {
        "path": "send-notification"
      }
    },
    {
      "name": "Send Email",
      "type": "emailSend",
      "parameters": {
        "to": "{{ $json.email }}",
        "subject": "Notification from Mendix",
        "text": "{{ $json.message }}"
      }
    }
  ]
}

📄 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

Made with ❤️ for Mendix and n8n integration

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
gradle/wrapper		gradle/wrapper
icons		icons
src/main/java/com/company/mendix/n8n		src/main/java/com/company/mendix/n8n
.gitignore		.gitignore
MENDIX_IMPLEMENTATION_GUIDE.md		MENDIX_IMPLEMENTATION_GUIDE.md
README.md		README.md
TIMEOUT_CONFIGURATION_GUIDE.md		TIMEOUT_CONFIGURATION_GUIDE.md
build.gradle		build.gradle
deploy-to-mendix.ps1		deploy-to-mendix.ps1
gradlew		gradlew
gradlew.bat		gradlew.bat
quick-deploy.bat		quick-deploy.bat
settings.gradle		settings.gradle
setup-and-test.ps1		setup-and-test.ps1

Folders and files

Latest commit

History

Repository files navigation

Mendix n8n Integration

🚀 Features

📋 Requirements

🛠️ Installation

1. Build the JAR

2. Deploy to Mendix Project

Option A: Manual Copy

Option B: Automated Deployment (Windows)

Option C: Quick Deploy (Windows)

3. Refresh Mendix Project

🔧 Usage in Mendix Studio Pro

Create Java Action

Use in Microflows

📚 API Reference

Main Method (requires session ID)

Session + Content Type Method

Session + Timeout Method

Full Control with Session Method

🧠 Session Support for n8n Simple Memory

How Session IDs Work

Session ID Examples

Session ID Best Practices

⏱️ Timeout Configuration

🔗 Webhook Integration

Request Format

Headers

Response Processing

🛡️ Error Handling

🧪 Building

Build the JAR

📁 Project Structure

🚀 Quick Start Examples

Example 1: Basic Webhook Call with Session

Example 2: Authenticated Webhook with Session

Example 3: Custom Timeout for Long Workflows

Example 4: Session Support for n8n Simple Memory

Example 5: Custom Content Type

🔧 Development

Build Commands

Deployment Scripts

🐛 Troubleshooting

Common Issues

Debug Output

📊 n8n Workflow Examples

Example Workflow 1: Data Processing

Example Workflow 2: Email Notification

📄 License

🤝 Contributing

🔗 Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages