Agents Overview

Owned by Stonebranch
Feb 06, 2023
7 min read

Agents

Agent resources refer to Universal Agents, running programs on one or more remote machines, connected to the Controller via Universal Message Service (OMS).

OMS must be running in order for you to run tasks on an Agent.

There are three types of Agents:

Displaying Agent Details

When you start an Agent for the first time, the Controller automatically creates a database record for that Agent. You can view these records for details and status information.

(You also can view status information about Agents from the Command Line Interface (CLI).)
 

Step 1

From the Agents & Connections navigation pane, select Agents > All Agents or Agents > <type of agent>. An Agents list displays:
 

 
See Agents List Field Descriptions, below, for a description of the columns on an Agent List.

Step 2

To display Details about an Agent on the list, click the details icon or click anywhere in the Agent row.
 

 
Most fields are display-only; however, you can make the following changes:

You also can choose to:

  • Temporarily suspend the agent's ability to run tasks.



For information on how to access additional details - such as Metadata and complete database Details - for Agent (or any type of record), see Records.

Agents List Column Descriptions

The following table describes the default display columns on an Agents list.

Column

Description

Name

User-defined during installation; name used within the Controller to identify this Agent.

Host Name

User-provided during installation; IP address or domain/name of the host machine where the resource resides.

Type

All Agents list only; Agent's platform: Linux/Unix, Windows, or z/OS.

Agent ID

Unique ID for this Agent, created during installation.

Version

System-supplied; version number of the Agent program.

Last Heartbeat

System-supplied; date and time the most recent heartbeat was received from the resource.

Current Task Count

System supplied; current number of tasks currently being run by this Agent.

Suspended

Specification (true or false) for whether or not this Agent has been suspended from the ability to run tasks.

Status

System-supplied; status of the Agent.

  • Active: the Agent is running.
  • Offline: the Agent is not running.

Started Date

Time stamp of when the Agent started or connected.

Updated By

User that last updated this record.

Updated

Date when this record was last updated.

Member of Business Service

Business Services that this Agent belongs to.

Agent Details Field Descriptions

Detailed descriptions of the fields in the Agent Details are provided for each type of Agent.

Starting and Stopping Agents

For instructions on starting and stopping Agents, see Starting and Stopping Agent Components.

Suspending Agents, Agent Clusters, and Agent Cluster Memberships

If an Agent or Agent Cluster reaches its Task Execution Limit, all new work queued against that Agent or Agent Cluster will transition into the Execution Wait status until the Current Task Count falls below the Limit Amount.

You also can manually suspend (and resume) Agents and Agent Clusters, as well as Agent memberships in Agent Clusters.

Note

The following roles and permissions are required to suspend/resume Agents, Agent Clusters, and Agent Cluster Memberships:

  • Agent Suspend/Resume requires the ops_admin role and the appropriate Agent permissions for Agent Suspend/Resume commands.
  • Agent Cluster Suspend/Resume and Agent Cluster Membership Suspend/Resume require the ops_agent_cluster_admin role.

Suspending an Agent

You can temporarily suspend the ability of an Agent to run tasks from the Agent list or the Agent Details for that Agent. Any tasks queued against a suspended Agent will transition into Execution Wait status until the Agent has been resumed.

  • To suspend an Agent from the Agents list, either:
    • Right-click the Name of the Agent to be suspended and, on the Action menu, click Suspend Agent.
    • Click the box to the left of the Name and, from the Action on selected rows... drop-down list at the bottom of the page, click Suspend Agent.
  • To suspend an Agent from the Agent Details, click the Suspend Agent button. A Resume Agent button replaces the Suspend Agent button.

Resuming an Agent

(To end the suspension, and resume the ability of an Agent to run tasks, either:

  • Click Resume Agent on the Action menu or from the Action on selected rows... drop-down list.
  • Click the Resume Agent button.

Suspending an Agent Cluster

You can temporarily suspend the ability of a cluster of Agents to run tasks from the Agent Clusters list or an Agent Cluster Details. Any tasks queued against a suspended agent cluster will transition into Execution Wait status until the agent cluster has been resumed.

  • To suspend an Agent Cluster from the Agent Clusters list, either:
    • Right-click the Name of the agent cluster to be suspended and, on the Action menu, click Suspend Agent Cluster.
    • Click the Details icon next to the Name of the Agent Cluster and, in the Agent Cluster Details, click Suspend Agent Cluster.
  • To suspend an Agent Cluster from an Agent Cluster Details, click the Suspend Cluster button. A Resume Cluster button replaces the Suspend Cluster button.
  • When an Agent Cluster is Suspended or Resumed, a Suspended On or Resumed On field indicates the date and time of the suspension or resumption.

Resuming an Agent Cluster

  • To end the suspension, and resume the ability of a Agents in an Agent Cluster to run tasks, from the Agent Clusters list, either:
    • Right-click the Name of the agent cluster to be resumed and, on the Action menu, click Resume Agent Cluster.
    • Click the Details icon next to the Name of the Agent Cluster and, in the Agent Cluster Details, click Resume Agent Cluster.
  • To resume an Agent Cluster from an Agent Cluster Details, click the Resume Cluster button. A Suspend Cluster button replaces the Resume Cluster button.
  • When an Agent Cluster is Suspended or Resumed, a Suspended On or Resumed On field indicates the date and time of the suspension or resumption.

Suspending an Agent Cluster Membership

You can temporarily suspend the membership of an Agent in an agent cluster from an Agent Cluster Details. Suspending the membership of an Agent in an agent cluster is equivalent to removing the Agent from the agent cluster, except it is meant to be temporary. The Agent will not be available as a selection from the agent cluster when a task is queued against the agent cluster until the membership of the Agent has been resumed.
 

Note

If a task specifies both an Agent and an agent cluster in which that Agent is a member, and the specified Agent has been suspended from the agent cluster, the Agent still has the ability to run the task. Directly specifying an Agent overrides its suspension from an agent cluster.


To suspend the membership of an Agent from an Agent Cluster Details, click the Agents in Cluster tab and then either:

  • Right-click an Agent on the list and, on the Action menu, click Suspend Cluster Membership.

Suspending an Agent Cluster Membership Due to Decommissioning

A suspended cluster membership cannot be resumed if it was suspended due to decommissioning. The cluster membership will be restored if the Agent is recommissioned or deleted if the Agent is deleted.

Resuming an Agent Cluster Membership

To end the suspension, and resume the membership of an Agent in an agent cluster:

  • Click Resume Cluster Membership on the Action menu or from the Action on selected rows... drop-down list.

Resetting the Current Task Count

The Current Task Count field in Agent Details and Agent Cluster Details identifies the current number of tasks currently being run by, respectively, that Agent or Agent Cluster.

If there is a limit to the number of tasks that an Agent or Agent Cluster can run concurrently (as specified by the Task Execution Limit and Limit Amount fields), you can reset the current task count to 0. This can help avoid a situation where the Controller believes the Agent to be running more tasks than it actually is running, and therefore might impose the task limit on the Agent unnecessarily.

To reset the Current Task Count field, hover your cursor over the down arrow on the Agent Details or the Agent Cluster Details title bar, or right-click the title bar, and then click, respectively, Reset Agent Task Count or Reset Cluster Task Count.

Note

The following roles and permissions are required to reset the current task count:

  • Reset Agent Task Count requires the ops_admin role and the Update Agent permission.
  • Reset Cluster Task Count requires the ops_agent_cluster_admin role.

Sending Notifications on Status of an Agent

You can configure an Agent to send a notification via email or SNMP if the Agent goes down (Offline) or then when it comes back up (Active).

Note

The Agent Notification Disabled If Suspended Universal Controller system property lets you disable the sending of notifications for suspended Agents.

Step 1

From the Agents & Connections navigation pane, select Agents > All Agents or Agents > <type of agent>. An Agents list displays.

Step 2

Click the icon next to the Name of an Agent, or click anywhere in the Agent row, to display Details about the Agent.

Step 3

Click the Notifications tab to display a list of any Email and SNMP notifications configured for the Agent.

Step 4

Select the type of notification you want the Agent to send, and then click New. Notification Details for a new Notification displays (See Email Notification Details and SNMP Notification Details, below.

Step 5

Complete the fields as needed (see Email Notification Details Field Descriptions and SNMP Notification Details Field Descriptions, below).
 

Note

Agent built-in variables are available to pass data about the Agent into the notification. (User-defined variables, including Global variables, are not available for use in Agent email notifications).

Step 6

Click the Save button to save the record.

Email Notification Details

Email Notification Details Field Descriptions

The following table describes the fields and buttons on Email Notification Details.

Field Name

Description

Criteria

This section contains criteria for sending the notification.

Status Options

  • Offline = Trigger the notification when the resource goes offline.
  • Active = Trigger the notification when the resource comes up.

Details

This section contains assorted detailed information about the notification.

Email Template

Name of an Email template defined in an Email Template Details. An Email template allows you to specify standard recipients and text for outgoing emails. Enter the name of an existing Email template, select an Email template from the drop-down list, or click the Details icon to create a new Email template.

Every Email template specifies an Email connection. If you do not specify an Email template in this field, you must specify an Email connection in the Email Connection field.

If you specify both an Email template (in this field) and an Email Connection, the Email server specified in the Email Connection field overrides the Email server specified in this field.

(Any information specified in an Email task overrides what is specified in an Email template.)

Email Connection

Required if an Email Template is not specified in the Email Template field; Name of an outgoing Email Connection (Type = Outgoing). An Email Connection specifies information about an outgoing or incoming email server. Enter the name of an existing outgoing Email Connection, select an existing outgoing Email Connection from the drop-down list, or clear the Email Connection field and click the Details icon to create a new Email Connection (Outgoing will be pre-selected in the Type field).

If you specify both an Email Template and an Email Connection (in this field), the Email Connection specified in this field overrides the Email Connection specified in the Email Template field.

Reply-To


Email address of the sender. Use commas to separate multiple recipients. Variables and functions supported.

To


Email address of the recipient. Use commas to separate multiple recipients. Variables and functions supported.

CC


Email address of the party being sent a copy of the email, if any. Use commas to separate multiple recipients. Variables and functions supported.

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

Subject


Subject line of the email. Variables and functions supported.

Body


Text of the email message. Variables and functions supported.
 

Note

If both the Email Template and the Email Task (or Email Notification) contain text in the Body, the text in the Email Template is appended to the text in the Email Task (or Email Notification).

Buttons

This section identifies the buttons displayed above and below the Notification Details that let you perform various actions.

Save

Submits the new record to the database.

Save & New

Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.

Save & View

Saves a new record in the Controller database and continues to display that record.

Update

Saves updates to the record.

Delete

Deletes the current record.

Refresh

Refreshes any dynamic data displayed in the Details.

Close

For pop-up view only; closes the pop-up view of this notification.

SNMP Notification Details

SNMP Notification Details Field Descriptions

The following table describes the fields and buttons on SNMP Notification Details.

Field Name

Description

Criteria

This section contains criteria for sending the notification.

Status Options

  • Offline = Trigger the notification when the resource goes offline.
  • Active = Trigger the notification when the resource comes up.

Details

This section contains assorted detailed information about the notification.

SNMP Manager


The SNMP Manager that will receive the SNMP notification. Enter the name of an existing SNMP Manager, select an existing SNMP Manager from the drop-down list, or clear the SNMP Manager field and click the Details icon to create a new SNMP Manager.

Notification Severity

Severity of this notification.
 
Options:

  • Normal (1)
  • Warning (2)
  • Minor (3)
  • Major (4)
  • Critical (5)

Buttons

This section identifies the buttons displayed above and below the Notification Details that let you perform various actions.

Save

Submits the new record to the database.

Save & New

Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.

Save & View

Saves a new record in the Controller database and continues to display that record.

Update

Saves updates to the record.

Delete

Deletes the current record.

Refresh

Refreshes any dynamic data displayed in the Details.

Close

For pop-up view only; closes the pop-up view of this notification.