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¶ publishMessagePublishes 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¶ sendRequestSends 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¶ sendReplySends 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¶ pollSynchronously 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¶ browseBrowses 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¶ acknowledgeMessageAcknowledges 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¶ nackMessageNegatively 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¶ beginTransactionStarts 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¶ commitCommits 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¶ rollbackRolls 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/>