SchedulerService Service

The following terms are associated with the SchedulerService service:

Agents (or iBots) - These are Presentation Services catalog objects.
Jobs - These are scheduler objects, and every agent has at least one job stored in the BI_PLATFORM schema.
JobInstances - These are scheduler objects representing active or completed jobs and are stored in the BI_PLATFORM schema.

Use this service to list, and detail scheduler jobs and job instances, and to purge and remove job instances (removing a job automatically purges job instances). Deleting agents automatically removes jobs.

To use this service, you must obtain a user session ID to return a list of Job or Job Instance Reference ID's, which you use to get details or remove the object. You obtain a user session ID by using the logon() method of the SAW session service (for more information, see logon() Method). You must then apply filters to specify particular Job Reference IDs and Job Instance IDs.

For examples of using the SchedulerService service methods, see Examples of Using the SchedulerService API

The client must be granted the privileges Access SOAP, and Access SchedulerService Service to call methods in the SchedulerService service API. These privileges are granted by default to the BIConsumer application role. You manage these privileges using the Manage Privileges Page in Presentation Services Administration.

The methods described in this section are synchronous unless stated otherwise.

iBotService Service shows the supported methods.

Method Names	Description
getJobReferences() Method	Returns a list of Jobs that match the selection criteria in the specified filter argument.
getJobInstanceReferences() Method	Returns a list of Job Instances that match the selection criteria in the specified filter argument.
getJob() Method	Returns a Job definition for a specified Job reference.
getJobInstance() Method	Returns Job Instance details for a specified Job Reference.
cancelJobInstance() Method	Requests to cancel an executing Job Instance for a specified Job Reference.
removeJobs() Method	Requests to remove a Job definition for a specified Job Reference.
purgeJobInstances() Method	Requests to purge an existing Job Instance for a specified Job Reference.

getJobReferences() Method

Use the getJobReferences() method to get a list of job references based on a filter.

Returned references are not live and are invalidated when jobs or instances are deleted.

Signature

JobReference[] getJobReferences(List[] JobFilter, String SessionID);

Arguments	Description
List[] JobFilter	Selection criteria that returns matching job references. An empty JobFilter results in all job references being returned. Note that filters are applied in the context of the calling user, which means that a user is restricted to listing jobs within their tenancy but does not require any Presentation Services catalog permissions on the agent corresponding to the job. For more information, see JobFilter Structure, and JobReferenceAndInstanceReferences Structure.
String SessionID	Specifies the session ID, which is usually returned by the login method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null. If no Session IDs are specified then all JobReferences are returned.

Arguments

Description

List[] JobFilter

Selection criteria that returns matching job references. An empty JobFilter results in all job references being returned. Note that filters are applied in the context of the calling user, which means that a user is restricted to listing jobs within their tenancy but does not require any Presentation Services catalog permissions on the agent corresponding to the job.

For more information, see JobFilter Structure, and JobReferenceAndInstanceReferences Structure.

String SessionID

Specifies the session ID, which is usually returned by the login method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null. If no Session IDs are specified then all JobReferences are returned.

getJobInstanceReferences() Method

Use the getJobInstanceReferences() method to get a list of job instances that correspond to running, cancelled or completed jobs.

The JobInstanceFilter must include one or more Job References (unknown Job References are ignored).

A structure is returned in the list for each Job which has associated Job Instances that satisfy the filter. For example, if the method is invoked with a JobInstanceFilter that specifies three Job references, and two of these Jobs are found to have associated Job Instances, then there will be two JobReferenceAndInstanceReferences structures returned in the list.

There is no limit to the number of structures and job instances that can be returned. Performance of this method is critical and must be optimized to allow efficient polling of job status.

References are not live and are invalidated if jobs or instances are deleted or cancelled.

The following properties can be applied when listing job instance references:

List of JobReference [Mandatory]. For more information, see JobReferenceAndInstanceReferences Structure
JobInstanceStatus [Optional] For more information, see JobInstanceStatus Enumeration.
JobFilter, JobInstanceFilter, and PurgeJobInstancesFilter properties are selection criteria that are used as follows:
- A filter is always applied in the context of the current user.
- Properties in the filter are selection criteria.
- Filter and its properties must be populated according to the schema.
- If the selection criteria are valid, but would return Jobs that are not visible to the current user these jobs is excluded without error.
- All properties in a filter is used as selection criteria (union).
- Filter criteria are applied by the server at the time the request is serviced.
For more information, see JobFilter Structure, JobInstanceFilter Structure, and PurgeJobInstancesFilter Structure.

Signature

JobReferenceAndInstanceReferences[] getJobInstanceReferences(Array JobInstanceFilter, String SessionID);

Arguments	Description
JobInstanceFilter filter	Specifies the selection criteria that determines which JobInstanceReferences to return. For more information, see JobInstanceFilter Structure and JobReferenceAndInstanceReferences Structure.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

getJob() Method

Use the getJob() method to get the Job definition given a Job Reference.

If you try to get a job that doesn't exist, you get Job not found error.

Signature

Job[] getJob(String JobReference, String SessionID);

Arguments	Description
String JobReference	Specifies a unique job identifier. For more information, see Job Structure.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

getJobInstance() Method

Use the getJobInstance() method to get the Job Instance details, when given a Job Instance Reference.

If you try to get a Job Instance that doesn't exist, you get JobInstance not found error.

Signature

JobInstance[] getJobInstance(String JobReference, String JobInstanceReference, String SessionID);

Arguments	Description
String JobReference	Specifies a unique job identifier. For more information, see JobInstance Structure.
String JobInstanceReference	Specifies a unique job instance identifier.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

cancelJobInstance() Method

Use the cancelJobInstance() method to request to cancel an executing Job Instance, when given a reference to an existing Job Instance.

Successful return indicates that the cancellation request has been accepted. Callers must use the getJobInstanceReferences operation (with an appropriate filter - such as Job Reference and State) or using the getJobInstance operation (and checking the JobInstanceStatus property), to determine if the cancellation has completed.

Cancelling a Job Instance that is not running has no effect. Cancelling a Job Instance that doesn't exist raises a JobInstance not found error.

Signature

Boolean cancelJobInstance(String JobReference, String JobInstanceReference, String SessionID);

Arguments	Description
String JobReference	Specifies a unique job identifier.
String JobInstanceReference	Specifies a unique job instance identifier. For more information, see JobReferenceAndInstanceReferences Structure.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

removeJobs() Method

Use the removeJobs() method to remove associated jobs, given a list of Job References.

If you try to remove a job that does not exist, it will be ignored and logged. The number of Jobs actually removed is returned.

Signature

Unsigned Integer removeJobs(List JobReference[], String SessionID);

Arguments	Description
List JobReference[]	Specifies the job identifiers of the removed jobs. For more information, see JobReferenceAndInstanceReferences Structure.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

purgeJobInstances() Method

Use the purgeJobInstances() method to purge Job Instances based on a filter.

The purgeJobInstancesFilter must contain either a populated list of Job References or UserIDs, and if this is not done correctly then it will result in an Invalid Choice SOAP fault being raised. Attempting to purge with a Job Reference or UserID that does not exist will be ignored and logged.

The following properties can be applied when purging job instances:

Choice of only one of the following: [Mandatory]:
- List of Job Reference [Optional].
- List of User IDs [Optional].

Signature

Void purgeJobinstances(List[] PurgeJobInstancesFilter, String SessionID);

Arguments	Description
List[] PurgeJobInstancesFilter	Specifies filter properties for the Job Instances to purge. For more information, see PurgeJobInstancesFilter Structure.
String SessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Examples of Using the SchedulerService API

This section assumes that the reader is familiar with Java and SOAP based web services. The Java code that follows is intended to illustrate API usage.

Example - Creating a Session and Scheduler Service

As with all services detailed here, to use the scheduler service you must first establish a SAWSession, then instantiate a handle to the service endpoint:

SAWSessionService sessionService = new SAWSessionService();

SAWSessionServiceSoap sessionServiceSoap = sessionService.getSAWSessionServiceSoap();

String sessionId = sessionServiceSoap.logon("<USER_NAME>", "<PASSWORD>");
 
SchedulerService schedulerService = new SchedulerService();

SchedulerServiceSoap schedulerServiceSoap = schedulerService.getSchedulerServiceSoap();

Example - Finding Job References for a User and Displaying the Job Names

Example code for finding job references for a user and displaying the job names.

This example depends on the code from Example - Creating a Session and Scheduler Service to create the session and service.

JobFilter jobFilter = new JobFilter();
 
jobFilter.getUserID().add("<USER_ID>");
 
List<Long> jobRefs = schedulerServiceSoap.getJobReferences(jobFilter, sessionId);
 
for (long jobRef : jobRefs) 
   {
    Job job = schedulerServiceSoap.getJob(jobRef, sessionId);
    System.out.println("Name = " + job.getName());
   }

Example - Finding Job Instances for Two Given Job References

Example code for finding job instanes for two given job references.

This example depends on the code from Example - Creating a Session and Scheduler Service to create the session and service.

// Create Job Instance Filter
JobInstanceFilter jobInstanceFilter = new JobInstanceFilter(); 
jobInstanceFilter.getJobReference().add(<JOB_REFERENCE_1>);
jobInstanceFilter.getJobReference().add(<JOB_REFERENCE_2>);
jobInstanceFilter.setJobInstanceStatus(null);

List<JobReferenceAndInstanceReferences> listJobRefAndInstanceRefs = schedulerServiceSoap.getJobInstanceReferences(jobInstanceFilter, sessionId);

System.out.println("Number of Jobs with Instances found: " + listJobRefAndInstanceRefs.size());
for (JobReferenceAndInstanceReferences jobRefAndInstanceRefs : listJobRefAndInstanceRefs) 
   {
    System.out.println("Job Ref = " + 
    jobRefAndInstanceRefs.getJobReference() + ", Job Instance Refs = " +
    jobRefAndInstanceRefs.getJobInstanceReference());
   }

Example - Cancelling All Job Instances Associated with a Job Reference

This example cancels all Job Instances for the Job with the given Job Reference.

This example also depends on the code from Example - Creating a Session and Scheduler Service to create the session and service.

// Create Job Instance Filter
JobInstanceFilter jobInstanceFilter = new JobInstanceFilter();
jobInstanceFilter.getJobReference().add(<JOB_REFERENCE>);

// Get JobInstance References
List<JobReferenceAndInstanceReferences> listJobRefAndInstanceRefs = schedulerServiceSoap.getJobInstanceReferences(jobInstanceFilter, sessionId);

// Cancel all the obtained Job Instances
for (JobReferenceAndInstanceReferences jobRefAndInstanceRefs : listJobRefAndInstanceRefs) 
{
for (BigInteger jobInstanceRef : jobRefAndInstanceRefs.getJobInstanceReference()) 
   {
    System.out.println("Cancelling Job = " + jobRefAndInstanceRefs.getJobReference() + ", Job Instance = " + jobInstanceRef);
    boolean result = schedulerServiceSoap.cancelJobInstance(jobRef, jobInstanceRef, sessionId);
    System.out.println("Result = " + result);
   }
}

Example - Finding and Displaying all Agents in the WebCatalogService

This example shows how to iterate through the WebCatalogService and display the path of all the agents found.

This example also depends on the code from Example - Creating a Session and Scheduler Service to create the session and service.

You could extend this example, so that once an agent has been found, it can be used to call iBot web service methods (for example, Enable the Agent using the Agent path found). iBotService Service

WebCatalogService webCatalogService = new WebCatalogService();
WebCatalogServiceSoap webCatalogServiceSoap = webCatalogService.getWebCatalogServiceSoap();

void outputAgentsInFolder(String path) {   List<ItemInfo> items = null;   try {       // Get folder items       items = webCatalogServiceSoap.getSubItems(path, "*", false, null, sessionId);       for (ItemInfo itemInfo : items) {            // If item is Agent then display Agent path       if (itemInfo.getSignature().equals("coibot1")) {             System.out.println("Agent Path = " + itemInfo.getPath());       }      // If item is a folder then recurse       if (itemInfo.getType() == ItemInfoType.FOLDER) {             outputAgentsInFolder (itemInfo.getPath());       }    }} catch (SOAPFaultException soapFault){         System.out.println("SOAP Fault for path: " + path);} catch (Exception e) {         e.printStackTrace();   }}