n8n-nodes-solace

An n8n community node for integrating with Solace PubSub+ message brokers. This node provides reliable message consumption from Solace queues with guaranteed delivery, supporting multiple message formats including JSON, Protocol Buffers, and binary data.

Table of Contents

• Installation
• Features
• Credentials
• Node Configuration
• Message Formats
• Usage Examples
• Troubleshooting
• Development
• Contributing
• License

Installation

Via n8n Community Nodes

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-solace
5. Click Install

Via npm (for self-hosted n8n)

# Install globally
npm install -g n8n-nodes-solace

# Or install in your n8n project
npm install n8n-nodes-solace

For Development

# Clone the repository
git clone https://github.com/yourusername/n8n-nodes-solace.git
cd n8n-nodes-solace

# Install dependencies
npm install

# Build the node
npm run build

# Link for local development
npm link

Features

• ✅ Guaranteed Message Delivery - Consume messages from Solace queues with reliable delivery
• ✅ Multiple Message Formats - Support for JSON, Protocol Buffers, binary, and auto-detection
• ✅ Flexible Authentication - Username/password and client certificate authentication
• ✅ Message Acknowledgment - Automatic and manual acknowledgment modes
• ✅ Connection Management - Automatic reconnection and error handling
• ✅ Message Properties - Access to all Solace message properties and user properties
• ✅ SSL/TLS Support - Secure connections with certificate validation options
• ✅ Parallel Processing - Optional parallel message processing for high throughput

Credentials

Solace API Credentials

Create a new credential of type Solace API with the following settings:

Field	Description	Required	Example
Host URL	Solace broker URL with protocol	Yes	ws://localhost:8008
VPN Name	Message VPN name	Yes	default
Username	Client username	Yes	admin
Password	Client password	Yes	admin
Client Name	Unique client identifier	No	n8n-solace-client
Connection Timeout	Connection timeout in milliseconds	No	10000
Keep Alive Interval	Keep alive interval in milliseconds	No	3000
Reconnect Retries	Number of reconnection attempts	No	3
Allow Self-Signed Certificates	Disable SSL certificate validation	No	false

Supported Protocols

• WebSocket: ws://hostname:port (default: 8008)
• Secure WebSocket: wss://hostname:port (default: 443)
• TCP: tcp://hostname:port (default: 7000)
• Secure TCP: tcps://hostname:port (default: 7001)

Node Configuration

Solace Trigger Node

The Solace Trigger node listens for messages on a specified queue and triggers the workflow for each received message.

Basic Settings

Parameter	Description	Required	Default
Queue Name	Name of the queue to consume from	Yes	-
Message Format	Expected message format	No	Auto Detect
Protobuf Schema	Protocol Buffers schema definition	Conditional	-
Message Type	Protobuf message type name	Conditional	-

Advanced Options

Option	Description	Default
Include Message Properties	Include Solace message properties in output	true
Auto Acknowledge	Automatically acknowledge messages	true
Parallel Processing	Process messages in parallel	false
Include Binary Payload	Include base64-encoded binary payload	false
Consumer Window Size	Max unacknowledged messages	1

Message Formats

Auto Detect (Default)

Automatically detects the message format:

• Tries to parse as JSON first
• Falls back to text for string payloads
• Treats binary data as binary format

JSON

Parses the message payload as JSON:

{
  "orderId": "12345",
  "customerId": "cust-001",
  "items": [
    {"productId": "prod-001", "quantity": 2}
  ]
}

Protocol Buffers

Decodes binary protobuf messages using a provided schema:

syntax = "proto3";

message Order {
  string order_id = 1;
  string customer_id = 2;
  repeated Item items = 3;
}

message Item {
  string product_id = 1;
  int32 quantity = 2;
}

Binary

Treats the message as raw binary data, useful for custom formats or when you need direct access to the byte array.

Usage Examples

Basic Message Consumption

// Workflow triggered by Solace message
// Message data is available in the input
const messageData = $input.all()[0].json;

console.log('Queue:', messageData.queue);
console.log('Message ID:', messageData.messageId);
console.log('Payload:', messageData.payload);
console.log('Timestamp:', messageData.timestamp);

Working with Message Properties

// Access message properties
const properties = $input.all()[0].json.properties;

console.log('Delivery Mode:', properties.deliveryMode);
console.log('Priority:', properties.priority);
console.log('Time to Live:', properties.timeToLive);
console.log('Redelivered:', properties.redelivered);

// Access user properties
const userProps = $input.all()[0].json.userProperties;
console.log('Custom Property:', userProps.customField);

Protocol Buffers Example

// For protobuf messages, the payload is automatically decoded
const order = $input.all()[0].json.payload;

console.log('Order ID:', order.order_id);
console.log('Customer ID:', order.customer_id);
console.log('Items:', order.items);

// Process each item
order.items.forEach(item => {
  console.log(`Product: ${item.product_id}, Quantity: ${item.quantity}`);
});

Error Handling

// Check for parsing errors
const messageData = $input.all()[0].json;

if (messageData.parseError) {
  console.error('Message parsing failed:', messageData.parseError);
  // Handle the error or use the raw payload
  console.log('Raw payload:', messageData.payload);
}

Output Format

The Solace Trigger node outputs the following structure:

{
  "queue": "my-queue",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "messageId": "msg-12345",
  "isRedelivered": false,
  "deliveryCount": 1,
  "payload": {}, // Parsed message content
  "format": "json", // Detected/specified format
  "properties": {
    "applicationMessageId": "app-msg-001",
    "correlationId": "corr-001",
    "deliveryMode": 2,
    "priority": 4,
    "redelivered": false,
    "timeToLive": 0,
    "replyTo": "reply-queue",
    "sequenceNumber": 1
  },
  "userProperties": {
    "customField": "customValue"
  },
  "binaryPayload": "base64EncodedData" // If enabled
}

Troubleshooting

Connection Issues

Problem: Connection failed: ECONNREFUSED

Solutions:

• Verify the host URL and port are correct
• Check if the Solace broker is running
• Ensure firewall allows the connection
• Try different ports (8008 for ws, 443 for wss, 7000 for tcp)

Problem: Authentication failed

Solutions:

• Verify username, password, and VPN name
• Check if the user has permission to consume from the queue
• Ensure the client name is unique

SSL Certificate Issues

Problem: SSL certificate validation errors

Solutions:

• Enable "Allow Self-Signed Certificates" for development
• Install proper CA certificates for production
• Verify the certificate chain is complete

Message Processing Issues

Problem: Messages not being consumed

Solutions:

• Verify the queue exists on the broker
• Check if the queue has messages
• Ensure the user has consume permissions
• Check the consumer window size setting

Problem: Protobuf parsing errors

Solutions:

• Verify the protobuf schema is correct
• Ensure the message type name matches the schema
• Check if the binary data is actually protobuf format

Performance Issues

Problem: Slow message processing

Solutions:

• Enable parallel processing for high throughput
• Increase the consumer window size
• Use auto-acknowledge mode for faster processing
• Consider message batching in your workflow

Development

Prerequisites

• Node.js 18+
• npm or yarn
• n8n development environment

Setup

# Clone the repository
git clone https://github.com/yourusername/n8n-nodes-solace.git
cd n8n-nodes-solace

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Link for local development
npm link

Project Structure

n8n-nodes-solace/
├── credentials/
│   └── SolaceApi.credentials.ts    # Credential definition
├── nodes/
│   └── Solace/
│       ├── SolaceTrigger.node.ts   # Main node implementation
│       ├── SolaceTrigger.node.json # Node metadata
│       └── solace.svg              # Node icon
├── dist/                           # Compiled output
├── package.json                    # Package configuration
├── tsconfig.json                   # TypeScript configuration
└── README.md                       # This file

Building

# Development build with watch
npm run dev

# Production build
npm run build

# Format code
npm run format

# Lint and fix
npm run lintfix

Testing

# Link the node locally
npm link

# In your n8n project
npm link n8n-nodes-solace

# Start n8n and test the node
n8n start

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 tests and linting (npm run lint)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Follow the existing TypeScript/JavaScript style
• Use meaningful variable and function names
• Add comments for complex logic
• Follow n8n community node guidelines

License

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

Support

• Issues: GitHub Issues
• Documentation: n8n Community Nodes
• Solace Documentation: Solace Developer Portal

Acknowledgments

• n8n - Workflow automation platform
• Solace - Event streaming and messaging platform
• solclientjs - Solace JavaScript client library