/
Agent Cluster Web Services

Agent Cluster Web Services

Jan 25, 2023

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

 

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

See Read an Agent Cluster: XML and JSON Examples.

Agent Cluster Properties

See Agent Cluster Properties.

Agent Properties

See Agent Properties.

Agent Cluster: Email Notification Properties

See Agent Cluster Email Notification Properties.

Agent Cluster: SNMP Notification Properties

See Agent Cluster SNMP Notification Properties.

Example Response

  • Status 200 /OK
    Successfully created the agent cluster with sysId {sysId}.

Agent Cluster Properties

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

currentCount

Current Task Count

If limitType is Limited (2); Current number of tasks currently being run by the Agents in this agent cluster.

Integer; Read only.

N

description

Description

User-defined; description of this record.

 

N

distribution

Distribution

Method used to select an Agent in the Agent Cluster.

Valid Values:

  • As String = Any, As Value = 1

  • As String = Round Robin, As Value = 2

  • As String = Lowest CPU Utilization, As Value = 3

  • As String = Network Alias, As Value = 4

Default is Any (1).

N

exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read only

N

exportTable

n/a

Record table information.

read only

N

ignoreInactiveAgents

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

ignoreSuspendedAgents

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

lastAgentUsed

Last Agent Used

Agent that was selected the last time a task was sent to this Agent Cluster.

Read only.

N

lastResolution

Last Resolution

If distribution is Network Alias (4); Last attempted time of Network Alias resolution.

Read only.

N

limitAmount

Limit Amount

If limitType is Limited (2); Number of tasks that can be running at the same time by the Agents in this agent cluster.

 

N

limitType

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:

  • As String = Unlimited, As Value = 1

  • As String = Limited, As Value = 2

Default is Unlimited (1).

N

name

Cluster Name

Name of this Agent Cluster.

 

Y

networkAlias

Network Alias

If distribution is Network Alias (4); Network alias (or VIP).

 

N

networkAliasPort

Agent Port

If distribution is Network Alias (4); Network alias (or VIP) port that the Agent's Universal Broker is listening on.

 

N

opswiseGroups

Member of Business Services

List of Business Services that this Agent Cluster belongs to.
 
Format:
 
XML

<opswiseGroups> <opswiseGroup>test</opswiseGroup> </opswiseGroups>

 
JSON

"opswiseGroups": ["test"]

 

N

resolutionDescription

Resolution Description

If distribution is Network Alias (4); Description of the last attempted resolution.

Read only.

N

resolutionStatus

Resolution Status

If distribution is Network Alias (4); Status of the last resolution of the Network Alias.

Read only.

N

resumedOn

Resumed On

Date and time when a suspended Agent Cluster was resumed.

Read only.

N

retainSysIds

n/a

Specification for whether or not the Create an Agent Cluster web service will persist the sysId - CAC property.

 

  • If retainSysIds="true" and sysId is included in the request, sysId will be persisted to the database.

  • If retainSysIds="false" and sysId is included in the request, sysId will be ignored; it will be autogenerated by the Controller.

Note

In XML web services, retainSysIds is specified as an attribute in the <agentCluster> element.

Optional; Valid values: true/false (default is true).

N

suspended

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

suspendedOn

Suspended On

Date and time when the Agent Cluster was suspended.

Read only.

N

sysId

n/a

sys_id used within the Controller to identify this Agent Cluster.

 

N

type

n/a

Type of Agent Cluster.

For List Agent Clusters: Read only; Valid values:

  • Windows

  • Linux/Unix

For Create/Modify/Read Agent Clusters: Applicable to JSON only; Specifies agent cluster type to create/modify. Valid values: windowsAgentCluster and unixAgentCluster

N

Agent Properties

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

agentName

Agent

Name of an Agent in the Agent Cluster.

 

Y

membershipDecommissioned

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

membershipResumedOn

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

membershipSuspended

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

membershipSuspendedOn

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

type

n/a

Type of Agent

Read only; Valid values:

  • Windows

  • Linux/Unix

N

sysId

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

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.

state

Notification State

Comma-separated list of Notification states

Valid values:

  • As String = Agents Unavailable, As Value = 1

  • As String = Agent Available, As Value = 2

  • As String = Suspended, As Value = 4

  • As String = Resumed, As Value = 8

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.