Skip to content

Add solace event integration content #507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
samithkavishke wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add solace event integration content #507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4069cf0
Add solace event integration content
samithkavishke May 26, 2026
f33d3b3
Change the order of the image in the solace
samithkavishke May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 82 additions & 61 deletions en/docs/develop/integration-artifacts/event/solace.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,28 +27,9 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic
| **Message VPN** | The message VPN to connect to. | `default` |
| **Destination** | Whether to consume from a **Queue** or a **Topic**. | `Queue` |

**When Destination is Queue:**

| Field | Description | Default |
|---|---|---|
| **Queue Name** | Queue to listen for incoming messages. | `test-queue` |
| **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` |

**When Destination is Topic:**

| Field | Description | Default |
|---|---|---|
| **Topic Name** | Topic to listen for incoming messages. | `test/topic` |
| **Subscriber Name** | Name to use for the subscription. | `default` |
| **Durable Subscriber** | When enabled, persists the subscription when the client disconnects. | — |
| **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` |

Expand **Advanced Configurations** to set the listener name and authentication method.
<Tabs>
<TabItem value="basic-authentication" label="Basic" default>

| Field | Description | Default |
|---|---|---|
| **Listener Name** | Identifier for the listener created with this service. | `solaceListener` |
| **Authentication method** | How to authenticate with the Solace broker. Select **Basic Authentication**, **Kerberos Authentication**, or **OAuth 2.0 Authentication**. | `Basic Authentication` |

**Basic Authentication fields:**

Expand All @@ -58,25 +39,65 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic
| **Password** | Password for broker authentication. |
| **Secure Socket** | SSL/TLS configuration for a secure connection. |

</TabItem>
<TabItem value="kerbos-authentication" label="Kerbos">
**Kerberos Authentication fields:**

| Field | Description | Default |
|---|---|---|
| **Service Name** | Kerberos service name. | `solace` |
| **JAAS Login Context** | JAAS login context name. | `SolaceGSS` |
| **Mutual Authentication** | Enable Kerberos mutual authentication. | Enabled |
| **JAAS Config Reload** | Enable automatic JAAS configuration reload. | — |
| **Secure Socket** | SSL/TLS configuration for a secure connection. | — |
| **JAAS Config Reload** | Enable automatic JAAS configuration reload. | - |
| **Secure Socket** | SSL/TLS configuration for a secure connection. | - |

</TabItem>

<TabItem value="oauth2-authentication" label="Oauth2">
Comment on lines +43 to +56

@coderabbitai coderabbitai Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix authentication label/value typos for consistency.

Line 43 uses kerbos-authentication and Kerbos, and Line 56 uses Oauth2. Please standardize to kerberos-authentication, Kerberos, and OAuth2 to match terminology used elsewhere in the page.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/docs/develop/integration-artifacts/event/solace.md` around lines 43 - 56,
Update the TabItem value and label strings to correct typos: change the TabItem
with value "kerbos-authentication" and label "Kerbos" to value
"kerberos-authentication" and label "Kerberos", and change the TabItem label
"Oauth2" to "OAuth2" so the TabItem components (value/label attributes) use
consistent spelling across the document.

**OAuth 2.0 Authentication fields:**

| Field | Description | Default |
|---|---|---|
| **Issuer** | OAuth 2.0 issuer identifier URI. | `https://auth.example.com` |
| **Access Token** | OAuth 2.0 access token for authentication. | — |
| **OIDC Token** | OpenID Connect ID token for authentication. | — |
| **Secure Socket** | SSL/TLS configuration for a secure connection. | — |
| **Access Token** | OAuth 2.0 access token for authentication. | - |
| **OIDC Token** | OpenID Connect ID token for authentication. | - |
| **Secure Socket** | SSL/TLS configuration for a secure connection. | - |

</TabItem>
</Tabs>


<Tabs>
<TabItem value="uiQueue" label="Queue" default>
**When Destination is Queue:**

| Field | Description | Default |
|---|---|---|
| **Queue Name** | Queue to listen for incoming messages. | `test-queue` |
| **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` |

</TabItem>
<TabItem value="uiTopic" label="Topic" default>
**When Destination is Topic:**

| Field | Description | Default |
|---|---|---|
| **Topic Name** | Topic to listen for incoming messages. | `test/topic` |
| **Subscriber Name** | Name to use for the subscription. | `default` |
| **Durable Subscriber** | When enabled, persists the subscription when the client disconnects. | - |
| **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` |

</TabItem>
</Tabs>
Comment on lines +70 to +91

@coderabbitai coderabbitai Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

In Docusaurus Tabs/TabItem (MDX), what happens if multiple sibling <TabItem> elements are marked with the default prop? Is only one allowed?

💡 Result:

If multiple sibling elements are marked with the default prop, Docusaurus does not specify that only one is allowed; instead it picks the first tab marked default (and otherwise falls back to the first tab). In the Tabs theme logic, the initial selected tab is computed by searching tab values for the first one with default and using tabValues.find((tabValue) => tabValue.default) ?? tabValues[0]—so when more than one TabItem has default, the earliest one in the rendered children order wins, and the others are ignored for the initial selection [1]. The docs also describe the mechanism as “adding default to one of the tab items” to override the “first tab displayed by default” behavior, which aligns with the “first default wins” implementation [2]. Answer: Yes, only one will effectively be chosen for the initial render—specifically the first sibling TabItem with default—but Docusaurus does not document/enforce an error for multiple defaults; they’re just resolved by “first default wins” [1].

Citations:

Remove the duplicate default prop from sibling <TabItem>
Docusaurus “first default wins” for initial tab selection, so multiple defaults won’t cause runtime ambiguity—but having two is redundant and confusing; keep only one <TabItem ... default> in the <Tabs> group.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/docs/develop/integration-artifacts/event/solace.md` around lines 70 - 91,
The two sibling TabItem components (TabItem value="uiQueue" and TabItem
value="uiTopic") both include the default prop; remove the duplicate by keeping
the default only on the primary TabItem (e.g., TabItem value="uiQueue") and
deleting the default prop from the other TabItem (TabItem value="uiTopic") so
only one TabItem has default in the Tabs group.


Expand **Advanced Configurations** to set the listener name and authentication method.

| Field | Description | Default |
|---|---|---|
| **Listener Name** | Identifier for the listener created with this service. | `solaceListener` |
| **Authentication method** | How to authenticate with the Solace broker. Select **Basic Authentication**, **Kerberos Authentication**, or **OAuth 2.0 Authentication**. | `Basic Authentication` |


4. Click **Create**.

5. WSO2 Integrator opens the service in the **Service Designer**. The canvas shows the attached listener pill, the destination name pill, and an empty **Event Handlers** section.
Expand All @@ -88,6 +109,8 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic
</TabItem>
<TabItem value="code" label="Ballerina Code">

Define a Solace listener and attach a service with the `@solace:ServiceConfig` annotation to consume messages:

```ballerina
import ballerinax/solace;
import ballerina/log;
Expand Down Expand Up @@ -132,7 +155,7 @@ In the **Service Designer**, click the **Configure** icon in the header to open
<Tabs>
<TabItem value="ui" label="Visual Designer" default>

![Solace Event Integration Configuration panel — service config and listener URL](/img/develop/integration-artifacts/event/solace/step-service-config.png)
![Solace Event Integration Configuration panel - service config and listener URL](/img/develop/integration-artifacts/event/solace/step-service-config.png)

The **Service Configuration** field accepts a record expression that sets the destination and message handling options.

Expand All @@ -155,6 +178,8 @@ The **Service Configuration** field accepts a record expression that sets the de
</TabItem>
<TabItem value="code" label="Ballerina Code">

Set the destination and message-handling options in the `@solace:ServiceConfig` annotation. Use `queueName` for a queue or `topicName` for a topic:

```ballerina
// Queue subscription
@solace:ServiceConfig {
Expand Down Expand Up @@ -183,27 +208,21 @@ In the **Solace Event Integration Configuration** panel, select **solaceListener
<Tabs>
<TabItem value="ui" label="Visual Designer" default>

<!-- ![Listener configuration — Message VPN, Auth, Secure Socket, Transacted, Client Id](/img/develop/integration-artifacts/event/solace/step-listener-config-1.png) -->
<!--
![Listener configuration — Allow Duplicate Client Id, Enable Dynamic Durables, Direct Transport, Direct Optimized, Localhost](/img/develop/integration-artifacts/event/solace/step-listener-config-2.png)

![Listener configuration — Connect Timeout, Read Timeout, Compression Level, Retry Config, Additional Values](/img/develop/integration-artifacts/event/solace/step-listener-config-3.png) -->

| Field | Description | Default |
|---|---|---|
| **Name** | Identifier for the listener. | `solaceListener` |
| **Url** | The Solace broker URL in the format `<scheme>://[username]:[password]@<host>[:<port>]`. Supported schemes: `smf` (plain-text) and `smfs` (TLS/SSL). Comma-separate multiple hosts for failover. Default ports: 55555 (standard), 55003 (compression), 55443 (SSL). | `smf://localhost:55554` |
| **Message VPN** | The name of the message VPN to connect to. | `default` |
| **Auth** | Authentication configuration. Supports basic authentication, Kerberos, and OAuth 2.0. For client certificate authentication, configure the `secureSocket.keyStore` field. | `{username: "default"}` |
| **Secure Socket** | SSL/TLS configuration for secure connections. | `{}` |
| **Transacted** | Enables transacted messaging. When `true`, messages are sent and received within a transaction context requiring explicit commit or rollback. Must be `false` for XA transactions. | — |
| **Client Id** | Client identifier. If not specified, a unique client ID is auto-generated. | — |
| **Client Description** | Human-readable description of the client connection. | — |
| **Allow Duplicate Client Id** | Whether to allow the same client ID across multiple connections. | — |
| **Enable Dynamic Durables** | Enables automatic creation of durable queues and topic endpoints on the broker. | — |
| **Direct Transport** | When `true`, uses direct (at-most-once) delivery. When `false`, uses guaranteed (persistent) delivery. Must be `false` for transacted sessions. | — |
| **Direct Optimized** | Optimizes message delivery in direct transport mode by reducing protocol overhead. Only applicable when **Direct Transport** is `true`. | — |
| **Localhost** | Local interface IP address to bind for outbound connections. | — |
| **Transacted** | Enables transacted messaging. When `true`, messages are sent and received within a transaction context requiring explicit commit or rollback. Must be `false` for XA transactions. | - |
| **Client Id** | Client identifier. If not specified, a unique client ID is auto-generated. | - |
| **Client Description** | Human-readable description of the client connection. | - |
| **Allow Duplicate Client Id** | Whether to allow the same client ID across multiple connections. | - |
| **Enable Dynamic Durables** | Enables automatic creation of durable queues and topic endpoints on the broker. | - |
| **Direct Transport** | When `true`, uses direct (at-most-once) delivery. When `false`, uses guaranteed (persistent) delivery. Must be `false` for transacted sessions. | - |
| **Direct Optimized** | Optimizes message delivery in direct transport mode by reducing protocol overhead. Only applicable when **Direct Transport** is `true`. | - |
| **Localhost** | Local interface IP address to bind for outbound connections. | - |
| **Connect Timeout** | Maximum time in seconds permitted for a JNDI connection attempt. Set to `0` to wait indefinitely. | `0.0` |
| **Read Timeout** | Maximum time in seconds permitted for reading a JNDI lookup reply from the host. | `0.0` |
Comment on lines 226 to 227

@coderabbitai coderabbitai Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Resolve conflicting timeout defaults between UI and code tables.

Line 226-227 says Connect Timeout/Read Timeout default to 0.0, while Line 272-273 lists 30.0/10.0. These defaults should match in both sections to prevent incorrect configuration expectations.

Also applies to: 272-273

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/docs/develop/integration-artifacts/event/solace.md` around lines 226 -
227, The Connect Timeout and Read Timeout defaults are inconsistent between the
two tables; update the first table entries for "Connect Timeout" and "Read
Timeout" (currently `0.0`) so they match the later table's defaults (`30.0` and
`10.0` respectively) used by the implementation/UI, or vice versa if the later
table is wrong—ensure both table rows with labels "Connect Timeout" and "Read
Timeout" contain the same default values across the document so the UI and code
documentation are consistent.

| **Compression Level** | ZLIB compression level. Valid range is 0–9, where `0` disables compression. Higher values improve compression at the cost of throughput. | `0` |
Expand All @@ -217,6 +236,8 @@ Click **Save Changes** to apply updates.
</TabItem>
<TabItem value="code" label="Ballerina Code">

Configure the listener by passing fields to the `solace:Listener` constructor:

```ballerina
listener solace:Listener solaceListener = check new (
url = "smf://localhost:55554",
Expand All @@ -238,20 +259,20 @@ listener solace:Listener solaceListener = check new (
|---|---|---|---|
| **url** | `string` | Required | Solace broker URL |
| **messageVpn** | `string` | `"default"` | Message VPN name |
| **auth** | `solace:BasicAuthConfig\|solace:KerberosConfig\|solace:OAuth2Config` | — | Authentication configuration |
| **secureSocket** | `solace:SecureSocket?` | — | SSL/TLS configuration |
| **transacted** | `boolean?` | — | Enable transacted messaging |
| **clientId** | `string?` | — | Client identifier |
| **clientDescription** | `string?` | — | Client description |
| **allowDuplicateClientId** | `boolean?` | — | Allow duplicate client IDs |
| **enableDynamicDurables** | `boolean?` | — | Auto-create durable endpoints |
| **directTransport** | `boolean?` | — | Use direct (at-most-once) delivery |
| **directOptimized** | `boolean?` | — | Optimize direct transport delivery |
| **localhost** | `string?` | — | Local interface IP address |
| **auth** | `solace:BasicAuthConfig\|solace:KerberosConfig\|solace:OAuth2Config` | - | Authentication configuration |
| **secureSocket** | `solace:SecureSocket?` | - | SSL/TLS configuration |
| **transacted** | `boolean?` | - | Enable transacted messaging |
| **clientId** | `string?` | - | Client identifier |
| **clientDescription** | `string?` | - | Client description |
| **allowDuplicateClientId** | `boolean?` | - | Allow duplicate client IDs |
| **enableDynamicDurables** | `boolean?` | - | Auto-create durable endpoints |
| **directTransport** | `boolean?` | - | Use direct (at-most-once) delivery |
| **directOptimized** | `boolean?` | - | Optimize direct transport delivery |
| **localhost** | `string?` | - | Local interface IP address |
| **connectTimeout** | `decimal` | `30.0` | Connection timeout in seconds |
| **readTimeout** | `decimal` | `10.0` | Read timeout in seconds |
| **compressionLevel** | `int` | `0` | ZLIB compression level (0–9) |
| **retryConfig** | `solace:RetryConfig?` | — | Retry configuration |
| **retryConfig** | `solace:RetryConfig?` | - | Retry configuration |

</TabItem>
</Tabs>
Expand All @@ -265,22 +286,22 @@ listener solace:Listener solaceListener = check new (

In the **Service Designer**, click **+ Add Handler**. The **Select Handler to Add** panel lists `onMessage` and `onError`.

**onMessage** — opens a configuration panel before saving:

![onMessage handler configuration panel](/img/develop/integration-artifacts/event/solace/step-add-handler.png)
**onMessage** - opens a configuration panel before saving:

![Service Designer showing the Solace Event Integration canvas](/img/develop/integration-artifacts/event/solace/adding-event-handler.png)

| Option | Description |
|---|---|
| **+ Define Payload** | Define the expected content type of the incoming message (e.g., a typed record). |

Click **Save** to add the handler.

**onError** — added directly without additional configuration.
**onError** - added directly without additional configuration.

</TabItem>
<TabItem value="code" label="Ballerina Code">

**onMessage handler** — called for each message received:
**onMessage handler** - called for each message received:

```ballerina
type TradeEvent record {|
Expand All @@ -306,7 +327,7 @@ service on solaceListener {
}
```

**onError handler** — called when message retrieval or processing fails:
**onError handler** - called when message retrieval or processing fails:

```ballerina
service on solaceListener {
Expand All @@ -329,6 +350,6 @@ service on solaceListener {

## What's next

- [Kafka](kafka.md) — consume messages from Apache Kafka topics
- [RabbitMQ](rabbitmq.md) — consume messages from RabbitMQ queues
- [Connections](../supporting/connections.md) — reuse Solace connection credentials across services
- [Kafka](kafka.md) - consume messages from Apache Kafka topics
- [RabbitMQ](rabbitmq.md) - consume messages from RabbitMQ queues
- [Connections](../supporting/connections.md) - reuse Solace connection credentials across services
Binary file added en/static/img/develop/integration-artifacts/event/solace/adding-event-handler.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified en/static/img/develop/integration-artifacts/event/solace/step-creation-form.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified en/static/img/develop/integration-artifacts/event/solace/step-service-config.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified en/static/img/develop/integration-artifacts/event/solace/step-service-designer.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading