This documentation is for WSO2 Enterprise Integrator version 6.1.1 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc
Skip to end of metadata
Go to start of metadata

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

When the client sends the appointment reservation request to the ESB, the message payload will contain the name of the hospital where the appointment needs to be confirmed. The HTTP request method will be 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.

In this tutorial, you will use a Switch mediator to route messages based on the message content to the relevant HTTP Endpoint defined in the ESB. The back-end service used in this example is a micro service stored in the MSF4J profile of WSO2 EI.

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

See the following topics for a description of the concepts that you need to know when creating ESB artifacts:

Before you begin,

  1. Install Oracle Java SE Development Kit (JDK) version 1.8.* and set the JAVA_HOME environment variable.
  2. Download the WSO2 EI ZIP file from here, and then extract the ZIP file. 
    The path to this folder will be referred to as <EI_HOME> through out this tutorial.
  3. Select and download the relevant EI tooling ZIP file based on your operating system from here and then extract the ZIP file. 
    The path to this folder will be referred to as <EI_TOOLING> through out this tutorial.
  4. If you did not try the Sending a Simple Message to a Service tutorial yet, open the WSO2 EI Tooling environment, click File, and then click Import. Next, select Existing WSO2 Projects into workspace under the WSO2 category, click Next and upload the pre-packaged project. This contains the configurations of the Sending a Simple Message to a Service tutorial so that you do not have to repeat those steps.
  5. Download the MSF4J service from here and copy the JAR file to the <EI_HOME>/wso2/msf4j/deployment/microservices folder. The back-end service is now deployed in the MSF4J profile of WSO2 EI.

Let's get started!

This tutorial contains the following sections:

Connecting to the back-end service

In this tutorial we have three hospital backend services hosted in the MSF4J profile of WSO2 EI:

  • Grand Oak Community Hospital : http://localhost:9090/grandoaks/

  • Clemency Medical Center :  http://localhost:9090/clemency/

  • Pine Valley Community Hospital :   http://localhost:9090/pinevalley/

The request method is POST and a sample request URL expected by the backend services is:


Let's now 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:

    Endpoint NameGrandOakEP
    Endpoint TypeHTTP Endpoint
    URI Templatehttp://localhost:9090/grandoaks/categories/{uri.var.category}/reserve
    Static Endpoint(Select this option because we are going to use this endpoint in this ESB Config project only and will not re-use it in other projects.)
    Save Endpoint inSampleServices

    Click Finish.

  3. Create similar HTTP endpoints for the other two hospital services using the relevant URI Template as follows:
    • ClemencyEP :  http://localhost:9090/clemency/categories/{uri.var.category}/reserve
    • PineValleyEP :  http://localhost:9090/pinevalley/categories/{uri.var.category}/reserve

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

You can also create a single endpoint where the differentiation of the hospital name can be handled using a variable in the URI template. See the following tutorial: Exposing Several Services as a Single Service.

Using three different endpoints is advantageous when the back-end services are very different from one another and/or when there is a requirement to configure error handling differently for each of them.

Mediating requests to the back-end service

To implement the routing scenario, we will 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 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. With the API Resource you added in the previous step selected, access the Property tab and fill in the following details:
    • Url Style: Click in the Value field, click the down arrow, and then select URI_TEMPLATE from the list
    • URI-Template: /categories/{category}/reserve
  3. Set the value of Post to true in the Methods section of the properties tab.
  4. Drag a Property Mediator from the Mediators palette to the In Sequence of the API resource and name it Get Hospital. This will be used to extract the hospital name that is sent in the request payload.
  5. 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
  6. We will now add the JSONPath expression that will extract the hospital from the request payload. Click value field of Value Expression in the Property tab and add the following expression:

  7. Add a Switch mediator from the Mediator palette just after the Property Mediator you added above. 

  8. 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 there are three cases. Enter 3 for Number of branches and click OK

  9. With the Switch mediator selected, go to the Property tab.

  10. The Source XPath field is where we will specify the XPath expression that obtains the value of Hospital that we stored in the Property mediator. To specify the expression, click in the Value field of the Source XPath property, click the browse (...) button, and then overwrite the default expression with the following and click OK:


    For more information on get-property(), see XPath Extension Functions.

  11. Click in the Value field of the Case Branches property, click the browse (...) button, and then change the RegExp value as follows:

    • Case 1: grand oak community hospital
    • Case 2:  clemency medical center
    • Case 3:  pine valley community hospital

    Click OK

  12. 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, name it 'Grand Oak Log', access the Properties tab and enter the following:

    • Log Category: INFO
    • Log Level: CUSTOM
  13. Click the Value field of the Properties property, and then click the browse (...) icon that appears. In the Log Mediator Configuration dialog box, click New, and then add a property called 'message' 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 the following:
      • Property expression: fn:concat('Routing to ', get-property('Hospital'))
        This is an XPath expression value that uses the value stored in the Property mediator and will then concatenate the two strings to display the log message “Routing to <hospital name>”.

    Click OK.
  14. Add a Send mediator adjoining the Log mediator and add GrandOakEP from Defined Endpoints palette to the empty box adjoining the Send mediator.

  15. Add Log mediators in the other two Case boxes in Switch mediator and then enter the same properties as in Step 13. Name the two Log mediators as 'Clemency Log' and 'Pine Valley Log'. 
    Add Send mediators adjoining these log mediators and respectively add endpoints ClemencyEP and PineValleyEP from the Defined Endpoints palette.

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

  16. Let's now configure the default case in the switch mediator. This will handle requests where an invalid hospital is sent in the request payload.  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, this time naming it Fault Log and changing its Value/Expression as follows:
    fn:concat('Invalid hospital - ', get-property('Hospital'))
    This results in the message "Invalid hospital - <Hospital Name>" to be logged for requests where the request payload contains an invalid hospital.
  17. Drag a Respond mediator adjoining the Log mediator you added in the above step. This ensures that there is no further processing of the current message and returns the request message back to the client.

    The API resource configuration should now look like this:
  18. Drag a Send mediator to the Out sequence of the API resource to send the response back to the client. 
  19. Save the updated REST API configuration.

Packaging the artifacts

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

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

  • HealthcareAPI
  • ClemencyEP
  • GrandOakEP
  • PineValleyEP

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.

If you do not have a server added in Eclipse, refer this tutorial.

You can also deploy the artifacts to the ESB server using a Composite Application Archive (CAR) file. 

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.


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": "[email protected]"
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "appointment_date": "2017-04-02"

    You can also try using any of the following paramaters 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. Open a command line terminal and execute the following command from the location where request.json file you created is saved:

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

    This is derived from the URI-Template defined when creating the API resource.


    You will see the following response:

           {"name":"thomas collins",
            "hospital":"grand oak community hospital",
            "category":"surgery","availability":"9.00 a.m - 11.00 a.m",
          {"name":"John Doe",
           "email":"[email protected]"},

    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 seen how requests received by the ESB can be routed to the relevant endpoint using the Switch mediator. 

  • No labels