Scheduler REST API

Modified on Tue, 13 Jun, 2023 at 10:08 AM


Omniscope Evo allows you to use REST API to effortlessly execute new or pre-existing tasks in the Scheduler. With this functionality, you can leverage third-party scripts/software to execute task/actions via the scheduler.


The rest of the article describes the different API endpoints and other useful information.


Permissions


To utilize the API, make sure your license has the Scheduler enabled.

If you're using OpenID authentication, ensure that the request is pre-authenticated. Alternatively, you can opt for the "List of users" authentication mechanism and pass user/password details using basic authentication through the Authorization header.

To generate a basic authentication header based on your credentials, you can use convenient websites like https://www.blitter.se/utils/basic-authentication-header-generator/. They simplify the process and make it incredibly easy!


For more information on how to set permissions see here.



Admin app - Scheduler Jobs 


In the Admin app, navigate to the Scheduler API jobs section. This section provides a comprehensive list of recently executed jobs through the Scheduler API.


Note that this page exclusively displays jobs submitted via the Scheduler REST API and does not include scheduled jobs. Additionally, all scheduler API job results are stored in the scheduler log files, such as service_scheduler_task_log.csv.






Swagger docs


To access the Swagger API documentation, visit the following URL in your browser:


http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/meta


This URL will grant you access to the comprehensive Swagger documentation providing in-depth documentation of the API.



API Methods:

  • Execute an existing task


The API endpoint provided allows you to submit a request to execute an existing task that is already defined in your scheduler configuration.


Please keep in mind that the submitted task will run independently of its current status in the scheduler. To avoid duplication and conflicts, it's crucial to ensure that you do not submit tasks for API execution if they are already running. Otherwise, you may end up with two tasks performing the same job. This is due to the fact that the Scheduler API manages task execution separately from the machine scheduler.


Request


Endpoint
http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/task/{taskName}/execute
Method
POST
BodyNone

NOTE: Replace {taskName} with the URL-encoded name of the pre-configured task in the scheduler configuration.

Example: To execute a task called "My test task" from the scheduler configuration, use the following API endpoint: 

Example: http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/task/My%20test%20task/execute


Response


The response you receive will be in plain text format and will contain the Job ID. This Job ID is important as it allows you to track the request using the "get status" endpoint, as explained below.




  • Execute a new task/action


This API endpoint enables you to submit a new task or action to be executed by including it in the body of the request.

 

Request


Endpoint
http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/execute
Method
POST
BodyXML (see below)



To utilize this API endpoint, you need to provide a valid XML as the body of the POST request. The recommended approach for creating the XML task is as follows:

  1. Use the scheduler web interface to create and configure the desired task.
  2. Once the configuration is complete, click on the "Download" button.
  3. Open the downloaded XML file using a text editor of your choice.
  4. Copy and paste the contents of the XML file into the body of your POST request.

NOTE: If you only want to submit the action itself rather than the entire task, you can extract the <action> element from the XML and use that as the body of your request.



Example XML:


<?xml version="1.0" encoding="UTF-8"?>
<schedulerTask name="My test Task" enabled="false" isWebBasedUiTask="true" timeOut="300" skipIfDelayedBy="0" warnIfDelayedBy="0">
<action>
<schedulerChainAction title="Task action" logTimings="false" timeOut="0" numberOfRetriesOnFailure="0" sleepBeforeRetryingOnFailure="2" propagateFailure="true" chainRepetitions="1">
<actions>
<schedulerExecAction command="sleep 10" waitUntilTerminated="true" ignoreError="false" customTitle="Execute Command Action" />
</actions>
</schedulerChainAction>
</action>
<recurrences>
<schedulerRecurrence startDate="1685631480000" endDate="9223372036854775807" increment="1" calendarUnit="3" />
</recurrences>
</schedulerTask>

Response


The response you receive will be in plain text format and will contain the Job ID. This Job ID is important as it allows you to track the request using the "get status" endpoint, as explained below.



  • Get job status


With this API endpoint, you can query the status of a job by providing the Job ID.  To retrieve the status of a job, use the following API endpoint:



Request


Endpoint
http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/job/{JobID}
Method
GET
BodyNone



Replace `{jobID}` with the specific Job ID you want to query. This will return the status of the job, providing you with valuable information about its progress and completion.


Example: http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/job/D6E49_1



Response


You will get a JSON response detailing the description of the job:


   "jobId": "string",  

   "jobName": "string",  

   "status": "QUEUED"

   "submitTime": 0,  

   "startTime": 0,  

   "endTime": 0,  

   "durationFormatted": "string",  

   "logOutput": "string",  

   "queuePosition": 0 

}


the job status can be one of :

  • RUNNING
  • QUEUED
  • FAILED
  • COMPLETED
  • CANCELLED



  • Get all jobs 


With this API endpoint, you can access a list of all the jobs that have been executed on the server.


Request


Endpoint
http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/all
Method
GET
BodyNone



Response


You will get a JSON response detailing the description of all the jobs of the job:


[

    { 

   "jobId": "string",  

   "jobName": "string",  

   "status": "QUEUED"

   "submitTime": 0,  

   "startTime": 0,  

   "endTime": 0,  

   "durationFormatted": "string",  

   "logOutput": "string",  

   "queuePosition": 0 

    }

]



  • Delete/Cancel existing job


This API endpoint provides the capability to delete or cancel an existing job, provided it is in a queued or running state.


Request


Endpoint
http[s]://<hostname>:[port]/_admin_/scheduler/api/v1/job/{JobID}
Method
DELETE
BodyNone



Response


You will get a plain text response code of 200 if successful.





.








 

 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article