[Article] Develop and Deploy ESB Artifacts Using WSO2 Developer Studio

Introduction

As ESB is the heart of most service-oriented architecture (SOA) where message mediation, transformation, service integration and core SOA functions take place. You may need to configure the ESB for these tasks depending on their requirement. The WSO2 Developer Studio provides a featured graphical mediation flow composer to create configurations for WSO2 ESB. In simple terms, when using the WSO2 Developer Studio creating ESB configurations is just a few clicks and drag and drops away. The improved ESB graphical editor supports almost all building blocks of the WSO2 ESB including proxy service, REST APIs, sequences, endpoints and many more.

To demonstrate the use of the developer studio on creating ESB configuration project, we use a sample scenario described in [1], since this covers creating proxy services, sequences and endpoints. The scenario described at [1] is a service chaining use case where ESB plays the service integration role. Please note that we do not describe the use case [1] deeply in this tutorial, therefore it is highly recommend to read [1] along with this.

If you are using WSO2 ESB 4.9 make sure to use WSO2 Developer Studio 3.8.

Summary of the use case

• There are three separate services running at different places (namely GeoEP, HCFacilityLocatorServiceEP, and HCInformationService)
• The service at GeoEP is capable of mapping a given coordinate (longitude - latitude) to a Zip Code (Postal Code)
• The service at HCFacilityLocatorServiceEP can resolve a given zip code to the Healthcare center codes (IDs). One important thing to note here is that, for a given zip code, there may be multiple healthcare center codes returning from the service
• Finally, the service hosted at HCInformationService can resolve the Healthcare Center code to the matching healthcare center details.
• The goal of the above scenario is to get details of the nearest healthcare centre by providing location information about coordinates (long, lat)
• The ESB here should perform this service integration. First it needs to call the 'Geo Service' to resolve the zip code from the given coordinate. Then it should pass the zip code to the HCFacilityLocatorService to get Healthcare center codes. Finally the healthcare center code is sent to healthcare information service to get the particular center details

Implementation with WSO2 Developer Studio

As described in the use case, we need to create a proxy service, few sequences and 3 endpoints for the 3 services listed. To create these artifacts we need to create an ESB configuration project to hold them. This article assumes that the user has the latest WSO2 Developer Studio downloaded and installed. For installation instructions please follow [2].

Creating the ESB project

For detailed instruction on creating the ESB project refer [3]. For this scenario the following steps will be used;

• Go to the developer studio dashboard
• Click on the ‘ESB Config Project’ link
• On the ‘New ESB Project’ wizard page leave the ‘New ESB Config Project’ checked as it is the default option
• Click ‘Next’
• Name the project ‘HealthcareEsbConfig’
• Click ‘Finish’

You may also refer the screencast [4] to follow up above steps.

Creating endpoints

For this scenario we need to create 3 endpoints named GeoEP, HCFacilityLocatorServiceEP and HCInformationService. For detailed instructions on creating endpoints refer [4]. To create GeoEP use the following steps;

• Go to the developer studio dashboard as seen in Figure 1 and click on the ‘Endpoint’ link

Figure 1

• Leave the ‘Create A New Endpoint’ checked

Figure 2

• Set the Endpoint Name as GeoEp
• Chose the Endpoint Type as Address Endpoint
• Enter https://localhost:9764/services/GeoService/ into the Address textbox
• Choose the above created HealthcareEsbConfig for the ‘Save endpoint in’ using the ‘Browse’ button

Figure 3

Once the endpoint is created, the workspace would look as follows;

Figure 4

You may notice the following on the workspace;

• On the left hand side of the ‘Project Explorer’ the created ESB project and endpoint is created under synapse config/endpoints directory as GeoEP.xml
• GeoEp is listed in the ‘Tool’ pallet under ‘Defined Endpoints’ tool group
• GeoEp.xml is opened in the graphical editor, which uses the 'WSO ESB Graphical’ perspective
• The properties of endpoints are listed in the property viewer

Create the HCFacilityLocatorServiceEP and HCInformationService endpoints by following the same steps. The only difference when doing this would be the ‘Address’ field.

HCFacilityLocatorServiceEP Endpoint

HCInformationService Endpoint

Creating proxy service

For general information on creating a proxy service refer [5]. For this scenario we have to use the ‘Custom Proxy’. Use the following steps to create the proxy service named HCCProxyService;

• Go to the developer studio dashboard and click on the ‘Proxy Service’ link
• In the new proxy wizard page keep ‘Create New Proxy Service’ checked
• Click ‘Next’
• Set the Proxy Service Name to HCCProxyService and set the Proxy Service Type as ‘Custom Proxy’ from the combo-box. Choose HealthcareEsbConfig project as the saving destination of the proxy service
• Click ‘Finish’

Once the proxy is created workspace would appear as follows;

Figure 5

Now we are ready to configure it.

Configuring the proxy service

For the first service we need to call the 'Geo Service' to resolve the zip code from the given coordinate. Therefore we have to create a new request that needs to be sent to Geo Service. Then that request needs to be enriched with the original values of longitude and latitude given by the client.

Since we need to use the original values of longitude and latitude from the client's request, we use property mediators to keep these values. Later we can verify that the values are properly extracted by inserting log mediators. To add a property mediator to the in-sequence of proxy service do the following;

Click on ‘Property Mediator’ in the tool palette and then place your mouse somewhere near the arrowhead of the in-sequence. If you find it difficult to find the property mediator, just search for and locate it (click somewhere on tool palette and type 'p' 'r' and it will appear at the beginning of mediators list).

Figure 6

The objective of the first property mediator is to extract the longitude value. To make it clear we will add the description ‘extract longitude’ to the property mediator. As soon as a mediator is dropped the mouse cursor is in focus for you to edit this description or you can do this later by double-clicking on the mediator. Adding a description will help you easily understand the function of the mediator; it’s like a comments you put on source codes. Then set the parameters of property mediator as Name equals to ‘longitude’ and Expression equals to ‘//heal:getHealthcareCenterInfo/heal:longitude/text()’. This can be done via the properties panel.

Figure 7

In the properties panel type in ‘longitude’ for the 'Property Name' field and then leave the ‘Property Action’ field as 'set' since we need to set this property. Set the 'Value Type' as expressions since we use an xpath expression to extract the values from client requests.

When you click on the 'Value Expression' field, you will see a button with three dots (…) ; click on that button to open the expression editor where you can edit the expressions and relevant namespaces (here the namespace is 'heal'). The following is the screenshot of the expression editor for the ‘Value Expression’ of the above property mediator.

Figure 8

Once configured as above, the corresponding source view of the property mediator should be as follows;

Similarly, add another property mediator to set the latitude value. Click on the property mediator and drop it after the first property mediator. The graphical editor will connect this automatically for you. Then set the parameters as described in [1].

Then we will add a log mediator to log the values of the properties we set using the above property mediators.

Logging help for debug purposes for this scenario can be used to verify that the values are properly extracted. To add a log mediator just search for the log in tool palette, click on the ‘Log Mediator’ tool and then click on the graphical editor (after the second property mediator). After adding the log mediator set its parameters via the property panel. Keep the log category as INFO and log level as SIMPLE and click on the properties field; you will see the (…) button. Click on that button to open the property editor and add properties to the log.

Figure 9

Add an enrich mediator to construct the message as expected by GeoEP. Then you can use two more enrich mediators to set the longitude and latitude properties that we extracted above. For your reference read the docs at [6] for information on the enrich mediator.

Once you finish the above configurations your proxy service will look appear as follows;

Figure 10

We will add another log mediator for debugging purposes to verify the constructed message. Now we are ready to send the constructed message to GeoEP. To do this we need a send mediator. Add a send mediator to end of the message flow in the same manner in which we added other mediators in earlier steps.

Figure 11

Now set the endpoint for the send mediation. Here we need to set GeoEP since this request is aimed at Geo Service which is running at GeoEP. To do so, expand the defined endpoints tool group and click on GeoEP and drop it inside the send mediator. You may notice that all the endpoints we created earlier are listed in the 'Defined Endpoints' group.

Figure 12

Our next step is to receive the response from Geo Service, extract the zipcode from it and construct the required payload for the HCFacilityLocatorService. To accomplish this we use the receiving sequence property of the send mediator.

Refer 'Setting the receiving sequence' at the end of this document. It will describe how to set hciRequset as the receiving sequence of the send mediator in hcfRequest. You can follow the same steps to set the hcfRequest (after creating) as the receiving sequence for this (proxy service) send mediator.

Now we need to create a sequence (named hcfRequest as described in [1]) to set as the receiving sequence of this send mediator. The following section describes how to create the required sequences.

Creating sequences

For this use-case we need to create two sequences; namely hcfRequest and hciRequest. To create a sequence in developer studio refer [7]. To create hcfRequest sequence you can follow the steps below;

1. Go to the developer studio dashboard and click on the “Sequence” link
2. In the new proxy wizard page keep “Create New Sequence” checked
3. Click ‘Next’
4. Set the ‘Sequence Name’ to hcfRequest, and chose HealthcareEsbConfig project to save the sequence.
5. Click ‘Finish’

You can create the hciRequest sequence in a similar manner.

Configuring the hcfRequest sequence

You can open the hcfRequest either by navigating the project explorer to HealthcareEsbConfig/src/main/synapse-config/sequences/hcfRequest.xml and double clicking on the hcfRequest.xml or by simply finding it via the ‘Defined Sequences’ tool group. Once you open the sequence its initial view will looks as follows;

Figure 13

Now we are ready to configure the hcfRequest sequence. The objective of this sequence is to extract the zipcode from the response (we get this from the GeoService) and then construct the required payload compatible for the HCFacilityLocatorService. This can be achieved via a property mediator (to extract the zipcode) and a payload factory mediator [8]. Adding mediators to the sequence is the same as what we did for the proxy service. Add the property mediator and payload factory mediator and configure them as per the requirement according to [1].

Figure 14

For debug/verifying purposes we will add log mediators in the beginning, middle and end of the payload factory mediator. An interesting fact to mention here is you don't need to add mediators one after the other. The graphical editor allows you to add mediators in the middle as well. It will show where you can drop a mediator using a green tick mark. Once you add the mediators, the sequence will appear as follows.

Figure 15

The objective of the first log mediator is to log the full response that we get from Geo Service. The second log mediator is configured to log the zipcode property which is extracted via the property mediator. The last log mediator is to log the payload that we constructed via the payload factory mediator. Note that the descriptions under each mediators are not mandatory but once you add them it’s easy to understand their purpose.

Please note that the manner in which you should configure each mediator was not discussed here. Configuring the parameters of mediators is the same as what was done for the mediators in the proxy service. What you have to do is click on the particular mediator and configure it via the properties panel at the bottom (once you click on a mediator its parameters will be shown in the properties panel). Please refer to [9] to know how you could configure mediators and refer to the use case [1] for the specific requirement.

Now we need to add a send mediator to send this (constructed) request to HCFacilityLocatorService. Add a send mediator to the end of the sequence and add the HCFacilityLocatorServiceEP endpoint (from the defined endpoints tools group) inside the send mediator. The steps are the same as the process for adding endpoints to the proxy service.

Figure 16

Now we are done with most of the configurations of the hcfRequest sequence. According to the use case[1] we are referring to, once the request is sent to HCFacilityLocatorService it will return one or multiple healthcare center codes as its response. Then we need to send these healthcare center codes to HCInformationService to get the matching healthcare center details. That means we have to add another mediation logic to handle this. For this purpose we need to add a receiving sequence to the send mediator and configure the mediation logic inside that sequence.

Setting the receiving sequence

Setting a receiving sequence to the send mediator can be done via the properties panel. To do so first click on the send mediator and the properties panel shows the send mediator properties (if the properties view does not show up in the first time, right click the Show Properties View option). Then you need to change the 'Receiving Sequence Type' property to static or dynamic (by default it is set to 'Default' as in the diagram below). For this use case we will set it to static since we have all the sequences defined under our esb config project (HealthcareEsbConfig).

Figure 17

Once you change the Receiving Sequence Type property to static you will notice that another field (Static Receiving Sequence) will appear with the default value of “/default/sequence”.

Figure 18

Then click on the button with three dots (...) that appears at the right hand side of the 'Static Receiving Sequence' field. Once you click on it, it will open the resource key editor. From here you can select the resource (note that the sequence is also a resource under the ESB config project) from either workspace, registry or local entries. For this we will choose 'workspace' since all our sequences are within the esb project.

Figure 19

Clicking on the workspace link will open the Workspace Element Providers dialog. This dialog will display all the available resources under the workspace. Choose hciRequest since we need to set hciRequest as the receiving sequence of the send mediator(of the hcfRequest).

Figure 20

Now we are done with all the configurations of the hcfRequest. We have one more sequence to configure; the hciRequest. Configuration details are not discussed here since configuration steps are very similar to the hcfRequest. Please refer [1] for the configuration requirement and [9] for the mediators. Once you drag and drop and configure the hciRequest sequence it will as as follows;

Figure 21

Note that we use an iterate mediator since we need to handle multiple healthcare center codes returning from the HCFacilityLocator service. You may notice that iterate mediator is a special mediator where you can define a message flow within it similar to that of a sequence. . The send mediator is also a complex mediator but the difference is that it can only contain endpoints. Now we have finished configuring all the artifacts and they are ready to be deployed.

Deployment

Refer [13] to see how you can deploy these using the composite application project.

Summary

This article explained how you can use WSO2 Developer Studio to create and configure an ESB project including its endpoints, proxy services and sequences. WSO2 Developer Studio makes it simple for you to develop and deploy your ESB artifacts through its improved graphical editors.

References

1. https://wso2.com/library/articles/2012/11/enterprise-service-integration-wso2-esb/
2. https://docs.wso2.org/display/DVS350/Installationro
3. https://docs.wso2.org/display/DVS350/Creating+ESB+Artifacts#CreatingESBArtifacts-CreatinganESBConfigPject
4. https://wso2.com/library/tutorials/2014/05/screencast-creating-an-esb-project-and-end-point-with-wso2-developer-studio/
5. https://docs.wso2.org/display/DVS350/Creating+ESB+Artifacts#CreatingESBArtifacts-Creatinganendpoint
6. https://wso2.com/library/tutorials/2014/04/screencast-configuring-send-mediator-in-developer-studio/
7. https://docs.wso2.org/display/DVS350/Creating+ESB+Artifacts#CreatingESBArtifacts-Creatingaproxyservice
8. https://wso2.com/library/tutorials/2014/04/screencast-configuring-proxy-service-fault-sequence-and-out-sequence-in-wso2-developer-studio/
9. https://docs.wso2.org/display/ESB480/Enrich+Mediator
10. https://docs.wso2.org/display/DVS350/Creating+ESB+Artifacts#CreatingESBArtifacts-Workingwithsequences
11. https://docs.wso2.org/display/ESB480/PayloadFactory+Mediator
12. https://docs.wso2.org/display/ESB480/Mediators
13. https://docs.wso2.org/display/DVS350/Deploying+and+Debugging