Web API

The main function of a Dispatcher is to communicate information from the Datastore to the Agents. The Dispatcher also offers the availability of a Web API. This allows system developers to build and develop their own RESTful and SOAP web services and to integrate Job scheduling in external systems. Communication with the Web API is secured with the regular login accounts of your Ivanti Automation environment.

This chapter provides basic information about how to get started with the Dispatcher Web API. To use the Web API, you should have a basic familiarity with software development and RESTful and SOAP Web services.

Authentication

Web API authentication will only be applied if there are one or more Logins defined in Ivanti Automation (at Administration > Security).
Only accounts using Ivanti Automation Authentication, and that have a password defined, can be used to access the Web API.

Configuration

The Dispatcher Web API is disabled by default. You can enable it by enabling the global setting WebAPI state (at Setup > Global Settings > Dispatcher WebAPI section) or the setting on Dispatcher-level (Topology > Dispatchers > Settings > Dispatcher WebAPI section). When using the Dispatcher Web API in your Ivanti Automation environment, it is also possible to secure communication using HTTPS. It is not necessary to manually configure these settings in the Dispatcher configuration file. The settings in the Dispatcher configuration file will be ignored when deploying the Dispatcher.

To access the Web API, use the following base address in your browser as a basis for Job scheduling in an external system or client:
- Enabled: http://[host name]/Dispatcher/SchedulingService/
- SSL enabled: https://[host name]/Dispatcher/SchedulingService/
The host name specifies the name or IP address of the computer that hosts the Dispatcher. If you are hosting the web services on a different address (URL) and/or port number, specify an alternative base address and/or custom port number in the Dispatcher WebAPI setting.

When prompted for a username and password, use the credentials of an existing login account in your Ivanti Automation environment. This needs to be an account using Ivanti Automation Authentication, and that has a password defined. If your Ivanti Automation environment does not contain any login accounts, you can leave the fields empty.

The Help for the Web API is available at: http://[host name]/Dispatcher/SchedulingService/help. This page gives an overview of all available resources and actions. All actions correspond to the functionality in the Jobs nodes of the Console.

Schedule a new Job
URL	http://[host name]/Dispatcher/SchedulingService/jobs
Method	POST
Parameter:	Explanation:
-	-
To schedule a new Job, send an XML message with the new Job settings. See the Web API Help for the message format.

Retrieve a list of Jobs
URL	http://[host name]/Dispatcher/SchedulingService/jobs?stage={STAGE} &page={PAGE}&pagesize={PAGESIZE}&runbookjobs={INCLUDERUNBOOKJOBS} &recurringjobs={INCLUDERECURRINGJOBS}
Method	GET
Parameter:	Explanation:
STAGE PAGE PAGESIZE INCLUDERUNBOOKJOBS INCLUDERECURRINGJOBS	Specifies which Jobs should be shown. Values: All, Scheduled, Active, History. Specifies which page of the overview of Jobs should be shown. Values: 1,2,3, etc. Specifies how many Jobs should be shown on the page. Values: 10,20,...,100. Specifies whether to include Run Book Jobs in the overview. Values: true, false. Specifies whether to include recurring Jobs in the overview. Values: true, false.

Retrieve Job details
URL	http://[host name]/Dispatcher/SchedulingService/jobs/{JOBID}
Method	GET
Parameter:	Explanation:
JOBID	Specifies the Job GUID (for example, {7E9C07B8-C5E6-4F60-A01B-F096F98E5919}).
When retrieving the Job details, also the parameters of the specific Modules and Projects are shown.

Abort a Job
URL	http://[host name]/Dispatcher/SchedulingService/jobs/{JOBID}
Method	PUT
Parameter:	Explanation:
JOBID	Specifies the Job GUID (for example, {7E9C07B8-C5E6-4F60-A01B-F096F98E5919}).
To abort a Job, send an XML message with the new Job settings. This sends the Job status Aborting to the Job. See the Web API Help for the message format.

Retrieve Job results
URL	http://[host name]/Dispatcher/SchedulingService/jobs/ {JOBID}/results?overview={INCLUDEOVERVIEW}&detailed={INCLUDEDETAILED}
Method	GET
Parameter:	Explanation:
JOBID INCLUDEOVERVIEW INCLUDEDETAILED	Specifies the Job GUID (for example, {7E9C07B8-C5E6-4F60-A01B-F096F98E5919}). Specifies whether to include an overview of the results of the Job. Values: true, false. Specifies whether to include a detailed overview of the results of the Job. Values: true, false.

When exporting the Job results, the document will be wrapped in a soap document. This Job results document is base64-encoded and added to the soap document. As a result, the document needs to be decoded with a base64 decoder first before it can be read.

Report on Team composition
URL	http://[host name]/Dispatcher/SchedulingService/report/teams
Method	GET
Parameter:	Explanation:
-	-
The report will only show the resulting Agents from Teams the user has Read or Modify access to.

Report on Job usage
URL	http://[host name]/Dispatcher/SchedulingService/report/jobusage?start={START}&stop={STOP}
Method	GET
Parameter:	Explanation:
START STOP	Specifies the date time when the Job was started. Specifies date time when the Job was finished. When specifying the date time, use the format yyyyMMddHHmmss: yyyy: Year (e.g. 2013) MM: Month (e.g. 03) dd: Day (e.g. 27) HH: Hour (e.g. 19 - use 24h notation) mm: Minute (e.g. 59) ss: Seconds (e.g. 30)

Retrieve Job details of a Run Book Job
URL	http://[host name]/Dispatcher/SchedulingService/runbookjobs/{JOBID}
Method	GET
Parameter:	Explanation:
JOBID	Specifies the Job GUID (for example, {7E9C07B8-C5E6-4F60-A01B-F096F98E5919}).

Retrieve a list of input parameters for a Module, Project or Run Book
URL	http://[host name]/Dispatcher/SchedulingService/what/{WHATTYPE}s/{WHATID}/inputparameters
Method	GET
Parameter:	Explanation:
WHATTYPE WHATID	Specifies what was executed. Values: RunBook, Project, Module. Specifies the GUID of the Run Book, Project, or Module.

Retrieve a list of available Modules
URL	http://[host name]/Dispatcher/SchedulingService/what/modules
Method	GET
Parameter:	Explanation:
-	-

Retrieve a list of available Projects
URL	http://[host name]/Dispatcher/SchedulingService/what/projects
Method	GET
Parameter:	Explanation:
-	-

Retrieve a list of available Run Books
URL	http://[host name]/Dispatcher/SchedulingService/what/runbooks
Method	GET
Parameter:	Explanation:
-	-

Retrieve a list of available Agents/Teams
URL	http://[host name]/Dispatcher/SchedulingService/who
Method	GET
Parameter:	Explanation:
INCLUDEAGENTS INCLUDETEAMS ONLINEONLY LICENSEDONLY SEARCHFOR	Specifies whether to include Agents in the selection of Agents/Teams. Values: true, false. Specifies whether to include Agents in the selection of Agents/Teams. Values: true, false. Specifies whether to show online Agents only. Values: true, false. Specifies whether to show licensed Agents only. Values: true, false. Specifies the Agents to search for: [Agent name].

When scheduling a Run Book to an Agent from Ivanti Identity Director, it is possible to use the Agent GUID and the Agent name as a unique identifier. The Agent GUID is only supported when communicating via the Web API and the command line. The Ivanti Automation Console does not accept the Agent GUID.