Agents (HOST)

Agents are programs that run on the target system, which can be either an Operating System or an application such as SAP, PeopleSoft, Siebel, etc. They establish the connection between the Automation Engine and those target systems, start the execution of tasks and make both their monitoring and the corresponding reporting possible. Agents create log files that record what occurs. As an administrator user, you install and configure them.

There are three possibilities for installing the agents:

  • During the installation of the Automation Engine

  • Later on via the Automic Web Interface in the Process Assembly perspective of Client 0

  • Later on via the Automic Web Interface in the Administration perspective of any client.

As an administrator user, you create agents manually in Client 0 in the Process Assembly perspective or in another client in the Administration perspective. You maintain and work with them in the Administration perspective. Agents are configured using their INI files. You can change some of their properties using the Automic Web Interface.


  • Once the agents are installed, it is not possible to start working with them immediately. First you must authenticate them. There are three Authentication Methods, namely NO, LOCAL and LOCAL_REMOTE. Depending on the method you are applying, the steps to authenticate the agents are slightly different. For more information, see Agent Authentication.

  • Rapid Automation Agents are an exception. They are not created automatically upon installation, you must create them manually after you have loaded the Rapid Automation solution in the database via the Utility DB Load.

Tip: You may need to work with many objects, lists and monitors simultaneously. To make your work easier, you can open them in different browser windows and arrange them side by side on your screen. For more information about this and other useful functions, see Opening and Arranging Multiple Views.

Object Definition

  • Object class: System object
  • Object type/Short form: HOST

This page includes the following:


Do the following to be able to start working with an agent:

  • Install it according to the target system requirements, see Installing the Agents Manually

  • Set the Authentication Method, see Agent Authentication

  • Configure the INI file, see Agents

  • Authenticate the agents in Client 0

  • Assign the agent to the clients it should have access to and define the rights it should have, see Assigning Clients to Agents

  • Define user and user group authorizations on the agent. This grants users and user groups specific rights on the agent. You do it in each client. For more information, see Authorizations Page.

Login and Connection

An agent logs in only once and, once connected, it remains always connected. The following duplicate login validation takes place:

  • Upon installation, the agent starts and tries to log in. If there is no agent connection with the same name, the Automation Engine accepts the login attempt and stores the agent name, port number, start time etc. It deletes this information when the particular agent connection ends.
  • Agents connect via TCP/IP to the communication process (CP) or Java communication process (JCP). The communication between CP/JCP and agent is encrypted. It is the agents that are in charge of keeping the connection alive, as well. When it is lost, they try to reconnect; the interval of reconnect attempts is configurable.

    For more information, see TLS/SSL Communication and Encryption and Non-TLS/SSL Communication and Encryption.

Agents List

You define the number of agents to be displayed on the list in the AGENT_LIST_LIMIT key in the UC_SYSTEM_SETTINGS variable. For more information, see AGENT_LIST_LIMIT. The default is 5,000, the maximum is 20,000.

The number of agents currently displayed is shown on the list toolbar. A plus next to the number indicates that there are more agents available than those displayed. For example, if the AGENT_LIST_LIMIT has been set to "200" and more than 200 agents have been assigned to the client, Agents (200+) is displayed on the toolbar.

The following columns are displayed by default:

  • Status

  • Inactive agents are grayed out

  • Name

    • Maximum length: 32 characters

    • Always in uppercase

    • Do not use special characters when adding an agent to avoid problems in the target system

  • Authenticated

    Authenticated agents are check marked

  • Version

  • TLS

    Agents that use TLS/SSL and establish a connection with the Java communication process (JCP) are check marked

    If an Agent is not check marked, it is a non-TLS/SSL Agent and establishes a connection with a communication process (CP) or connect through the CP port of the TLS Gateway, see TLS Gateway.

  • Platform

  • Platform type of the agent

    Note: This is not the operating system.

  • Hardware

  • Information about the computer on which the agent is running such as the system type, number of processors, or processor type

  • Software

  • Type of platform or operating system of the computer on which the agent is installed

  • Software Version

  • IP address

  • Port no.

  • Last logoff

  • Number of clients

  • Number of user-defined clients in which the Agent has authorizations

  • Linked

  • Whether the agent is linked to a ServiceManager or not

    This depends on the settings made in the Service Manager section.

  • Process ID

  • ZDU Version

  • Either base (B) or target (T) version of the agent in connection with a ZDU, see Zero Downtime Upgrade

The following columns are also available:

  • Last check

    The time at which the status and other agent-related information was last checked

  • Communication Process

    Communication process connected with the agent

  • Time difference

    Time difference between the time of the agent and the time of the Automation Engine

    This is helpful for interpreting job reports when the Automation Engine and the agent run on different hosts with different system times.

  • MIB

    MIB information of the Agent that is used in connection with SNMP

    If available, the unique ID that identifies each monitored net element is displayed.

    For more information, see SNMP Support.

  • Services

    Whether the Agent performs a special service:

    • MAIL - Agent used for e-mail connection

    • SQL - Database Agent used for resolving variable objects of type SQL

  • Compression

    Compression method used as standard in File Transfers

  • Authorizations

    Privileges granted to this Agent in the current Client:

    • R = Read, send data by a File Transfer

    • W = Write, receive data from a File Transfer

    • X = Execute

  • Job res. max.

    Maximum Agent resources available for jobs

  • FT. res. max.

    Maximum agent resources available for File Transfers

  • Keep alive

    Interval in seconds in which the connection to the communication process is checked

    If the connection is lost, the agent tries to reconnect automatically to the first available communication process (CP), which could be a different agent to the previous one.

  • Roles

    Administrators can define a role (free text) for the agent in its INI file. If so, it is displayed here.

  • TLS Gateway

    Name of the TLS Gateway that is used when a non-TLS Agent is connected through the CP port of the TLS Gateway, see TLS Gateway.

  • Net Area

    By default, this is the name of the Automation Engine system. For more information, see Net Areas in the Automation Engine.

    Important! This field is populated only for TLS Gateway instances that are used as a communication process (CP) and are assigned to a net area. It does not apply to the Agents nor to TLS Gateway instances acting as an Agent as only communication processes can be grouped in net areas.

More information:

Displaying the Agent Variables

To see the variables that have been defined for a particular agent, select it and click the Details button on the toolbar. The Details pane displays the variables and the values that have been defined for the agent .

Filtering the Content of the List

It is possible to use different filters to customize the content of the Agents list. Click the Filter button on the toolbar to open the Filter pane. Agent Name, Status and IP Address are always displayed but you can add additional criteria.

Tip: You can share filtered lists with other users. You can also bookmark the filtered list to be able to access it quickly next time. For more information, see Bookmarking and Sharing Links.

Editing the Agent Properties

Once an agent has been added to your system, you can edit its properties as follows:

  1. Right-click the Agent and select Open or Open in New Window.
  2. Edit the properties on the Agent pages described below.

Authorizations Section

Grant or remove the rights of the Agent on Clients.

Attributes Section

Trusted IPs

If the communication with the Agent runs with encryption, you can specify the IP addresses from which the Agent accepts non-encrypted connections. They must be separated by semicolons. Communication to components such as the Event Monitors (BS2000, z/OS) or the Output Collector (NSK) takes place without encryption.

By default, the Agent accepts non-encrypted messages from the local host ( on IPv4 and ::1 on IPv6) and its own IP address. If Event Monitors on z/OS are used in LPARs on different computers, you must specify the relevant IP addresses here.

Releasing individual IP addresses is only reasonable if login attempts of former Agent versions should be rejected.

Service Manager Section

These properties are necessary for the connection between the agent and the Service Manager, an external monitoring tool that allows you to start and stop the Automation Engine.

The Service Manager comes with a proprietary user interface. If you want to use the AWI instead, you can do so provided you enter the necessary information. This way, agents can start directly via the User Interface or via the script element MODIFY_SYSTEM.

All values will automatically be replaced if the connection to the corresponding Service Manager service was successful.

To refresh the connection, right-click the agent and select Update Service Manager Link from the context menu. The default port number 8871 is used, unless a different specification is provided in the SMGR_PORT_RANGE key in the UC_SYSTEM_SETTINGS variable.

  • Phrase is the name of the Service Manager environment.
  • Name refers to the service in the Service Manager.
  • Port is the port number of the Service Manager.
  • Activate Link Agent to Service Manager, otherwise you can no longer start the agent either through the Administration perspective or using the MODIFY_SYSTEM script element. This specification is automatically set if the Service Manager scan for the agent was successful.

More information:

Job Execution

If a Job is started on an OS Agent, it will be initiated in the OS independently of the agent. The agent monitors it and reports its status to the Automation Engine. When the Job finishes, follow-up Jobs can be triggered.

Job Reports

Job reports can be configured in the Job object. When the Job is executed they are transferred to the Automation Engine database. The OS Agent provides the report as a file. The Automation Engine loads the report as individual blocks into the database.
Should the report exceed a configurable limit, only data with the configured size will be transferred into the database, where the last block transferred always contains the file's end. Thus the beginning and end of a Job report are available in the database.

File Transfer Objects

A File Transfer is an executable object that is always executed between two OS Agents. A TCP/IP connection is created between both. The data transfer is encrypted.

The agent sending files reports the Job status and the end of the Job execution to the Automation Engine system. The connection between the two agents is closed at the end of the File Transfer. For more information, see File Transfers (JOBF).

Monitoring and Reporting

As soon as a Job is started, the agent starts monitoring and reporting its status to the Automation Engine. Likewise, when the Job finishes, it reports it. For more information, see Reports for Servers and Agents.

See also: