Agent Cluster Web Services
Overview
Universal Controller supports the following RESTful-based web services for Agent Cluster operations, which are listed alphabetically on this page.
- Create an Agent Cluster
- Delete an Agent Cluster
- List Agent Clusters
- Modify an Agent Cluster
- Read an Agent Cluster
- Resolve an Agent Cluster
- Resume an Agent Cluster
- Resume an Agent Cluster Membership
- Return an Agent from an Agent Cluster
- Set an Agent Cluster Task Execution Limit
- Suspend an Agent Cluster
- Suspend an Agent Cluster Membership
Formatting specifications for each web service, including details about property requirements, are provided.
Create an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster |
HTTP Method |
POST |
Description |
Creates a new Agent Cluster. |
Example URI |
http://localhost:8080/uc/resources/agentcluster |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
n/a |
Example Request |
|
Agent Cluster Properties |
|
Agent Properties |
See Agent Properties. |
Agent Cluster: Email Notification Properties |
|
Agent Cluster: SNMP Notification Properties |
|
Example Response |
|
Agent Cluster Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Agent Limit Amount | If agentLimitType = Limited; Limit of number of agents in this agent cluster. |
Default is 10. | N |
|
Agent Limit | Specification for whether the agent cluster has a Limited or Unlimited number of agents. |
Valid Values:
Default is Unlimited (1). |
N |
|
Current Task Count |
If |
Integer; Read only. |
N |
|
Description |
User-defined; description of this record. |
|
N |
|
Distribution |
Method used to select an Agent in the Agent Cluster. |
Valid Values:
Default is Any (1). |
N |
|
n/a |
Universal Controller release that the record was exported from. |
read only | N |
|
n/a | Record table information. | read only | N |
|
Ignore Inactive Agents |
Specification for whether or not inactive (offline) Agents should be ignored when the agent cluster is used for broadcasting. |
Optional; Valid values: true/false (default is false). |
N |
|
Ignore Suspended Agents |
Specification for whether or not suspended Agents should be ignored when the agent cluster is used for broadcasting. |
Optional; Valid values: true/false (default is false). |
N |
|
Last Agent Used |
Agent that was selected the last time a task was sent to this Agent Cluster. |
Read only. |
N |
|
Last Resolution |
If |
Read only. |
N |
|
Limit Amount |
If |
|
N |
|
Task Execution Limit |
Specification for whether a Limited or Unlimited number of task instances can be run concurrently by the Agents in this Agent Cluster. |
Valid Values:
Default is Unlimited (1). |
N |
|
Cluster Name |
Name of this Agent Cluster. |
|
Y |
|
Network Alias |
If |
|
N |
|
Agent Port |
If |
|
N |
|
Member of Business Services |
List of Business Services that this Agent Cluster belongs to. <opswiseGroups> <opswiseGroup>test</opswiseGroup> </opswiseGroups> "opswiseGroups": ["test"] |
|
N |
|
Resolution Description |
If |
Read only. |
N |
|
Resolution Status |
If |
Read only. |
N |
|
Resumed On |
Date and time when a suspended Agent Cluster was resumed. |
Read only. |
N |
|
n/a |
Specification for whether or not the Create an Agent Cluster web service will persist the sysId - CAC property.
Note In XML web services, |
Optional; Valid values: true/false (default is true). |
N |
|
Strict Business Services Membership |
Specifies whether to only allow Agent to Cluster Associations where the Business Service matches. If true, only agents with matched Member of Business Services can be added to the cluster. |
Boolean; Valid values: true/false. Default is false. |
N |
|
Suspended |
Indication of whether or not the ability for this cluster of Agents to run tasks has been suspended. |
Read only; Boolean; Valid Values: true/false. |
N |
|
Suspended On |
Date and time when the Agent Cluster was suspended. |
Read only. |
N |
|
n/a |
sys_id used within the Controller to identify this Agent Cluster. |
|
N |
|
n/a |
Type of Agent Cluster. |
For List Agent Clusters: Read only; Valid values:
For Create/Modify/Read Agent Clusters: Applicable to JSON only; Specifies agent cluster type to create/modify. Valid values: |
N |
Agent Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Agent |
Name of an Agent in the Agent Cluster. |
|
Y |
|
Membership Decommissioned | Indication of whether or not the Agent has been temporarily decommissioned from the Agent Cluster; the Agent will not be available as a selection from the Agent Cluster while it is decommissioned. | N | |
|
Membership Resumed On |
Date and time that an Agent temporarily suspended from the Agent Cluster has been resumed. |
Read only; Boolean; Valid Values: true/false. |
N |
|
Membership Suspended |
Indication of whether or not the Agent has been temporarily suspended from the Agent Cluster; the Agent will not be available as a selection from the Agent Cluster while it is suspended. |
Read only; Boolean; Valid Values: true/false. |
N |
|
Membership Suspended On |
Date and time that the Agent has been temporarily suspended from the Agent Cluster. |
Read only; Boolean; Valid Values: true/false. |
N |
|
n/a |
Type of Agent |
Read only; Valid values:
|
N |
|
n/a |
sys_id used within the Controller to identify the Agent Cluster membership of this Agent. |
|
N |
Agent Cluster: Email Notification Properties
Property |
UI Field Name |
Description |
Specifications |
---|---|---|---|
|
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 |
Text of the email message. |
Variables and Functions are supported. If the |
|
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. |
|
Email Connection |
Name of an Email Connection. |
If you specify both an |
|
Email Template |
Name of an Email Template. |
If you specify both an |
|
Reply-To |
Email address of the sender of the email. |
Use commas to separate multiple recipients. Variables and Functions are supported. |
|
Notification State |
Comma-separated list of Notification states |
Valid values:
|
|
Subject |
Subject line of the email. |
Variables and Functions are supported. |
|
n/a |
sys_id used within the Controller to identify this Email Notification. |
|
|
To |
Email address of the recipient. |
Use commas to separate multiple recipients Variables and Functions are supported. |
Agent Cluster: SNMP Notification Properties
Property |
UI Field Name |
Description |
Specifications |
---|---|---|---|
|
Notification Severity |
Severity level of this notification. |
Valid values:
Default is Normal (1). |
|
SNMP Manager |
SNMP Manager that will receive this notification. |
|
|
Notification State |
Comma-separated list of Notification states |
Valid values:
|
|
n/a |
sys_id used within the Controller to identify this SNMP Notification. |
|
Delete an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster |
HTTP Method |
DELETE |
Description |
Deletes a specific Agent Cluster. |
URI Parameters |
|
Example URI |
http://localhost:8080/uc/resources/agentcluster?agentclusterid=35dc94a7a8834d28b51e03b5780cd90c |
Authentication |
HTTP Basic |
Example Response |
|
Delete an Agent Cluster: URI Parameters
Name |
Description |
Specifications |
Required |
Mutually Exclusive With |
---|---|---|---|---|
|
Unique ID for this Agent Cluster. |
|
Y |
|
|
Name used within the Controller to identify this Agent Cluster. |
|
Y |
|
List Agent Clusters
|
Description |
---|---|
URI |
|
HTTP Method |
GET |
Description |
Retrieves information on all Agent Clusters. |
Example URI |
http://localhost:8080/uc/resources/agentcluster/list |
Authentication |
HTTP Basic |
Consumes Content-Type |
n/a |
Produces Content-Type |
application/xml, application/json |
Response Examples |
|
Agent Cluster Properties |
|
Agent Properties |
See Agent Properties. |
Agent Cluster: Email Notification Properties |
|
Agent Cluster: SNMP Notification Properties |
List Agent Clusters: XML and JSON Examples
XML |
JSON |
---|---|
|
|
List Agent Cluster - Advanced
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster/listadv |
HTTP Method |
GET |
Description |
Retrieves Agent Clusters details using specific query parameters. |
Example URI |
|
Authentication |
HTTP Basic |
Produces Content-Type |
application/xml, application/json |
Consumes Content-Type |
n/a |
Example Responses |
See List Agent Cluster - Advanced: XML and JSON Examples |
URI Properties |
List Agent Cluster - Advanced: URI Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
agentclustername |
Name |
Name or partial name of one or more agent clusters. |
Wildcards are supported. |
N |
businessServices |
Member of Business Services |
Business Services that one or more agent clusters belong to. |
String value of comma-separated Business Services. |
N |
type |
n/a |
Agent Cluster Type of agent clusters to list. |
Valid values: One of the following (not case sensitive):
If type is not specified, defaults to all types. |
N |
List Agent Cluster - Advanced: XML and JSON Examples
XML |
JSON |
---|---|
|
|
Modify an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster |
HTTP Method |
PUT |
Description |
Modifies the Agent Cluster specified by the |
Example URI |
http://localhost:8080/uc/resources/agentcluster |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
n/a |
Example Request |
|
Agent Cluster Properties |
|
Agent Properties |
See Agent Properties. |
Agent Cluster: Email Notification Properties |
|
Agent Cluster: SNMP Notification Properties |
|
Example Response |
|
Modify an Agent Cluster: XML and JSON Examples
XML |
JSON |
---|---|
|
|
Read an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster |
HTTP Method |
GET |
Description |
Retrieves information on a specific Agent cluster. |
URI Parameters |
|
Example URI |
http://localhost:8080/uc/resources/agentcluster?agentclustername=cluster1 |
Consumes Content-Type |
n/a |
Produces Content-Type |
application/xml, application/json |
Example Response |
|
Agent Cluster Properties |
|
Agent Properties |
See Agent Properties. |
Agent Cluster: Email Notification Properties |
|
Agent Cluster: SNMP Notification Properties |
Read an Agent Cluster: URI Parameters
Parameter |
Description |
Specifications |
Required |
Mutually Exclusive With |
---|---|---|---|---|
|
ID used within the Controller to identify this Agent cluster. |
String; URI parameter. |
Y (unless |
|
|
Name used within the Controller to identify this Agent cluster. |
String; URI parameter. |
Y (unless |
|
Read an Agent Cluster: XML and JSON Examples
The
retainSysIds
and
version
properties are specified as attributes in XML.
The
exportReleaseLevel
and exportTable
properties are specified as attributes in XML.
XML |
JSON |
---|---|
|
|
Resolve an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster/resolve |
HTTP Method |
POST |
Description |
Resolves the Network Alias for the specified agent cluster. |
Example URI |
http://localhost:8080/uc/resources/agentcluster/resolve |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
|
Request Properties |
|
Example Response |
Resolve an Agent Cluster: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Resolve an Agent Cluster: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
Resume an Agent Cluster
|
Description |
---|---|
URI |
http://host_name/uc/resources/agentcluster/resume |
HTTP Method |
POST |
Description |
Resumes the specified agent cluster. |
Example URI |
http://localhost:8080/uc/resources/agentcluster/resume |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
|
Request Properties |
|
Example Response |
Resume an Agent Cluster: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Resume an Agent Cluster: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
Resume an Agent Cluster Membership
|
Description |
---|---|
URI |
http://host_name/uc/resources/agent/ops-resume-agent-cluster-membership |
HTTP Method |
POST |
Description |
Resumes the specified agent cluster membership. |
Example URI |
http://localhost:8080/uc/resources/agent/ops-resume-agent-cluster-membership |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
See Resume an Agent Cluster Membership: XML and JSON Examples. |
Request Properties |
|
Example Response |
See Resume an Agent Cluster Membership: XML and JSON Examples. |
Resume an Agent Cluster Membership: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Resume an Agent Cluster Membership: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
Mutually Exclusive With |
---|---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
|
|
Agent ID |
Defined by the user when installing the Agent; name used within the Controller to identify this resource. |
|
Y |
|
|
Agent Name |
Unique ID for this Agent, created during installation. The name of the communications server message queue. The Controller uses the communications server for communications between the Controller scheduler and Agents. |
|
Y |
|
Return an Agent from an Agent Cluster
|
Description |
---|---|
URI |
http://hostName:port/uc/resources/agentcluster/agent |
HTTP Method |
GET |
Description |
Retrieves information on a specific Agent from an Agent Cluster for which a Distribution method of Any or Lowest CPU Utilization is specified. |
URI Parameters |
|
Consumes Content-Type |
n/a |
Produces Content-Type |
application/xml, application/json |
Example Request URI |
http://localhost:8080/uc/resources/agentcluster/agent?agentclustername=testCluster&ignoreexecutionlimit=true |
Example Response |
See Return an Agent from an Agent Cluster: Example Response. |
Return an Agent from an Agent Cluster: URI Parameters
Parameter |
Description |
Specifications |
Required |
---|---|---|---|
|
Name used within the Controller to identify this agent cluster. |
Type = String; URI property. |
Y |
|
Specification to use or ignore the task execution limit. |
Type = Boolean (true/false), Default is false; URI property. |
N |
Return an Agent from an Agent Cluster: Example Response
XML Response |
JSON Response |
---|---|
|
|
Set an Agent Cluster Task Execution Limit
|
Description |
---|---|
URI |
|
HTTP Method |
POST |
Description |
Sets the task execution limit for the specified agent cluster. |
Example URI |
http://localhost:8080/uc/resources/agentcluster/taskexecutionlimit |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
See Set an Agent Cluster Task Execution Limit: XML and JSON Examples. |
Request Properties |
See Set an Agent Cluster Task Execution Limit: Request Properties. |
Example Response |
See Set an Agent Cluster Task Execution Limit: XML and JSON Examples. |
Set an Agent Cluster Task Execution Limit: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Set an Agent Cluster Task Execution Limit: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
|
Limit Amount |
Number of tasks that can be running at the same time by the Agents in this agent cluster. |
Set only if |
N |
|
Task Execution Limit |
Specification for whether a Limited or Unlimited number of task instances can be run concurrently by the Agents in this agent cluster. |
Valid values:
|
Y |
Suspend an Agent Cluster
|
Description |
---|---|
URI |
|
HTTP Method |
POST |
Description |
Suspends the specified agent cluster. |
Example URI |
http://localhost:8080/uc/resources/agentcluster/suspend |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
|
Request Properties |
|
Example Response |
Suspend an Agent Cluster: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Suspend an Agent Cluster: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
Suspend an Agent Cluster Membership
|
Description |
---|---|
URI |
http://host_name/uc/resources/agent/ops-suspend-agent-cluster-membership |
HTTP Method |
POST |
Description |
Suspends the specified agent cluster membership. |
Example URI |
http://localhost:8080/uc/resources/agent/ops-suspend-agent-cluster-membership |
Authentication |
HTTP Basic |
Consumes Content-Type |
application/xml, application/json |
Produces Content-Type |
application/xml, application/json |
Example Request |
See Suspend an Agent Cluster Membership: XML and JSON Examples. |
Request Properties |
See Suspend an Agent Cluster Membership: Request Properties. |
Example Response |
See Suspend an Agent Cluster Membership: XML and JSON Examples. |
Suspend an Agent Cluster Membership: XML and JSON Examples
Example |
XML |
JSON |
---|---|---|
Example Request |
|
|
Example Response |
|
|
Suspend an Agent Cluster Membership: Request Properties
Property |
UI Field Name |
Description |
Specifications |
Required |
Mutually Exclusive With |
---|---|---|---|---|---|
|
Cluster Name |
Name used within the Controller to identify this agent cluster. |
|
Y |
|
|
Agent ID |
Unique ID for this Agent, created during installation. |
|
Y |
|
|
Agent Name |
Name used within the Controller to identify this resource. |
|
Y |
|