Ivanti Automation powered by RES

Home 

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.


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other