Calling Web Services from RunMyJobs

You can call web services in RunMyJobs with Job Definitions. Web services can be imported into RunMyJobs using a wizard. The created Job Definitions are of type RedwoodScript.

These Job 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 Job 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 Jobs submitted via the published web service so you can differentiate them easily.

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

Web service Job Servers require the following license 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. If you have both license keys, the most restrictive applies. Note that the ProcessServerService.External.limit license key is also used by other Job Server types such as Platform Agents and SAP Connectors.
• A credential for the third-party web service.

Editing the Job Definition

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

To change this, you have to change the following:

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 Job Definition to XML.

Processing the Returned Response

The Job will retrieve the response with the following code:

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, assume you want to retrieve the price from the following response:

<?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:

// [...]
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.

jcsSetJobOutputParameter("retailPrice", price);

Special Parameters

You can use the following special Parameters for Job 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 RunMyJobs 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 RunMyJobs 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:

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

See Also

• Using the RedwoodScript Definition Type
• Using RedwoodScript in Processes
• RedwoodScript
• Integrating Redwood Server with Web Services
• Connecting Web Services with Redwood Server