Routing and Service Chaining with WSO2 ESB Part 2

Part 1 > Part 2 > Part 3 

Part 2 of this series will cover the following:

Deployment of GeoService, HCFacilityLocatorService and HCInformationService in the WSO2 Application Server. 

Creation of the endpoints GeoEP, HCFacilityLocatorServiceEP and HCInformationService in the WSO2 ESB. 

Creation of HCCService proxy service in the WSO2 ESB.

Bear in mind that all the artifacts can be downloaded from - https://sites.google.com/site/duckysfilecabinet/dlmi . This will be a step-by-step guide to creating the artifacts that are  given.

Abbreviations

AS - Application Server

EPR - Endpoint Reference

ESB - Enterprise Service Bus

Prerequisites

1) Read part 1 of this tutorial to understand the demo scenario. 

2) Have the following installed:

WSO2 ESB Version - 4.0.3 

WSO2 Application Service Version - 4.1.2  Go to repository/conf/carbon.xml in from the home folder of the application server and set port offset to 1. The reason being that the ESB and the Application server both need to run at the same time on the same machine and they are configured to run on the same port - 9443. When the port offset is set to 1 in the Application Server, it will now run on port 9444. 

soapUI - 2.5

Adding the Services to AS

Download the following services and deploy them to AS.  

GeoService

HCFacilityLocatorService

HCInformationService

Go to the management console of the WSO2 Application Server.

Add -> Axis2 Service

Browse and choose the file as shown below. 

Deploy the given .aar files - GeoService (geows-SNAPSHOT.aar), HCFacilityLocatorService (hcfacilitylocator-SNAPSHOT.aar) and HCInformationService (hcinformationservice-SNAPSHOT.aar)

If you click on the GeoService service, the service dashboard will appear. On the endpoints section you will see the http and https endpoint URLs. Similarly you can obtain information about the other services as well. 

Creating Endpoints 

Go to the management console of the ESB. Click on Endpoints under Service Bus and the following screen will appear. Click on Address Endpoint.

An Address endpoint is an endpoint defined by specifying the EPR and other attributes of the endpoint directly in the configuration. The 'uri' attribute of the address element contains the EPR of the target endpoint.

To create the first endpoint, fill in with the following details as given in the screenshot.  

Name - GeoEP

Address - http://10.200.3.38:9764/services/GeoService/

After the endpoint is created, if you click on the source view tab you will see the following - 

<endpoint xmlns="http://ws.apache.org/ns/synapse" name="GeoEP">
   <address uri="http://localhost:9764/services/GeoService/" format="soap11" >
      <suspendOnFailure>
         <progressionFactor>1.0</progressionFactor>
      </suspendOnFailure>
      <markForSuspension>
         <retriesBeforeSuspension>0</retriesBeforeSuspension>
         <retryDelay>0</retryDelay>
      </markForSuspension>
   </address>
</endpoint>

Similarly create the HCFacilityLocatorServiceEP endpoint with the following properties - 

Name - HCFacilityLocatorServiceEP

Address - http://10.200.3.38:9764/services/HCFacilityLocatorService/

And the HCInformationService endpoint with the following properties.

Name - HCInformationService

Address - http://10.200.3.38:9764/services/HCInformationService/

After saving each of the endpoints that were created, you will now be able to view the list of endpoints available in the Defined Endpoints tab. 

Creating the HCCService Proxy Service (Part 1) 

As mentioned in the previous post, HCCService will be the proxy service used. The In Sequence of the HCCService will first call the GeoService service with the longitude and latitude values. 

Go to the management console of the WSO2 ESB. Go to Add -> Proxy Service as shown below. 

Select Custom Proxy.

Next a 3 step wizard will appear. Step 1 of 3 will be to fill in basic settings.

Proxy Service Name - HCCService (leave everything else as they are).

(Alternatively you could publish a WSDL for the proxy service if required. You can find the WSDL for the HCCService here).

Then click on Next.

For step 2 of 3, which is to create the in sequence, select Define Inline and click on Create.

(You can define an endpoint if you do not want to mediate the incoming message instead of defining the in sequence).

You will now see a graphical editor to add mediators to sequences. Click on Add Child. 

We will first add a property mediator. Add Child -> Core -> Property. 

The editor will now have a new child node, which is the property mediator.

Let's take a look at the request message before we set the properties of the property mediator. We need to obtain the longitude and latitude values to  pass on to the GeoService service. 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:heal="http://healthcare.wso2">
   <soapenv:Header/>
   <soapenv:Body>
      <heal:getHealthcareCenterInfo>
         <!--Optional:-->
         <heal:longitude>3</heal:longitude>
         <!--Optional:-->
         <heal:latitude>4</heal:latitude>
      </heal:getHealthcareCenterInfo>
   </soapenv:Body>
</soapenv:Envelope>

The property mediators will be used to store the values of longitude and latitude. Click on the property mediator and go to the properties view below. Give the following values.

Name - longitude

Action - Set  (The action can be set or remove. 'Set' to add a new property and 'Remove' to remove a property with the given name).

Set Action as - Expression (Specify which type of value to store) 

Type - String

Expression - //heal:getHealthcareCenterInfo/heal:longitude/text()  (XPath expression)

Add another property mediator and add the following properties as shown below.

Name - latitude

Action - Set  

Set Action as - Expression 

Type - String

Expression - //heal:getHealthcareCenterInfo/heal:latitude/text()

For more information on the property mediator check here. 

Let's now add a log mediator. 

In the properties section add the properties as given below. 

Log Category - INFO  (Log messages will be logged in log4j with selected log category. The default log category is INFO)

Log level - Custom (Custom: Only properties specified to the Log mediator)

Log Seperator - , (The log separator is used to separate the attributes being logged. The default separator is ',' (comma))

Add properties for the log mediator. Longitude and Latitude values will be loggged because the Log level is Custom. 

$ctx:longitude and $ctx:latitude ($ctx is the prefix for Synapse message context properties)

For more information on the log mediator check here.

As shown in the screenshot below, let's add an enrich mediator now. For more information on enrich mediator check here. Actually, we can avoid using the enrich mediator here and use the payloadfactory mediator instead. You can see the reason for this later where I explain about its use.  

With the enrich mediator we will be replacing the body of the message with the body of a request message that goes to the GeoService. 

Give the following values for the enrich mediator as shown.

Source:

Clone - true (By setting the clone configuration, the message can be cloned or else used as a reference during the enriching)

Type - inline (Specifies an inline xml value)

Inline Content should be chosen from the radio buttons. 

Inline XML -

<geo:getZipCode xmlns:geo="http://geo.wso2">
                        <geo:longitude>0</geo:longitude>
                        <geo:latitude>0</geo:latitude>
                    </geo:getZipCode>

Target:

Action - replace  (By specifying the action type the relevant action can be applied to outgoing message. By specifying the replace action type it replaces the xml message based on the target type specified on the target configuration)

Type - body (Body of the original message will be used for enriching)

Add another enrich mediator and add the following values.  This is used to replace the longitude value of the body with the longitude value received by the proxy service. 

Source:

Clone - true

Type - property (Specifies a property)

Property - longitude

Target:

Action - replace

Type - custom (To give custom XPath value) 

XPath Expression - //geo:getZipCode/geo:longitude/text()

Add a 3rd enrich mediator as shown below. This is used to replace the latitude value of the body with the latitude value received by the proxy service.  This will be similar to the previous endpoint except for the values for the following properties. 

Property - latitude

XPath Expression - //geo:getZipCode/geo:latitude/text()

Add another log mediator as shown below with the given properties. 

Finally add a send mediator as shown below. Add Child -> Core -> Send. 

Following is the screenshot when everything is complete for the send mediator.

Select Endpoint type - Pick from Registry (browse in the configuration registry as shown and select GeoEP endpoint).

In the properties view of the send mediator, the receiving sequence type should be selected as static (or dynamic if calculated using a XPath).

The receiving sequence (hcfRequest) can be selected and given as shown below.

For more information on the send mediator click here. 

Note that hcfRequest is a sequence that needs to be created. When the screenshot was taken hcfRequest was already created and added as the receiving sequence for the ease of understanding. Since you have not created hcfRequest sequence at this point, after creating the send mediator, save the proxy service and let's get on to creating the hcfRequest sequence. After creating it, come back to the send mediator and add the sequence as shown above. hcfRequest will be created in part 3 of this tutorial series.

Routing and Service Chaining with WSO2 ESB Part 1

Part 1 > Part 2 > Part 3 

This will be the first part of a series of posts on Routing and Service Chaining with WSO2 ESB and will cover the use case and high level architectural details. 

The use case is the transmission of a request to a geo service locator to obtain information on the nearest health care centers using the user's longitude and latitude values. 

The request will be received by a proxy service that is deployed in the ESB. The proxy service will send/receive the messages to/from 3 different services in order to obtain information on the health care centers.  

The following web services will be made use of for this purpose:

GeoService    HCFacilityLocatorService    HCInformationService

For this tutorial these three services will be deployed in the WSO2 Application Server. Let's take a look at what each of these services do. 

GeoService service will take the longitude and latitude values and will return a zipcode value.

HCFacilityLocatorService requires a zipcode value and will return the healthcare center code(s) for the given area (zipcode). 

HCInformationService requires the healthcare center code to return information about the healthcare center pertaining to the healthcare center code. 

What the user needs to do is send the location and get the nearest healthcare center information. There are 3 service calls involved. Hence the application can be written so that the user sends the request to a proxy service that will perform service orchestration. In simple words, the proxy service will first invoke GeoService with the longitude and latitude values and obtain the zipcode value. It will then invoke HCFacilityLocatorService with the zipcode value and obtain healthcare center codes. Finally, it will invoke the HCInformationService for each healthcare center code that will return the details of the healthcare center for each healthcare center code; details of each of the healthcare centers will be merged into one message and be sent to the user as a list. 

Configuring the WSO2 ESB

The mediation engine of WSO2 ESB is driven off a set of XML configuration files. The configuration files that drive the mediation engine are stored in the ESB_HOME/repository/conf/synapse-config directory. These configuration files are written using the Synapse configuration language which is a domain specific language based on XML.

It is recommended to use the graphical wizards and tools provided in the WSO2 ESB management console to setup the mediation configuration, thus avoiding having to write XML configurations manually. Understanding how the files are stored will allow you to use third party tools and scripts for configuration management activities.  In this series, I will be showing how to use the graphical interface to create xml configurations as well as make the xml files available for download. 

The mediation engine of the WSO2 ESB consists of Proxy services, Endpoints, Sequences and Startup jobs managed by the ESB. It also contains the interface to the Registry/Repository being used by the mediation engine. Items like sequences, endpoints and proxy services could be made to reference different configuration elements that are served through the Registry. 

For more information go to the Service Mediation WSO2 Enterprise Service Bus (ESB) Configuration page. 

Let's take a look at the components of the WSO2 ESB that will be used in order to carry out the above operations required to implement the use case above. For this scenario we have created 3 endpoints, 1 proxy service and 2 sequences. Let's take a look at what each of these components fulfill. 

Endpoints

An Endpoint defines an external service endpoint and any attributes or semantics that should be followed when communicating with that endpoint. An endpoint definition can be named for re-use, or defined in-line or anonymously within a configuration. Typically an endpoint would be based on a service Address or a WSDL. Additionally WSO2 ESB supports Failover and Load-balance endpoints - which are defined over a group of endpoints. Endpoints may be defined within the synapse-config configuration or within the Registry. The following endpoints are used for this scenario.                                                                                                                                               
GeoEP.xml    HCFacilityLocatorServiceEP.xml    HCInformationService.xml

Sequences

A sequence element is used to define a sequence of mediators that can be invoked later by name. A sequence is a sequential arrangement of mediators. Mediators are the simplest functional component and performs a predefined action on a given message. 

The sequences named "main" and "fault" are significant in a Synapse configuration. The "main" sequence handles any message that is accepted for 'Message Mediation', and the "fault" sequence is invoked if Synapse encounters a fault, and a custom fault handler is not specified for the sequence via its "onError" attribute. If the "main" or "fault" sequences are not defined locally or not found in the Registry, the Synapse ESB defines suitable defaults at initialization. The following sequences are used for this scenario.

hcfRequest.xml    hciRequest.xml

Proxy Services

A proxy service is a virtual service hosted in the ESB runtime. For a service client it appears to be a real Web Service which accepts service requests. The proxy service mediates any accepted requests and forwards them to a specified endpoint, most of the time to an actual Web Service. The responses coming back from the target endpoint are mediated back to the client which sent the original service request. Proxy services often make references to sequences, endpoints and local entries.

An 'inSequence' in a proxy service would decide how the message would be handled after the proxy service receives the message. The 'outSequence' defines how the response is handled before it is sent back to the client. Unlike sequences and endpoints which can be stored and loaded from the registry, proxy services cannot be loaded from the registry. However a proxy service can make references to sequences and endpoints stored in the registry. The following proxy service is used for this scenario.

HCCService.xml

Message Flow

In the above example the following takes place in the given order:

1. The request message is first received by the inSequence of the HCCService proxy service and mediation occurs.
2. The message is forwarded to the GeoService service via the GeoEP endpoint. 
3. The response (zip code) from GeoService is forwarded to hcfRequest sequence for mediation.
4. hcfRequest forwards the message to the HCFacilityLocatorService via the HCFacilityLocatorServiceEP endpoint. 
5. The response from HCFacilityLocatorService is forwarded to hciRequest sequence for mediation. 
6. hciRequest forwards the message to HCInformationService service via the HCInformationService endpoint. 
7. The message is received by the outSequence of the HCCService proxy service which performs the final mediation steps and sends the response to the consumer. 

Now that the technical overview of this use case has been discussed, we can move on to implementing the given configurations from scratch using the graphical interface of the WSO2 ESB. Await for a step by step guide and detailed explanations on implementation in Part 2.