Skip to main content
Feedback

Solace PubSub+ – Partner connection

Updated 

The Solace PubSub+ - Partner connection specifies how to connect to a PubSub+ event broker.  The connection can be reused for multiple connection operations that use the same broker.

Connection tab

If using a Solace Cloud broker, the connection properties can be found by:

  1. Navigating to the Cluster Manager in the PubSub+ Platform.
  2. Selecting a event broker service.
  3. Clicking the Connect tab.
  4. Expanding the Solace Messaging section.

Host - The host address to the PubSub+ event broker.  If there are multiple hosts to provide high availability, this field can be a comma-separated protocol://host:port list. For instance, tcp://primaryHost:primaryPort,tcp://backupHost:backupPort

Message VPN Name - The name of the Message VPN. (For larger enterprises, Message VPNs separate a single event broker into multiple logical parts.)

Client Username - A username that is authorized to connect to the broker.

Password - The password associated with the provided client username.

Custom Properties - Any additional properties that need to be set for the connection. Available properties can be found in the Reference Guide. Note that Client channel is the only supported complex property. Use "client_channel" as the key and a JSON formatted string as the value. For instance, { “connectRetries”: 3, “reconnectRetries”: 2 }.

This table also accepts the connector's own properties, such as the SHARE_PUBLISHER_SESSION and SHARED_PUBLISHER_SESSION_TTL_SECS properties that control publisher connection reuse. These are interpreted by the connector itself. They are not JCSMP properties and they are not passed through to the underlying Solace client, so they do not appear in the reference guide linked above. See the Shared publisher sessions section below.

Proxy Configuration

The connector supports HTTP proxy configuration for Solace broker connections. To enable proxy support:

  1. Configure your proxy settings at the basic runtime/runtime cluster level in the Boomi platform.

  2. Set the container property com.boomi.connector.solace.honor.proxy.settings=true on your basic runtime.

note

Proxy support is disabled by default for backward compatibility. The connector will only honor proxy settings when explicitly enabled through the container property.

API Token - An Event Portal token with read permissions. The PubSub+ Connector uses this token to import event-driven architecture artifacts like schemas and topic strings from the Event Portal, accelerating development and applying best practices.

API Version - To select a specific version of the Event Portal API used for the imports. PubSub+ Event Portal 2.0 is selected by default. The steps to generate the API Token for either of the versions remains the same. More about PubSub+ Event Portal versions can be found here.

To get an Event Portal V1/V2 token:

  1. Navigate to Create Token in the PubSub+ Platform.
  2. Name the token "Event Portal Read Access".
  3. Under the Event Portal Permission Set, select the Read toggle.
  4. Click Generate Token at the bottom of the screen.
  5. Copy the Event Portal Token to a secure location. It cannot be recreated.

Shared publisher sessions

By default, every concurrent invocation of a Send operation opens its own connection to the event broker and closes it shortly after the invocation completes. A process that runs Send operations frequently, or that runs many of them concurrently, therefore creates and closes broker connections at a high rate.

The connector can instead keep a long-lived publisher connection and share it across concurrent Send operations that use the same connection settings. This lowers the rate at which connections are established and closed, and removes the cost of establishing a connection on each invocation. The feature is disabled by default and is enabled per connection, using the following keys in the Custom Properties table of the connection.

SHARE_PUBLISHER_SESSION

Set to true to let concurrent Send operations share a single publisher connection to the broker. The default is false, which keeps the previous behavior of one connection per Send invocation.

Sharing applies only to the Direct and Persistent Non-Transacted Send modes. Persistent Transacted Send, Get and Request operations always use an exclusive connection, because their transactions, consumer flows and subscriptions cannot be shared.

Send operations share a connection only when they resolve to the same host, message VPN, client username, password and custom properties, and when they run in the same JVM. A single-node basic runtime is one JVM, while each runtime cluster node and each execution worker is a separate JVM that maintains its own shared connection. Operations that differ in any of those values continue to use separate connections.

SHARED_PUBLISHER_SESSION_TTL_SECS

The idle timeout of a shared publisher connection, in seconds. The default is 300 (5 minutes). The timer starts when the last Send operation using the connection completes, and it is cancelled if another Send operation claims the connection before the timeout elapses. A value that is not a positive integer is ignored: the connector logs a warning and uses the default.

This property only takes effect when SHARE_PUBLISHER_SESSION is true. It is read when a shared connection is created, so setting it while sharing is disabled has no effect on its own.

Important

A shared connection is closed when its idle timeout elapses, and not when the process that used it finishes. It therefore remains established on the broker for up to the configured idle timeout, 5 minutes with the default value, after the last message is published. This also applies when the process or the deployment using it is stopped or undeployed: the connection is released once the idle timeout elapses, or when the Atom itself is stopped. Take this into account when you plan a redeployment, when you count the client connections a Message VPN carries, and when you choose the idle timeout value.

Recommended settings:

  • Set the idle timeout longer than the interval at which the publishing process runs, so that the connection survives the idle gaps between executions. A value shorter than that interval reopens a connection on every execution and provides little benefit.

  • The default of 300 seconds suits processes that publish continuously or every few minutes. Increase it (for example, to 1800) for processes that publish in bursts that are spaced further apart, when holding a broker connection open between those bursts is acceptable.

  • Lower it when connections should be given back to the broker promptly after a process goes idle, keeping in mind that a lower value trades away some of the connection reuse the feature provides.

  • Each shared connection that is held open counts against the client connection limits of the Message VPN and of the event broker service. Weigh the idle timeout against the number of basic runtimes, runtime clusters, execution workers and distinct connections that publish to the same broker.

  • A shared connection whose transport has failed permanently, meaning the broker disconnected and the client gave up after exhausting its reconnect retries, is discarded and replaced on the next Send invocation. A transparent reconnect does not discard the shared connection.

Performance considerations

A shared connection carries the traffic of every Send operation that publishes through it at the same time, so the publishing limits of the session apply to those operations collectively instead of to each operation on its own. The limit to review is the publisher acknowledgement window, which bounds how many guaranteed messages can be in flight without an acknowledgement from the broker. The connector sets PUB_ACK_WINDOW_SIZE to 5 for every connection by default, and with sharing enabled that window is consumed by all of the Persistent Non-Transacted Send operations that publish through the shared connection. Once it is full, publishing waits for acknowledgements to free space in it, so a window that is adequate for a single operation can limit the throughput of several concurrent ones.

Tune the window for the load that the shared connection carries:

  • Set PUB_ACK_WINDOW_SIZE in the Custom Properties table of the connection to a value that reflects how many Send operations publish concurrently through the shared connection and how many documents they send per execution. Validate the value against your expected peak load, because a window that is larger than necessary keeps more unacknowledged messages in flight.

  • A Persistent Non-Transacted Send operation waits for the broker to acknowledge the documents it published before it completes, and it reports an application error for a document that is not acknowledged in time. A window that is too small for the load makes that wait longer on a contended shared connection. A larger window, a lower number of concurrent operations, or smaller batches all reduce that risk.

  • Direct mode Send operations do not use publisher acknowledgements, so this window does not apply to them.

  • Tuning the window changes the connection settings, and connections that differ in their custom properties do not share a session. Apply the value to the connection whose Send operations should share a publisher session.

OAuth connection

The Solace PubSub+ connector supports OAuth 2.0 authentication through two configuration
methods:

OAuth proxy configuration

The connector supports HTTP proxy configuration for OAuth token requests and refresh operations when using the Custom OAuth 2.0 Configuration (Legacy) method. To enable OAuth proxy support:

  1. Configure your proxy settings at the runtime/runtime cluster level in the Boomi Platform.

  2. Set the container property com.boomi.connector.solace.oauth.honor.proxy.settings=true on your runtime.

  3. Use the Custom OAuth 2.0 Configuration method described below (proxy settings do not apply to the Standard OAuth 2.0 Configuration tab).

note

OAuth proxy support is disabled by default for security and backward compatibility and
is independent of the general Solace connection proxy setting. The connector will only honor
proxy settings for OAuth operations when explicitly enabled through the container property
and when using custom OAuth configuration properties.

Use the OAuth 2.0 configuration tab for streamlined authentication setup that follows Boomi Connector SDK standards. This method provides platform-managed token handling and supports the following grant types:

Grant types

  • Client credentials
  • Authorization code

Configuration

  1. Select OAuth 2.0 tab in the connection configuration
  2. Choose the appropriate Grant Type
  3. Configure the required OAuth parameters as prompted by the UI
  4. Set AUTHENTICATION_SCHEME to AUTHENTICATION_SCHEME_OAUTH2 in the Custom Properties section

Token Refresh: The Boomi Platform automatically handles the actual OAuth token refresh operations. The connector fetches tokens from the platform at regular intervals, with a default interval of 5 minutes. Custom fetch intervals can be configured using OAUTH2_REFRESH_BUFFER_TIME and OAUTH2_REFRESH_BUFFER_TIMEUNIT properties in the Custom Properties section to control how frequently the connector retrieves updated tokens from the platform.

note

When using the standard OAuth 2.0 configuration tab, the AUTHENTICATION_SCHEME
property must be explicitly set to AUTHENTICATION_SCHEME_OAUTH2 in the Custom Properties
section. The standard OAuth 2.0 tab is used as a fallback when custom OAuth properties
(OAUTH2_REFRESH_TOKEN or OAUTH2_CLIENT_SECRET) are not configured in the Custom
Properties section.

Proxy Configuration: OAuth proxy settings (com.boomi.connector.solace.oauth.honor.proxy.settings) do not apply to this configuration method as token management is handled by the Boomi Platform,
which is automatically tuned to handle proxy configuration.

Configuration Priority: The connector uses the following priority when determining OAuth
configuration:

  1. Custom Properties - If OAUTH2_REFRESH_TOKEN or OAUTH2_CLIENT_SECRET are
    configured in Custom Properties, these take precedence

  2. Standard OAuth 2.0 tab - Used as fallback when custom OAuth properties are not configured and AUTHENTICATION_SCHEME is set to AUTHENTICATION_SCHEME_OAUTH2

Custom OAuth 2.0 configuration (Legacy)

For advanced use cases or backward compatibility, you can configure OAuth 2.0 authentication
using custom properties by setting the AUTHENTICATION_SCHEME property as AUTHENTICATION_SCHEME_OAUTH2 in the Custom Properties section.

note

If you need OAuth operations to use proxy settings, you can enable the com.boomi.connector.solace.oauth.honor.proxy.settings container property.

Custom OAuth 2.0 token setup

Access Token: Provides the property OAUTH2_ACCESS_TOKEN with a valid (non-expired) access token.

Token Refresh: RFC 6749 The OAuth 2.0 Authorization Framework, Refreshing an Access Token

If the access token is temporary (that is, it has an expiration date) and you wish to avoid
connection disruptions, provide the following properties in Custom properties in addition to
the access token. This enables the connector to automatically refresh the token, ensuring a
consistent connection:

  • Refresh Token URL as OAUTH2_REFRESH_TOKEN_URL

  • Client ID as OAUTH2_CLIENT_ID

  • Refresh Token as OAUTH2_REFRESH_TOKEN

Disclaimer

Our system does not retain fetched access or refresh tokens due to environmental constraints. In the event of a connector restart, the original user-provided refresh token is used to reestablish the connection. If this token has expired or is invalid, the connector may fail to connect. For a more long-lasting stable connection, consider adopting the Client Credentials strategy outlined below.

Client Credentials Grant: RFC 6749 The OAuth 2.0 Authorization Framework, Client
Credentials Authorization Grant

If you prefer the application to fetch the Access token on your behalf using the client credentials grant, provide the following properties:

  • OAuth Token provider URL as OAUTH2_TOKEN_PROVIDER_URL

  • Client ID as OAUTH2_CLIENT_ID

  • Client Secret as OAUTH2_CLIENT_SECRET (You might choose to select the encrypted option for this sensitive data)

The connector will handle the token retrieval for you, so no need to provide the access token.

Optionally, for additional parameters to the token request, you can provide:

  • Scope as OAUTH2_SCOPE

  • Resource as OAUTH2_RESOURCE

  • Audience as OAUTH2_AUDIENCE

Token refresh buffer

The token is refreshed periodically based on a specified buffer time or percentage relative to
the access token's lifespan. By default, the buffer is set to 30% of the access token's lifetime.

To customize the buffer, you have the following options:

  1. Set a specific buffer time:
  • Time Unit as OAUTH2_REFRESH_BUFFER_TIMEUNIT
  • Absolute Time as OAUTH2_REFRESH_BUFFER_TIME
  1. Define a custom buffer percentage:
  • OAUTH2_REFRESH_BUFFER_PERCENTAGE (for example, set to 0.5 for 50% buffer)

If neither of these options is configured, the default buffer percentage of 30% will be applied.

SSL verification

If you provide the OAuth server URL or Refresh token server URL and wish to disable SSL
verification, set SSL_VALIDATE_CERTIFICATE as false.

On this Page