Agents Overview
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: |
---|---|
Step 2 | To display Details about an Agent on the list, click the details icon or click anywhere in the Agent row.
You also can choose to:
|
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.
|
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 |
|
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 |
|
To |
|
CC |
|
BCC |
|
Subject |
|
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 |
|
Details | This section contains assorted detailed information about the notification. |
SNMP Manager |
|
Notification Severity |
Severity of this 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. |