Improve Kafka and RabbitMQ event integration guides and standardize artifact creation steps#549
Open
LakshanWeerasinghe wants to merge 7 commits into
Open
Improve Kafka and RabbitMQ event integration guides and standardize artifact creation steps#549LakshanWeerasinghe wants to merge 7 commits into
LakshanWeerasinghe wants to merge 7 commits into
Conversation
LakshanWeerasinghe
requested review from
KavinduZoysa,
NipunaRanasinghe,
anupama-pathirage and
rosensilva
as code owners
Contributor
|
Warning Review limit reached
More reviews will be available in 55 minutes and 53 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses rolling per-developer review limits. Reviews become available again as older review attempts age out of the rolling limit window. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
📝 WalkthroughWalkthroughDocumentation updates across WSO2 Integrator IDE artifact pages: the sidebar and two get-started pages rename "Event-Driven Integration" and "File-Driven Integration" to shorter forms. All artifact creation walkthroughs gain a new initial "open integration" step. Kafka and RabbitMQ event pages are substantially rewritten. HTTP service subsection headings are reformatted to bold text. ChangesTerminology Rename
Documentation Content Updates
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
en/docs/develop/integration-artifacts/event/azure-service-bus.md (1)
36-42:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winFix duplicate step numbering in the artifact creation flow.
Lines 36 and 38 both start with step "5." The sequence should read:
- Step 5: Click Create
- Step 6: WSO2 Integrator opens the service in the Service Designer...
- Step 7: Click + Add Handler to add event handlers.
🔢 Proposed fix for step numbering
5. Click **Create**. -5. WSO2 Integrator opens the service in the **Service Designer**. The canvas shows the attached listener pill and the **Event Handlers** section. +6. WSO2 Integrator opens the service in the **Service Designer**. The canvas shows the attached listener pill and the **Event Handlers** section.  -6. Click **+ Add Handler** to add event handlers. +7. Click **+ Add Handler** to add event handlers.🤖 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/azure-service-bus.md` around lines 36 - 42, The markdown document has duplicate step numbering where both the "Click **Create**" step and the "WSO2 Integrator opens the service in the **Service Designer**" step are numbered as step 5. Fix this by renumbering the second step (WSO2 Integrator opens the service...) from 5 to 6, and then update the final step (Click **+ Add Handler** to add event handlers) from 6 to 7 to maintain the correct sequential order throughout the artifact creation flow.en/docs/develop/integration-artifacts/service/graphql.md (1)
53-60:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winDuplicate step number: Step 6 appears twice; steps 7+ are mis-numbered.
Line 55 (newly renumbered) correctly sets step 6 as "WSO2 Integrator opens the service in the GraphQL diagram...". However, line 59 still has the old step 6 label for "Select + Create Operations", and line 60 is labeled step 7. After the step insertion, these should be steps 7 and 8.
🔧 Proposed fix
6. WSO2 Integrator opens the service in the **GraphQL diagram**, an interactive canvas where you define types, fields, and resolvers. The diagram shows the service card labeled with the base path (for example, `/graphql`) and a **+ Create Operations** button. Use the **Configure** button at the top right to edit service and listener settings, and the toolbar at the bottom left to zoom, fit, refresh, or export the diagram.  -6. Select **+ Create Operations** on the service card to add a **Query**, **Mutation**, or **Subscription** field. -7. Select the field row to open the **flow designer** and define the resolver logic. +7. Select **+ Create Operations** on the service card to add a **Query**, **Mutation**, or **Subscription** field. +8. Select the field row to open the **flow designer** and define the resolver logic.🤖 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/service/graphql.md` around lines 53 - 60, The documentation has duplicate step numbering where step 6 is listed twice. The first instance at the beginning of the paragraph describing the GraphQL diagram canvas is correctly numbered as step 6, but the subsequent steps labeled as "Select **+ Create Operations** on the service card" and "Select the field row to open the **flow designer**" are incorrectly numbered as 6 and 7 respectively. Renumber these last two steps to be 7 and 8 to maintain proper sequential ordering in the numbered list.
🤖 Prompt for all review comments with 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.
Inline comments:
In `@en/docs/develop/integration-artifacts/event/kafka.md`:
- Line 203: In the event handlers table where the `onConsumerRecord` entry is
defined, fix the subject-verb agreement error in the description. The current
text "New message arrive from the subscribed topics" has a singular subject with
a plural verb. Change it to either "New messages arrive from the subscribed
topics" (keeping plural form) or "A new message arrives from the subscribed
topics" (using singular form with singular verb). Choose whichever maintains
better consistency with the rest of the documentation.
In `@en/docs/develop/integration-artifacts/event/salesforce-events.md`:
- Around line 35-37: The step numbering in the document contains a duplicate:
the instruction "Click **Create**" is correctly labeled as step 5, but the
following instruction beginning with "WSO2 Integrator opens the service in the
**Service Designer**" is also incorrectly numbered as step 5. Change the step
number of the "WSO2 Integrator opens the service..." instruction from 5 to 6 to
maintain proper sequential numbering throughout the procedure.
In `@en/docs/develop/integration-artifacts/service/tcp.md`:
- Line 26: Step 2 in the TCP artifact creation documentation currently only
mentions the design view option for adding artifacts, which is inconsistent with
the wording used in other artifact pages like HTTP, GraphQL, and event
artifacts. Update step 2 to mention both the canvas and sidebar options for
adding artifacts to match the consistent pattern used across all other artifact
creation documentation pages.
---
Outside diff comments:
In `@en/docs/develop/integration-artifacts/event/azure-service-bus.md`:
- Around line 36-42: The markdown document has duplicate step numbering where
both the "Click **Create**" step and the "WSO2 Integrator opens the service in
the **Service Designer**" step are numbered as step 5. Fix this by renumbering
the second step (WSO2 Integrator opens the service...) from 5 to 6, and then
update the final step (Click **+ Add Handler** to add event handlers) from 6 to
7 to maintain the correct sequential order throughout the artifact creation
flow.
In `@en/docs/develop/integration-artifacts/service/graphql.md`:
- Around line 53-60: The documentation has duplicate step numbering where step 6
is listed twice. The first instance at the beginning of the paragraph describing
the GraphQL diagram canvas is correctly numbered as step 6, but the subsequent
steps labeled as "Select **+ Create Operations** on the service card" and
"Select the field row to open the **flow designer**" are incorrectly numbered as
6 and 7 respectively. Renumber these last two steps to be 7 and 8 to maintain
proper sequential ordering in the numbered list.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0944c2d1-9bef-4f80-8b51-32c08008cb27
⛔ Files ignored due to path filters (1)
en/static/img/develop/integration-artifacts/event/kafka/handler-config.pngis excluded by!**/*.png
📒 Files selected for processing (17)
en/docs/develop/integration-artifacts/automation.mden/docs/develop/integration-artifacts/event/azure-service-bus.mden/docs/develop/integration-artifacts/event/cdc-mssql.mden/docs/develop/integration-artifacts/event/cdc-postgresql.mden/docs/develop/integration-artifacts/event/github-webhooks.mden/docs/develop/integration-artifacts/event/kafka.mden/docs/develop/integration-artifacts/event/mqtt.mden/docs/develop/integration-artifacts/event/rabbitmq.mden/docs/develop/integration-artifacts/event/salesforce-events.mden/docs/develop/integration-artifacts/event/solace.mden/docs/develop/integration-artifacts/event/twilio.mden/docs/develop/integration-artifacts/service/graphql.mden/docs/develop/integration-artifacts/service/http.mden/docs/develop/integration-artifacts/service/tcp.mden/docs/get-started/build-event-driven-integration.mden/docs/get-started/build-file-driven-integration.mden/sidebars.ts
Broken links, images & orphan pages
Links/images come from one crawl of the production build (baseUrl-aware). Orphans are docs not referenced by Summary
Broken links & imagesIntroduced by this PRNo new broken link(s)/image(s) introduced by this PR. ✅ Already on
|
| # Kafka | ||
|
|
||
| Listen to messages from Apache Kafka topics with consumer group management, offset control, and schema-aware deserialization. | ||
| Kafka event integrations connect WSO2 Integrator to Apache Kafka topics as a consumer. Use them to build real-time data pipelines, fan out events across downstream systems, and trigger processing logic whenever messages arrive on a topic. This page covers how to create a Kafka service, configure the service and listener settings, define event handlers for message processing and error recovery, and apply error handling patterns. |
Contributor
There was a problem hiding this comment.
Suggested change
| Kafka event integrations connect WSO2 Integrator to Apache Kafka topics as a consumer. Use them to build real-time data pipelines, fan out events across downstream systems, and trigger processing logic whenever messages arrive on a topic. This page covers how to create a Kafka service, configure the service and listener settings, define event handlers for message processing and error recovery, and apply error handling patterns. | |
| Kafka event integrations connect WSO2 Integrator to Apache Kafka topics as a consumer. Use them to build real-time data pipelines, route and distribute events across downstream systems, and trigger processing logic whenever messages arrive on a topic. This page covers how to create a Kafka service, configure the service and listener settings, define event handlers for message processing and error recovery, and apply error handling patterns. |
Saying our integration fans events out is misleading IMO
Comment on lines
+115
to
+116
| import ballerinax/kafka; | ||
| import ballerina/log; |
Contributor
There was a problem hiding this comment.
Suggested change
| import ballerinax/kafka; | |
| import ballerina/log; | |
| import ballerina/log; | |
| import ballerinax/kafka; |
| topics: "orders" | ||
| }); | ||
|
|
||
| service on orderListener { |
Contributor
There was a problem hiding this comment.
Isn't this a repetition of the source code under Creating a Kafka service?
Comment on lines
+248
to
+261
| import ballerina/log; | ||
| import ballerinax/kafka; | ||
|
|
||
| type Order readonly & record { | ||
| int orderId; | ||
| string productName; | ||
| decimal price; | ||
| boolean isValid; | ||
| }; | ||
|
|
||
| listener kafka:Listener orderListener = new (kafka:DEFAULT_URL, { | ||
| groupId: "order-processor", | ||
| topics: "orders" | ||
| }); |
Contributor
There was a problem hiding this comment.
Suggested change
| import ballerina/log; | |
| import ballerinax/kafka; | |
| type Order readonly & record { | |
| int orderId; | |
| string productName; | |
| decimal price; | |
| boolean isValid; | |
| }; | |
| listener kafka:Listener orderListener = new (kafka:DEFAULT_URL, { | |
| groupId: "order-processor", | |
| topics: "orders" | |
| }); |
I feel like we are repeating the same source again and again while appending a bit more each time. Shall we add only the service code here?
| Use the flow canvas to add a conditional branch on the error type, log the failure, seek past the erroneous record using a Kafka **Caller** action, or forward the raw record to a dead letter topic. | ||
|
|
||
| ### Main configurations | ||
| <!-- TODO: Add screenshot of onError Flow Designer canvas --> |
Contributor
There was a problem hiding this comment.
Shall we add the needed SS's here
|
|
||
| | Field | Description | | ||
| |---|---| | ||
| | **Durable** | When `true`, the queue survives broker restarts. Defaults to `false`. | |
Contributor
There was a problem hiding this comment.
With 1.6.0 (pending), the default of durable is updated to true. Auto delete will be updated to false.
Suggested change
| | **Durable** | When `true`, the queue survives broker restarts. Defaults to `false`. | | |
| | **Durable** | When `true`, the queue survives broker restarts. Defaults to `true`. | |
| |---|---| | ||
| | **Durable** | When `true`, the queue survives broker restarts. Defaults to `false`. | | ||
| | **Exclusive** | When `true`, the queue is used by only one connection and is deleted when that connection closes. Defaults to `false`. | | ||
| | **Auto Delete** | When `true`, the queue is automatically deleted when the last consumer unsubscribes. Defaults to `true`. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | **Auto Delete** | When `true`, the queue is automatically deleted when the last consumer unsubscribes. Defaults to `true`. | | |
| | **Auto Delete** | When `true`, the queue is automatically deleted when the last consumer unsubscribes. Defaults to `false`. | |
- kafka: fix subject-verb agreement (New messages arrive) - kafka: reword intro (route and distribute events) - kafka: order ballerina/log import before ballerinax/kafka - rabbitmq: correct Durable (true) and Auto Delete (false) defaults for 1.6.0 - salesforce-events, azure-service-bus, graphql: fix duplicate step numbering - tcp: align "Add Artifact" step with other service pages (canvas and sidebar) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Summary
This PR improves the event integration documentation and standardizes the
"create artifact" workflow across service and event pages. The largest changes
are substantial rewrites of the Kafka and RabbitMQ guides, which now cover
service creation, listener configuration, event handlers, and error handling
patterns in full. Smaller consistency fixes are applied across the remaining
artifact pages and the sidebar.
What changed
Kafka and RabbitMQ guides (major rewrite)
just a listener.
onConsumerRecordandonErrorevent handlers, includingtyped payload binding, record metadata access, and validation/seek behavior.
current API.
handler-config.pngimage.Standardized artifact creation steps
IDE. If you don't have an integration yet, see Create a new integration..." —
and renumbered subsequent steps across:
automation,http,graphql,tcp,kafka,rabbitmq,mqtt,solace,twilio, and the CDC/Azure/Salesforce/GitHub event pages.
HTTP service page
###subheadings under the Ballerina Code tab to bold labels to fixsub-section navigation/anchor issues.
Navigation and titles
File-Driven Integration → File Integration.
new naming.
Summary by CodeRabbit