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.

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.
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.
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.
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.
Start the production.
In your SOAP toolkit, 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 soappassthrough/. See Configuring a Web Application for a Pass-through Business Service.
- passthrough-service-name/ — for example, ConvertCurrencySOAPCSPServ/
- URL required by the external service, such as CurrencyConvertor.asmx.
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.

Using REST Pass-through Services and Operations