Installing/Upgrading the Hyperion FM Agent in an Existing Automation Engine System

This topic describes how to install the Agent in an existing Automation Engine system.

Steps to Install or Upgrade the Agent

Make sure that this and other Java 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 Agents for JMX, Databases, SAP, and RA.

To set-up the RA Hyperion FM Agent, you need to:

• Meet the Java Requirements as described in the Java Requirements section below.
• For Automation Engine version 12.1 or earlier, load a license in the database for the Agent.
• Put the Agent core file(s) on the host machine.
• Do one of the following: 
• Edit the ucxjcitx.ini file.
• Load the  .jar file into the database.
• Delete the contents of the lib folder. The folder should remain empty.
• Set the environment variables EPM_ORACLE_HOME and EPM_ORACLE_INSTANCE, if they are not set.

Example for Windows:

SET EPM_ORACLE_HOME=C:\Oracle\Middleware\EPMSystem11R1

SET EPM_ORACLE_INSTANCE=C:\Oracle\Middleware\user_projects\epmsystem1

• Create an Agent object. The RA Agent only starts if an Agent object of the same name exists in system client 0000.
• Enable Rapid Automation trace to provide more troubleshooting information.
• Start the Agent.
• Disable Rapid Automation trace.

Java Requirements

The Hyperion FM 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 shown below:

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. An example is shown below:

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

For information on supported Java versions, see the Automic Compatibility Checker.

You can get the necessary files to install Java from Oracle.

Putting Agent Core Files on the Host Machine

Install each RA Agent in its own sub-directory on its host machine.

Warning! The Agent core must be the same version as 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 the Automic Download Center and putting the Agent files in place following these instructions.

Warning! The RA Hyperion FM Agent must be installed on the Hyperion Financial Management host system.

For UNIX

1. 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. For example:

automic/agents/ra_ftp

automic/agents/ra_bo

automic/agents/ra_ws

2. Copy the ucxjcitx.tar.gz file in the \Automation.Platform\Agents\rapidautomation\Core\unix sub-directory from the Automic Download Center to the sub-directory you created for this Agent.
3. Unpack the ucxjcitx.tar.gz file using the following commands:

gunzip ucxjcitx.tar.gz

tar -xvf ucxjcitx.tar

For Windows

1. 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. For example:

C:\automic\agents\ra_ftp

C:\automic\agents\ra_bo

C:\automic\agents\ra_ws

2. Copy the files in the \Automation.Platform\Agents\rapidautomation\Core\windows\x86 sub-directory from the Automic Download Center to the sub-directory you created for this Agent.
3. Execute the setup.exe file.

Supplied Files

The Rapid Automation Agent core includes the following notable files:

• ucxjcitx.jar

Agent core for Rapid Automation

• ucxjcitx.ini

Rapid Automation configuration file

• *.jar

Libraries

• uc.msl

Message library

• setup.exe

The Windows installation executable for the RA Agent core

Editing the ucxjcitx.ini File

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 your Automation Engine documentation.

Loading the .jar File into the Database

On the host machine, start the utility AE.DB Load and select the RA Hyperion FM Agent's .jar file. The utility will then load it to the Automation Engine database.

Note: Loading with the utility using the binary executables (ucybdbld.exe under Windows or ucybdbld under Unix) in batch mode is not possible. It's only possible if you use the .jar Loader (ucybdbld.jar).

The RA Agent can only connect to one RA solution. If you intend to use several RA solutions, keep in mind that each solution requires its own RA Agent.

You cannot load the same .jar file of an RA solution to several systems at a time. Any attempt to do so can cause the utility Automation Engine DB Load to abort.

Starting the Agent

The Hyperion FM Agent only starts if an Agent object of the same name exists in system client 0000. A template for the Agent objects is stored in the TEMPLATE folder.

The path may be changed depending on the target installation.

For Windows:

java -Xmx512M -cp ucxjcitx.jar;uc4.jar;shared/uc4-ra.jar;groovy-all.jar;shared/bsf-2.4.0.jar;shared/commons-codec-1.9.jar;shared/commons-logging-1.2.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\epm_hfm_web.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\epm_j2se.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\epm_thrift.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\ess_japi.jar com.uc4.ex.cit.UCXJCITX

For Unix:

java -Xmx512M -cp ucxjcitx.jar:uc4.jar:shared/uc4-ra.jar:groovy-all.jar:shared/bsf-2.4.0.jar:shared/commons-codec-1.9.jar:shared/commons-logging-1.2.jar:shared/hfm_web.jar:/opt/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/lib/epm_hfm_web.jar:/opt/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/lib/epm_j2se.jar:/opt/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/lib/epm_thrift.jar:/opt/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/lib/ess_japi.jar com.uc4.ex.cit.UCXJCITX

If you load the Hyperion FM 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.