Overview

Universal Controller supports the following RESTful-based web services for Agent operations, which are listed alphabetically on this page.

Delete an Agent
List Agents
List Agents - Advanced
Modify an Agent
Read an Agent
Resume an Agent
Set an Agent Task Execution Limit
Suspend an Agent

Formatting specifications for each web service, including details about property requirements, are provided.

Delete an Agent

	Description

	Description
URI	http://host_name/uc/resources/agent
HTTP Method	DELETE
Description	Deletes an Agent.
URI Parameters	See Delete an Agent: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/agent?agentname=test-pc-SS0001 http://localhost:8080/uc/resources/agent?agentid=SS0001
Authentication	HTTP Basic
Example Response	Success: Status 200 /OK Agent deleted successfully Failure: Status 400 /Bad Request Mutual exclusion violation. Cannot specify agentname and agentid at the same time.

Delete an Agent: URI Parameters

Name	Description	Specifications	Required	Mutually Exclusive With

Name	Description	Specifications	Required	Mutually Exclusive With
`agentid`	Unique ID for this Agent, created during installation.		Y (unless `agentname` is specified)	`agentname`
`agentname`	Name used within the Controller to identify this agent.	Maximum 40 alphanumerics.	Y (unless `agentid` is specified)	`agentid`

List Agents

	Description

	Description
URI	http://host_name/uc/resources/agent/list
HTTP Method	GET
Description	Retrieves information on all agents.
Example URI	http://localhost:8080/uc/resources/agent/list
Authentication	HTTP Basic
Produces Content-Type	application/xml, application/json
Example	See List Agents: XML and JSON Examples.
Properties	See List Agents: Properties.

List Agents: XML and JSON Examples

The following XML and JSON examples are for the List Agents web service.

XML	JSON

XML

JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<agents>
    <agent>
        <credentialsRequired>false</credentialsRequired>
        <extAccept>true</extAccept>
        <extAcceptList>
            <extension>*</extension>
        </extAcceptList>
        <extApiLevelMax>1.4.0</extApiLevelMax>
        <extApiLevelMin>1.0.0</extApiLevelMin>
        <extensions>
            <extension checksum="7C3BBD763658E528A4049E85BEA206866A9C42530C56F9A852525CEC7944DB12">qaextension</extension>
        </extensions>
        <hostName>SBUS30</hostName>
        <ipAddress>192.168.56.1</ipAddress>
        <name>SBUS30 - AGNT0003</name>
        <outputProhibited>false</outputProhibited>
        <queueName>AGNT0003</queueName>
        <status>Active</status>
        <suspended>false</suspended>
        <sysID>8dc34ce553314894a5419d28a20b3579</sysID>
        <transient>false</transient>
        <type>Windows</type>
        <version>7.4.0.0</version>
    </agent>
</agents>

[
    {
        "credentialsRequired": false,
        "extAccept": true,
        "extAcceptList": [
            "*"
        ],
        "extApiLevelMax": "1.4.0",
        "extApiLevelMin": "1.0.0",
        "extensions": [
            {
                "name": "qaextension",
                "checksum": "7C3BBD763658E528A4049E85BEA206866A9C42530C56F9A852525CEC7944DB12"
            }
        ],
        "hostName": "SBUS30",
        "ipAddress": "192.168.56.1",
        "name": "SBUS30 - AGNT0003",
        "outputProhibited": false,
        "queueName": "AGNT0003",
        "status": "Active",
        "suspended": false,
        "sysID": "8dc34ce553314894a5419d28a20b3579",
        "transient": false,
        "type": "Windows",
        "version": "7.4.0.0"
    }
]

List Agents: Properties

Property	UI Field Name	Description

Property	UI Field Name	Description
`extAccept`	Accept Extensions	Indication of whether or not the Agent will accept deployment of Universal Extensions.
`extAcceptList`	Accept List	If `extAccept` is true; either: List of specific Universal Extensions that are allowed to be deployed to the Agent. * for no deployment restrictions.
`extApiLevelMin`	API Level Minimum	Minimum extension API level supported.
`extApiLevelMax`	API Level Maximum	Maximum extension API level supported.
`extensions`	Extensions	List of deployed Universal Extensions and their corresponding checksums.
`hostName`	Host Name	IP address or domain/name of the host machine where the Agent resides.
`ipAddress`	IP Address	TCP/IP address of the machine where the Agent is running. If the currently logged in user is a non-Administrator (ops_admin) user, and the Agent Address Information Restricted Universal Controller system property is set to true, ipAddress will be set to <ipAddress /> (XML) and "ipAddress": null (JSON). Note This also applies to the ipAddress of z/OS secondary Agents.
`name`	Agent Name	Name used within the Controller to identify this Agent.
`outputProhibited`	Retrieve Output Prohibited	Specification (true or false) for whether or not Retrieve Output requests are disallowed from being performed for this Agent.
`queueName`	Agent Id	Unique ID for this Agent.
`status`	Status	Status of the Agent.
`suspended`	Suspended	Indication (true or false) of whether or not the Agent currently is suspended.
`sysID`	n/a	System ID field in the database for this Agent record.
`transient`	Transient	For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is considered a Transient Agent.
`type`	Operating System	Operating system on which the Agent is running.
`version`	Version	Version number of the Agent program.

List Agents - Advanced

	Description

	Description
URI	http://host_name/uc/resources/agent/listadv http://host_name/uc/resources/agents/listadv
HTTP Method	GET
Description	Retrieves Agent details using specific query parameters.
Example URI	http://localhost:8080/uc/resources/agent/listadv http://localhost:8080/uc/resources/agent/listadv?agentname=SBUS30&businessServices=A&type= http://localhost:8080/uc/resources/agent/listadv?agentname=SBUS30 http://localhost:8080/uc/resources/agent/listadv?type=windows
Authentication	HTTP Basic
Produces Content-Type	application/xml, application/json
URI Parameters	See List Agents - Advanced: URI Parameters.
Example Response	See List Agents - Advanced: XML and JSON Examples.

List Agents - Advanced: URI Parameters

Name	UI Field Name	Description	Specifications	Required

Name

UI Field Name

Description

Specifications

Required

type

n/a

Type of Agent

Valid values (case insensitive):

As String = Windows, As Value =1
As String = Linux/Uni, As Value = 2
As String = z/OS, As Value = 3
As String = IBM i, As Value = 9

N

agentname

n/a

Name used within the Controller to identify this Agent.

Wildcards are supported.

N

businessServices

n/a

Business Services that this Agent belongs to.

String value of comma-separated business services.

N

List Agents - Advanced: XML and JSON Examples

The following XML and JSON examples are for the List Agents - Advanced web service.

XML	JSON

XML

JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<agents>
    <windowsAgent>
        <authVersion>2</authVersion>
        <build>84</build>
        <buildDate>20200108073718</buildDate>
        <cpu>AMD64 (12 CPU(s))</cpu>
        <cpuLoad>7</cpuLoad>
        <credentials />
        <credentialsRequired>false</credentialsRequired>
        <currentCount>0</currentCount>
        <decommissioned>false</decommissioned>
        <decommissionedDate />
        <extAccept>false</extAccept>
        <extAcceptList/>
        <extApiLevelMax />
        <extApiLevelMin />
        <extensions/>
        <hbDate>2021-04-28 15:48:20 -0400</hbDate>
        <hbGracePeriod />
        <hbIntvl>120</hbIntvl>
        <hostName>SBUS30</hostName>
        <ipAddress>192.168.56.1</ipAddress>
        <jobs>3</jobs>
        <limitAmount>5</limitAmount>
        <limitType>Unlimited</limitType>
        <logLevel>Informational</logLevel>
        <name>SBUS30 - AGNT0005</name>
        <notifications/>
        <omsServer>localhost</omsServer>
        <opswiseGroups>
            <opswiseGroup>A</opswiseGroup>
            <opswiseGroup>B</opswiseGroup>
        </opswiseGroups>
        <os>Microsoft Windows</os>
        <osRelease>Professional  (Build 9200)</osRelease>
        <outputProhibited>false</outputProhibited>
        <pid>8216</pid>
        <queueName>AGNT0005</queueName>
        <startDate>2021-04-28 13:37:15 -0400</startDate>
        <status>Active</status>
        <suspended>false</suspended>
        <sysId>1530cd78f6dd4c449820e84419bcfa46</sysId>
        <transient>false</transient>
        <version>6.8.0.0</version>
    </windowsAgent>
	<unixAgent>
		<authVersion>2</authVersion>
		<build>86</build>
		<buildDate>20200908093406</buildDate>
		<cpu>GenuineIntel Common KVM processor (1 CPU)</cpu>
		<cpuLoad>1</cpuLoad>
		<credentials />
		<currentCount>0</currentCount>
		<decommissioned>false</decommissioned>
		<decommissionedDate />
		<extAccept>false</extAccept>
		<extAcceptList/>
		<extApiLevelMax />
		<extApiLevelMin />
		<extensions/>
		<hbDate />
		<hbGracePeriod />
		<hbIntvl>120</hbIntvl>
		<hostName>qa-lx4u18-x64.stone.branch</hostName>
		<ipAddress>127.0.1.1</ipAddress>
		<jobs>0</jobs>
		<limitAmount>5</limitAmount>
		<limitType>Unlimited</limitType>
		<logLevel>Informational</logLevel>
		<name>qa-lx4u18-x64.stone.branch - AGNT-QA-LX4U18-X64-1AU</name>
		<notifications/>
		<omsServer />
		<opswiseGroups/>
		<os>Linux</os>
		<osRelease>x86_64 4.15.0-23-generic (#25-Ubuntu SMP Wed May 23 18:02:16 UTC 2018)</osRelease>
		<outputProhibited>false</outputProhibited>
		<pid />
		<queueName>AGNT-QA-LX4U18-X64-1AU</queueName>
		<startDate />
		<status>Offline</status>
		<suspended>false</suspended>
		<sysId>064a4de67fb1457eba88c01a8d7e1a49</sysId>
		<transient>false</transient>
		<version>6.9.0.0</version>
	</unixAgent>
	<zosAgent>
		<authVersion>2</authVersion>
		<build>41</build>
		<buildDate>20210318123354</buildDate>
		<cpu>3907</cpu>
		<cpuLoad>0</cpuLoad>
		<credentials />
		<currentCount>0</currentCount>
		<decommissioned>false</decommissioned>
		<decommissionedDate />
		<extAccept>false</extAccept>
		<extAcceptList/>
		<extApiLevelMax />
		<extApiLevelMin />
		<extensions/>
		<hbDate />
		<hbGracePeriod />
		<hbIntvl>120</hbIntvl>
		<hostName>DVZOS202</hostName>
		<ipAddress>192.168.30.84</ipAddress>
		<jobs>0</jobs>
		<limitAmount>5</limitAmount>
		<limitType>Unlimited</limitType>
		<logLevel>Informational</logLevel>
		<name>DVZOS202 - AGNT0014</name>
		<notifications/>
		<omsServer>localhost:7878</omsServer>
		<opswiseGroups/>
		<os>ZOS</os>
		<osRelease>020200</osRelease>
		<outputProhibited>false</outputProhibited>
		<pid />
		<queueName>AGNT0014</queueName>
		<secondaryAgentCount>0</secondaryAgentCount>
		<secondaryAgents/>
		<startDate />
		<status>Offline</status>
		<suspended>false</suspended>
		<sysId>11cc3d5269de40c3ae3b03d7b3c771e8</sysId>
		<systemName>DVZOS202</systemName>
		<transient>false</transient>
		<version>7.0.0.0</version>
	</zosAgent>	
</agents>

[
	{
		"type": "unixAgent",
		"authVersion": "2",
		"build": "86",
		"buildDate": "20200908093406",
		"cpu": "GenuineIntel Common KVM processor (1 CPU)",
		"cpuLoad": 1,
		"credentials": null,
        "credentialsRequired": false,
		"currentCount": 0,
		"decommissioned": false,
		"decommissionedDate": null,
		"extAccept": false,
		"extAcceptList": [],
		"extApiLevelMax": null,
		"extApiLevelMin": null,
		"extensions": [],
		"hbDate": null,
		"hbGracePeriod": null,
		"hbIntvl": 120,
		"hostName": "qa-lx4u18-x64.stone.branch",
		"ipAddress": "127.0.1.1",
		"jobs": 0,
		"limitAmount": 5,
		"limitType": "Unlimited",
		"logLevel": "Informational",
		"name": "qa-lx4u18-x64.stone.branch - AGNT-QA-LX4U18-X64-1AU",
		"notifications": {
			"emailNotifications": [],
			"snmpNotifications": []
		},
		"omsServer": null,
		"opswiseGroups": [],
		"os": "Linux",
		"osRelease": "x86_64 4.15.0-23-generic (#25-Ubuntu SMP Wed May 23 18:02:16 UTC 2018)",
		"outputProhibited": false,
		"pid": null,
		"queueName": "AGNT-QA-LX4U18-X64-1AU",
		"startDate": null,
		"status": "Offline",
		"suspended": false,
		"sysId": "064a4de67fb1457eba88c01a8d7e1a49",
		"transient": false,
		"version": "6.9.0.0"
	}
    {
        "authVersion": "2",
        "build": "84",
        "buildDate": "20200108073718",
        "cpu": "AMD64 (12 CPU(s))",
        "cpuLoad": 7,
        "credentials": null,
        "currentCount": 0,
        "decommissioned": false,
        "decommissionedDate": null,
        "extAccept": false,
        "extAcceptList": [],
        "extApiLevelMax": null,
        "extApiLevelMin": null,
        "extensions": [],
        "hbDate": "2021-04-28 15:48:20 -0400",
        "hbGracePeriod": null,
        "hbIntvl": 120,
        "hostName": "SBUS30",
        "ipAddress": "192.168.56.1",
        "jobs": 3,
        "limitAmount": 5,
        "limitType": "Unlimited",
        "logLevel": "Informational",
        "name": "SBUS30 - AGNT0005",
        "notifications": {
            "emailNotifications": [],
            "snmpNotifications": []
        },
        "omsServer": "localhost",
        "opswiseGroups": [
            "A",
            "B"
        ],
        "os": "Microsoft Windows",
        "osRelease": "Professional  (Build 9200)",
        "outputProhibited": false,
        "pid": "8216",
        "queueName": "AGNT0005",
        "startDate": "2021-04-28 13:37:15 -0400",
        "status": "Active",
        "suspended": false,
        "sysId": "1530cd78f6dd4c449820e84419bcfa46",
        "transient": false,
        "version": "6.8.0.0"
    }
	{
		"type": "zosAgent",
		"authVersion": "2",
		"build": "41",
		"buildDate": "20210318123354",
		"cpu": "3907",
		"cpuLoad": 0,
		"credentials": null,
		"currentCount": 0,
		"decommissioned": false,
		"decommissionedDate": null,
		"extAccept": false,
		"extAcceptList": [],
		"extApiLevelMax": null,
		"extApiLevelMin": null,
		"extensions": [],
		"hbDate": null,
		"hbGracePeriod": null,
		"hbIntvl": 120,
		"hostName": "DVZOS202",
		"ipAddress": "192.168.30.84",
		"jobs": 0,
		"limitAmount": 5,
		"limitType": "Unlimited",
		"logLevel": "Informational",
		"name": "DVZOS202 - AGNT0014",
		"notifications": {
			"emailNotifications": [],
			"snmpNotifications": []
		},
		"omsServer": "localhost:7878",
		"opswiseGroups": [],
		"os": "ZOS",
		"osRelease": "020200",
		"outputProhibited": false,
		"pid": null,
		"queueName": "AGNT0014",
		"secondaryAgentCount": 0,
		"secondaryAgents": [],
		"startDate": null,
		"status": "Offline",
		"suspended": false,
		"sysId": "11cc3d5269de40c3ae3b03d7b3c771e8",
		"systemName": "DVZOS202",
		"transient": false,
		"version": "7.0.0.0"
	}
]

Modify an Agent

	Description

	Description
URI	http://host_name/uc/resources/agent
HTTP Method	PUT
Description	Modifies the Agent specified by the `sysId`. To modify Agent properties without modifying related records, see the excludeRelated property.
Example URI	http://localhost:8080/uc/resources/agent
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Agent: XML and JSON Examples.
Agent Properties	See Agent: Properties.
Email Notification Properties	See Agent: Email Notification Properties.
SNMP Notification Properties	See Agent: SNMP Notification Properties.
Example Response	Status 200 /OK Successfully updated the Agent with sysId <sysId> to version <version>. Status 400 /Bad Update Agent failed. A duplicate value has been detected. Agent name must be unique.

Read an Agent

	Description

	Description
URI	http://host_name/uc/resources/agent
HTTP Method	GET
Description	Retrieves information on a specific Agent.
URI Parameters	See Read an Agent: URI Parameters.
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example URI	http://localhost:8080/uc/resources/agent?agentid=SS0001
Example Response	See Agent: XML and JSON Examples.
Agent Properties	See Agent: Properties.
Email Notification Properties	See Agent: Email Notification Properties.
SNMP Notification Properties	See Agent: SNMP Notification Properties.

Read an Agent: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With

Parameter	Description	Specifications	Required	Mutually Exclusive With
`agentid`	ID used within the Controller to identify this Agent.	String; URI parameter.	Y (unless `agentname` is specified)	`agentname`
`agentname`	Name used within the Controller to identify this Agent.	String; URI parameter.	Y (unless `agentid` is specified)	`agentid`

Agent: XML and JSON Examples

XML	JSON

XML

JSON

<windowsAgent> <authVersion>2</authVersion> <build>120</build> <buildDate>20210306121725</buildDate> <cpu>AMD64 (8 CPU(s))</cpu> <cpuLoad>10</cpuLoad> </credentials> <credentialsRequired>false</credentialsRequired> <currentCount>0</currentCount> <decommissioned>true</decommissioned> <decommissionedDate /> <extAccept>true</extAccept> <extAcceptList> <extension>extension1</extension> <extension>extension2</extension> <extension>extension3</extension> <extension>extension4</extension> </extAcceptList> <extApiLevelMax>1.0.0</extApiLevelMax> <extApiLevelMin>1.0.0</extApiLevelMin> <extensions> <extension checksum="E5A36DB088762D853C1088C3AD3B5C94D3F7A363ED02BBC20BA360BAEAF7A513">extension1</extension> <extension checksum="2C5BA72269E13EE87C3A6C2D79C5C2DAEC245D4646E958D01D1C080AAD4B91F8">extension2</extension> </extensions><hbDate>2021-03-19 08:55:45 -0700</hbDate><hbGracePeriod>120</hbGracePeriod> <hbIntvl>120</hbIntvl> <hostName>test-pc</hostName> <ipAddress>10.253.1.77</ipAddress> <jobs>1</jobs> <limitAmount>10</limitAmount> <limitType>Limited</limitType> <logLevel>Errors</logLevel> <name>test-pc-SS0001</name><notifications> <emailNotification> <status>Offline,Active</status> <sysId>2b7286b87a7048399fbd95c01a380002</sysId> <bcc /> <body /> <cc /> <emailConnection>uc - Gmail Account</emailConnection> <emailTemplate>uc - Template</emailTemplate> <replyTo /> <subject /> <to /> </emailNotification> <snmpNotification> <status>Offline</status> <sysId>21d992c72be44b159aac91c4ee9f40c6</sysId> <severity>Minor</severity> <snmpManager>SNMP Manager</snmpManager> </snmpNotification> </notifications> <omsServer>localhost:7878</omsServer> <opswiseGroups> <opswiseGroup>group1</opswiseGroup> </opswiseGroups> <os>Microsoft Windows</os> <osRelease>Home Edition (Build 9200)</osRelease> <outputProhibited>false</outputProhibited> <pid>13356</pid> <queueName>SS0001</queueName><startDate>2021-03-15 06:09:42 -0700</startDate> <status>Offline</status><suspended>false</suspended><sysId>2f5885727ec947df9c03ed7d9ca6464d</sysId> <systemName>zos1213</systemName> <transient>true</transient> <version>7.0.0.0</version></windowsAgent>

Agent Web Services

Overview

Delete an Agent

Delete an Agent: URI Parameters

List Agents

List Agents: XML and JSON Examples

List Agents: Properties

List Agents - Advanced

List Agents - Advanced: URI Parameters

List Agents - Advanced: XML and JSON Examples

Modify an Agent

Read an Agent

Read an Agent: URI Parameters

Agent: XML and JSON Examples