Routing Requests Based on Message Content

In the Sending a Simple Message to a Service tutorial, we routed a simple message to a single endpoint in the back-end service. In this tutorial, we are building on the same sequence, by creating the mediation artifacts that can route a message to the relevant endpoint, depending on the content of the message payload.

When the client sends the appointment reservation request to the ESB, the message payload of the request contains the name of the hospital where the appointment needs to be confirmed. The HTTP request method that is used for this is POST. Based on the hospital name sent in the request message, the ESB should route the appointment reservation to the relevant hospital's back-end service.

For more details on how routing of messages within the ESB is done based on the message content, refer Content-Based Router Enterprise Integration Pattern.

Let's get started!

This tutorial contains the following sections:

Connecting to the back-end service

Let's create three different HTTP endpoints for the above services.

1. Right-click SampleServices in the Project Explorer and navigate to New -> Endpoint. Ensure Create a New Endpoint is selected and click Next.

2. Fill in the information as in the following table:

   Field	Value
   Endpoint Name	GrandOakEP
   Endpoint Type	HTTP Endpoint
   URI Template	http://localhost:9090/grandoaks/categories/{uri.var.category}/reserve
   Method	POST
   Static Endpoint	Select this option because we are going to use this endpoint only in this ESB Solution project and will not re-use it in other projects.
   Save Endpoint in	SampleServices

   

3. Click Finish.
4. Similarly, create the HTTP endpoints for the other two hospital services using the URI Templates given below:
   • ClemencyEP:  http://localhost:9090/clemency/categories/{uri.var.category}/reserve
   • PineValleyEP:  http://localhost:9090/pinevalley/categories/{uri.var.category}/reserve

You have now created the three endpoints for the hospital  backend services that will be used to make appointment reservations.

Mediating requests to the back-end service

To implement the routing scenario, let's update the REST API we created in the previous section by adding a new API resource. We will then use a Switch mediator to route the message to the relevant back-end service based on the hospital name that is passed in the payload of the request message. 

Let’s update the REST API we created in the previous tutorial using WSO2 EI Tooling.

1. In the REST API configuration, select API Resource in the API palette and drag it onto the canvas just below the previous API resource that was created.
   

2. Click the API Resource you just added to access the Properties tab and fill in the following details:

   Url Style	Click in the Value field, click the down arrow, and select URI_TEMPLATE  from the list.
   URI-Template	Enter /categories/{category}/reserve
   Methods	Set the value of Post to true.

   

3. Drag a Property Mediator from the Mediators palette to the In Sequence of the API resource and name it Get Hospital.
   This is used to extract the hospital name that is sent in the request payload.

4. With the Property mediator selected, access the Properties tab and fill in the following details:

   Property Name	New Property...
   New Property Name	Hospital
   Property Action	set
   Value Type	EXPRESSION
   Value Expression	Click Value field of Value Expression in the Property tab and add the following expression: json-eval($.hospital) This is the  JSONPath expression that will extract the hospital from the request payload.

5. Add a Switch mediator from the Mediator palette just after the Property Mediator. 

6. Right-click the Switch mediator you just added and select Add/Remove Case to add the number of cases you want to specify.
   
   In this scenario, we are assuming there are three different hospitals, hence there are three cases. 

7. Enter 3 for Number of branches and click OK. 
    

8. With the Switch mediator selected, go to the Properties tab, and fill in the details given below:

   Source XPath

   The Source XPath field is where we specify the XPath expression, which obtains the value of Hospital that we stored in the Property mediator. Follow the steps given below to specify the expression: Click in the Value field of the Source XPath property. Click the browse (...). Enter get-property('Hospital') and overwrite the default expression. Click OK. For more information on get-property(), see XPath Extension Functions.

   Case Branches

   Follow the steps given below to add the case branches: Click in the Value field of the Case Branches property. Click the browse (...). Change the RegExp values as follows: Case 1: grand oak community hospital Case 2:  clemency medical center Case 3:  pine valley community hospital Click OK.

9. Let's add a Log mediator to print a message indicating to which hospital the request message is being routed.
   Drag a Log mediator to the first Case box of the Switch mediator, and name it Grand Oak Log.
   

10. With the Log mediator selected, access the Properties tab and fill in the information given in the table below:

    Field	Value	Description
    Log Category	INFO	Indicates that the log contains an informational message.
    Log Level	CUSTOM	When Custom is selected, only specified properties will be logged by this mediator. For more information on the available log levels, see the  Log Mediator.
    Log Separator	(blank)	Since there is only one property that is being logged, we do not require a separator, so this field can be left blank.
    Properties	Follow the steps given below to extract the stock symbol from the request and print a welcome message in the log Click the Value field of the Properties property, and then click the browse (...) icon that appears. In the Log Mediator Configuration dialog, click New, and then add a property as follows: Name: message Type: EXPRESSION (We select EXPRESSION because the required properties for the log message must be extracted from the request, which we can do using an XPath expression.) Value/Expression: Click the browse (...) icon in the Value/Expression field and enter fn:concat('Routing to ', get-property('Hospital')). This XPath expression value gets the value stored in the Property mediator and concatenates the two strings to display the log message Routing to <hospital name>. Click OK.

11. Add a Send mediator adjoining the Log mediator and add the GrandOakEP endpoint from Defined Endpoints palette to the empty box adjoining the Send mediator.
    

12. Add Log mediators in the other two Case boxes in Switch mediator and then enter the same properties as in Step 10.
    Make sure to name the two Log mediators as Clemency Log and Pine Valley Log respectively. 

13. Add Send mediators adjoining these log mediators and respectively add the ClemencyEP and PineValleyEP endpoints from the Defined Endpoints palette.

    You have now configured the Switch mediator to log the Routing to <Hospital Name> message when a request is sent to this API resource. The request message will then be routed to the relevant hospital backend service based on the hospital that is sent in the request payload. 

14. Add a Log mediator to the Default (the bottom box) of the Switch mediator and configure it the same way you did for the Log mediator above.

    Make sure to name it Fault Log and changing its Value/Expression as follows: fn:concat('Invalid hospital - ', get-property('Hospital'))

    The default case of the Switch mediator handles the invalid hospital requests that are sent to the request payload.  This logs the message Invalid hospital - <Hospital Name>" for requests that have the invalid hospital name.

15. Drag a Respond mediator next to the Log mediator you just added.
    This ensures that there is no further processing of the current message and returns the request message back to the client.
    The In Sequence of the API resource configuration should now look like this:
    
16. Drag a Send mediator to the Out sequence of the API resource, to send the response back to the client. 
17. Save the updated REST API configuration.

Packaging the artifacts

Package the C-App names SampleServicesCompositeApplication project with the artifacts created. 

1. Open the pom.xml file of the C-App project in the Composite Application Project POM Editor.

2. Select the artifact that needs to be included into the CAR file.

   Ensure the following artifact check-boxes are selected in the Composite Application Project POM Editor.

   • HealthcareAPI
   • ClemencyEP
   • GrandOakEP
   • PineValleyEP

   

3. Click  and define the location you want to create the CAR file.

Starting the Integrator runtime and deploying the artifacts

Assuming you have already added a server in Eclipse, on the Servers tab, expand the WSO2 Carbon server, right-click  SampleServicesCompositeApplication, and choose Redeploy. The Console window will indicate that the CApp has been deployed successfully.

Starting the MSF4J profile

To be able to send requests to the back-end service (which is an MSF4J service deployed in the MSF4J profile), you need to first start the MSF4J runtime:

1. Open a terminal and navigate to the <EI_HOME>/wso2/msf4j/bin directory.

2. Start the runtime by executing the MSF4J startup script as shown below.

   sh carbon.sh 

The Healthcare service is now active and you can start sending requests to the service.

Sending requests to WSO2 EI

Let's send a request to the API resource to make a reservation.

1. Create a JSON file names request.json with the following request payload.

   {
     "patient": {
       "name": "John Doe",
       "dob": "1940-03-19",
       "ssn": "234-23-525",
       "address": "California",
       "phone": "8770586755",
       "email": "johndoe@gmail.com"
     },
     "doctor": "thomas collins",
     "hospital": "grand oak community hospital",
     "appointment_date": "2017-04-02"
   }

   You can also try using any of the following parameters in your request payload.

   For hospital:

   • clemency medical center

   • pine valley community hospital

   Doctor Names:

   • thomas collins

   • henry parker

   • abner jones

   • anne clement

   • thomas kirk

   • cailen cooper

   • seth mears

   • emeline fulton

   • jared morris

   • henry foster

2. Navigate to the directory where you have saved the request.json file and execute the following command.

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

   The URI-Template format that is used in this command was defined when creating the API resource in step 2 of Connecting to the backend service: http://<host>:<port>/categories/{category}/reserve

   You get the following response:

   {"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":"1990-03-19",
          "ssn":"234-23-525",
          "address":"California",
          "phone":"8770586755",
          "email":"johndoe@gmail.com"},
     "fee":7000.0,
     "confirmed":false}

3. Now check the Console tab in Eclipse and you will see the following message: INFO - LogMediator message = Routing to grand oak community hospital
This is the message printed by the Log mediator when the message from the client is routed to the relevant endpoint in the Switch mediator.

You have successfully completed this tutorial and have seen how the requests received by the ESB can be routed to the relevant endpoint using the Switch mediator.