Configure the Pulsar Connector

Publish SIA Connect item values to Apache Pulsar topics using optional JWT authentication.

+ More

The Pulsar Connector publishes data from SIA Connect to an Apache Pulsar broker. Use it as a destination Connector when a mapping must send an item value to a Pulsar topic.

The Connector creates a producer for the configured topic and sends each value synchronously as the message content. It supports optional JSON Web Token (JWT) authentication.

The Connector is producer-only. It does not consume Pulsar messages or create subscriptions.

Before you begin

Install the Pulsar Connector. See Install and manage Connectors.
Obtain the Pulsar broker service URL.
Allow SIA Connect to reach the broker through the required network port.
Create or identify the tenant, namespace, and topic used by the integration.
Obtain a JWT if the broker requires token authentication.
Confirm that the authenticated role is allowed to produce messages to the topic.
Create the source instance and item whose value will be published.

Treat the JWT as a credential. Do not include it in screenshots, exported examples, support messages, or article comments.

Understand the data flow

The Pulsar item is a destination for a mapping:

A source Connector reads or generates a value.
A mapping sends the value to a Pulsar item.
The Pulsar Connector creates a producer for the item's topic.
The Connector publishes the mapped value as the message content.
The Connector closes the Pulsar client after the send operation.

The published content is the value produced by the mapping. Use a mapping template or transformation when the broker must receive JSON or another specific payload structure.

Create a Pulsar instance

The Connector does not support instance or item discovery. Configure the broker and topics manually.

In the sidebar, expand Workspace and select Instances.
Select Create instance.
Select the Pulsar Connector.
Enter a unique name for the instance.
Enter the Pulsar broker service URL in Address.
Configure the instance parameters described below.
Create the instance.

Example: A broker service URL can use the format pulsar://192.168.1.50:6650. Replace the address and port with the values for your Pulsar environment.

Parameter	Required	Default	Description
Address	Yes	None	Pulsar broker service URL passed to the Pulsar client.
JWT token	Only when required by the broker	Empty	Authentication token sent to the broker. Leave empty to connect without authentication. The field accepts up to 2,048 characters.
Connection timeout	Yes	`5000`	Maximum time in milliseconds allowed for the broker connection. Enter a positive whole number.

When JWT token is empty, the Connector does not configure authentication. The broker must therefore allow the unauthenticated connection.

Create a Pulsar item

Create one destination item for each topic that SIA Connect must publish to. Several source items can map to the same Pulsar item when they must use the same topic and payload handling.

Open the Pulsar instance.
Open the Items section.
Select Add item.
Select the manual item option.
Enter a descriptive item name.
Configure the item for write access.
Enter the Pulsar topic in Topic.
Create the item.

Parameter	Required	Default	Description
Topic	Yes	`persistent://public/default/my-topic`	Complete Pulsar topic name used when the producer is created. The field accepts up to 512 characters.

A complete persistent topic name uses this structure:

persistent://tenant/namespace/topic

Example:

persistent://factory/production/line-1

Confirm that the tenant, namespace, and topic match the broker configuration exactly.

For general item settings, see Create and edit items.

Create a mapping to Pulsar

Open the instance containing the source item.
Create a mapping from the source item to the Pulsar item.
Add any required condition or trigger.
Add a template or transformation if the value must be converted into a structured payload.
Enable the mapping.

See Create and edit mappings for the complete procedure.

Format the message content

The Connector publishes the mapped item value as UTF-8 message content. It does not automatically add a JSON object, timestamp, item name, unit, message key, or custom Pulsar properties.

For a plain value, map the source directly to the Pulsar item.

For a JSON message, build the required content in the mapping. For example:

{"name":"temperature","value":%value%}

Adapt the example to the value type and the payload expected by the receiving application.

The Connector sends one synchronous message for each write operation. It does not batch or chunk messages.

Verify the configuration

Enable the Pulsar instance and destination item.
Enable the source instance, source item, and mapping.
Generate or read a new source value.
Confirm that the Pulsar instance and item do not show an error.
Use a Pulsar consumer or administration tool to confirm that the message arrived on the configured topic.
Compare the received content with the mapping output.

A successful send means the Pulsar client created the producer and the broker accepted the message.

Troubleshoot the Pulsar Connector

Message or symptom	Cause and action
An error occured creating producer - Error message	The Pulsar client could not create a producer for the configured broker and topic. Read the Pulsar result included in the message. Check the broker service URL, network access, authentication, topic name, permissions, and broker availability.
The message could not be sendt, received code	The producer was created, but the synchronous send failed. Record the returned code. Check whether the broker became unavailable, the connection timed out, or the message was rejected.
The broker cannot be reached	Confirm that Address contains the broker service URL rather than a web administration URL. Check DNS, routing, firewall rules, port forwarding, and the Pulsar broker service.
The connection times out	Confirm that Connection timeout contains a positive number of milliseconds. Increase it for a slow or remote broker, then test the network path separately.
Authentication fails	Confirm that JWT token contains only the current token value. Check its expiry, signature, issuer, audience, and the broker's authentication configuration.
Authorization or permission is denied	Confirm that the JWT role is allowed to produce to the configured tenant, namespace, and topic.
The topic cannot be created or found	Check the full topic name. Confirm that the tenant and namespace exist. If automatic topic creation is disabled on the broker, create the topic before retrying.
No message is received, but no Pulsar error is shown	Confirm that the mapping is enabled and is writing to the correct Pulsar item. Generate a new source value, check the mapping condition and trigger, and confirm that the consumer is subscribed to the exact topic.
The message content is not in the expected format	The Connector sends the mapping output without adding a wrapper. Correct the mapping template or transformation and test the resulting value again.
Only the value is received	This is expected. Add the item name, timestamp, unit, or other metadata through the mapping when the receiving application requires them.
Messages arrive more often than expected	Review the source item update interval and the mapping trigger. Each write to the Pulsar item causes a synchronous publish attempt.
Messages are delayed	The Connector creates and closes the client for each write and waits for the send result. Check broker response time, network latency, and the number of writes being generated.

The wording of the two Connector errors contains spelling mistakes in the current software. They are reproduced above so you can identify the exact messages shown by the Edge Portal.

If a problem continues, review the Connector, instance, item, and mapping errors. See Troubleshoot Connector, instance, item, and mapping errors.

apache pulsar connector jwt messaging producer topic troubleshooting

Contact Us