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.
Before you begin!
- Install Oracle Java SE Development Kit (JDK) version 1.8.* and set the JAVA_HOME environment variable.
- 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>throughout this tutorial.
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>throughout this tutorial.
Getting an error message? See the troubleshooting tips given under Installing Enterprise Integrator Tooling.
- If you did not try the Sending a Simple Message to a Service tutorial yet, open the WSO2 EI Tooling environment, click File, and click Import.
Next, expand the WSO2 category and select Existing WSO2 Projects into workspace, 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.
- Download the MSF4J service from here and copy the JAR file to the
<EI_HOME>/wso2/msf4j/deployment/microservicesdirectory. 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:
Pine Valley Community Hospital:
The request method is POST and the format of the request URL expected by the backend services is:
Let's create three different HTTP endpoints for the above services.
Right-click SampleServices in the Project Explorer and navigate to New -> Endpoint. Ensure Create a New Endpoint is selected and click Next.
Fill in the information as in the following table:
Field Value Endpoint Name
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
- Click Finish.
- Similarly, create the HTTP endpoints for the other two hospital services using the URI Templates given below:
You have now created the three endpoints for the 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, 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.
- 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.
Click the API Resource you just added to access the Properties tab and fill in the following details:
Click in the Value field, click the down arrow, and select URI_TEMPLATE from the list.
Methods Set the value of Post to true.
- 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.
With the Property mediator selected, access the Properties tab and fill in the following details:
New Property Name
Click Value field of Value Expression in the Property tab and add the following expression:
This is the JSONPath expression that will extract the hospital from the request payload.
Add a Switch mediator from the Mediator palette just after the Property Mediator.
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.
Enter 3 for Number of branches and click OK.
With the Switch mediator selected, go to the Properties tab, and fill in the details given below:
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 (...).
get-property('Hospital')and overwrite the default expression.
- Click OK.
For more information on
get-property(), see XPath Extension Functions.
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.
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.
With the Log mediator selected, access the Properties tab and fill in the information given in the table below:
Field Value Description Log Category
Indicates that the log contains an informational message. Log Level
Customis selected, only specified properties will be logged by this mediator.
For more information on the available log levels, see the Log Mediator.
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:
EXPRESSIONbecause 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.
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.
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
Pine Valley Logrespectively.
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.
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.
- 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:
- Drag a Send mediator to the Out sequence of the API resource, to send the response back to the client.
- Save the updated REST API configuration.
Packaging the artifacts
Package the C-App names SampleServicesCompositeApplication project with the artifacts created.
- Open the
pom.xmlfile of the C-App project in the Composite Application Project POM Editor.
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.
- 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:
- Open a terminal and navigate to the
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.
Create a JSON file names
request.jsonwith the following request payload.
You can also try using any of the following parameters in your request payload.
clemency medical center
pine valley community hospital
Navigate to the directory where you have saved the
request.jsonfile and execute the following command.
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:
You get the following response:
Now check the Console tab in Eclipse and you will see the following message:
INFO - LogMediator message = Routing to grand oak community hospitalThis 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.