Installing the Agent for Rapid Automation

Rapid Automation (RA) refers to a generic technology in Automic Automation that offers various solutions to integrate and automate third-party applications. Rapid Automation Agents make the functions of a Rapid Automation solution accessible.

You can run a Rapid Automation Agent in a container by building and running a Docker image hosting the Agent. You can use them either for an on-premises Automic Automation system or an Automic Automation Kubernetes Edition environment. The installation of the RA Core agent in a container is the same as for any Java agent.

Tip! The agent installation instruction on this page refer only to the manual installation process. For instructions on how to install the RA Core agent in a container, see Installing Containerized Java Agents.

The Enterprise Software Academy provides examples on how to deploy an Automic Automation Java, Windows or UNIX agent in a container. To access this additional information please select the relevant link:

This page includes the following:

Overview

All RA Agent solutions use common technology, so the install procedure for each of them is similar. However, there are specific requirements and installation steps for each Agent solution. Furthermore, there are often different requirements and installation steps for different versions of the same Agent solution, which are supported for various Automation Engine releases.

Important! The RA Core Agent must have the same version or a version lower than the Automation Engine. You can update the Agent core by getting updated files for an Automation Engine release by downloading the image for that release from our download center at https://downloads.automic.com/and putting the Agent files in place as described in this page.

RA Agents consist of two components:

the RA Core Agent, which is the generic Rapid Automation Agent framework used for any RA solution
the RA solution, which contains the business logic to integrate with third-party applications

To deploy a Rapid Automation agent solution successfully, you have to carry out the following two steps:

Install the RA Core agent in Automic Automation either:
- manually, see Installing the RA Core Agent
- or in a container, see Installing Containerized Java Agents.
In both cases you can use the agent for an on-premises Automic Automation system or an Automic Automation Kubernetes Edition environment.
Load the RA solution into the AE database using either the AE.DB Load utility or the system/ra-solutions/ endpoint of the AE REST API.

The RA Core Agent can only get one RA solution from the AE database. That means that, even if you have loaded different RA solutions to the AE database, the RA Core Agent gets only one. The same applies to different versions of the same RA solution. Therefore, if you intend to use several RA solutions, keep in mind that each solution and/or each version of the same solution requires its own RA Core Agent.

Example

If you have installed only one RA Core Agent and it gets the RA REST solution from the AE database, it becomes the RA REST Agent and there is no RA Core Agent available anymore.

If you have installed two RA Core Agents and both get the RA REST solution from the AE database, they both become RA REST Agents.

If you then proceed to load the next version of the RA REST solution into the AE database, the version is overwritten. The next time the RA REST Agents start, they have the version of the updated RA REST solution.

When the RA Agent starts, it checks whether the RA solution has already been stored locally. If not, it requests the RA solution's JAR file from the Automation Engine. The RA Agent unpacks it in the cache folder as specified in the cache_directory= parameter of the [RA] section of the INI file of the RA Core agent (see Agent RA Core INI file). The name of the created subfolder is the RA solution object's latest modification date. While starting, the system checks whether this timestamp complies with the AE database's timestamp. If they differ from each other because a later version has been loaded to the AE database, the RA Agent retrieves the JAR file and replaces the local RA solution.

There are several Rapid Automation solutions available, including the following:

You can also access the RA Agent documentation from https://docs.automic.com/documentation.

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Note: The TLS/SSL implementation does not apply to the HP-UX Agent, as it is no longer supported in this version.

You can use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

TLS/SSL Agents (in containers or on-premises) and the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer and not the JCP directly. The ingress / HTTPS load balancer must be reachable and requires a certificate for authentication. The address of the load balancer must be defined on both sides: the Automation Engine and the Agent / TLS Gateway.

Important! When you install or upgrade Agents manually for an Automic Automation Kubernetes Edition system, you have to make sure that you configure your Agents and/or TLS Gateway to reach the TCP or HTTPS load balancer and not the CP or JCP directly. Also, make sure that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Installing the RA Core Agent

This section guides you through the installation of the Rapid Automation Core Agent used for Rapid Automation Solutions in an existing Automation Engine system.

Supplied Files

The files that are relevant for the RA Core Agent installation in Windows and UNIX are stored in \Automation.Platform\Agents\rapidautomation\Core. This folder includes (amongst others) all files that are relevant for the installation of the RA Core Agent:

ucxjcitx.jar: Agent core for Rapid Automation
ucxjcitx.ini: Rapid Automation configuration file
*.jar: Libraries
uc.msl: Message library
setup.exe: Windows installation executable for the RA Agent core.
ucxjcitx.sh: UNIX installation executable for the RA Agent core (included in the ucxjcitx.tar.gz file)

Installing and Upgrading the Agent

To set up the Rapid Automation Core agent, carry out the steps described below.

Note: The agents can only connect to TCP port numbers that are lower than 65536. If they use a higher port number, the Agent cannot start and aborts with an error message. This limitation is caused by Java and affects the Rapid Automation Agents.

Make sure you fulfill the Java requirements, see Java Requirements.
Put the Agent core file(s) on the host machine and run the relevant installation file: setup.exe for Windows and ucxjcitx.sh for UNIX, see Installing the RA Core Agent.
Edit the INI file (ucxjcitx.ini), see Editing the INI File (ucxjcitx.ini).
Load the respective .jar file into the database using either the AE.DB Load utility or the system/ra-solutions/ endpoint of the AE REST API, see Loading the RA Solution (.jar File) into the AE Database.
Create an Agent object. The RA Agent only starts if an Agent object of the same name exists in Client 0, see Adding and Configuring Agents.
Start the Agent, see Starting the Agent.

Important! Some RA solutions might have additional Java requirements, might require additional installation steps (such as setting environment variables) or might offer different options for starting the Agent. For more information on a specific RA solution, please refer to the relevant RA solution documentation at https://docs.automic.com/documentation.

Java Requirements

For information on supported Java versions, see the (missing or bad snippet).

On the host and each machine where an Automation Engine user interface is installed, install the Java Runtime Environment (JRE).

You can download the required JRE from https://www.oracle.com/java/technologies/. This automatically installs the Java Plug-in for Web browsers. You can deactivate it in the system control since the AE does not need it. If you already have JRE installed, you can ignore this step.

Use the following command to check the version of the current Java virtual machine (VM):

java -version

If several JRE or Java SDK Versions are installed on the computer, make sure that the order of the directories is correct in the %PATH% or $PATH settings since the first JRE that is found in the list of directories is used.
The Agent requires a supported version of Java on the Agent machine and all machines where the user interface is installed. If a supported version of Java is not the default or the user interface, it can be specified in the ucdj.ini file as follows:

cmd="C:\Program Files (x86)\Java\jre<version>\bin\javaw" -Xmx1024m -Dsun.locale.formatasdefault=true - com.uc4.ucdf.UCDialogFactory - U%User%
On the Agent machine, the explicit path to a supported version of the Java JDE or JDK is needed on the command to start the Agent, for example:

/etc/alternatives/jdk<version>/bin/java -Xmx2048m -jar ucxjcitx.jar disable_cache

Note: Some RA solutions might have additional Java requirements. For more information, please refer to the relevant RA solution documentation at https://docs.automic.com/documentation.

Moving Core Files and Installing the Agent

You have to put the Agent core files in the host machine and install each RA Agent in its own sub-directory.

Installing the Agent - Windows

On the host machine, create a directory for the Agent. We highly recommend installing each RA Agent type on the same host in its own sub-directory.

Example:

C:\automic\agents\ra_ftp

C:\automic\agents\ra_bo

C:\automic\agents\ra_ws

Copy the files in the \Automation.Platform\Agents\rapidautomation\Core\windows\x86 sub-directory from our download center at https://downloads.automic.com/to the sub-directory you created for this Agent.
Execute the setup.exe file.
For the RA Web Service SOAP Agent, RA Web Service REST Agent, RA Hyperion FM Agent, RA Hyperion FDMEE Agent, RA Hyperion EPMA Agent, and RA Hyperion ESSBASE Agent, delete the co of the lib folder. The folder should remain empty.

Installing the Agent - UNIX

On the host machine, create a directory for the Agent. We highly recommend installing each RA Agent type on the same host in its own sub-directory.

Example:

automic/agents/ra_ftp

automic/agents/ra_bo

automic/agents/ra_ws
Copy the ucxjcitx.tar.gz file in the \Automation.Platform\Agents\rapidautomation\Core\unix sub-directory from from our download center at https://downloads.automic.com/to the sub-directory you created for this Agent.
Unpack the ucxjcitx.tar.gz file using the following commands:

gunzip ucxjcitx.tar.gz

tar -xvf ucxjcitx.tar
For the RA Web Service SOAP Agent, RA Web Service REST Agent, RA Hyperion FM Agent, RA Hyperion FDMEE Agent, RA Hyperion EPMA Agent, and RA Hyperion ESSBASE Agent, delete the contents of the lib folder. The folder should remain empty.

Editing the INI File (ucxjcitx.ini)

Edit the required parameters in the INI file of the RA Core Agent. For more information, see Agent RA Core INI file.

[GLOBAL]

name= Name of the Agent object. The Agent name is limited to 32 of the following characters: "A-Z", "0-9", "_", ".", "$", "@", "-" and "#".

Hyphens ("-") are only allowed in Agent names. They must not be used in the names of any other objects.

Although Agent names are limited to 32 characters, you should keep them under 25 characters. The last seven characters are used for adding the suffix '.NEW.nn' when a new Agent is created from its template.
system=Automation Engine system name. This entry must be identical to the entry in the .ini file of the Automation Engine server.

[TRACE]

ra= Used for additional trace. Before starting a newly installed or upgraded Agent, it is a good idea to turn Rapid Automation trace on by adding ra=99 as shown below. This will give more troubleshooting information if something goes wrong during the install. After a successful Agent start, you can set ra=0, and restart the Agent to turn Rapid Automation trace off.

[TCP/IP]

connection= Address of the Java communication process in the Automation Engine system to which the Agent should connect itself. The format is:

<DNS name or TCP/IP address>:<port number>

[AUTHORIZATION]

trustedCertFolder= Path to the folder where the trusted certificates are stored

If this parameter is not set, the certificates should be installed in the respective store; that is the Java trust store.
agentSecurityFolder= Path to the folder where the agent stores security related files such as private keys, signed certificates, root certificates
keyPassword= Password for the key

Default value: changeit

If the value is not defined or is left empty, the system uses the default value.

Note: The keyPassword can be encrypted with the UCYBCRYP Utility. For more information, see Encoding Passwords.

[RA]

cache_directory= Directory to which the Agent should store the RA solutions. This will be set to cache by default and does not need to be altered unless you want to change it.
lib_directory= Directory that contains external libraries that are not part of the solution (such as ojdbc6.jar).

Default: lib

Example ucxjcitx.ini

The required parameters are shown in bold:

[GLOBAL]

name=RA01

system=AE

logcount=10

logging=../temp/RA_LOG_##.TXT

;LogMaxSize: 0...default, qualifiers k...Kilo, M...Mega, G...Giga

LogMaxSize = 0

language=E

helplib=uc.msl

[TRACE]

file=..\temp\RA_TRACE_##.TXT

;TraceMaxSize: 0...default, qualifiers k...Kilo, M...Mega, G...Giga

TraceMaxSize=0

tcp/ip=0

ra=99

trccount=10

[TCP/IP]

connection=jcphost:8443

connect=20

[AUTHORIZATION]

initialPackage=

trustedCertFolder=

agentSecuriyFolder=

keyPassoword=

[RA]

cache_directory=cache

ext_directory=external

shared_directory=shared

lib_directory=lib

[VARIABLES]

uc_host_jcl_var=RA

uc_ex_path_bin=.

uc_ex_path_temp=..\temp\

uc_ex_path_jobreport=..\temp\

[JCP_LIST]

JCP1=8843

Loading the RA Solution (.jar File) into the AE Database

You must load the RA solution (.jar file) into the AE database. To do so, you can either use the AE.DB Load utility or the system/ra-solutions/ endpoint of the AE REST API, see REST API Reference.

To use the AE.DB Load utility, on the host machine, start the utility AE.DB Load and select the Agent's .jar file. The utility loads it to the Automation Engine database.

Note: You must use the .jar Loader (ucybdbld.jar). Loading with the utility using the binary executables (ucybdbld.exe for Windows or ucybdbld for Unix) in batch mode is not possible.

Example

java -jar ucybdbld.jar -B -C0000 -X<path><RA_Solution>.jar

Example

If you have installed only one RA Core Agent and it gets the RA REST solution from the AE database, it becomes the RA REST Agent and there is no RA Core Agent available anymore.

If you have installed two RA Core Agents and both get the RA REST solution from the AE database, they both become RA REST Agents.

Starting the Agent

The Agent only starts if an Agent object of the same name exists in Client 0. A template for the Agent objects is stored in the TEMPLATE folder.

You can use the following command to start the agent:

java -jar -Xrs -Xmx2048m ucxjcitx.jar disable_cache

For the RA Web Service REST Agent and the RA Web Service SOAP Agent, use the following command:

/etc/alternatives/jdk1.7.0_45/bin/java -Xmx2048m -jar ucxjcitx.jar disable_cache

You can also start the Agent using the Service Manager. For more information, see ServiceManager.

Important! Web Service Agents must be started via the Service Manager program. If you start them from the command line, you will receive errors during adapter compilation.

If you load the relevant Rapid Automation solution, then start the Agent shortly afterward, you may get a cached Agent rather than the one you just loaded. You can avoid this by adding disable_cache to the end of the start command. That way the loaded version is always started.

Note: Some RA solutions might have additional options or requirements for starting the Agent. For more information, please refer to the relevant RA solution documentation at https://docs.automic.com/documentation.