Calling Web Services from within Redwood Server

You can call web services in Redwood Server via Process Definitions. Web services can be imported into Redwood Server using a wizard, the created Process Definitions are of type RedwoodScript.

These Process Definitions allow you to:

  • Use RedwoodScript, which is a powerful Java-based scripting language, in your requests
  • Use parameters in your requests, which adds all the benefits of parameters (scripting, user interaction, constraints and a lot more)
  • Easy schedule of the requests
  • Add basic authentication to the request; if authentication is not required, you leave the User and Password fields of the wizard empty in which case a credential with the Real User{redwood}:nocredential is created for you.

These Process Definitions can then be customized and published as new web services, which can then be called by third party applications. Notes can be added to processes submitted via the published web service so you can differentiate them easily.

To create a Process Definition based on a web service, you will need the URL to the WSDL. The default Process Definition that gets created will have parameters for each parameter of the request.

Web service Process Servers require the following key

  • WebServices.OutboundServer.limit - the total number of distinct web service credential endpoints

You should always specify the FQDN for each server in a credential endpoint.

Prerequisites

  • a free slot in WebServices.OutboundServer.limit and ProcessServerService.External.limit for a credential to the third-party web service. The number of soap credentials for a given endpoint you can create is limited by the WebServices.OutboundServer.limit and ProcessServerService.External.limit license keys; when you have both license keys, the most restrictive applies. Note that the ProcessServerService.External.limit license key is also used by other Process Server types such as Platform Agents and SAP connectors.
  • a credential for the third-party web service

Editing the Process Definition

The default Process Definition is designed to help you tailor it to your own needs. The process will print both the request and the answer into the output file of the process, by default.

To change this, you have to change the following:

Copy 
jcsOut.println("Request:");
jcsOut.println(message);
jcsOut.println("Response:");
jcsOut.println(answer);

You would usually only have the following jcsOut.println(answer); to write the entire response to an output file. You might want to set the format of the Process Definition to XML.

Processing the Returned Response

The process will retrieve the response with the following code:

Copy 
answer = SOAP.formatXML(req.getResponseXML());

. The response will thus be a standard XML document. You can use the getStringByXPath method to retrieve given values inside the response.

For example, you want to retrieve the price from the following response:

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <xsd:getPrice xmlns:xsd="http://prices.example.com/xsd">
      <xsd:return>42.0</xsd:return>
    </xsd:getPrice>
  </soap:Body>
</soap:Envelope>

Using the following code, you can retrieve the price value of 42.0 and store it in the variable price:

Copy 
// [...]
answer = req.getResponseXML();
if (answer != null )
{
  answer = SOAP.formatXML(req.getResponseXML());
  jcsErrLog.debug(answer);

  // Set the namespace
  req.setNamespace("http://prices.example.com/xsd");

  // retrieve the value of the specific XPath and store it in the variable price
  String price = req.getStringByXPath("soap:Envelope/soap:Body/xsd:getPrice/xsd:return");

  //Optional, but good; print the result to the ErrLog file when the process is run in debug mode
  jcsErrLog.debug(price);
}

//[...]

If you followed the example above, you might want to store the price in an Out parameter, such as: retailPrice

Copy 
jcsSetJobOutputParameter("retailPrice", price);

Special Parameters

You can use the following special parameters for Process Definitions that call web services:

  • SOAP_HEADER_<header> - set the SOAP header named <header>
  • SOAP_URL - use an alternate URL to the one in the WSDL
  • SOAP_Action - use an alternate action to the one in the WSDL
  • JCS_USER - the username required for the request
  • JCS_PASSWORD - the password required for the request; if JCS_USER is set and not JCS_PASSWORD, then Redwood Server will look for the password in the credential associated with the soap protocol, endpoint, and username (matching the value of JCS_USER)

Note: You always need to have a credential for each outbound web service, even if you specify the JCS_PASSWORD parameter.

Credentials

The soap credential protocol is not only used to store username, password, and endpoint combinations; it is also used to enforce license restrictions. Each and every web service you call from Redwood Server needs a valid credential, even if the call itself does not require authentication.

When a web service is called, a valid credential must exist for the remote server, the lookup is performed on the endpoint in the following order:

  1. <server>:<port>.
  2. <server>.

If no authentication is required and a credential matching the server has been found, the process will be submitted.

If authentication is required, the JCS_USER and JCS_PASSWORD parameters will be evaluated:

JCS_USER JCS_PASSWORD Authentication Details Used
<user> not set <user>-<server>[:<port>]-soap
{virtual}:<v_user> <user>-<server>[:<port>]-soap that has Virtual User set to <v_user>

<user> <password> <user>/<password>
not set not set none, if process requires authentication, process will fail

To prevent authentication headers to be sent to the web service, you can use the {redwood}:nocredential syntax in the Run As User field; in your Process Definition source, you can also use req.setAuthentication(SOAPRequest.REDWOOD_NOCREDENTIAL, null); to this effect.

See Also

webservice