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.

This page includes the following:

Overview

The RA Agent solutions mentioned in this section 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.
Load the RA solution using the AE.DB Load utility.

For more information, see Installing and Upgrading the Agent.

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.

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 Agent for Rapid Automation.
Edit the INI file (ucxjcitx.ini), see Editing the INI File (ucxjcitx.ini).
Load the respective .jar file into the database using the AE.DB Load utility, 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 Working with 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 ucxjcitx.ini file for the RA Agent described below.

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.
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
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.
cp= Address of the 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>

For information on the additional parameters in the ucxjcitx.ini file, see Agent RA Core INI file.

A sample ucxjcitx.ini file is shown below. 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

[RA]

cache_directory=cache

ext_directory=external

shared_directory=shared

lib_directory=lib

[TCP/IP]

connect=20

cp=localhost:2217

[AUTHORIZATION]

KeyStore=

InitialPackage=

[VARIABLES]

uc_host_jcl_var=RA

uc_ex_path_bin=.

uc_ex_path_temp=..\temp\

uc_ex_path_jobreport=..\temp\

[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

[CP_LIST]

2218=PC01

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

You must load the RA solution (.jar file) into the AE database using the AE.DB Load utility. To do so, 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.