/
Agent Web Services

Agent Web Services

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

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": [ "A