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
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
`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
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

<?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>

JSON

[
    {
        "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
`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
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

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

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

<?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>

JSON

[
	{
		"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
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
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 roperties.

Read an Agent: URI Parameters

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

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

JSON

{
  "type": "windowsAgent",
  "authVersion": 2,
  "build": "100",
  "buildDate": "20210324174216",
  "cpu": "AMD64 (8 CPU(s))",
  "cpuLoad": 5,
  "credentialsRequired": false,
  "credentials": null,
  "currentCount": 0,
  "decommissioned": false,
  "decommissionedDate": null,
  "extAccept": true,
  "extAcceptList": [
       "extension1",
       "extension2",
       "extension3",
       "extension4"
   ],
  "extApiLevelMax": "1.0.0",
  "extApiLevelMin": "1.0.0",
  "extensions": [
       {
           "name": "extension1",
           "checksum": "E5A36DB088762D853C1088C3AD3B5C94D3F7A363ED02BBC20BA360BAEAF7A513"
       },
       {
           "name": "extension2",
           "checksum": "2C5BA72269E13EE87C3A6C2D79C5C2DAEC245D4646E958D01D1C080AAD4B91F8"
       }
  ], 
"hbDate": null,
"hbGracePeriod": 120, 
"hbIntvl": 120, 
"hostName": "Mark-4", 
"ipAddress": "192.168.1.21", 
"jobs": 1, 
"limitAmount": 5, 
"limitType": "Limited", 
"logLevel": "Informational", 
"name": "Mark-4 - AGNT001", 
"notifications": {
"emailNotifications": [ {
"bcc": null,
"body": "${ops_system_identifier}", 
"cc": null, 
"emailConnection": "ecu-office-365", 
"emailTemplate": "agent-built-variables", 
"replyTo": null, 
"status": "Offline,\nActive", 
"subject": null, 
"sysId": "e120f05abd104e2e952c6b9e693891ab", 
"to": "support@stonebranch.com" 
} ], 
"snmpNotifications": [ {
"severity": "Minor", 
"snmpManager": "test_manager", 
"status": "Offline", 
"sysId": "fc4f4e8b0dea4b51a77a3c20f7e62b2a" 
} ] 
}, 
"omsServer": "localhost:7878", 
"opswiseGroups": [ "Accounting" ], 
"os": "Microsoft Windows", 
"osRelease": "Home Edition (Build 9200)", 
"outputProhibited": false, 
"pid": null, 
"queueName": "AGNT001",
"startDate": null, 
"status": "Offline", 
"suspended": false, 
"sysId": "6a363c84d9bd4730bfd6cf43129b4984",
"systemName": "zos123",
"transient": true, 
"version": "7.0.0.0" 
}

Agent: Properties

Property	UI Field Name	Description	Specifications
`authVersion`	Authentication Version	Type of encryption in use for this Agent.	Read only.
`build`	Build Id	Build ID of the Agent.	Read only.
`buildDate`	Build Date	Date that the Agent program was last built.	Read only.
`cpu`	CPU	Information about the CPU on the Agent machine.	Read only.
`cpuLoad`	CPU Load	Current CPU load on the Agent machine.	Read only; Integer. Expressed as a percentage. For example, 1 means 1% currently utilized.
`credentials`	Credentials	Credentials under which this Agent runs tasks. These credentials are overridden by any credentials provided in the task definition for any tasks being run by this Agent.
`credentialsRequired`	Credentials Required	Specifies if credentials are required to execute any task on the agent.	Valid Values: true/false (default is false).
`currentCount`	Current Task Count	If `limitType` is Limited; Current number of tasks currently being run by this Agent.	Read only.
`decommissioned`	Decommissioned	For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is decommissioned.	Valid values: true/false (default is false).
`decommissionedDate`	Decommissioned Date	For Linux Unix Agents only; If `decommissioned` is true: Date when the Agent was decommissioned.	Read only.
`excludeRelated`	n/a	For the Modify Agent web service; specification for whether or not to exclude related records from the update, even if they are provided in the request. Note In XML, `excludeRelated` is specified as an attribute in the <agent> element.	Valid values: true/false (default is false).
`extAccept`	Accept Extensions	Indication of whether or not the Agent will accept deployment of Universal Extensions.	Read only.
`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.	Read only.
`extApiLevelMin`	API Level Minimum	Minimum extension API level supported.	Read only.
`extApiLevelMax`	API Level Maximum	Maximum extension API level supported.	Read only.
`extensions`	Extensions	List of deployed Universal Extensions and their corresponding checksums.	Read only.
`hbDate`	Last Heartbeat	Date and time that the most recent heartbeat was received from the Agent.	Read only.
`hbGracePeriod`	Heartbeat Grace Period	Grace period, in seconds, that the Controller will allow for a delayed heartbeat message	Integer.
`hbIntvl`	Heartbeat Interval	Heartbeat interval (in seconds). The heartbeat is a status message sent from the Agent to the Controller.	Integer.
`hostName`	Host Name	Read only; IP address or domain/name of the host machine where the resource resides.	Read only.
`ipAddress`	IP Address	Read only; 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.	Read only.
`jobs`	Jobs Run	Read only; Total number of jobs that have been run through the Controller to this Agent.	Read only; Integer.
`limitAmount`	Limit Amount	If `limitType` is Limited; Number of tasks that can be running at the same time by the Agent.	Integer.
`limitType`	Task Execution Limit	Specification for whether a Limited or Unlimited number of task instances can be run concurrently on the Agent.	Valid values: As String = Unlimited, As Value = 1 As String = Limited, As Value = 2 Default is Unlimited (1).
`outputProhibited`	Retrieve Output Prohibited	Specification for whether or not Retrieve Output requests are disallowed from being performed for this Agent.	Read only; Boolean. Valid values: true/false.
`logLevel`	Log Level	Level of logging that the Agent can perform	Valid values: Sever Error Errors Warnings Informational Debug Trace Default is Informational.
`name`	Name	Name used within the Controller to identify this Agent.
`omsServer`	OMS Server	Host name of the OMS Server.	Read only.
`opswiseGroups`	Member of Business Services	One or more Business Services that this Agent belongs to.	Read only.
`os`	Operating System	Operating system on which the Agent is running.	Read only.
`osRelease`	Operating System Release	Release information for the operating system on which the Agent is running.	Read only.
`pid`	PID	Process ID of the Agent.	Read only.
`queueName`	Agent ID	Unique ID for this Agent, created during installation.	Read only.
`secondaryAgentCount`	Secondary Agent Licenses	For z/OS Agents only; Number of secondary agent licenses.	Read only; Integer
`secondaryAgents`	Secondary Agent(s)	For z/OS Agents only; List of secondary agent information.	Read only. Format: <secondaryAgents> <secondaryAgent> <build>10</build> <buildDate>20200821154510</buildDate> <cpu>3900</cpu> <hostName>dvos200</hostName> <ipAddress>192.168.30.10</ipAddress> <mode>Active</mode> <os>zos</os> <osRelease>020200</osRelease> <pid>1000</pid> <startDate>09-04-2020 18:14:14 -07:00</startDate> <sysName>dvos200</sysName> <version>6.9.0.0</version> </secondaryAgent> <secondaryAgent> <build>11</build> <buildDate>20200821154511</buildDate> <cpu>3901</cpu> <hostName>dvos201</hostName> <ipAddress>192.168.30.11</ipAddress> <mode>Offline</mode> <os>zos</os> <osRelease>020200</osRelease> <pid>1001</pid> <startDate>09-05-2020 18:14:14 -07:00</startDate> <sysName>dvos201</sysName> <version>6.9.0.1</version> </secondaryAgent> </secondaryAgents>
`startDate`	Started Date	Date/timestamp when the Agent was last started.	Read only.
`status`	Status	Status of the Agent.	Read only. Valid values: Offline Active Passive
`suspended`	Suspended	Indication that the Agent's ability to run tasks has been suspended.	Read only; Boolean. Valid values: true/false.
`sysid`	n/a	System ID field in the database for this Agent.	Read only.
`systemName`	System Name	For z/OS Agents only; System name.	Read only.
`transient`	Transient	For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is considered a Transient Agent.	Valid values: true/false (default is false).
`version`	Version	Version number of the Agent program.	Read only.

Agent: Email Notification Properties

Property	UI Field Name	Description	Specifications
`bcc`	Bcc	Email address of the party being sent a blind (hidden) copy of the email, if any.	Use commas to separate multiple recipients. Variables and Functions are supported.
`body`	Body	Text of the email message.	Variables and Functions are supported. If the `emailTemplate` contains text in the body, this text is appended.
`cc`	Cc	Email address of the party being sent a copy of the email, if any.	Use commas to separate multiple recipients. Variables and Functions are supported.
`emailConnection`	Email Connection	Name of an Email Connection.	If you specify both an `emailConnection` and an `emailTemplate`, the Controller uses the `emailConnection`.
`emailTemplate`	Email Template	Name of an Email Template.	If you specify both an `emailConnection` and an `emailTemplate`, the Controller uses the `emailConnection`.
`replyTo`	Reply-To	Email address of the sender of the email.	Use commas to separate multiple recipients. Variables and Functions are supported.
`status`	Status Options	Comma-separated list of statuses	Valid values: As String = Offline, As Value = 0 As String = Active, As Value = 1
`subject`	Subject	Subject line of the email.	Variables and Functions are supported.
`sysId`	n/a	sys_id used within the Controller to identify this Email Notification.
`to`	To	Email address of the recipient.	Use commas to separate multiple recipients Variables and Functions are supported.

Agent: SNMP Notification Properties

Property	UI Field Name	Description	Specifications
`severity`	Notification Severity	Severity level of this notification.	Valid values: As String = Normal, As Value = 1 As String = Warning, As Value = 2 As String = Minor, As Value = 3 As String = Major, As Value = 4 As String = Critical, As Value = 5 Default is Normal (1).
`snmpManager`	SNMP Manager	SNMP Manager that will receive this notification.
`status`	Status Options	Comma-separated list of statuses	Valid values: As String = Offline, As Value = 0 As String = Active, As Value = 1
`sysId`	n/a	sys_id used within the Controller to identify this SNMP Notification.

Resume an Agent

	Description
URI	http://host_name/uc/resources/agent/ops-resume-agent
HTTP Method	POST
Description	Resumes the specified agent.
Example URI	http://localhost:8080/uc/resources/agent/ops-resume-agent
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Resume an Agent: XML and JSON Examples.
Request Properties	See Resume an Agent: Request Properties.
Example Response	See Resume an Agent: XML and JSON Examples.

Resume an Agent: XML and JSON Examples

Example

XML

JSON

Example Request

XML

By Agent Name

<resume-agent>
  <agentName>XPS-8300 - AGNT0001</agentName>
</resume-agent>

By Agent ID

<resume-agent>
  <agentID>AGNT0001</agentID>
</resume-agent>

JSON

{
 "agentName": "Mark-4 - AGNT001"
}
or
{
 "agentID": "AGNT001"
}

Example Response

XML

<command-response>
  <type>resume_agent</type>
  <success>true</success>
  <info>Successfully resumed agent "XPS-8300 - AGNT0001".</info>
  <errors />
</command-response>

JSON

{ 
"type": "resume_agent",
"success": true,
"info": "Successfully resumed agent "Mark-4 - AGNT001".",
"errors": ""
}

Resume an Agent: Request Properties

Properties	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`agentID`	Agent ID	Unique ID for this Agent, created during installation.		Y (unless `agentName` is specified)	`agentName`
`agentName`	Agent Name	Name used within the Controller to identify this resource.	Maximum 40 alphanumerics.	Y (unless `agentID` is specified)	`agentID`

Set an Agent Task Execution Limit

	Description
URI	http://host_name/uc/resources/agent/ops-set-agent-task-execution-limit
HTTP Method	POST
Description	Sets the task execution limit for the specified agent.
Example URI	http://localhost:8080/uc/resources/agent/ops-set-agent-task-execution-limit
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Set an Agent Task Execution Limit: XML and JSON Examples.
Request Properties	See Set an Agent Task Execution Limit: Request Properties.
Example Response	See Set an Agent Task Execution Limit: XML and JSON Examples.

Set an Agent Task Execution Limit: XML and JSON Examples

Example

XML

JSON

Example Request

XML

By Agent Name
Limit Type: Limited

<set-agent-task-execution-limit>
  <agentName>XPS-8300 - AGNT0001</agentName>
  <limitAmount>10</limitAmount>
  <limitType>Limited</limitType>
</set-agent-task-execution-limit>

By Agent ID
Limit Type: Limited

<set-agent-task-execution-limit>
  <agentID>AGNT0001</agentID>
  <limitAmount>10</limitAmount>
  <limitType>Limited</limitType>
</set-agent-task-execution-limit>

By Agent ID
Limit Type: Unlimited

<set-agent-task-execution-limit>
  <agentID>AGNT0001</agentID>
  <limitType>Unlimited</limitType>
</set-agent-task-execution-limit>

JSON

By Agent Name
Limit Type: Limited

{
 "agentName": "Mark-4 - AGNT001",
  "limitAmount": 10,
  "limitType": "Limited"
}

By Agent ID
Limit Type: Limited

{
 "agentID": "AGNT001",
  "limitAmount": 10,
  "limitType": "Limited"
}

By Agent ID
Limit Type: Unlimited

{
 "agentID": "AGNT001",
   "limitType": "Unlimited"
}

Example Response

XML

<command-response>
  <type>set_agent_task_execution_limit</type>
  <success>true</success>
  <info>Successfully updated agent "XPS-8300 - AGNT0001" with task limit type: "Limited", amount: "10".</info>
  <errors />
</command-resp

JSON

{ 
"type": "set_agent_task_execution_limit",
"success": true,
"info": "Successfully updated agent "Mark-4 - AGNT001" with task limit type: "Unlimited".",
"errors": ""
}

Set an Agent Task Execution Limit: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`agentID`	Agent ID	Unique ID for this Agent, created during installation.		Y (unless `agentName` is specified)	`agentName`
`agentName`	Agent Name	Name used within the Controller to identify this resource.	Maximum 40 alphanumerics.	Y (unless `agentID` is specified)	`agentID`
`limitAmount`	Limit Amount	Number of tasks that can be running at the same time by the Agent.		Y (if `limitType` is Limited (2).
`limitType`	Task Execution Limit	Specification for whether a Limited or Unlimited number of task instances can be run concurrently on the Agent. For purposes of imposing this task execution limit, running task instances are those in any of these statuses: Cancel Pending, Queued, Received, Running, Submitted, and Started.	Valid values: As String = Unlimited, As Value = 1 As String = Limited, As Value = 2	Y

Suspend an Agent

	Description
URI	http://host_name/uc/resources/agent/ops-suspend-agent
HTTP Method	POST
Description	Suspends the specified agent.
Example URI	http://localhost:8080/uc/resources/agent/ops-suspend-agent
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Suspend an Agent: XML and JSON Examples.
Request Properties	See Suspend an Agent: Request Properties, below.
Example Response	See Suspend an Agent: XML and JSON Examples.

Suspend an Agent: XML and JSON Examples

Example

XML

JSON

Example Request

XML

By Agent Name

<suspend-agent>
  <agentName>XPS-8300 - AGNT0001</agentName>
</suspend-agent>

By Agent ID

<suspend-agent>
  <agentID>AGNT0001</agentID>
</suspend-agent>

JSON

By Agent Name

{
 "agentName": "Mark-4 - AGNT001"
}

By Agent ID

{
 "agentID": "AGNT001"
}

Example Response

XML

<command-response>
  <type>suspend_agent</type>
  <success>true</success>
  <info>Successfully suspended agent "XPS-8300 - AGNT0001".</info>
  <errors />
</command-response>

JSON

{ 
"type": "suspend_agent",
"success": true,
"info": "Successfully suspended agent "Mark-4 - AGNT001".",
"errors": ""
}

Suspend an Agent: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`agentID`	Agent ID	Unique ID for this Agent, created during installation.		Y (unless `agentName` is specified)	`agentName`
`agentName`	Agent Name	Name used within the Controller to identify this resource.	Maximum 40 alphanumerics.	Y (unless `agentID` is specified)	`agentID`

Universal Controller 7.5.x

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

Agent: Properties

Agent: Email Notification Properties

Agent: SNMP Notification Properties

Resume an Agent

Resume an Agent: XML and JSON Examples

Resume an Agent: Request Properties

Set an Agent Task Execution Limit

Set an Agent Task Execution Limit: XML and JSON Examples

Set an Agent Task Execution Limit: Request Properties

Suspend an Agent

Suspend an Agent: XML and JSON Examples

Suspend an Agent: Request Properties