Web Services

Any job or job chain in the JobScheduler can be exposed as a Web Service. The JobScheduler accepts SOAP requests and sends a standard SOAP response.

The JobScheduler can be configured to accept requests to start jobs and job chains

via a generic JobScheduler Web Service interface:

<web_service
     ...
     name = "scheduler"
     url_path = "/scheduler" >
</web_service>

via a specific Web Service interface for an individual job or job chain:

<web_service
     ...
     name = "start_backup"
     url_path = "/start_backup" >
</web_service>

It is important here to distinguish between the two types of Web Service requests.

Asynchronous Web Service Requests

FEATURE AVAILABILITY ENDING WITH RELEASE 1.10

The Asynchronous Web Services Request feature is deprecated, see
JS-1347 - Getting issue details... STATUS

The caller receives an acknowledgement that his request has been accepted by the JobScheduler and will be processed. Job execution is done asynchronously i.e. at a later run time. This is useful if batch jobs need execution time or should start at a predefined point in time.

No changes to job implementations are required for asynchronous web service processing.

Configure JobScheduler

Update scheduler.xml with a generic web service interface. The following configuration will enable the JobScheduler to accept a variety of SOAP requests.

<http_server >			
	<web_service
         debug = "no"
         request_xslt_stylesheet = "config/scheduler_soap_request.xslt"
         response_xslt_stylesheet = "config/scheduler_soap_response.xslt"
         name = "scheduler"
         url_path = "/scheduler" >
    </web_service>
</http_server>

After the update to the scheduler.xml file to make the configuration effective restart the JobScheduler service (Windows) or daemon (Linux).
Now the JobScheduler is accessible via a SOAP web service. The web service can be accessed with URL http://<jobscheduler-host>:<jobscheduler-port>/scheduler e.g. http://localhost:4444/scheduler

Start a job chain

To start a job chain via SOAP web service the SOAP client should send a post request to the JobScheduler with the following SOAP format:

SOAP request to start a job chain

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <addOrder xmlns="http://www.sos-berlin.com/scheduler">
        <!-- Job Chain name with full qualified path after live folder-->
         <jobChain>examples/01_JobChainShellJobs/01_JobChainA</jobChain>
         <title>soaptest</title>
         <!-- parameters passed to the job chain-->
         <param>
            <name>SOAP_PARAM1</name>
            <value>Value1</value>
         </param>
         <param>
            <name>SOAP_PARAM2</name>
            <value>Value2</value>
         </param>
      </addOrder>
   </soapenv:Body>
</soapenv:Envelope>

Above given SOAP request will submit an order to the job chain example/01_JobChainShellJobs/01_JobChainA. The order will also have two parameters SOAP_PARAM1=Value1 and SOAP_PARAM2=Value2 that will be passed to the job chain.

With the SOAP request being received the JobScheduler will immediately add the order and send back the order id with the SOAP response.

SOAP response to start an order for a job chain

<?xml version="1.0" encoding="ISO-8859-1"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <sos:orderId xmlns:sos="http://www.sos-berlin.com/scheduler">100635</sos:orderId>
  </soapenv:Body>
</soapenv:Envelope>

Check Order Status

To check the status of the order that has been sent to JobScheduler you can send the below SOAP request to the JobScheduler.

For possible errors with this operation see JS-1183 - Getting issue details... STATUS for more information.

SOAP request to check order status

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <showOrder xmlns="http://www.sos-berlin.com/scheduler">
         <jobChain>examples/01_JobChainShellJobs/01_JobChainA</jobChain>
         <order>100638</order>
      </showOrder>
   </soapenv:Body>
</soapenv:Envelope>

Start a Job

To start a job via SOAP web service the SOAP client should send a post request to the JobScheduler with the following SOAP format.

SOAP request to start a job

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <startJob xmlns="http://www.sos-berlin.com/scheduler">
         <job>sos/housekeeping/scheduler_rotate_log</job>
         <at>now+60</at>
      </startJob>
   </soapenv:Body>
</soapenv:Envelope>

Above given SOAP request will start the job sos/housekeeping/scheduler_rotate_log. The job will be started 60 seconds after arrivall of the SOAP request.

With the SOAP request being received the JobScheduler will immediately process the task and the task id will be sent back with the SOAP response.

SOAP response on start of a job

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <sos:taskId xmlns:sos="http://www.sos-berlin.com/scheduler">17641247</sos:taskId>
   </soapenv:Body>
</soapenv:Envelope>

Synchronous Web Service Requests

Should a request be received by the JobScheduler then it will be instantly processed. The caller receives the job execution result on the fly. Jobs have to be prepared to handle this kind of request.

Configure JobScheduler

In order to use the synchronous web service feature a new web service has to be created in the <web_services> element as follows and it is required to configure a job chain, e.g. web_service_test in the scheduler.xml configuration file.

Update the scheduler.xml file with a web service interface.

<http_server >			
<web_service name="test"
        job_chain="web_service_test"
        url_path="/test"/>
</http_server>

To make changes to the scheduler.xml file effective restart the JobScheduler service (Windows) or daemon (Linux).

Configuration of a Synchronous Web Service

The following job chain and job elements have to be configured:

Job Chain

Job Chain

<?xml version="1.0" encoding="ISO-8859-1"?>
<job_chain  name="web_service_test">
    <job_chain_node  state="1" 
                       job="web_service_test_job" 
                next_state="success" 
               error_state="error"/>
    <job_chain_node  state="success"/>
    <job_chain_node  state="error"/>
</job_chain>

Job

web_service_test_job

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  order="yes" stop_on_error="no" name="web_service_test_job">
    <script  language="javax.script:ecmascript">
        <![CDATA[
function spooler_process(){
    var order = spooler_task.order();		
    var operation;	
      try{
			operation = order.web_service_operation();
		} catch (e){
			spooler_log.info("There is no Web Service operation attached to this order");
			return true;
		}
		
		// read request		
		var request = operation.request();
		spooler_log.info("Content of Webservice Request:\n"+request.string_content);
		
		// send reply
		var response = operation.response();
		response.string_content = "Task ID: " + spooler_task.id;
		response.send();
		
		return true;
}
        ]]>
    </script>
    <run_time />
</job>

The purpose of this job is to interpret possible protocols such as SOAP. The job receives the request content in either binary or string format. Note that in order to keep this example simple XML will not be interpreted as this would make the code longer and more complicated. The use of DOM is also not covered by this tutorial. Therefore the following job only logs the request content and returns a string containing the Task ID.

The Creation of Jobs for Synchronous Web Services

The following JavaScript solution shows a simple implementation of the request/response mechanism:

JavaScript : web_service_test_job

function spooler_process(){
    var order = spooler_task.order();		
    var operation;	
      try{
			operation = order.web_service_operation();
		} catch (e){
			spooler_log.info("There is no Web Service operation attached to this order");
			return true;
		}
		
		// read request		
		var request = operation.request();
		spooler_log.info("Content of Webservice Request:\n"+request.string_content);
		
		// send reply
		var response = operation.response();
		response.string_content = "Task ID: " + spooler_task.id;
		response.send();
		
		return true;
}

The purpose of this implementation is to interpret possible protocols such as SOAP. The job receives the request content in either binary or string format. Note that in order to keep this example simple XML will not be interpreted as this would make the code longer and more complicated. The use of DOM is also not covered by this tutorial. Therefore the following job logs the request content and returns a string containing the Task ID.

The web_service_operation() call is placed in a try-catch block at the start of the job. This is required as it is possible that the job has to process an order that was created by the JobScheduler but that has not been processed before the JobScheduler terminated. In this case the JobScheduler would load the order from its database although the HTTP connection to the wb service client no longer exists. Further, the Web_service_operation object would no longer exist. The job should catch this error and decide how to handle the order.

The request content is retrieved from the Web_service_request object and written in the log.

The answer is added to the Web_service_response object and synchronously sent back to the web service client using send().

In practice the Web_service_request would be retrieved by one job and the Web_service_response set by another. It is possible to create a job chain in which the first job reads the Web_service_request object and evaluates and writes the request parameters to the order payload. Subsequent jobs would then process the order payload and only the last job would write to the Web_service_response object and call the send() method.

References

Change Management References

T	Key	Linked Issues	Fix Version/s	Status	P	Summary	Updated

Loading...

Refresh

Documentation

JobScheduler Web Services

Space shortcuts

Page tree

Web Services

Asynchronous Web Service Requests

Configure JobScheduler

Start a job chain

Check Order Status

Start a Job

Synchronous Web Service Requests

Configure JobScheduler

Configuration of a Synchronous Web Service

Job Chain

Job

The Creation of Jobs for Synchronous Web Services

References

Change Management References

Documentation

Space shortcuts

Page tree

How To - SOAP Interface

Web Services

Asynchronous Web Service Requests

Configure JobScheduler

Start a job chain

Check Order Status

Start a Job

Synchronous Web Service Requests

Configure JobScheduler

Configuration of a Synchronous Web Service

Job Chain

Job

The Creation of Jobs for Synchronous Web Services

References

Change Management References

Documentation