Agent Web Services

Owned by Stonebranch (Deactivated)
Last updated: Nov 11, 2024 by Alec Berger
15 min read

Overview

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

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

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 ExtensionsIndication 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 MinimumMinimum extension API level supported.

extApiLevelMax

API Level MaximumMaximum extension API level supported.

extensions

ExtensionsList 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

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

GET

Description

Retrieves Agent details using specific query parameters.

Example URI

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

  • As String = IBM i, As Value = 9

N

agentname

n/a

Name used within the Controller to identify this Agent.

Wildcards are supported.

N

businessServicesn/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 Properties.

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.


credentialsRequiredCredentials RequiredSpecifies 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 DateFor 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 ExtensionsIndication 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 MinimumMinimum extension API level supported.Read only.

extApiLevelMax

API Level MaximumMaximum extension API level supported.Read only.

extensions

ExtensionsList 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 PeriodGrace period, in seconds, that the Controller will allow for a delayed heartbeat messageInteger.

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