Skip to main content

Pass-through Service and Operation Walkthrough

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.

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 Web 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 Web port, you must define a web application in the namespace and a role. See Configuring an InterSystems IRIS 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.GenericServiceOpens in a new tab.

  1. On the production configuration page, click the plus sign for adding new operations.

    1. Specify the operation class: EnsLib.REST.GenericOperationOpens in a new tab

    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 click 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 check box.

    6. Select Apply.

  3. Click the plus sign for adding new services.

    1. Specify the service class: EnsLib.REST.GenericServiceOpens in a new tab

    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 click 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 Connection Settings, check the Enable Standard Requests check box.

    4. 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.

    5. Check the Enabled check box.

    6. Select Apply.

  5. Start the production.

  6. Enter the URL for the pass-through service using the Web port. The URL has the following form:

    • https://<baseURL>/ — the <baseURL> for your IRIS instance.

    • web-application-name/ that you specified, for example restpassthrough/. See Configuring a Web Application for a Pass-through Business Service.

    • passthrough-service-name/ — for example, WeatherRESTPassthroughServ/

    • URL required by the external service, such as data/2.5/weather?q=London&appid=asd9g87w42MyAPIKey. You need to sign-up for an OpenWeather account to obtain an API key.

    For example, enter the following URL in a web browser, including the API key that you obtained from OpenWeather:

    http://<baseURL>/restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=London&appid=asd9g87werMyAPIKey

    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 has the following form, using the <baseURL> for your instance:

http://<baseURL>/Restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=London

and the URL sent to the external server is:

http://api.openweathermap.org/data/2.5/weather?q=London

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 outgoing URL.

Note:

The EnsLib.REST.GenericServiceOpens in a new tab class does not provide any additional functionality over the EnsLib.HTTP.GenericServiceOpens in a new tab class. Although you could use the EnsLib.HTTP.GenericServiceOpens in a new tab 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 InterSystems IRIS. 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 production message tracing for the production. A successful message trace looks like the following:

    Message trace without error icons

    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:

    • HTTP Server: localhost

    • HTTP Port: port that TCP trace is listening on

    Then Select Apply and enter the pass-through service URL in a web browser, using the <baseURL> for your instance:

    http://<baseURL>/Restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=Boston,ma

    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 Web 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/Opens in a new tab.

Select or create a namespace and production. In order to use the Web port, you must define a web application in the namespace and a role. See Configuring an InterSystems IRIS 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.GenericServiceOpens in a new tab.

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:

  • Create a new project.

  • Specify the following as the location of the WSDL file:

    http://www.webservicex.net/CurrencyConvertor.asmx?WSDL
    
  • Select the request generated for the project. If your toolkit generates a SOAP 1.1 and 1.2 requests, use the SOAP version 1.2 request. The toolkit displays the SOAP message that is sent to the server. For example, SOAPUI displays:

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:web="http://www.webserviceX.NET/">
      <soap:Header/>
      <soap:Body>
        <web:ConversionRate>
          <web:FromCurrency>?</web:FromCurrency>
          <web:ToCurrency>?</web:ToCurrency>
        </web:ConversionRate>
      </soap:Body>
    </soap:Envelope>
    
  • Replace the two question marks with the abbreviations for the currencies. For example, to convert Euros to US Dollars, replace the first question mark with EUR and the second question mark with USD.

  • Execute the request. Using SOAPUI, you execute the request by Selecting the green arrow. The SOAP toolkit displays the response SOAP message, such as:

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <soap:Body>
        <ConversionRateResponse xmlns="http://www.webserviceX.NET/">
          <ConversionRateResult>1.3603</ConversionRateResult>
        </ConversionRateResponse>
      </soap:Body>
    </soap:Envelope>
    

Adding the SOAP Passthrough Service and Operation

This section adds a SOAP passthrough operation and a SOAP passthrough service that use the Web port.

  1. Go to the Production Configuration page and click the plus sign for adding new operations.

    1. Specify the operation class: EnsLib.SOAP.GenericOperationOpens in a new tab

    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 click 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 check box.

    5. Select Apply.

  3. Click the plus sign for adding new services.

    1. Specify the operation class: EnsLib.SOAP.GenericServiceOpens in a new tab

    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 click the Settings tab.

    1. Check the Enabled check box.

    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 Connection Settings, check the Enable Standard Requests check box.

    5. In Additional Settings, set Pool Size to 0. This suppresses the passthrough service from listening on the special port.

    6. Select Apply.

  5. Start the production.

  6. In your SOAP toolkit, enter the URL for the pass-through service using the Web port. The URL has the following form:

    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:

    http://<baseURL/soappassthrough/ConvertCurrencySOAPCSPServ/CurrencyConvertor.asmx

    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.

FeedbackOpens in a new tab