Working with Agents

Right-clicking an Agent opens a context-menu with all its available functions, which depend on whether it is active or not.

This topic describes those functions or provides links to the corresponding descriptions:

Starting an Stopping an Agent

Prerequisite: Enable the relevant ports in your firewall, so that the server process will be able to connect to the ServiceManager. You have to use the ports defined in the INI file of the ServiceManager, see Service Manager Service.

Right click one or more Agents and select Start to initiate them via the ServiceManager.

Right-click one or more active Agents and select Stop to deactivate it/them. The agent stops immediately, however, processes that are currently running will continue.

Disconnecting the Agent

This option is available for active Agents.

When you start a new Communication Process and the Agents rearrange themselves to improve their workload balance, you may want to temporarily cut the connection between the Automation Engine and the Agents.

For this purpose, right-click one or more active Agents and select Disconnect Agent Connection. The Agents reconnect to the Automation Engine as soon as the next signal for Agent checking is sent.

Initiating Log Rotation

This option is available for active Agents.

The Automation Engine logs large amounts of information. To be able to handle your log files easily, you can define system-wide settings that break the information to be logged in smaller chunks and thus produce also smaller log files.

For example, you can determine the maximum size of the log file; or you can specify the number of days that may elapse before a new file starts. You do so in the UC_SYSTEM_SETTINGS variable using the CHANGE_LOGGING_DAYS and CHANGE_LOGGING_MB keys. For more information, see CHANGE_LOGGING Parameters and UC_SYSTEM_SETTINGS - Systemwide Settings.

You can also change the log settings via the Automic Web Interface. For this purpose, right-click one or more records and select Initiate Log Rotation; this causes a new log file to be written. A dialog prompts you to confirm your action.

Updating the Service Manager Link

Prerequisite: Enable the relevant ports in your firewall, so that the server processes will be able to connect to the ServiceManager. You have to use the ports defined in the INI file of the ServiceManager, see Service Manager Service.

This option is available for active Agents.

To be able to start Agents either manually from the Administration perspective or via the script element MODIFY_SYSTEM using a ServiceManager, the connection settings between Agent and ServiceManager must be up-to-date. There can be situations in which this is not the case, for example, it can happen that the service name which has been entered in the Agent object does not comply with the corresponding service name in the ServiceManager anymore.

Right-click one or more Agents and select Update Service Manager Link to refresh their ServiceManager connection settings. Alternatively, you can enter the relevant values manually in the Service Manager section of the Agent definition page. For more information, see Agents (HOST).

Replacing Agents

This option is available for active and inactive Agents, provided no tasks are running on them.

You can replace an Agent with another one of the same type and have the new Agent take over all tasks immediately. All references to the replaced agent are automatically changed in the settings of the objects that use it.

Important! Replacing Agents does not work for Scripts. After automatically replacing an Agent using this function, you still have to replace the references to the Agent(s) in Scripts manually.

To Replace the References to an Agent in Objects

Right-click the Agent that must be replaced and select Replace.
The Replace Agent dialog is displayed.

The list in the lower part of the dialog displays all objects in which the selected Agent is being used.
From the Replacement dropdown list select the Agent with which you want to replace it.
By default all objects are selected; if you leave it so, the reference to the "old" Agent will be replaced with the "new" one in all of them.

If you do not want to replace the Agent in all the objects but only in some of them, do one of the following:
- Deactivate the checkbox in the table header; this deselects all checkboxes. Now activate the checkboxes next to the objects in which you want to replace the Agent.
- Deactivate the checkboxes next to the objects in which you do not want to replace the Agent.
When replacing an Agent with a different one, you may want to also modify some of the other settings of the affected objects. For this purpose, select one or more object in the list and click Open in new Window. This opens the definition pages of the selected objects in a new browser window each.
Click the Replace button.

If you select an Agent Group in the Replacement dropdown list, all Agent Groups in the list below are disabled because it is not possible to assign an Agent group to another Agent Group.

Adding and Downloading an Agent - Administration Perspective

You can create a new Agent and download a pre-configured Agent directly from the Administration perspective. You can do so in any Client in the system. However, the Agent object is always also available in Client 0. When you download a pre-configured Agent, you don not have to make any additional definitions. However, you can change them as needed in Client 0.

In Client 0, you can also download an Agent from the Process Assembly perspective.

Prerequisite! The Packs required for a Centralized Agent Upgrade (CAU) must be installed before you can download an Agent from the Administration perspective. You can download the CAU packs from https://marketplace.automic.com/. Once you have downloaded them, you have to install them in Client 0. You can do so from the Packs page in the Administration perspective. For more information, see Centralized Agent Upgrade (CAU).

This example video walks you through the installation of a Linux Agent in Automic Automation:

Note: This option is available for UNIX, Windows, all Java based Agents and the TLS Gateway.

To Add and Download an Agent

Open the Administration perspective and select Agents & Groups > Agents from the navigation pane on the left.
You have two options:
- Right-click anywhere on the list and select Add > Add Agent
- Click the Add Agent button on the toolbar
Select the relevant Agent from the list and click the Add button. The Object Name dialog is displayed.
Enter a descriptive Name.
Optionally, enter a short and descriptive Title that helps you recognize the Agent.
Click OK.

The new Agent is available in the Agents list.
You can download an Agent either from the Administration or the Process Assembly perspective:
- In the Administration perspective, add an Agent as described before. On the Agents list you have two options:
  - select the Agent and click the Download Agent button on the toolbar
  - right-click the relevant Agent and select Download Agent
- In the Process Assembly perspective, right-click the relevant Agent object and select Download Agent.
The Download Agent dialog is displayed. The Name field is populated automatically.
Define the corresponding Operating System and Architecture.
Optionally, select the ServiceManager checkbox.

Note: When the Service Manager checkbox is not selected, the Operating System and Architecture fields are disabled for Java based Agents. Also, when you select a Windows Agent, the Operating System is Windows by default and the field is disabled.
Once you have defined all parameters, click Download. Your browser notification shows the Agent .zip file is being downloaded.
Unpack the .zip file on the same machine on which the Agent runs.
Once the file is unpacked, you must do the following:

UNIX (Linux) Agents
1. Register to the host with your user ID, for example, AE.
2. Ensure that all files have the correct owner and group entry. The owner must be the same user you used to register (AE) and the group must correspond to the code of the user (AE). Only a privileged user, such as root, can make these modifications.
  
  Example
  - chown AE * changes the owners of all files to AE
  - chgrp Group_name * changes the user groups of all files.
3. For actual operation, the ucxj??? file can be given the permissions of a privileged user such as root.
  - Change the owner to root: chown root ucxj???
  - Set S-Bit (Set-Userid): chmod 4755 ucxj???
  Note: You need at least the permissions 755 for executable objects such as agents.
4. Set the SSL_CERT_DIR and SSL_CERT_FILE environment variables with the User which will start the Agent.
  
  These variables allow you to load the certificates from the TLS/SSL store. The certificates can be stored either in one file per certificate or all certificates in one .pem file :
  - SSL_CERT_DIR location of the trusted CA certificates with each certificate in a separate file, for example,/etc/ssl/certs/
  - SSL_CERT_FILE location of the .pem file with all the trusted CA certificates, for example, /etc/pki/tls/certs/ca-bundle.crt
5. Run the ucxjlx6 binary file to start the Agent.
The downloaded Agent is ready to work.

For more information, see Agents (HOST).

Renaming/Deleting an Agent

You can rename and/or delete Agents from the Agents list in any Client that you have access to, given the following applies:

You have write (W) permissions on the Agent
No tasks are running on the Agent
The Agent is inactive
The Agent is not used in multiple Clients

Note: If you try to rename or delete an Agent that is used in multiple Clients, an error message is displayed.

To rename and/or delete an Agent, right-click it and select Rename/Delete.

Using Scripts

You can use scripts to easily create, download and extract agent packs, as well as start agents running on a Windows or UNIX system.

We have gathered a number of deployment script examples for SQL, REST, Windows, and UNIX agents. They allow you to deploy and start the agents without having to create your own script. You can also merge separate scripts used in the examples into one large script.

More information: