OPEN SOURCE - Job Scheduler - Web Services for Executable Files

Job Scheduler
 
  Web Services for Executable Files

  This package includes configurations and implementations that can be used out of the box to launch executable files and shell scripts with Web Services.

For security reasons you should not configure jobs to execute files that have been directly addressed by a Web Service request. Instead you should configure the names of executable files as job parameters.

The implementation below suggests the use of environment variables to hand parameters from a request to an executable file: the variable names are forwarded as parameters to the command line. Note that the values themselves are not given as command line parameters as this would be quite tedious to secure against code injection.

The files for this solution stack are available in the archives:
Unix scheduler_shell_webservice.tar.gz
Windows scheduler_shell_webservice.zip


Configuration

Configurations and implementations are available in three languages, select the language required below:

  • Java

    The configuration in config/scheduler_shell_webservice_java.xml can be included in the scheduler.xml configuration file by using <base file="scheduler_shell_webservice_java.xml"/>.

    Download the job implementation from the sos.stacks.jar archive - the source code is given below.

  • JavaScript

    The configuration in config/scheduler_shell_webservice_javascript.xml can be included in scheduler.xml using <base file="scheduler_shell_webservice_javascript.xml"/>.

    The job implementation source code is given below.

  • Perl

    The configuration in config/scheduler_shell_webservice_perlscript.xml can be included in scheduler.xml using <base file="scheduler_shell_webservice_perlscript.xml"/>.

    The job implementation source code is given below.

    The jobs are implemented for Unix and Windows: a Perl implementation for Unix is included in the Job Scheduler distribution; for Windows systems a widespread Perl implementation such as provided by ActiveState (http://www.activestate.com) should be installed. At the time of writing version 5.8.0 of Perl for Unix and version 5.8.x of Perl for Windows have been tested to work with the Job Scheduler. Other Perl releases might not work as expected.

Use the Job Scheduler's own graphical Job Configuration Editor to modify the configuration.
A sample how to include configurations is given in config/scheduler_shell_webservice.xml


Web Service Request

To launch an executable file using a Web Service you have to create a request that might look like this:

  • for asynchronous job execution use the <startJob> element as in job.xml: 
    <?xml version="1.0" encoding="ISO-8859-1"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsa:To xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
      http://www.sos-berlin.com:10110/shell_job
    </wsa:To>
    <wsa:ReplyTo 
      xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
      <wsa:Address>
        http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
      </wsa:Address>
    </wsa:ReplyTo>
  </soapenv:Header>
  <soapenv:Body>
    <startJob xmlns="http://www.sos-berlin.com/scheduler">
      <job>shell_job/<job>
      <param><name>job_param_name_1</name><value>job_param_value_1</value>
      <param><name>job_param_name_2</name><value>job_param_value_2</value>
    </startJob>
  </soapenv:Body>
</soapenv:Envelope>
  • for synchronous job execution use the <addOrder> element as in order.xml: 
    <?xml version="1.0" encoding="ISO-8859-1"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsa:To xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
      http://www.sos-berlin.com:10110/shell_job_service
    </wsa:To>
    <wsa:ReplyTo 
      xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
      <wsa:Address>
        http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
      </wsa:Address>
    </wsa:ReplyTo>
  </soapenv:Header>
  <soapenv:Body>
    <addOrder xmlns="http://www.sos-berlin.com/scheduler">
      <param><name>job_param_name_1</name><value>job_param_value_1</value>
      <param><name>job_param_name_2</name><value>job_param_value_2</value>
    </addOrder>
  </soapenv:Body>
</soapenv:Envelope>

Note that besides the standard SOAP headers, these requests contain either the <startJob/> or <addOrder/> element. These elements are automatically transformed by the Job Scheduler into an asynchronous job start or into a job chain order for synchronous processing respectively. You are not limited to the element structure of <startJob/> or <addOrder/> in your request, but could use any valid xml structure. In this case, however, you would have to provide an xslt stylesheet that transforms the incoming request to the xml structure that is understood by the job implementation. See the job details below for the style sheet parameters.

The above samples are available in the directory samples/shell.webservice.request.
To simplify the creation of requests the samples/shell.webservice.command directory includes command files that post the sample files to the Job Scheduler Web Service:
Unix webservice_client.sh
Windows webservice_client.cmd


Addressing Web Services

For an asynchronous Web Service, such as a job start, the Web Service URL is configured in your scheduler.xml like this: 
<web_service name = "shell_job"
             url_path = "/shell_job"
             request_xslt_stylesheet = "config/scheduler_soap_request.xslt"
             response_xslt_stylesheet = "config/scheduler_soap_response.xslt">
</web_service>
 This configuration exposes a Web Service that can be addressed using http://host:port/shell_job, where host and port are the values specified in configuring the Job Scheduler, and /shell_job is the URL path in the sample above.

For synchronous Web Services with job chains the address would be configured as: 
<web_service name = "shell_job_service"
             url_path = "/shell_job_service"
             job_chain = "shell_job_service">
</web_service>
 No style sheets are given for this Web Service as the Job Scheduler does not transform the request but immediately hands the order to the job chain. Please note that the corresponding shell_job_service job chain has to be configured as shown in the configuration examples.


Web Service Response

For asynchronous Web Services the outgoing response is automatically transformed with a style sheet. The response returns the id that has been assigned to the job which could be used in later requests from the caller as <show_history/>: 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <sos:taskId xmlns:sos="http://www.sos-berlin.com/scheduler">42</sos:taskId>
  </soapenv:Body>
</soapenv:Envelope>
 For synchronous Web Services the execution result might be more informative: 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <sos:order xmlns:sos="http://www.sos-berlin.com/scheduler">
      <sos:id>857</sos:id>
      <sos:state>response</sos:state>
      <sos:initialState>request</sos:initialState>
      <sos:jobChain>shell_job_service</sos:jobChain>
      <sos:job>shell_job_response</sos:job>
      <sos:task>2740</sos:task>
      <sos:inProcessSince>2006-05-26 21:02:58.984</sos:inProcessSince>
      <sos:created>2006-05-26 21:02:58.906</sos:created>
      <sos:priority>0</sos:priority>
      <sos:webService>shell_job_service</sos:webService>
      <params>
        <param><name>order_param_name_1</name><value>order_param_value_1</value></param>
        <param><name>order_param_name_2</name><value>order_param_value_2</value></param>
      </params>
    </sos:order>
  </soapenv:Body>
</soapenv:Envelope>
 You might be tempted to ask why the <params> element structure is not prefixed with sos. The reason is that these elements are not part of the sos namespace but had been given as additional elements in the initial request. They were subsequently transformed into order parameters and are now returned to the caller.


Web Service Jobs

For asynchronous requests the launch executable files job is implemented as follows:

  • Job: Launch Executable File or Shell Script (shell_job)

    This job receives the parameters from the XML request, creates environment variables for every job parameter and starts an executable file specified in the job parameters for every job parameter and starts an executable file specified in the shell_command job parameter.

    Environment variables are used for security reasons: the variable names are forwarded as parameters to the command line, the values themselves are not given as command line parameters as this would be too tedious to secure against code injection. Output to stdout and stderr is caught and added to the Job Scheduler log file.

    Note that the samples/shell.webservice.command directory includes an example executable shell script. This script includes command files that simply echo the names and values of the command line parameters:
    Unix webservice_shell.sh
    Windows webservice_shell.cmd

    Show Job Documentation Show Job Source Code for Java
    Show Job Source Code for JavaScript Show Job Source Code for Perl


For synchronous job execution the request is processed by a job chain with the following jobs:

 
 
  Office Automation - Document Delivery - Job Scheduling - Systems Integration - Output Management - Enterprise Application Integration - Connectivity