Skip to main content

Agent Cluster Web Services

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

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

agentLimitAmount

Agent Limit Amount

If agentLimitType = Limited; Limit of number of agents in this agent cluster.

Default is 10.

N

agentLimitType

Agent Limit

Specification for whether the agent cluster has a Limited or Unlimited number of agents.

Valid Values:

  • As String = Unlimited, As Value = 1
  • As String = Limited, As Value = 2

Default is Unlimited (1).

N

createdBy

Created By

Name of the user that created this record.

Read only

N

created

Created

Date and time that this record was created.

Read only

N

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

excludeRelated

n/a

For the Modify an Agent Cluster web service; specification for whether or not to exclude related records from the update, even if they are provided in the request.

info

In XML, excludeRelated is specified as an attribute in the <agentCluster> element.

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

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.
info

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

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

N

strictBsrvcMembership

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

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
  • IBM i

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

Valid values:

  • windowsAgentCluster
  • unixAgentCluster
  • ibmiAgentCluster

N

updatedBy

Updated By

Name of the user that last updated this record.

Read only

N

updated

Updated

Date and time that this record was last updated.

Read only

N

Agent Properties​

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
  • IBM i

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

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.

to

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

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.

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

sysId

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

See Delete an Agent Cluster: URI Parameters.

Example URI

http://localhost:8080/uc/resources/agentcluster?agentclusterid=35dc94a7a8834d28b51e03b5780cd90c

Authentication

HTTP Basic

Example Response

  • Status 200 /OK
    Agent cluster deleted successfully.
  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify agentclustername and agentclusterid at the same time.
  • Status 404 /Not Found
    A custom day with id "f87848b00a0001037f43e7c81c8ec969" does not exist.

Delete an Agent Cluster: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

agentclusterid

Unique ID for this Agent Cluster.

Y
(unless agentclustername
is specified)

agentclustername

agentclustername

Name used within the Controller to identify this Agent Cluster.

Y
(unless agentclusterid
is specified)

agentclusterid

List Agent Clusters​

Description

URI

http://host_name/uc/resources/agentcluster/list

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

See List Agent Clusters: 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.

List Agent Clusters: XML and JSON Examples​

JSON
JSON
[
  {
  "agents": [ {
    "agentName": "Mark-4 - AGNT001",  
    "membershipDecommissioned": true,  
    "membershipResumedOn": null,  
    "membershipSuspended": true,
    "membershipSuspendedOn": "2021-06-29 19:18:30 -400",
    "sysId": "941e558d6f2b4656bdb870e2551fa85e",
    "type": "Linux/Unix"
  } ],
  "currentCount": 0,  
  "description": "Cluster of Linux Agents",
  "distribution": "Network Alias",
  "ignoreInactiveAgents": true,
  "ignoreSuspendedAgents": true,
  "lastAgentUsed": "sb-qa-123",
  "lastResolution": "2018-09-12 09:52:03.410 -0500",
  "limitAmount": 5,
  "limitType": "Unlimited",
  "name": "Cluster 1",
  "networkAlias": "qa-123",
  "networkAliasPort": null,
  "notifications": {
    "emailNotifications": [ {
      "bcc": null,
      "body": "${ops_system_identifier}",
      "cc": null,
      "emailConnection": "ecu-office-365",
      "emailTemplate": "agent-built-variables",
      "replyTo": null,
      "state": "Agents Unavailable",
      "subject": null,
      "sysId": "e120f05abd104e2e952c6b9e693891ab",
      "to": "support@stonebranch.com"
    } ],
    "snmpNotifications": [ {
      "severity": "Minor",
      "snmpManager": "test_manager",
      "state": "Agents Unavailable",
      "sysId": "fc4f4e8b0dea4b51a77a3c20f7e62b2a"
    } ]
  },
  "opswiseGroups": [],
  "resolutionDescription": "Agent in Use:'sb-qa-123'",
  "resolutionStatus": "Success",
  "resumedOn": "2021-06-29 19:18:30 -400",  
  "strictBsrvcMembership":false,  
  "suspended": false,  
  "suspendedOn": null,
  "sysId": "35dc94a7a8834d28b51e03b5780cd90c",
  "type": "Windows"
  "version": 1
  },
  {
  "agents": [ {
    "Agent Cluster Web Services#agentName": "Mark-4 - AGNT002",  
    "membershipDecommissioned": false,
    "membershipResumedOn": null,  
    "membershipSuspended": true,  
    "membershipSuspendedOn": "2021-06-29 19:18:30 -400",
    "sysId": "941e558d6f2b4656bdb870e2551fa85f",
    "type": "Windows"
  } ],
  "currentCount": 0,  
  "description": "Cluster of Windows Agents",
  "distribution": "Network Alias",
  "ignoreInactiveAgents": true,
  "ignoreSuspendedAgents": true,
  "lastAgentUsed": "sb-qa-123",
  "lastResolution": "2018-09-13 10:52:03.410 -0500",
  "limitAmount": 5,
  "limitType": "Unlimited",
  "name": "Cluster 2",
  "networkAlias": "qa-123",
  "networkAliasPort": null,
  "notifications": {
    "emailNotifications": [ {
      "bcc": null,
      "body": "${ops_system_identifier}",
      "cc": null,
      "emailConnection": "ecu-office-365",
      "emailTemplate": "agent-built-variables",
      "replyTo": null,
      "state": "Agents Unavailable",
      "subject": null,
      "sysId": "e120f05abd104e2e952c6b9e693891ab",
      "to": "support@stonebranch.com"
    } ],
    "snmpNotifications": [ {
      "severity": "Minor",
      "snmpManager": "test_manager",
      "state": "Agents Unavailable",
      "sysId": "fc4f4e8b0dea4b51a77a3c20f7e62b2a"
    } ]
  },
  "opswiseGroups": [],
  "resolutionDescription": "Agent in Use:'sb-qa-123'",
  "resolutionStatus": "Success",
  "resumedOn": null,  
  "strictBsrvcMembership":false,  
  "suspended": true,  
  "suspendedOn": 2021-06-29 19:18:30 -400,
  "sysId": "35dc94a7a8834d28b51e03b5780cd90d",
  "type": "Windows"
  "version": 1
  }
]

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

See List Agent Cluster - Advanced: 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):

  • As String = Windows, As Value = 1
  • As String = Linux/Unix, As Value = 2
  • As String = IBM i, As Value = 9

If type is not specified, defaults to all types.

N

List Agent Cluster - Advanced: XML and JSON Examples​

JSON
JSON
[
    {
        "type": "unixAgentCluster",
        "agents": [],
        "currentCount": 0,
        "description": null,
        "distribution": "Any",
        "exportReleaseLevel": "7.3.0.0",
        "exportTable": "ops_unix_agent_cluster",
        "ignoreInactiveAgents": false,
        "ignoreSuspendedAgents": false,
        "lastAgentUsed": null,
        "lastResolution": null,
        "limitAmount": 5,
        "limitType": "Unlimited",
        "name": "linux_cluster_1",
        "networkAlias": null,
        "networkAliasPort": null,
        "notifications": {
            "emailNotifications": [],
            "snmpNotifications": []
        },
        "opswiseGroups": [],
        "resolutionDescription": null,
        "resolutionStatus": "None",
        "resumedOn": null,
        "retainSysIds": true,
        "strictBsrvcMembership": false,
        "suspended": false,
        "suspendedOn": null,
        "sysId": "89ef2f9a35684825849881978b827ee7",
        "version": 2
    },
    {
        "type": "unixAgentCluster",
        "agents": [],
        "currentCount": 0,
        "description": null,
        "distribution": "Any",
        "exportReleaseLevel": "7.3.0.0",
        "exportTable": "ops_unix_agent_cluster",
        "ignoreInactiveAgents": false,
        "ignoreSuspendedAgents": false,
        "lastAgentUsed": null,
        "lastResolution": null,
        "limitAmount": 5,
        "limitType": "Unlimited",
        "name": "linux_cluster_2",
        "networkAlias": null,
        "networkAliasPort": null,
        "notifications": {
            "emailNotifications": [],
            "snmpNotifications": []
        },
        "opswiseGroups": [],
        "resolutionDescription": null,
        "resolutionStatus": "None",
        "resumedOn": null,
        "retainSysIds": true,
        "strictBsrvcMembership": false,
        "suspended": false,
        "suspendedOn": null,
        "sysId": "a47c4a0e6c1d4da5896dd9c072bacb28",
        "version": 2
    },
    {
        "type": "windowsAgentCluster",
        "agents": [],
        "currentCount": 0,
        "description": null,
        "distribution": "Any",
        "exportReleaseLevel": "7.3.0.0",
        "exportTable": "ops_windows_agent_cluster",
        "ignoreInactiveAgents": false,
        "ignoreSuspendedAgents": false,
        "lastAgentUsed": null,
        "lastResolution": null,
        "limitAmount": 5,
        "limitType": "Unlimited",
        "name": "wins_cluster_1",
        "networkAlias": null,
        "networkAliasPort": null,
        "notifications": {
            "emailNotifications": [],
            "snmpNotifications": []
        },
        "opswiseGroups": [],
        "resolutionDescription": null,
        "resolutionStatus": "None",
        "resumedOn": null,
        "retainSysIds": true,
        "strictBsrvcMembership": false,
        "suspended": false,
        "suspendedOn": null,
        "sysId": "3f5c2bb17d2d43149eb70da856c51fe2",
        "version": 1
    },
    {
        "type": "windowsAgentCluster",
        "agents": [],
        "currentCount": 0,
        "description": null,
        "distribution": "Any",
        "exportReleaseLevel": "7.3.0.0",
        "exportTable": "ops_windows_agent_cluster",
        "ignoreInactiveAgents": false,
        "ignoreSuspendedAgents": false,
        "lastAgentUsed": null,
        "lastResolution": null,
        "limitAmount": 5,
        "limitType": "Unlimited",
        "name": "wins_cluster_2",
        "networkAlias": null,
        "networkAliasPort": null,
        "notifications": {
            "emailNotifications": [],
            "snmpNotifications": []
        },
        "opswiseGroups": [],
        "resolutionDescription": null,
        "resolutionStatus": "None",
        "resumedOn": null,
        "retainSysIds": true,
        "strictBsrvcMembership": false,
        "suspended": false,
        "suspendedOn": null,
        "sysId": "3dc7749381ab461883f6a1807c7c3c7d",
        "version": 1
    }
]

Modify an Agent Cluster​

Description

URI

http://host_name/uc/resources/agentcluster

HTTP Method

PUT

Description

Modifies the Agent Cluster specified by the sysId.

Example URI

http://localhost:8080/uc/resources/agentcluster

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Modify 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 updated the agent cluster with sysId {sysId}.

Modify an Agent Cluster: XML and JSON Examples​

JSON
JSON
{
  "type": "windowsAgentCluster",
  "description": "Cluster of Windows Agents",  
  "distribution": "Any",
  "ignoreInactiveAgents": true,
  "ignoreSuspendedAgents": true,
  "limitAmount": 5,
  "limitType": "Unlimited",
  "name": "cluster1",
  "networkAlias": null,
  "networkAliasPort": null,
  "notifications": {
    "emailNotifications": [ {
      "bcc": null,
      "body": "${ops_system_identifier}",
      "cc": null,
      "emailConnection": "ecu-office-365",
      "emailTemplate": "agent-built-variables",
      "replyTo": null,
      "state": "Agents Unavailable",
      "subject": null,
      "sysId": "e120f05abd104e2e952c6b9e693891ab",
      "to": "support@stonebranch.com"
    } ],
    "snmpNotifications": [ {
      "severity": "Minor",
      "snmpManager": "test_manager",
      "state": "Agents Unavailable",
      "sysId": "fc4f4e8b0dea4b51a77a3c20f7e62b2a"
    } ]
  },
  "sysId": "35dc94a7a8834d28b51e03b5780cd90c",
}

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 Read an 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

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.

Read an Agent Cluster: URI Parameters​

Parameter

Description

Specifications

Required

Mutually Exclusive With

agentclusterid

ID used within the Controller to identify this Agent cluster.

String; URI parameter.

Y (unless agentclustername is specified)

agentclustername

agentclustername

Name used within the Controller to identify this Agent cluster.

String; URI parameter.

Y (unless agentclusterid is specified)

agentclusterid

Read an Agent Cluster: XML and JSON Examples​

The retainSysIdsand versionproperties are specified as attributes in XML.

The exportReleaseLevel and exportTable properties are specified as attributes in XML.

JSON
JSON
{
  "type": "windowsAgentCluster",
  "agents": [ {
    "Agent Cluster Web Services#agentName": "Mark-4 - AGNT001",
    "membershipResumedOn": null,  
    "membershipSuspended": true,  
    "membershipSuspendedOn": "2021-06-29 19:18:30 -400",
    "sysId": "941e558d6f2b4656bdb870e2551fa85e",
    "type": "Windows"
  } ],
  "currentCount": 0,
  "description": "Cluster of Windows Agents",  
  "distribution": "Network Alias",  
  "exportReleaseLevel": "7.2.0.0",  
  "exportTable": "ops_windows_agent_cluster",
  "ignoreInactiveAgents": true,
  "ignoreSuspendedAgents": true,
  "lastAgentUsed": "sb-qa-123",
  "lastResolution": "2018-09-12 09:52:03.410 -0500",
  "limitAmount": 5,
  "limitType": "Unlimited",
  "name": "Cluster 1",
  "networkAlias": "qa-123",
  "networkAliasPort": null,
  "notifications": {
    "emailNotifications": [ {
      "bcc": null,
      "body": "${ops_system_identifier}",
      "cc": null,
      "emailConnection": "ecu-office-365",
      "emailTemplate": "agent-built-variables",
      "replyTo": null,
      "state": "Agents Unavailable",
      "subject": null,
      "sysId": "e120f05abd104e2e952c6b9e693891ab",
      "to": "support@stonebranch.com"
    } ],
    "snmpNotifications": [ {
      "severity": "Minor",
      "snmpManager": "test_manager",
      "state": "Agents Unavailable",
      "sysId": "fc4f4e8b0dea4b51a77a3c20f7e62b2a"
    } ]
  },
  "opswiseGroups": [],
  "resolutionDescription": "Agent in Use:'sb-qa-123'",
  "resolutionStatus": "Success",
  "retainSysIds": true,
  "resumedOn": "2021-06-29 19:18:30 -400",  
  "strictBsrvcMembership":false,  
  "suspended": false,  
  "suspendedOn": null,
  "sysId": "35dc94a7a8834d28b51e03b5780cd90c",
  "version": 1
}

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

See Resolve an Agent Cluster: XML and JSON Examples.

Request Properties

See Resolve an Agent Cluster: Request Properties.

Example Response

See Resolve an Agent Cluster: XML and JSON Examples.

Resolve an Agent Cluster: XML and JSON Examples​

Example Request​

JSON
JSON
{
  "agentClusterName": "Agent_Cluster_Alias_Production"
}

Example Response​

JSON
JSON
{
    "type": "resolve_agent_cluster",
    "success": true,
    "info": "Successfully resolved agent cluster\"Agent_Cluster_Alias_Production\".",
    "errors": ""
}

Resolve an Agent Cluster: Request Properties​

Property

UI Field Name

Description

Specifications

Required

agentClusterName

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

See Resume an Agent Cluster: XML and JSON Examples.

Request Properties

See Resume an Agent Cluster: Request Properties.

Example Response

See Resume an Agent Cluster: XML and JSON Examples.

Resume an Agent Cluster: XML and JSON Examples​

Example Request​

JSON
JSON
{
  "agentClusterNameagentClusterName": "uc - Default Windows Cluster"
}

Example Response​

JSON
JSON
{
    "type": "resume_agent_cluster",
    "success": true,
    "info": " Successfully resumed agent cluster "uc - Default Windows Cluster".",
    "errors": ""
}

Resume an Agent Cluster: Request Properties​

Property

UI Field Name

Description

Specifications

Required

agentClusterName

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

See Resume an Agent Cluster Membership: Request Properties.

Example Response

See Resume an Agent Cluster Membership: XML and JSON Examples.

Resume an Agent Cluster Membership: XML and JSON Examples​

Example Request​

Details

JSON By Agent Name

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "agentName": "XPS-8300 - AGNT0001"
}

By Agent ID

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "agentID": "AGNT0001"
}

Example Response​

JSON
JSON
{
    "type": "resume_agent_cluster_membership",
    "success": true,
    "info": " Successfully resumed agent cluster membership.",
    "errors": ""
}

Resume an Agent Cluster Membership: Request Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

agentClusterName

Cluster Name

Name used within the Controller to identify this agent cluster.

Y

agentID

Agent ID

Defined by the user when installing the Agent; name used within the Controller to identify this resource.

Y
(unless agentName
is specified)

agentName

agentName

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
(unless agentId
is specified)

agentId

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

See Return an Agent from an Agent Cluster: 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

agentclustername

Name used within the Controller to identify this agent cluster.

Type = String; URI property.

Y

ignoreexecutionlimit

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​

JSON Response
JSON Response
{
  "hostName": "Mark-4",
  "ipAddress": "192.168.1.21",
  "name": "Mark-4 - AGNT0002",
  "outputProhibited": false,
  "queueName": "AGNT0002",
  "status": "Active",
  "suspended": false,
  "sysID": "b4784b52bf0e453db37dc0c5e9bd441a",
  "type": "Windows",
  "version": "6.4.1.0"
}

Set an Agent Cluster Task Execution Limit​

Description

URI

http://host_name/uc/resources/agentcluster/taskexecutionlimit

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 Request​

Details

JSON Limit Type: Limited

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "limitAmount": 15,
  "limitType": "Limited"
}

Limit Type: Unlimited

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "limitType": "Unlimited"
}

Example Response​

JSON
JSON
{
    "type": "set_agent_cluster_task_execution_limit",
    "success": true,
    "info": " Successfully updated agent cluster"uc - Default Windows Cluster" with task limit type: "Limited", amount: "15".",
    "errors": ""
}

Set an Agent Cluster Task Execution Limit: Request Properties​

Property

UI Field Name

Description

Specifications

Required

agentClusterName

Cluster Name

Name used within the Controller to identify this agent cluster.

Y

limitAmount

Limit Amount

Number of tasks that can be running at the same time by the Agents in this agent cluster.

Set only if limitType is Limited (2).

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.

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 Cluster​

Description

URI

http://host_name/uc/resources/agentcluster/suspend

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

See Suspend an Agent Cluster: XML and JSON Examples.

Request Properties

See Suspend an Agent Cluster: Request Properties.

Example Response

See Suspend an Agent Cluster: XML and JSON Examples.

Suspend an Agent Cluster: XML and JSON Examples​

Example Request​

JSON
JSON
{
  "agentClusterName": "uc - Default Windows Cluster"
}

Example Response​

JSON
JSON
{
    "type": "suspend_agent_cluster",
    "success": true,
    "info": " Successfully suspended agent cluster "uc - Default Windows Cluster".",
    "errors": ""
}

Suspend an Agent Cluster: Request Properties​

Property

UI Field Name

Description

Specifications

Required

agentClusterName

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 Request​

Details

JSON By Agent Name

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "agentName": "XPS-8300 - AGNT0001"
}

By Agent ID

JSON
{
  "agentClusterName": "uc - Default Windows Cluster",
  "agentID": "AGNT0001"
}

Example Response​

JSON
JSON
{
    "type": "suspend_agent_cluster_membership",
    "success": true,
    "info": " Successfully suspended agent cluster membership.",
    "errors": ""
}

Suspend an Agent Cluster Membership: Request Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

agentClusterName

Cluster Name

Name used within the Controller to identify this agent cluster.

Y

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.

Y
(unless agentId
is specified)

agentId