Skip to content

Solace Connector Reference

The following operations allow you to work with the Solace Connector. Click an operation name to see its parameters and notes.

To use the Solace connector, first create a connection to the broker, then reference that connection from each operation using the Connection (configKey) parameter.

Note

If a numeric parameter is given an invalid value, the connector logs a warning and falls back to that parameter's default instead of failing the mediation.


Connection configuration

The connection authenticates WSO2 Integrator: MI with the Solace PubSub+ broker and is shared by all operations. In the synapse configuration it is stored as a local entry containing a <solace.init> element.

Connection parameters

ParameterDescriptionRequiredDefault
connectionNameA unique name to identify the connection.Yes-
hostHost URL of the Solace broker, e.g. tcp://localhost:55555 or tcps://broker.example.com:55443 for TLS.Yestcp://localhost:55555
vpnNameThe Message VPN name.Yesdefault
authenticationSchemeHow the broker authenticates the connection: BASIC (username/password), CLIENT_CERTIFICATE (mutual TLS; username derived from the certificate CN), or OAUTH2 (access token / OIDC ID token).NoBASIC
usernameUsername for the broker. Required when authenticationScheme is BASIC.Conditional-
passwordPassword for the broker. Required when authenticationScheme is BASIC.Conditional-
apiProvidedUsernameOptional. Used only when the VPN is configured with allow-api-provided-username. For CLIENT_CERTIFICATE, leave blank to use the certificate CN; for OAUTH2, leave blank (identity comes from the token).No-
oauth2AccessTokenOAuth2 access token. Used when authenticationScheme is OAUTH2.No-
oidcIdTokenOIDC ID token, used in the OAuth client-role profile. Provide either this, an access token, or both.No-
oauth2IssuerIdentifierOptional issuer URI to disambiguate when the broker has multiple OAuth profiles.No-
clientNameUnique client name for the session. Auto-generated if not provided.No-
connectionTimeoutConnection timeout in milliseconds.No30000
readTimeoutRead timeout in milliseconds.No10000
connectRetriesNumber of initial connection retry attempts.No3
connectRetriesPerHostNumber of connection retries per host.No0
reconnectRetriesNumber of reconnection retry attempts after a connection loss.No3
reconnectRetryWaitWait time between reconnection retries in milliseconds.No3000
compressionLevelCompression level (0-9). 0 disables compression.No0

SSL/TLS Security (used with tcps:// hosts)

ParameterDescriptionRequiredDefault
sslTrustStorePathPath to the trust store containing CA certificates used to validate the broker.No-
sslTrustStorePasswordPassword for the trust store.No-
sslTrustStoreFormatTrust store format (JKS or PKCS12).NoJKS
sslKeyStorePathPath to the key store containing the client certificate and private key (for CLIENT_CERTIFICATE / mutual TLS).Conditional-
sslKeyStorePasswordPassword for the key store.No-
sslKeyStoreFormatKey store format (JKS or PKCS12).NoJKS
sslKeyPasswordPassword for the private key.No-
sslValidateCertificateWhether to validate the broker's certificate against the trust store. Set false only for self-signed brokers in dev/lab; disabling it removes protection against man-in-the-middle attacks, so never do so in production.Notrue
sslValidateCertificateDateWhether to validate the certificate expiration date.Notrue
sslValidateHostnameWhether to verify that the broker certificate's hostname matches the host you connect to. Disabling it defeats man-in-the-middle protection, so never do so in production.Notrue

sslValidateCertificateDate and sslValidateHostname apply only when sslValidateCertificate is enabled.

Secure Vault is supported for password, oauth2AccessToken, oidcIdToken, sslTrustStorePassword, sslKeyStorePassword, and sslKeyPassword; each accepts a plain value or a vault expression.

Advanced Message Options

ParameterDescriptionRequiredDefault
generateSendTimestampsAutomatically generate send timestamps on messages.Nofalse
generateSequenceNumbersAutomatically generate sequence numbers on messages.Nofalse
calculateMessageExpirationCalculate message expiration based on TTL.Nofalse

Sample connection (local entry)

<localEntry key="SOLACE_CONNECTION" xmlns="http://ws.apache.org/ns/synapse">
  <solace.init>
    <connectionType>SOLACE</connectionType>
    <host>tcp://localhost:55555</host>
    <vpnName>default</vpnName>
    <authenticationScheme>BASIC</authenticationScheme>
    <username>default</username>
    <password>default</password>
    <clientName>wso2mi-client</clientName>
    <name>SOLACE_CONNECTION</name>
  </solace.init>
</localEntry>

Publish and request-reply operations

publishMessage

publishMessage

Publishes a message to a topic or queue. Use DIRECT delivery for best-effort topic pub/sub, or PERSISTENT/NON_PERSISTENT for guaranteed delivery (required for queues).

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
destinationTypeTOPIC or QUEUE.YesTOPIC
destinationNameName of the topic or queue to publish to.Yes-
messageTypeTEXT, BYTES, or XML. JSON payloads are auto-detected and carried as TEXT.NoTEXT
deliveryModeDIRECT (TOPIC only), PERSISTENT, or NON_PERSISTENT. Queues require PERSISTENT or NON_PERSISTENT.NoDIRECT
correlationIdOptional trace ID echoed by any consumer that replies.No-
priorityMessage priority (0-255).No0
timeToLiveTime to live in milliseconds.No0
applicationMessageIdApplication-defined message ID.No-
applicationMessageTypeApplication-defined message type.No-
replyToDestinationTypeFor asynchronous reply-to: TOPIC or QUEUE where consumers should send replies.NoQUEUE
replyToDestinationNamePre-existing destination where replies should arrive. For synchronous request-reply use sendRequest instead.No-
userPropertiesKey-value pairs attached to the message for content-based routing and filtering.No-
dmqEligibleWhether the message is eligible for the Dead Message Queue if it cannot be delivered.Notrue
elidingEligibleWhether the message is eligible for eliding (broker may discard intermediate topic messages).Nofalse
waitForAckBlock for the broker ACK before returning. Applies only to PERSISTENT / NON_PERSISTENT delivery. Outcome exposed via solace.ack.status (ACK | NACK | TIMEOUT).Nofalse
ackTimeoutMax time in milliseconds to wait for the broker ACK when waitForAck is enabled.No10000
continueOnAckFailureWhen enabled, a NACK or ACK timeout does not throw; inspect solace.ack.status to branch. When disabled, failures go to the fault sequence.Nofalse
responseVariableVariable name where the publish result JSON is stored.NosolacePublishResponse

Returns a status object in the response variable ('${vars..payload}') and operation does not overwrite the message body.

Response fields: destination, destinationType, deliveryMode, messageType, ackStatus, ackReceived, correlationKey, error, publishedAt.

Sample configuration

<solace.publishMessage configKey="SOLACE_CONNECTION">
    <destinationType>QUEUE</destinationType>
    <destinationName>Q.orders</destinationName>
    <messageType>TEXT</messageType>
    <deliveryMode>PERSISTENT</deliveryMode>
    <correlationId>{${payload.orderId}}</correlationId>
    <waitForAck>true</waitForAck>
    <ackTimeout>5000</ackTimeout>
    <responseVariable>solacePublishResponse</responseVariable>
</solace.publishMessage>

sendRequest

sendRequest

Sends a request message and blocks until a reply is received on a temporary reply-to destination, or until the request times out (synchronous request-reply, requestor side).

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
destinationTypeTOPIC or QUEUE.YesTOPIC
destinationNameName of the topic or queue to send the request to.Yes-
messageTypeTEXT, BYTES, or XML.NoTEXT
requestTimeoutMaximum time to wait for a response in milliseconds.No30000
deliveryModeDIRECT (TOPIC only), PERSISTENT, or NON_PERSISTENT.NoDIRECT
applicationMessageIdApplication-defined message ID.No-
applicationMessageTypeApplication-defined message type.No-
userPropertiesKey-value pairs attached to the message.No-
responseVariableVariable name where the reply is stored.NosolaceResponse
overwriteBodyReplace the message body with the reply.Nofalse

Sample configuration

<solace.sendRequest configKey="SOLACE_CONNECTION">
    <destinationType>TOPIC</destinationType>
    <destinationName>{${"airline/request/seats/" + payload.flightNo}}</destinationName>
    <messageType>TEXT</messageType>
    <deliveryMode>DIRECT</deliveryMode>
    <requestTimeout>30000</requestTimeout>
    <responseVariable>solaceResponse</responseVariable>
    <overwriteBody>true</overwriteBody>
</solace.sendRequest>

sendReply

sendReply

Sends a reply to an inbound request message, using the reply-to destination and correlation ID taken from the current message context. Call this from a sequence driven by the Solace Inbound Endpoint (the replier side of request-reply).

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
deliveryModeDIRECT, PERSISTENT, or NON_PERSISTENT.NoDIRECT
messageTypeTEXT, BYTES, or XML.NoTEXT
applicationMessageTypeApplication-defined message type.No-
userPropertiesKey-value pairs attached to the reply.No-
responseVariableVariable name where the operation result is stored.NosolaceResponse

Returns a status object in the response variable and operation does not overwrite the message body.

Sample configuration

<solace.sendReply configKey="SOLACE_CONNECTION">
    <deliveryMode>DIRECT</deliveryMode>
    <messageType>TEXT</messageType>
    <applicationMessageType>SEAT_QUERY_REPLY</applicationMessageType>
    <responseVariable>solaceResponse</responseVariable>
</solace.sendReply>

Queue consumption operations

poll

poll

Synchronously polls a single message from a queue. Returns null on timeout.

Settlement: outside a transaction, the message is acknowledged on receipt (at-most-once). Inside beginTransaction/commit, settlement is deferred: commit acknowledges the message, rollback redelivers it (at-least-once). Manual ack/nack of polled messages is not supported.

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
queueNameName of the queue to poll.Yes-
pollTimeoutMaximum time to wait for a message in milliseconds.No5000
selectorOptional SQL-92 selector expression for filtering on headers and user properties, e.g. region = 'EU' AND priority > 5.No-
responseVariableVariable name where the result JSON is stored.NosolacePollResponse
overwriteBodyReplace the message body with the polled payload.Nofalse

Response fields: destination, received, timedOut, messageId, correlationId, payload, contentType.

Sample configuration

<solace.poll configKey="SOLACE_CONNECTION">
    <queueName>Q.orders</queueName>
    <pollTimeout>5000</pollTimeout>
    <responseVariable>solacePollResponse</responseVariable>
    <overwriteBody>true</overwriteBody>
</solace.poll>

browse

browse

Browses messages on a queue without consuming them. Live consumers continue to see the same messages.

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
queueNameName of the queue to browse.Yes-
maxMessagesMaximum number of messages to return.No10
browseTimeoutMaximum time to wait per message read in milliseconds. Browse stops once no message arrives within this window.No2000
selectorOptional SQL-92 selector expression for filtering on headers and user properties.No-
responseVariableVariable name where the result JSON is stored.NosolaceBrowseResponse
overwriteBodyBrowse returns messages via the response variable; this flag is unused.Nofalse

Response fields: destination, messageCount, messages (array of message summaries with payload and headers).

Sample configuration

<solace.browse configKey="SOLACE_CONNECTION">
    <queueName>Q.orders</queueName>
    <maxMessages>10</maxMessages>
    <browseTimeout>2000</browseTimeout>
    <responseVariable>solaceBrowseResponse</responseVariable>
    <overwriteBody>true</overwriteBody>
</solace.browse>

Guaranteed message settlement operations

These operations settle a message that was delivered by the Solace Inbound Endpoint. They require the inbound endpoint to be configured with solace.autoAck=false, and must be called from the inbound's mediation sequence.

acknowledgeMessage

acknowledgeMessage

Acknowledges the inbound message so the broker can remove it from the queue (successful processing).

ParameterDescriptionRequiredDefault
descriptionOptional description of the operation.No-
responseVariableVariable name where the operation result is stored.NosolaceAckResponse

Returns a status object in the response variable and operation does not overwrite the message body.

Sample configuration

<solace.acknowledgeMessage>
    <responseVariable>solaceAckResponse</responseVariable>
</solace.acknowledgeMessage>

nackMessage

nackMessage

Negatively acknowledges the inbound message. The inbound endpoint must declare the required settlement outcomes (FAILED, REJECTED) on its consumer flow.

ParameterDescriptionRequiredDefault
outcomeTypeFAILED (broker redelivers, subject to max-redelivery, then DMQ) or REJECTED (broker routes immediately to the DMQ, otherwise discards).YesFAILED
descriptionOptional description of the operation.No-
responseVariableVariable name where the operation result is stored.NosolaceNackResponse

Returns a status object in the response variable and operation does not overwrite the message body.

Sample configuration

<solace.nackMessage>
    <outcomeType>REJECTED</outcomeType>
    <responseVariable>solaceNackResponse</responseVariable>
</solace.nackMessage>

Local transaction operations

Group multiple publishMessage calls (and deferred settlement of poll) into a single atomic unit. Start with beginTransaction, then end with commit or rollback.

beginTransaction

beginTransaction

Starts a new local transaction on the Solace connection. Subsequent publishMessage/poll calls participate atomically.

ParameterDescriptionRequiredDefault
configKeyThe Solace connection to use.Yes-
transactionTimeoutMillisAuto-rollback after this many milliseconds if commit/rollback is not reached. Prevents leaks from forgotten or faulted sequences.No60000

Sample configuration

<solace.beginTransaction configKey="SOLACE_CONNECTION">
    <transactionTimeoutMillis>30000</transactionTimeoutMillis>
</solace.beginTransaction>

commit

commit

Commits the current local transaction, finalizing all publishes and deferred settlements made during the transaction.

ParameterDescriptionRequiredDefault
descriptionOptional description of the operation.No-

Sample configuration

<solace.commit/>

rollback

rollback

Rolls back the current local transaction, discarding all publishes and redelivering any deferred-settlement messages.

ParameterDescriptionRequiredDefault
descriptionOptional description of the operation.No-

Sample configuration

<solace.rollback/>