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 store the request message in the RabbitMQ broker. You then use a Message Processor to retrieve the message from the store before delivering it to the back-end service.

Let's get started!

Step 1: Set up the workspace

The following software and configurations are required to proceed with this tutorial:

• Visual Studio Code (VS Code): with the Micro Integrator extension installed.
• Java Development Kit (JDK): Ensure the JDK is properly configured in your system's PATH environment variable.
• Apache Maven: Ensure Apache Maven is installed and its path is correctly set within the system's PATH environment variable.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.

• 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.

1. Launch VS Code with the Micro Integrator extension installed.

2. Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.

   

3. Click Create New Project on Design View.

   

   Next, the Project Creation Form will be opened.

4. In the Project Creation Form, enter StoreAndForwardTutorial as the Project Name.

5. Provide a location under Select Project Directory.

   

6. Click Create.

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

Create a REST API

1. Go to MI Project Explorer > APIs.

   

2. Hover over APIs and click the + icon that appears to open the API Form.

   

3. Specify values for the required REST API properties:

   
   

   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.

   Click on the GET API resource under Available resources on the Service Designer.

   You will now see the graphical view of the HealthcareAPI with its default API Resource.

   Click the Edit icon to edit the API resource.

   

   Specify values for the required resource properties:

   Property	Description
   URI-Template	/categories/{category}/reserve This defines the request URL format. In this case, the full request URL format is http://host:port/categories/{category}/reserve where {category} is a variable.
   Url Style	URI_TEMPLATE
   Methods	POST This defines that the API resource only handles requests where the HTTP method is POST.

   

4. Click Update.

Create the Message Store

Now, let's create a message store artifact to represent the broker.

1. Go to MI Project Explorer > Message Stores.

   

2. Hover over Message Stores and click the + icon that appears to open the Message Store Form.

   

3. Create a RabbitMQ Message Store.

   

4. Specify values for the required Message Store properties:

   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.
   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.
   Routing Key	key	The exchange and queue binding value.
   User Name	user name	The user name to connect to the broker.
   Password	password	The password to connect to the broker.

5. Click Create.

Create new Endpoint

Let's create an Endpoint to represent the Hospital Service back-end service.

1. Navigate to the MI Project Explorer > Endpoints.

   

2. Hover over Endpoints and click the + icon that appears.

   

3. Next, select HTTP Endpoint type from the Create Endpoint Artifact interface.

   

4. Let's create the hospital service endpoint (HospitalServicesEP) using the following values:

   Property	Value	Description
   Endpoint Name	HospitalServicesEP	This is a single endpoint configured to forward requests to the relevant hospital by reading the hospital specified in the request payload.
   URI Template	http://localhost:9090/{uri.var.hospital}/categories/{uri.var.category}/reserve	The template for the request URL expected by the back-end service. The following two variables will be replaced by the corresponding values in the request message: {uri.var.hospital} {uri.var.category}
   Method	POST	Endpoint HTTP REST Method.

5. Click Create.

Create a Sequence

Let's create a Sequence that uses the message in the message store to send the request to the hospital service endpoint.

1. Navigate to the MI Project Explorer > Sequences.

   

2. Hover over Sequences and click the + icon that appears.

   

3. In the Sequence Form that appears, provide HospitalServiceSequence as the Name.

   

4. Click Create. Then you will be directed to the MI Overview page.

5. Click on HospitalServiceSequence under Sequences that you have just created to open its diagram view.

6. Next, add a Call mediator to the sequence. Click the + icon and select Call mediator from the Palette.

   

7. In the sequence palette specify the endpoint as HospitalServicesEP. Click Submit.

8. Click + icon after the Call mediator and add a Log mediator from the palette and specify the following details:

   Field	Value
   Log Category	INFO
   Log Level	FULL

9. Click + icon after the Log mediator and add a Drop mediator from the palette. Click Submit.

Create the Message Processor

Let's create a Message Sampling Processor to dispatch the request message from the Message Store to the HospitalServiceSequence.

Info

You can also use the Scheduled Message Forwarding Processor here and define the endpoint within the processor. The Message Sampling Processor is used because you need to perform mediation on the request message in the next tutorial.

1. Navigate to the MI Project Explorer > Message Processors.

2. Hover over Message Processors and click the + icon that appears.

3. Next, select Message Sampling Processor type from the Create New Message Processor interface.

   Property	Value	Description
   Message Processor Name	HospitalServiceMessageProcessor	The name of the scheduled message forwarding processor.
   Message Store	HospitalServiceMessageStore	The message store from which the scheduled message forwarding processor consumes messages.
   Processor State	Activate	Whether the processor needs to be activated or deactivated.
   Sequence Name	HospitalServiceSequence	The name of the sequence to which the message from the store needs to be sent.

4. Click Create.

Update the mediation flow

Let's update the REST API so that the client request is forwarded to the message store we created above.

1. Navigate to the MI Project Explorer > APIs > HealthcareAPI > /categories/{category}/reserve.

   

2. To add Property mediator click + icon and select Property mediator from the palette.

   Info

   This is used to extract the hospital name that is sent in the request payload.

3. With the Property mediator selected, access the Properties tab and give the following details:

   Property	Description
   Property Name	Enter uri.var.hospital
   Property Action	Enter set
   Property Data Type	STRING
   Property Scope	Enter default
   Value	Click the Ex button before the Value field. This specifies the value type as expression. Enter json-eval($.hospital_id) as the expression value. Note: This is the JSONPath expression that will extract the hospital from the request payload.

4. Click Submit.

5. Click + icon after the Property mediator and add a Store mediator by clicking Store Message from the palette.

6. With the Store mediator selected, access the Property tab and specify the following details:

   Field	Description
   Message Store	Select HospitalServiceMessageStore
   Description	Hospital Service Store

7. Click Submit.

8. Click + icon after the Store mediator and add a Respond mediator from the palette. Click Submit.

We have now finished creating all the required artifacts.

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

Prerequisites

Before you begin, install Micro Integrator on your machine:

1. Go to the WSO2 Micro Integrator web page, click Download, provide necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.

2. Extract the ZIP file. The extracted folder will be referred as the <MI_HOME> folder.

Once you have downloaded and set up the Micro Integrator locally, follow the steps given below. Use one of the below two methods.

1. Click on the Command Palette on the top of the VS Code.

2. Type > to show the available commands.

3. Select MI: Add MI server.

4. Select Add MI server.

5. Select the folder where <MI_HOME> is located. This wll be set as the current server path.

   

6. Run the project.

   Click the Build and Run icon located in the top right corner of the 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

1. Download the JAR file of the back-end service from here.
2. Open a terminal, navigate to the location where you saved the back-end service.

3. Execute the following command to start the service:

   java -jar Hospital-Service-JDK11-2.0.0.jar
   

Send the client request

Let's send a request to the API resource. You can use Postman or any other HTTP Client:

1. Open the Postman application. If you do not have the application, download it from here : Postman

2. Add the request information as given below and click the Send button.

   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 HealthcareAPI: http://:/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", "appointment_date": "2025-04-02" } This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and data of appointment.

   
   
   
   
   

If you want to send the client request from your terminal:

1. Install and set up cURL as your REST client.

2. Create a JSON file named request.json with the following request 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",
       "appointment_date": "2025-04-02"
   }
   

3. Open a command line terminal and execute the following command from the location where the request.json file you created is saved:

   curl -v -X POST --data @request.json http://localhost:8290/healthcare/categories/surgery/reserve --header "Content-Type:application/json"
   

Analyze the response

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

Now check the OUTPUT tab of VS code and you will see the following message:

[2024-07-26 11:45:56,798]  INFO {LogMediator} - {api:HealthcareAPI} To: http://www.w3.org/2005/08/addressing/anonymous, WSAction: , SOAPAction: , MessageID: urn:uuid:03d39a92-1727-40c7-80a6-3a0cba58e57f, correlation_id: 2a3b2350-5ef9-4e30-b5bd-7ec5a6fb0167_1aa41990-0b7f-4c1c-bbeb-23976344f792, Direction: request, 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}

You have now explored how the Micro Integrator can be used to implement store and forward messaging using a Message Store, Message Processors, and the Store Mediator.