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. Starting with Ivanti Automation 2021.1, role-based access control configuration will be taken into account by the Dispatcher when executing various Web API calls. Configure Ivanti Automation logins with access permissions that best suit your need using the Administration > Security section in the Console.

For example, if the Web API call is used to get a list of modules, the used account needs to have at least read-only access to the modules node to be able to return any information.

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/

    Starting with Ivanti Automation 2021.1, a new URL is available for Resource management:

    • Enabled: http://[host name]/Dispatcher/ResourceService/

    • SSL enabled: https://[host name]/Dispatcher/ResourceService/

    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. Starting with Ivanti Automation 2021.1, a new URL was introduced. The Help can be accessed using http(s)://[host name]/Dispatcher/ResourceService/help”.

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 output parameters for a Module, Project or Run Book

URL

http(s)://[host name]/Dispatcher/SchedulingService/what/{WHATTYPE}s/{WHATID}/outputparameters

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].

Modify Team membership per Agent

URL

http(s)://[host name]/Dispatcher/SchedulingService/agentmembership

Method

Post

 To change Team membership per Agent, send an XML/JSON message with the new team membership settings. See the Web API Help for the message format.

Remove Agent from environment

URL

http(s)://[host name]/Dispatcher/SchedulingService/removeagent

Method

POST

To remove an Agent, send an XML/JSON message with the Agent removal settings. See the Web API Help for the message format.

Modify Agent membership per Team

URL

http(s)://[host name]/Dispatcher/SchedulingService/teammembership

Method

POST

 To change Agent membership per Team, send an XML/JSON message with the new team membership settings. See the Web API Help for the message format. 

Upload a new resource in Datastore

URL

http(s)://[host name]/Dispatcher/ResourceService/UploadResource

Method

POST

Headers:

Explanation:
  • Action
  • Description
  • Filename
  • Special
  • FolderGUID
  • Attribute
  • LastModifiedUTC
  • CacheResource
  • Mandatory. Value set to “newresource”.
  • Optional. Value of the Resource comment.
  • Mandatory. Resource name value.
  • Optional. Default value set to “none”. Other values: “parse”, “parsenoenv”.
  • Optional. The GUID of the folder where the Resources should be placed in Datastore.
  • Optional. Default value set to “A”. Other values: “R”, “H”, “AH”, “RH”, “ARH”, etc.
  • Optional. Default value set to timestamp of call execution. Format: yyyyMMddHHmmss. Eg: 20201122171020.
  • Optional. Default value based on Global Settings > Dispatcher Caching. Values: “true”, “false”
Body Mandatory. The content of the file specified in the “Filename” header.

Edit resource in Datastore

URL

http(s)://[host name]/Dispatcher/ResourceService/UploadResource

Method

POST

Headers:

Explanation:
  • Action
  • ResourceGUID
  • Description
  • Filename
  • Special
  • Attribute
  • LastModifiedUTC
  • CacheResource
  • Mandatory. Value set to “editresource”.
  • Mandatory. The GUID of the Resource to be modified.
  • Optional. Value of the Resource comment.
  • Optional. Resource name value.
  • Optional. No default value. Possible values: “none”, “parse”, “parsenoenv”.
  • Optional. Default value set to “A”. Other values: “R”, “H”, “AH”, “RH”, “ARH”, etc.
  • Optional. Default value set to timestamp of call execution. Format: yyyyMMddHHmmss. Eg: 20201122171020.
  • Optional. No default value. Values: “true”, “false”
Body Optional if “Filename” header is not used. The content of the file specified in the “Filename” header.

Delete resource from Datastore

URL

http(s)://[host name]/Dispatcher/ResourceService/DeleteResource

Method

POST

Headers:

Explanation:
  • ResourceGUID
  • Mandatory. The GUID of the Resource to be removed.

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.