Using Ensemble as an ESB
Pass-through Service and Operation Walkthrough
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This walkthrough demonstrates how to use pass-through services and operations.

Note:
This walkthrough makes use of some free services provided by the openweathermap.org server and the www.webservicex.net server. Neither of these servers is associated with InterSystems Corporation and these servers may not always be available. If they are not available, you can substitute any other REST or SOAP server available to you. The openweathermap.org server supplies free weather data. If you intend to use it in an application, you should get a application ID. Although the service is free, product support is available for the weather server at a fee. See http://openweathermap.com/ for more information about this server. The www.webservicex.net server is provided by Cloud Computing Technologies Ltd. For more information on the server, contact them at Info@WebserviceX.NET.
This section contains:
Using REST Pass-through Services and Operations
This section adds a REST pass-through service and a REST pass-through operation. The service listens on the CSP port and sends the HTTP REST message to the pass-through operation. The pass-through operation sends the HTTP REST message to an external server, api.openweathermap.org, that returns current weather information.
Select or create a namespace and production. In order to use the CSP port, you must define a web application in the namespace and a role. See Configuring an Ensemble System for step-by-step instructions to create a namespace, role, and web application. For this walkthrough, name the web application /restpassthrough (web application name should be lower case) and set the web application Dispatch Class to EnsLib.REST.GenericService.
  1. On the production configuration page, select the plus sign for adding new operations.
    1. Specify the operation class: EnsLib.REST.GenericOperation
    2. Name the operation, such as WeatherRESTPassthroughOp.
    3. Don't enable it yet.
    4. Select OK.
  2. Select the Pass-through operation that you created and select the Settings tab.
    1. If you are using the external service registry, set the External Registry ID to identify the registry entry that sets the HTTP Server,HTTP Port, and URL settings and skip to Step 3. Otherwise specify these settings directly as follows:
    2. Enter the HTTP Server: api.openweathermap.org
    3. Set the URL field to: |
    4. Leave the other fields at their default values.
    5. Check the Enabled checkbox.
    6. Select Apply.
  3. Select the plus sign for adding new services.
    1. Specify the service class: EnsLib.REST.GenericService
    2. Name the service, such as WeatherRESTPassthroughServ.
    3. Don't enable it yet.
    4. Select OK.
  4. Select the Pass-through service that you created and select the Settings tab.
    1. Ensure that the Port number is blank.
    2. In the TargetConfigName field, choose the pass-through operation that you added in the previous step.
    3. In Additional Settings, set Pool Size to 0. This suppresses the pass-through service from listening on the special port. If do not set the pool size to 0, you must specify a port number.
    4. Check the Enabled checkbox.
    5. Select Apply.
  5. Start the production.
  6. Enter the URL for the pass-through service using the CSP port. The URL consist of the following parts:
    For example, enter the following URL in a web browser:
    Note that all alphabetic characters in the web application name must be in lower case and the pass-through service name must match the case of the configuration item name.
If all is working, the call returns a JSON message with the current weather in London. For example, it can return the following JSON message:
{
"coord":{"lon":-0.13,"lat":51.51},
"sys":{"message":0.0441,"country":"GB","sunrise":1399609017,"sunset":1399664214},
"weather":[{"id":802,"main":"Clouds","description":"scattered clouds","icon":"03n"}],
"base":"cmc stations",
"main":{"temp":285.32,"pressure":1008,"temp_min":284.15,"temp_max":286.48,"humidity":91},
"wind":{"speed":5.14,"gust":6.17,"deg":284},
"rain":{"3h":0},
"clouds":{"all":32},
"dt":1399600508,
"id":2643743,
"name":"London",
"cod":200
}
Pass-through Background Information
Notice how the URL is transformed between your call to the pass-through service and the call to the external server. The URL sent to the pass-through service is:
http://localhost:57772/Restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=Boston,ma
and the URL sent to the external server is:
http://api.openweathermap.org/data/2.5/weather?q=London,uk
The last parts of the URL starting with data are identical. The HTTP Server field sets the server in the outgoing call. The | in the URL field instructs the operation to strip the web application name and configuration name from the incoming URL and then include the remainder in the outgoind URL.
Note:
The EnsLib.REST.GenericService class does not provide any additional functionality over the EnsLib.HTTP.GenericService class. Although you could use the EnsLib.HTTP.GenericService class to pass-through a REST call, you should use the appropriate subclass.
Pass-through Troubleshooting
There are a few troubleshooting steps you can take if you don't get the expected results.
  1. Enter the openweathermap URL directly in the web browser without using Ensemble. Enter the following URL in the web browser:
    http://api.openweathermap.org/data/2.5/weather?q=London,uk
    This ensures that the weather server is working correctly.
  2. Examine the Ensemble message tracing for the production. A successful message trace looks like the following:
    The trace may help you identify where the error is.
  3. Run a TCP trace utility. Specify a local port to listen on, the server api.openweathermap.org, and port 80. In the pass-through operation settings, set the following properties:
    Then Select Apply and enter the pass-through service URL in a web browser:
    The TCP trace should show the HTTP request being sent out by the pass-through operation and the server's response.
Using SOAP Pass-through Services and Operations
This section adds a SOAP pass-through service and a SOAP pass-through operation. The service listens on the CSP port and sends the SOAP message to the pass-through operation. The pass-through operation sends the SOAP message to an external server, www.webservicex.net, which among other services provides a currency conversion service that returns the exchange rate for two specified currencies. In order to call the SOAP passthrough services, you need to use a SOAP toolkiit, such as SOAPUI. For information on the SOAPUI toolkit, see http://www.soapui.org/.
Select or create a namespace and production. In order to use the CSP port, you must define a web application in the namespace and a role. See Configuring an Ensemble System for step-by-step instructions to create a namespace, role, and web application. For this walkthrough, name the web application /soappassthrough and set the web application Dispatch Class to EnsLib.SOAP.GenericService.
Calling the External Server from the SOAP Toolkit
Before creating the pass-through services and operations, use a SOAP toolkit to create a project and call the external server directly. Using your SOAP toolkit, do the following:
Adding the SOAP Passthrough Service and Operation
This section adds a SOAP passthrough operation and a SOAP passthrough service that use the CSP port.
  1. Go to the Production Configuration page and select the plus sign for adding new operations.
    1. Specify the operation class: EnsLib.SOAP.GenericOperation
    2. Name the operation, such as ConvertCurrencySOAPCSPOp.
    3. Don't enable it yet.
    4. Select OK.
  2. Select the pass-through operation that you created and select the Settings tab.
    1. If you are using the external service registry, set the External Registry ID to identify the registry entry that sets the HTTP Server,HTTP Port, and URL settings and skip to Step 3. Otherwise specify these settings directly as follows:
    2. Enter the HTTP Server: www.webservicex.net
    3. In the URL field, enter | (vertical bar). This instructs the operation to remove the extra parts of the incoming URL that are needed by the web application but are not expected by the external service
    4. Check the Enabled checkbox.
    5. Select Apply.
  3. Select the plus sign for adding new services.
    1. Specify the operation class: EnsLib.SOAP.GenericService
    2. Name the operation, such as ConvertCurrencySOAPCSPServ.
    3. Don't enable it yet.
    4. Select OK.
  4. Select the pass-through service that you created and select the Settings tab.
    1. Check the Enabled checkbox.
    2. Ensure that the Port field is blank.
    3. Set the TargetConfigName to the passthrough operation that you created in the previous step.
    4. In Additional Settings, set Pool Size to 0. This suppresses the passthrough service from listening on the special port.
    5. Select Apply.
  5. Start the production.
  6. In your SOAP toolkit, enter the URL for the pass-through service using the CSP port. The URL consist of the following parts:
    For example, if you specified the service name as soappassthrough and the passthrough business service name as ConvertCurrencySOAPCSPServ, enter the following URL in a web browser:
    Note that all alphabetic characters in the web application name must be in lower case and the pass-through service name must match the case of the configuration item name.
    Then execute the request. The SOAP toolkit should return the same XML message that it previously returned.