AgileApps Support Wiki Pre Release

REST API:scheduledJob Resource

From AgileApps Support Wiki

Manage scheduled jobs using the REST API.

Learn more: REST API Conventions and Considerations.

Permissions

Lock-tiny.gif

Users that have the Use Development Features permission can use this resource. 

Schedule a Job

If a class has been defined like the one described in Schedule a Job, the REST exec Resource can be used to schedule the job: Schedule the job by using the REST class/operation/exec resource to invoke the method in that class that does the scheduling (run):

<platform>
  <execClass>
    <clazz>com.platform.demo.cron.CronJobDemo</clazz>
    <method>run</method>
  </execClass>
</platform>

Get Job Details

Method
GET
URI
https://{yourDomain}/networking/rest/scheduledJob/{jobId}
Response
<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>
  
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>
See also: REST API:Error Codes

Delete a Job

Method
DELETE
URI
https://{yourDomain}/networking/rest/scheduledJob/{jobId}
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
See also: REST API:Error Codes

Dynamic Search of Job History

Method
GET
URI
https://{yourDomain}/networking/rest/scheduledJob?{query_parameters}
Sample Search
?fieldList=name,id&filter=name contains 'smith' & sortby='id'
(Field names are in the Fields section.)
Query Parameters
  • fieldList - A comma-separated list of field names to retrieve
  • The asterisk (*) wildcard specifies all fields
  • {fieldname} specifies an individual field (e.g. name)
(Use the REST API:field Resource to get a complete list of fields.)
  • For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
  • For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
  • alias.* specifies all fields in the aliased object.
  • filter - Filtering criteria to filter the records
  • pageSize - Number of records to retrieve from the result set in order to make a "page".
  • page - Number of the logical page in a database result set. The first page is page "zero" (0).
Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.
  • getTotalRecordCount returns the number of total records.
    Causes the following structure to be returned, where N is the total number of records:
<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>
  • sortBy - Field name for primary sort
    Ex: &sortBy=name
  • sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
    Ex: &sortOrder=desc
  • sortBy2 - Field name for secondary sort
  • sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)
For more information, see: Specifying Query Parameters in REST APIs


Response
<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>
   ...
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>
See also: REST API:Error Codes

Notes:

  • The response is a job history. If a job is scheduled and then deleted, there will be two entries with the same ID. The last entry shows the current status (deleted).
  • If rescheduled, the job will get a new ID, which makes it a separate job.
  • Entries are also added every time the job is executed, showing the time when execution occurred.

Example: Get a Complete Job History

This call returns a complete history of all jobs (scheduled, deleted, and executed) since the platform was installed. For example:

https://{yourDomain}/networking/rest/scheduledJob?fileList=*
Response
In this example, a job was scheduled, deleted, and re-scheduled. It was then executed twice.
<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-15T17:32:00-08:00</lastExecutionTime>
    <status>Job Deleted</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>7c4d4e54ee2143b49abf38ec5863af06</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T17:36:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>d4feb5d38a96492fab5f8d9cb4d3c9dc</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T17:57:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>7c4d4e54ee2143b49abf38ec5863af06</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-16T03:00:00-08:00</lastExecutionTime>
    <nextExecutionTime>2010-11-17T03:00:00-08:00</nextExecutionTime>
    <status>Executed Successfully</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>d4feb5d38a96492fab5f8d9cb4d3c9dc</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-16T03:00:00-08:00</lastExecutionTime>
    <nextExecutionTime>2010-11-17T03:00:00-08:00</nextExecutionTime>
    <status>Executed Successfully</status>
  </scheduledJob>

  <message>
    <code>0</code>
    <description>Success</description>
    </message>
    <recordCount>6</recordCount>
  </platform>

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
Name Type Attribute Required During Add Description Additional Information
jobId String Read Only Job identifier Used for individual-job requests
jobName String Read Only Name given to the job when created
cronExpression String Read Only Expression that tells when the job is to be run. Cron Expression
runAsUser String Read Only User ID Who to be when the job runs
scheduledDate String Read Only Date and time the job was created.
nextExecutionTime String Read Only The next time the job will run
lastExecutionTime String Read Only The last time the job was run
status String Read Only One of:
  • Job Scheduled
  • Job Deleted
  • Executed Successfully
  • Error {message}