ZeroMQ Socket Listener
ZeroMQSocketListenerTask receives messages from a configured ZeroMQSocket and turns them into Banalytics processing input. Use it for real-time telemetry, commands, external AI results, industrial gateways, and custom sidecar agents.
Receive ZeroMQ frames and route them into Banalytics workflows
The listener runs continuously on a background daemon thread. Each received frame can fire a ZeroMQEvent or be passed to child tasks through the execution context variable zmq-payload.
Inbound messages
Attach the task to a receive-capable socket such as SUB, PULL, REP, PAIR, DEALER, or ROUTER.
Events
Enable fireZMQEvent when Event Manager rules should react to each incoming message.
Child tasks
Keep event firing disabled when a local processing chain should consume zmq-payload directly.
Choose event-driven or child-task processing
Event-driven automation
Set fireZMQEvent=true when messages should trigger Event Manager rules, notifications, actions, or state transitions.
Local processing pipeline
Set fireZMQEvent=false when child tasks should process every message without creating a global event for each frame.
Text and JSON payloads
Keep stringPayload=true for JSON, CSV, plain text commands, line protocols, and expression-friendly rule conditions.
Binary payloads
Set stringPayload=false for images, protobuf, msgpack, compressed messages, or any protocol where raw bytes must be preserved.
Common listener topologies
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
ZeroMQ Socket | Yes | Reference to the ZeroMQSocket used for receiving messages. | None |
Generate event | Yes | Fires a ZeroMQEvent with code EVT_ZEROMQ_MESSAGE for each received message. | false |
String message | Yes | Converts received bytes to a UTF-8 String. Disable it to keep the payload as raw byte[]. | true |
Reconnect on idle timeout | Yes | Idle threshold in milliseconds before the task reports a socket processing problem and restarts through component lifecycle handling. Use 0 for very sporadic sources. | 30000 |
Interpret ZeroMQEvent and zmq-payload
When fireZMQEvent=true, the task emits ZeroMQEvent. Its payload field is either a String or byte[], depending on stringPayload. Child tasks can also read the same message from zmq-payload, even when global event firing is disabled.
| Mode | Payload type | Best for | How to use |
|---|---|---|---|
stringPayload=true | String | JSON, commands, CSV, numeric text, line protocol, Event Manager expressions. | Use payload in rules |
stringPayload=false | byte[] | Images, protobuf, msgpack, compressed data, custom binary frames. | Parse in JavaTask |
zmq-payload | Object | Execution context variable available to child tasks started by the listener. | Pipeline input |
stringPayload=true, Event Manager conditions can check values such as payload == 'START', payload.startsWith('cmd:'), or payload.contains('"alarm":true').
Object payload = ctx.getVar("zmq-payload");
if (payload instanceof String text) {
// Parse JSON, command text, CSV, or a line protocol value.
} else if (payload instanceof byte[] bytes) {
// Decode binary payload in a custom parser or JavaTask.
}Operational notes
Use a receive-capable socket
A listener is useful for inbound patterns. A pure PUB or PUSH sending socket will not provide messages to receive.
Calibrate idle recovery
For continuous streams, keep idleReconnectMs near the expected message cadence. For rare messages, set it to 0 or a much larger value.
Control event volume
Broad subscriptions and high-frequency publishers can create many events or child executions. Narrow the socket filter or process messages in batches when needed.
Frame boundaries matter
The listener handles one received frame at a time. If an external protocol uses multipart messages, assemble and interpret those frames explicitly in the companion workflow.