ei
2016/06/09
9 Jun, 2016

[Article] Common Use Cases of Message Translating and Enriching with WSO2 Enterprise Service Bus

  • Chathurika De Silva
  • Senior Software Engineer - Quality Assurance - WSO2

Table of contents



Introduction

To put this challenge into greater perspective, let’s consider a common everyday example - if you’re in a foreign country where language is a barrier to communication between you and the natives, you would seek help from a translator. Then there’s another impending problem; if there were several tribal groups who speak different dialects of the same language the translator you pick should be able to understand all of these and tweak accordingly when communicating messages between the two parties. The key here is to choose the most capable translator who can dissect and communicate information without compromising on accuracy.

From Tribal Translator to Message Transformation and Enriching

In terms of web services, however, you would need such a translator that can do the same; it would need to act as a middleman between two parties that simply do not understand each other or between parties who speak the same language in different dialects. A message transformer and enricher will help to meet this requirement in the context of web services; it has the ability to modify an incoming request so it matches with what’s expected from the backend. Specifically, a message enricher can be used to inject missing information. A message translator has the capability to replace an old set of information by a new set as desired.



Use case 1: Current request is not what the backend needs, I am replacing it

A seven-star hotel has a customer rewarding system and this system checks previous visits and expenditure by the guest in the hotel. When a guest is checking-in, a request should be sent to this system. The system expects the request to contain a customer identification/customer name as the request. It will then check the customer’s previous expenditure and will rate the customer as per their tiers - Platinum, Gold, Silver, or Bronze. Based on the rating, the guest will be awarded free services. If the customer is not listed, then the client is informed. When a guest checks-in, the staff makes a request to the system by providing the guest’s personal identification (passport, etc.), a number, and name.

Assumption: When a guest is checked-in, automatically a guest inventory is updated with a new row if the guest is new and assigned a customer identification.

Figure 1

As shown in Figure 1, the client request does not contain the fields the backend is expecting. So, the request should be replaced by the required values that correspond with the request as illustrated in Figure 2.

Figure 2



Use case demonstration with WSO2 ESB

In order to explain this story with WSO2 Enterprise Service Bus (WSO2 ESB), first the situation should be analyzed. As the story goes, we need to replace the body of the current payload. In order to replace, we need to query a database using the “Guest Personal Identification Number” that is sent in the request and obtain the customer ID. Further, we need to obtain the guest name from the request and send it as the customer name with the customer ID. As the above diagram illustrates, the backend is expecting the request in the form of a customer ID and customer name.

Now let’s look at what mediators we are going to pick, since we need to lookup the database using a parameter. In this example, a data service call will be used to obtain the necessary data from the database. Then we need to replace the current message payload, so in this demonstration, the PayLoadFactory mediator will be used too.

The Call mediator will invoke the data service that resides in WSO2 Data Services server. This invocation will be done in a blocking manner, so that the rest of the mediators will wait for a response from the data service to proceed.

The Payload Factory mediator that is designed to transform or replace a message content, will construct the new message body, and will insert a customer ID and customer name.


Sample data service

The following sample sequence illustrates how the mediators are placed to achieve the objective of the story.


Sample request sent by the client

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="https://sample.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
  	<sam:customerRewardChecker>
        	<sam:nic>123456789v</sam:nic>
          	<sam:guestName>John Doe</sam:guestName>
  	</sam:customerRewardChecker>
   </soapenv:Body>
</soapenv:Envelope>


Translated request reaching the backend

<soapenv:Envelope
	xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
	xmlns:sam="https://sample.wso2.org">
	<soapenv:Body>
    	<sam:customerRewardChecker>
           	<sam:customerid>cu0001</sam:customerid>
           	<sam:customerName>John Doe</sam:customerName>
    	</sam:customerRewardChecker>
	</soapenv:Body>
</soapenv:Envelope>



Use case 2: Current request does not contain all expected by backend, I am computing and injecting it

This time, another seven-star hotel is looking to expand and secure its customer base. They are going to offer promotions to their customers based on times they have visited and amount previously spent. They have a Customer Promotion Service where it’s expecting a customer ID, customer name, and customer type (i.e. Platinum, Gold, Silver, or Bronze).This is an outsourced service that’s hosted in a partner company, which is maintained by the partner company itself. The hotel’s internal system currently provides a customer ID, customer name, and customer type. The hotel sends the customer type in a number format as in 1, 2, 3 and 4. Unfortunately, with what’s provided, only the customer ID and customer name can be used as is. We have to enrich the message and calculate the expected customer value from the given values.

Figure 3

As shown in Figure 3, the client request does not contain the fields the backend is expecting. So the request should be modified by computing the missing data from the given ones and injecting them to the request as shown in Figure 4.

Figure 4



Use case demonstration with WSO2 ESB

As per the story, we have to change the content of the Customer Type so that’s what the backend is expecting. Here, we are cutting and pasting content to match the backend service. The reference values are already stored and all we need to do is to compare the incoming request with the stored values and obtain the stored values if equals.

For demonstration purposes the reference values are stored as local entries. Then by using the Switch mediator the incoming values are compared against the stored. When the Switch mediator case expressions return true, the message payload is enriched so the values are replaced to match the backend accordingly.

The following sample sequence illustrates how the mediators are placed to achieve the objective of the story.


Sample request from client

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="https://sample.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
  	<sam:customerPromotionChecker>
     	<!--Optional:-->
     	<sam:customerid>CU001</sam:customerid>
     	<!--Optional:-->
     	<sam:customerName>John Doe</sam:customerName>
     	<sam:customerType>1</sam:customerType>
  	</sam:customerPromotionChecker>
   </soapenv:Body>
</soapenv:Envelope>


Request sent to the backend after enriching

<soapenv:Envelope
	xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
	xmlns:sam="https://sample.wso2.org">
	<soapenv:Body>
    	<sam:customerPromotionChecker>
        	<sam:customerName>John Doe</sam:customerName>
        	<sam:customerType>gold</sam:customerType>
    	</sam:customerPromotionChecker>
	</soapenv:Body>
</soapenv:Envelope>



Use case 3: Current request does not contain all expected by backend, I am obtaining missing data from the environment and injecting it

Now there is another seven-star hotel and it provides its customers an in-house portal where they can book different sightseeing options they provide. The portal is outsourced so they can’t make any changes to it. The Reservation service hosted in the hotel expects every reservation request to contain a request ID, guest name, room number, place you want to visit, number of people, time of reservation, and system time. But the portal only sends the request ID, guest name, room number, place to visit, number of people, and time of reservation only. In order to use both the client and backend service unaltered, we need to inject the system time before the request is passed to the backend.

Figure 5

As shown in Figure 5, the client request does not contain the fields the backend is expecting. So the request should be modified by injecting the missing data through the environment. This can be done by enriching the message as follows in Figure 6.

Figure 6



Use case demonstration with WSO2 ESB

In order to achieve our story with WSO2 ESB, the enrich mediator is used to inject the system time in to request. For demonstration purposes, the synapse property, SYSTEM_DATE is used.

The following sample sequence illustrates how the mediators are placed to achieve the objective of the story.

Sample request by the client

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="https://sample.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
  	<sam:customerReservation>
     	<sam:reqId>REQ001</sam:reqId>
     	<sam:guestName>John Doe</sam:guestName>
     	<sam:roomNo>100</sam:roomNo>
     	<sam:placeToVisit>Blue Sea</sam:placeToVisit>
     	<sam:TimeOfReservation>19:00</sam:TimeOfReservation>
     	</sam:customerReservation>
   </soapenv:Body>
</soapenv:Envelope>


Request sent to backend

<soapenv:Envelope
	xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
	xmlns:sam="https://sample.wso2.org">
	<soapenv:Body>
    	<sam:customerReservation>
        	<sam:reqId>REQ001</sam:reqId>
        	<sam:guestName>John Doe</sam:guestName>
        	<sam:roomNo>100</sam:roomNo>
        	<sam:placeToVisit>Blue Sea</sam:placeToVisit>
        	<sam:TimeOfReservation>19:00</sam:TimeOfReservation>
        	<sam:SystemDate>2016.04.11.03.43</sam:SystemDate>
    	</sam:customerReservation>
	</soapenv:Body>
</soapenv:Envelope>



Use case 4: Current request does not contain all expected by backend, I am obtaining missing data from external party and injecting it

Next we have a seven-star hotel that’s expecting to launch “Week of Glamour”. The idea is to let the customers submit themselves and draw a raffle to select winners. The selected winners will receive a free two-day stay at the hotel. The hotel has developed a web portal so the customers can enroll themselves. Since they want to keep things simple, they will only ask the customer to fill in their name, personal identification, and last billing reference to prove their stay. The hotel has a validation service where the submitted information is validated. The validation service expects a customer ID, customer name, personal identification, and last billing reference.

Figure 7

There is a database that the hotel operates that stores customer ID against the customer’s personal identification number. We can use this database and obtain the customer ID and thereafter inject it to the request as illustrated in Figure 8.

Figure 8

After enriching, the request contains the required fields as expected from the backend service.



Use case demonstration with WSO2 ESB

In order to achieve this story with WSO2 ESB, first the situation should be analyzed. As the story goes, we need to inject the customer ID to the current payload. In order to inject, we need to query a database using the “Customer Personal Identification Number” that is sent in the request and obtain the customer ID.

As illustrated in use case 1, we will be using a data service call to obtain information from the database. The Payload mediator will be used to transform the message as needed by the dataservice. Thereafter the Call mediator will be used to execute the dataservice in a blocking manner. Then we need to inject to the current message payload, therefore, in this demonstration, the Enrich mediator will be used.

The following sample sequence illustrates how the mediators are placed to achieve the objective of the story.

Sample request from client

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="https://sample.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
  	<sam:customerValidator>
     	<sam:customerName>John Doe</sam:customerName>
     	<sam:custPersIdentification>123456789v</sam:custPersIdentification>
     	<sam:lastBillReference>ref100</sam:lastBillReference>
  	</sam:customerValidator>
   </soapenv:Body>
</soapenv:Envelope>


Sample request sent to backend

<soapenv:Envelope
	xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
	xmlns:sam="https://sample.wso2.org">
	<soapenv:Body>
    	<sam:customerValidator>
        	<sam:customerID>cu0001</sam:customerID>
        	<sam:customerName>John Doe</sam:customerName>
        	<sam:custPersIdentification>123456789v</sam:custPersIdentification>
        	<sam:lastBillReference>ref100</sam:lastBillReference>
    	</sam:customerValidator>
	</soapenv:Body>
</soapenv:Envelope>



Conclusion

Message transformation and enriching is a powerful enterprise integration concept that enables many systems to be integrated without requiring a change at the systems itself. Understanding the mechanisms of message transformation and enriching enables users to adopt the best available solution available at that time. WSO2 ESB optimally supports enterprise integration patterns and message enriching and transforming are supported mainly through the Enrich Mediator and Payload mediator.

 

About Author

  • Chathurika De Silva
  • Senior Software Engineer - Quality Assurance
  • WSO2