How to Store and Forward Messages for Guaranteed Delivery¶

What you'll build¶

Store and forward messaging is used to serve traffic to back-end services that can only accept request messages at a given rate. This method also ensures guaranteed delivery of messages. Messages are never lost since they are stored in the message store and available for future reference.

In this tutorial, instead of sending the request directly to the back-end service, you will store the request message in the RabbitMQ Message Store. You will then use a Message Processor to retrieve the message from the store and deliver it to the back-end service.

Let's get started!¶

Step 1: Set up the workspace¶

You need Visual Studio Code (VS Code) with the Micro Integrator for VS Code extension installed.

Info

See the Install Micro Integrator for VS Code documentation to learn how to install Micro Integrator for VS Code.

RabbitMQ: Install and setup Micro Integrator with RabbitMQ.

Step 2: Develop the integration artifacts¶

Create an integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter StoreAndForwardTutorial as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create a REST API¶

Go to MI Project Explorer and click + button to add artifact.
In the Add Artifact interface, under Create an Integration, click on API. This opens the API Form.

Enter the details given below to create a new REST API.

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare`.

Click Create. This will open the Service Designer interface.

You can now start configuring the API resource.
On the Service Designer, click on the three dots (⋮) and then Edit to access the Properties of the default API resource.

Enter the following details:

Property	Value	Description
Resource Path	`/categories/{category}/reserve`	The request URL should match this resource path. The `{category}` variable will be replaced with the value sent in the request.
Methods	`POST`	This API resource will accept POST requests.

Click Update.

Create the Message Store¶

Now, let's create a message store artifact that connects to the RabbitMQ broker to store the messages.

What is a Message Store?

A Message Store in WSO2 Micro Integrator (WSO2 MI) is a persistence layer used to temporarily hold messages for later processing. It acts as a buffer between message producers and consumers, enabling asynchronous message handling, retries, and reliable delivery. To learn more, see the Message Stores and Processors documentation.

In the MI Project Explorer click on + Add artifact.
Click + View More under Create an Integration.
Select Message Store under Other Artifacts to open the Message Store Form.
Select RabbitMQ Message Store.

Enter the following details to create a new RabbitMQ message store.

Note

In this tutorial, you will use a local RabbitMQ broker with the default configurations. If you plan to use a different RabbitMQ broker, update the following fields accordingly. Refer to the RabbitMQ Message Store documentation for more details and configuration options.

Property	Value	Description
Message Store Name	`HospitalServiceMessageStore`	The name of the message store.
RabbitMQ Server Host Name	`localhost`	The address of the RabbitMQ broker
RabbitMQ Server Port	`5672`	The port number of the RabbitMQ message broker.

Enter the following details in the Miscellaneous Properties section.

Property	Value	Description
RabbitMQ Queue Name	`HospitalServiceMessageStoreQueue`	The queue to which the subscription is created.
RabbitMQ Exchange Name	`exchange`	The name of the RabbitMQ exchange to which the queue is bound.
User Name	`guest`	The user name to connect to the broker.
Password	`guest`	The password to connect to the broker.

Click Create.

Update the mediation flow¶

Let’s update the REST API so that incoming client requests are forwarded to the Message Store you created earlier.

Navigate to MI Project Explorer > APIs > HealthcareAPI > /categories/{category}/reserve to open the Resource View.
Click on the + icon on the canvas to open the Mediator Palette. In the next step, you will add a Store mediator to store the incoming message in the Message Store you configured earlier.
Select the Store Message mediator under Mediators.
Select HospitalServiceMessageStore as the Message Store in the Add Store Mediator pane, and click Add to insert it into the integration flow.
Click the + icon after the Store mediator, and add a Respond mediator from the Mediator Palette to send a response back to the client.

You have now completed the integration flow that stores the message sent by the client in the configured message store. Next, we’ll create the integration flow that will be executed when the Message Processor retrieves a message from the store.

Create a Sequence¶

Let's create a sequence that will use the messages saved in the message store and send them to the hospital service backend. The sequence defines the integration flow that will be executed when the message processor picks up a message. You will link this sequence when creating the message processor later.

In the MI Project Explorer click on + Add artifact.
Click + View More under Create an Integration.
Select Sequence under Other Artifacts to open the Sequence Form.
In the Sequence Form that appears, provide HospitalServiceSequence as the Name, and click Create. This will open the Sequence View, where you can design the integration flow.

In the next steps, you will design the integration flow to call the hospital service backend and log the response it returns.
Click on the + icon on the canvas to open the Mediator Palette, to add the HTTP POST operation to call the hospital service backend.
Search for post in the Mediator Palette, and select the HTTP POST operation.
Click + Add new connection to create a new connection.
Select HTTP and fill in the following details to create a connection to hospital service backend. Finally, click Add in the Add New Connection form to create the connection.

Property Value

Connection Name HospitalConnection

Base URL http://localhost:9090
Provide /${payload.hospital_id}/categories/${params.pathParams.category}/reserve as the Relative Path, and click Add to add the operation to the integration flow.

Note

You can leave the rest of the configurations as default: Content Type set to JSON, Request Body as ${payload}, and Overwrite Message Body checked.
Click on the + icon after the HTTP POST operation, and select the Log mediator from the Mediator Palette to log the response received from the hospital backend service.
Provide Payload: ${payload} as the Message in the Add Log Mediator pane, and click Add to insert the Log mediator into the integration flow.
Finally, click on the + icon after the Log mediator, select the Drop mediator from the Mediator Palette, and click Add to add it to the integration flow.

You have now completed the integration flow that will be executed when the message processor picks up a message.
In the next step, you will create a Message Processor that will pick messages from the Message Store configured in the previous step.

Create the Message Processor¶

You need to create a Message Sampling Processor, which will retrieve messages from the Message Store and forward them to a specified sequence. In this tutorial, the messages will be dispatched to the HospitalServiceSequence created in the previous step.

What is a Message Processor?

A Message Processor in WSO2 Micro Integrator (WSO2 MI) is a background task that retrieves messages from a Message Store and forwards them to a defined sequence for processing. It supports scheduled, asynchronous, and reliable message delivery which is useful for store-and-forward patterns and retry mechanisms. To learn more, see the Message Stores and Processors documentation.

In the MI Project Explorer click on + Add artifact.
Click + View More under Create an Integration.
Select Message Processor under Other Artifacts to open the Message Processor Form.
Select Message Sampling Processor.

Enter the following details, and click Create to add a new Message Sampling Processor.

Property	Value	Description
Message Processor Name	`HospitalServiceMessageProcessor`	The unique name to identify the message processor. This processor will pick messages from the store and trigger the defined integration flow.
Message Store	`HospitalServiceMessageStore`	The message store where incoming requests are saved. The message processor continuously polls this store to fetch pending messages for processing.
Sequence Name	`HospitalServiceSequence`	The sequence that defines the integration logic to be executed once a message is fetched from the store. The message will be dispatched to this sequence for further processing.

You have now completed creating all the required artifacts for this integration.

Step 3: Start the RabbitMQ Broker¶

Be sure to install and start a RabbitMQ server instance before starting the Micro Integrator.

See the RabbitMQ documentation for more information on how to install and run the product.

Step 4: Build and run the artifacts¶

Now that you have developed an integration using the Micro Integrator for the Visual Studio Code plugin, it's time to deploy the integration to the Micro Integrator server runtime.

Click the Build and Run icon located in the top right corner of VS Code.

Step 5: Test the use case¶

Let's test the use case by sending a simple client request that invokes the service.

Start the back-end service¶

Download the JAR file of the back-end service from here.
Open a terminal, navigate to the location where you saved the back-end service.
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Send the client request¶

Now, let's test the integration service. For that, you can use the inbuilt try-it functionality in the MI for VS Code extension.

When you run the integration artifact as in Step 4, the Runtime Services interface is opened up. You can see all the available services.

Select the HealthcareAPI you have developed and test the resource using the following category and payload.

Category surgery

Payload


            {
                "patient":{
                    "name":"John Doe",
                    "dob":"1940-03-19",
                    "ssn":"234-23-525",
                    "address":"California",
                    "phone":"8770586755",
                    "email":"[email protected]"
                },
                "doctor":"thomas collins",
                "hospital_id":"grandoaks",
                "hospital":"grand oak community hospital",
                "cardNo":"7844481124110331",
                "appointment_date":"2025-04-02"
            }

This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and date of appointment.

Optionally, you can use Postman or cURL to send the request. You can refer to the following request information.

Method	`POST`
Headers	`Content-Type=application/json`
URL	`http://localhost:8290/healthcare/categories/surgery/reserve` The URI-Template format that is used in this URL was defined when creating the API resource: `http://host:port/healthcare/categories/{category}/reserve`
Body	`{ "patient": { "name": "John Doe", "dob": "1940-03-19", "ssn": "234-23-525", "address": "California", "phone": "8770586755", "email": "[email protected]" }, "doctor": "thomas collins", "hospital_id": "grandoaks", "hospital": "grand oak community hospital", "cardNo": "7844481124110331", "appointment_date": "2025-04-02" }`

Analyze the response¶

You will see the same request JSON as the response received by your HTTP Client.

Now, check the Output tab in VS Code. You should see a message similar to the following:

[2025-04-29 09:40:45,606]  INFO {LogMediator} - {api:HealthcareAPI POST /healthcare/categories/surgery/reserve} Payload: {"appointmentNumber":1,"doctor":{"name":"thomas collins","hospital":"grand oak community hospital","category":"surgery","availability":"9.00 a.m - 11.00 a.m","fee":7000.0},"patient":{"name":"John Doe","dob":"1940-03-19","ssn":"234-23-525","address":"California","phone":"8770586755","email":"[email protected]"},"fee":7000.0,"confirmed":false}

This message is printed by the Log mediator in the integration flow that is executed when the Message Processor retrieves a message from the Message Store.

You have now explored how WSO2 Micro Integrator can implement store-and-forward messaging using a RabbitMQ Message Store, a Message Processor, and the Store mediator.

Property	Value
Connection Name	`HospitalConnection`
Base URL	`http://localhost:9090`