HCL Workload Automation, Version 9.4

RESTful Web Services jobs

A RESTful Web Services job sends requests to a Web resource via the following HTTP methods:
DELETE
Deletes a resource
GET
Retrieves the header and body of a resource
HEAD
Retrieves only the header of a resource without its body
POST
Creates a resource
PUT
Changes the state of a resource or updates it
A description of the job properties and valid values are detailed in the context-sensitive help in the Dynamic Workload Console by clicking the question mark (?) icon in the top-right corner of the properties pane.
This section describes the required and optional attributes for RESTful Web Services jobs. Each job definition has the following format and arguments:
Table 1. Required and optional attributes for the definition of a RESTful Web Services job
Attribute Description/value Required
Authentication

If the Web service requires authentication, you can use either credentials or certificates to authenticate.

credentials userName The user name needed to gain access to the URI of the Web service.  
password The password with which userName gains access to the Web service.  
CertificateGroup keyStoreFilePath The fully qualified path of the keystore file containing the private key used to make the connection.

Only keystore files with the jks extension are supported.

  
password The password that protects the private key and is required to make the connection.  
HostnameVerifyCheckbox Verifies that the syntax of the Web server name, as featured in the keystore file, matches the URI of the Web service exactly. If they do not match, no authorization is granted to access the server.

This control is not enforced if this keyword is not used.

  
RESTAction URI The resource identifier of the Web service to which you are sending the request. ✓
method The HTTP method that defines the request. It can be: GET, DELETE, HEAD, PUT, or POST. ✓
outputFileName The full name of the file where the response from the Web resource is to be returned.  
QueryParametersValues

One or more query parameters that tailor and filter the response output. Enter a keyword for every parameter you need to specify.

 QueryParametersValue The name of the query parameter and its value. For example:
<jsdlrestful:QueryParametersValue 
  key="colour">blue</jsdlrestful:QueryParametersValue>
where colour is the parameter name and blue is its value.		  
Body contentType The media type of the entity-body sent to the recipient resource; for example: json, xml, html. In the case of the HEAD method, enter the media type that would have been sent had the request been a GET.  
BodyGroup

Enter either the name of the file that contains the body of the request or the body text directly.

Attention: DELETE requests refuse a body in the request. Do not enter any body input or the request will fail.
 FileBody InputFileName The name of the file containing the body of the request.  
TextBody InputTextBody The body of the request that you are sending with the HTTP method.  
Advanced HeadersValues

One or more HTTP or custom headers associated with the HTTP request. Enter a keyword for every header you need to specify.

 HeadersValue The name of the header and its value in the form:
<jsdlrestful:HeadersValue 
  key="Accept-Charset">utf-8</jsdlrestful:HeadersValue>
  
Accept The media type in which the response from the Web resource is to be returned. The type is usually specified by the resource to which you are sending the request.  
JSONPropertiesGroup JsonObjectResultQuery A query that retrieves the value of a specific field in a JSON-type response. This value can be located under the JSON Result item in the job properties returned after the job completed and can be passed to other jobs. For example:
query.results.quote.AskRealtime
  
Retry options NumberOfRetries The maximum number of retries, in case of connection failure. Default value is 0.  
RetryIntervalSeconds The wait time between retries, in case of connection failure. Default value is 30 seconds.  
The following example shows the definition of a job that sends a GET request to the Web service of LB AIRLINES to get the passengers list of a certain flight:
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdlrestful="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdlrestful" name="RESTFUL"
<jsdl:variables>
  <jsdl:stringVariable name="tws.jobstream.name">JOBS</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.jobstream.id">JOBS</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.name">getflightpasslst</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.workstation">FNC050799</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.iawstz">201406290000</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.promoted">NO</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.resourcesForPromoted">10</jsdl:stringVariable>
  <jsdl:stringVariable name="tws.job.num">612741339</jsdl:stringVariable>
</jsdl:variables>
<jsdl:application name="restful">
  <jsdlrestful:restful>
                      <jsdlrestful:RestfulParameters>
                              <jsdlrestful:Authentication>
                                      <jsdlrestful:credentials>
                                              <jsdl:userName>aladmin</jsdl:userName>
                                              <jsdl:password>{aes}t77HX7Zv9/NwG6DmFbePPdk6d
+JESD0AWRNO0XudYeM=</jsdl:password>
                                      </jsdlrestful:credentials>
                              </jsdlrestful:Authentication>
                              <jsdlrestful:RESTAction>
                                     <jsdlrestful:URI>https://query.lblines.com</jsdlrestful:URI>
                                     <jsdlrestful:method>GET</jsdlrestful:method>
<jsdlrestful:outputFileName>passnames.xls</jsdlrestful:outputFileName>
                                        <jsdlrestful:QueryParametersValues>
                                                <jsdlrestful:QueryParametersValue
key="flight">lb915</jsdlrestful:QueryParametersValue>
                                                <jsdlrestful:QueryParametersValue
key="day">thursday</jsdlrestful:QueryParametersValue>
                                                <jsdlrestful:QueryParametersValue
key="time">8:45</jsdlrestful:QueryParametersValue>
                                       </jsdlrestful:QueryParametersValues>
                              </jsdlrestful:RESTAction>
                              <jsdlrestful:Body>
<jsdlrestful:contentType>application/json</jsdlrestful:contentType>
                                      <jsdlrestful:BodyGroup>
                                              <jsdlrestful:FileBody>
                                                      <jsdlrestful:InputFileName/>
                                              </jsdlrestful:FileBody>
                                      </jsdlrestful:BodyGroup>
                              </jsdlrestful:Body>
                              <jsdlrestful:Advanced>
                                      <jsdlrestful:HeadersValues>
                                              <jsdlrestful:HeadersValue
key="Accept-Charset">utf-8</jsdlrestful:HeadersValue>
                                              <jsdlrestful:HeadersValue
key="Accept-Language">en-CA</jsdlrestful:HeadersValue>
                                      </jsdlrestful:HeadersValues>
                                      <jsdlrestful:Accept>json</jsdlrestful:Accept>
                                      <jsdlrestful:JSONPropertiesGroup>
<jsdlrestful:JsonObjectResultQuery>query.results.travellerlist</jsdlrestful:JsonObjectResultQuery>
                                      </jsdlrestful:JSONPropertiesGroup>
                              </jsdlrestful:Advanced>
                        </jsdlrestful:RestfulParameters>
              </jsdlrestful:restful>
  </jsdl:application>
  <jsdl:resources>
    <jsdl:orderedCandidatedWorkstations>
      <jsdl:workstation>71E6B2B225EF498E916BF57AD817A228</jsdl:workstation>
    </jsdl:orderedCandidatedWorkstations>
  </jsdl:resources>
</jsdl:jobDefinition>

Scheduling, stopping, and reconnecting to the job in HCL Workload Automation

You schedule HCL Workload Automation RESTful Web services jobs by defining them in job streams. Add the job to a job stream with all the necessary scheduling arguments and submit it.

You can submit jobs using the Dynamic Workload Console, Application Lab, or the conman command line.

You can submit jobs in a z/OS environment using the Dynamic Workload Console or the ISPF application.

After submission, when the job is running and is reported in EXEC status in HCL Workload Automation, you can stop it if necessary, by using the kill command. When you stop the job, HCL Workload Automation collects the job log when the agent restarts and assigns the Error or ABEND status to the job.

If the HCL Workload Automation agent becomes unavailable when you submit the job or while the job is running, as soon as the agent becomes available again HCL Workload Automation begins monitoring the job from where it stopped.

Job properties

You can see the job properties by running conman sj <job_name>;props, where <job_name> is the RESTful Web services job name.

The properties are listed in the Extra Information section of the output command. The properties are all HTTP_HEADERs returned by the server to the client with an exception for the Status Code and the JSON Result. The names of the header properties depend on the RESTful service response that changes from server to server. Some HTTP header names are standard, but most headers are optional or custom.

Job log content

You can see the job log content by running conman sj <job_name>;stdlist, where <job_name> is the RESTful Web services job name.

You can view the job log content from the Dynamic Workload Console and Application Lab. See Analyzing the job log.

Business Scenario

NEIGHBOURHOOD BROKERS runs - on the hour - a job stream that retrieves the current stock prices of three companies listed in the NY stock exchange and posts them on their web site. The job stream runs every hour and consists of the following jobs:
  • A number of RESTful Web Services jobs that each GET a company's stock value. The stock value is retrieved and saved together with the job properties in the job log.
  • A job that retrieves the value from the job properties of each job log and saves them in a temporary file.
  • A final job that takes these values from the temporary file and POSTs them on the NEIGHBOURHOOD BROKERS Web site.

See also

From the Dynamic Workload Console you can perform the same task as described in

Creating job definitions.

For more information about how to create and edit scheduling objects, see

Designing your Workload.