Skip to main content

Build an Event-Driven Integration

TimeUnder 10 minutes
What you'll buildAn event-driven integration that consumes messages from Orders queue in RabbitMQ broker and processes them.

Event integrations are designed for reactive workflows triggered by messages from a broker. This quick start demonstrates the complete flow: creating a RabbitMQ message listener, adding an event handler to process messages, and implementing the integration logic executed when a message is received.

Prerequisites​

A working WSO2 Integrator environment.

You'll also need access to a RabbitMQ instance that is reachable over the internet. Have the following details ready:

  • The instance's host and port.
  • A username and password for the instance.
  • The instance's virtual host.
Get a free RabbitMQ instance

If you don't have a RabbitMQ instance, create a free one on CloudAMQP using the Little Lemur plan. Then open the instance and find its connection details under AMQP details. Use port 5672, and use the User & Vhost value as both the username and the virtual host.

Note

The cloud editor runs in WSO2 Cloud and cannot connect to a RabbitMQ instance running on localhost on your computer.

Step 1: Create the integration​

  1. On the project home page, click Create on Cloud.

    WSO2 Cloud project home showing the Create on Cloud optionWSO2 Cloud project home showing the Create on Cloud option
  2. The WSO2 Integrator cloud editor opens in your browser.

    WSO2 Integrator cloud editor landing page showing an empty integration and the Deploy to WSO2 Cloud panelWSO2 Integrator cloud editor landing page showing an empty integration and the Deploy to WSO2 Cloud panel
Note

The cloud editor creates a default integration for you, so you don't need to name it now. You can change its name when you deploy it. For more information, see Save and deploy.

Step 2: Add a RabbitMQ event listener​

  1. In the design view, click Add Artifact manually.

    Integration design view with the Add Artifact manually button highlightedIntegration design view with the Add Artifact manually button highlighted
  2. Select RabbitMQ under Event Integration.

    Artifacts page with RabbitMQ highlighted under Event IntegrationArtifacts page with RabbitMQ highlighted under Event Integration
  3. Set Host to your RabbitMQ instance's host, and Port to its port. The default RabbitMQ port is 5672.

  4. Set Queue Name to Orders.

  5. Click Create.

    Create RabbitMQ Event Integration form with Host, Port, and Queue Name setCreate RabbitMQ Event Integration form with Host, Port, and Queue Name set
  6. Under Listeners in the project explorer, select rabbitmqListener to open the Rabbitmq Listener Configuration page.

  7. Set Username and Password to your RabbitMQ instance's username and password.

  8. Set Virtual Host to your instance's virtual host. For CloudAMQP, this is the same as the username.

    Rabbitmq Listener Configuration page with Username, Password, and Virtual Host setRabbitmq Listener Configuration page with Username, Password, and Virtual Host set
  9. Scroll to the bottom of the page, and click Save.

    Bottom of the Rabbitmq Listener Configuration page with the Save button highlightedBottom of the Rabbitmq Listener Configuration page with the Save button highlighted

Step 3: Add onMessage event handler​

  1. Under Entry Points in the project explorer, select RabbitMQ Event Integration to open the service design view.

  2. Click + Add Handler.

  3. In the Select Handler to Add panel, select On Message.

    Select Handler to Add panel with On Message highlightedSelect Handler to Add panel with On Message highlighted
  4. Click Save.

    Configure On Message Handler panel with Format set to On Message and the Save buttonConfigure On Message Handler panel with Format set to On Message and the Save button

Step 4: Add message processing logic​

  1. Click + inside the onMessage flow.

    onMessage flow with the add node button highlighted below the Start nodeonMessage flow with the add node button highlighted below the Start node
  2. Select Call Function under Statement.

    Node panel with Call Function highlighted under StatementNode panel with Call Function highlighted under Statement
  3. Search for printInfo in the functions panel.

  4. In the search results, go to the Standard Library section and select the printInfo function under log.

    Functions panel search results with printInfo highlighted under log in the Standard Library sectionFunctions panel search results with printInfo highlighted under log in the Standard Library section
  5. Set Msg to Received order.

  6. Click Save.

    log:printInfo panel with Msg set to Received orderlog:printInfo panel with Msg set to Received order

Step 5: Run and test the integration​

  1. Click Run. The integration starts and listens for messages on the Orders queue.

  2. In CloudAMQP, open your instance and click RabbitMQ Manager. The RabbitMQ management UI opens in a new tab, already signed in.

  3. Click the Queues and Streams tab, and then click Orders in the Name column.

  4. On the Orders queue page, scroll down and click the Publish message section heading to open it.

  5. In Payload, enter any text, for example order 1.

  6. Click the Publish message button below the Payload box.

  7. Confirm the Debug Console shows a log line that ends with message="Received order".

    Debug Console showing the Received order log line after a message is publishedDebug Console showing the Received order log line after a message is published

Step 6: Deploy to WSO2 Cloud​

To deploy your integration to WSO2 Cloud from the cloud editor, see Save and deploy.

Source code​

View the generated Ballerina code

The steps above generate the following complete, runnable Ballerina program:

import ballerina/log;
import ballerinax/rabbitmq;

listener rabbitmq:Listener rabbitmqListener = new (host = "<your-rabbitmq-host>", port = 5672, username = "<your-username>", password = "<your-password>", virtualHost = "<your-vhost>");

@rabbitmq:ServiceConfig {queueName: "Orders"}
service rabbitmq:Service on rabbitmqListener {
remote function onMessage(rabbitmq:AnydataMessage message) returns error? {
do {
log:printInfo("Received order");
} on fail error err {
// handle error
return error("unhandled error", err);
}
}
}

Supported event sources​

BrokerBallerina Package
Apache Kafkaballerinax/kafka
RabbitMQballerinax/rabbitmq
MQTTballerinax/mqtt
Azure Service Busballerinax/azure.servicebus
Salesforceballerinax/salesforce
GitHub Webhooksballerinax/github

Learn more​

  • Kafka — Consume and produce Kafka messages
  • Azure Service Bus — Integrate with Azure Service Bus queues and topics
  • RabbitMQ — Full RabbitMQ listener and publisher reference
  • MQTT — Handle MQTT messages from IoT and messaging devices
  • CDC for PostgreSQL — React to database changes with change data capture