Overview
Universal Controller supports the following RESTful-based web services for Agent Cluster operations, which are listed alphabetically on this page.
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: | 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: | 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: | 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.
| 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 5869707 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 5869707: Read only; Valid values: windowsAgentCluster and unixAgentCluster | 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: |
| 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 | See 5869707. |
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 |
|