Installing/Upgrading the Web Service Agent in an Existing Automation Engine System

This topic describes how to install the Agent in an existing Automation Engine system. It is not relevant when you load the Agent into an Applications Manager system.

Warning! The Web Service Rapid Automation Agent is not available on IBM AIX operating systems.

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 Web Service 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: 
  • For Windows: Execute the setup.exe file.
  • For UNIX: Unpack the ucxjcitx.tar.gz file.
• Edit the ucxjcitx.ini file.
• Load the  .jar file into the database.
• 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 Web Service 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

Some Agents, like Web Services require a supported version of the JDK on the host. The PATH environment variable on the Agent machine must contain the path to the bin directory of a JDK. In order to compile RA Web Service SOAP Agent connection files, the JDK must be in the PATH environment variable (before any other versions of the JDK). This way, the supported version of javac will be called to do the compiles.

If you do not wish to have the supported version of the JDK in the PATH or as the first JDK in your path, you can alternately use a -D option to specify the full path to the desired javac in the Service Manager program command to start the Agent like the following:

-Dautomic.ra.webservice.javac=/usr/jdk<version>/bin/javac

Here is an example in the Service Manager utility: 

java -Dautomic.ra.webservice.javac=/etc/alternatives/javac -jar /u01/users/agents/ra_webservices/bin/ucxjcitx.jar disable_cache

If the -D value has a blank in it, the fully-pathed file must be enclosed in quotes like the following:

-Dautomic.ra.webservice.javac="C:\Program Files (x86)\Java\<version>\bin\javac.exe"

The Web Service Agent requires a supported version of the JDK to be installed on the host. The PATH environment variable on the Agent machine must contain the path to the bin directory of a JDK. In order to compile RA Web Service SOAP Agent connection files, the JDK must be in the PATH environment variable (before any other versions of the JDK). This way, the supported version of javac will be called to do the compiles.

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.

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 Web Service 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.

Using the krb.ini (.conf) File for Kerberos Authentication

Previous releases of the Web Service Agent had additional Kerberos settings specified in the Connection object. Now all Kerberos settings other than User and Password are set in the krb.ini (.conf) file. If you upgraded from a previous version with other settings defined in the Connection object or you create a new Connection object with Kerberos authentication, you need to create/edit the krb.ini (.conf) file. The Agent itself does not read this file directly, it uses the Kerberos classes of the JRE.

The algorithm to locate the krb5.conf file is the following:

• If the system property java.security.krb5.conf is set, its value is assumed to specify the path and file name.
• If that system property value is not set, the configuration file is looked for in the directory:
• <java-home>\lib\security (Windows)
• <java-home>/lib/security (Solaris and Linux)

Here <java-home> refers to the directory where the JRE is installed. For example, if you have J2SE 5.0 installed on Solaris in a directory named /j2sdk1.5, the directory in which the configuration file is looked for is:

/j2sdk1.5/jre/lib/security

• If the file is still not found, then an attempt is made to locate it as follows:
• /etc/krb5/krb5.conf (Solaris)
• c:\winnt\krb5.ini (Windows)
• /etc/krb5.conf (Linux)
• If the file is still not found, and the configuration information being searched for is not the default realm and KDC, then implementation-specific defaults are used. If, on the other hand, the configuration information being searched for is the default realm and KDC because they weren't specified in system properties, and the krb5.conf file is not found either, an exception is thrown.

Starting the Agent

The Web Service 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.

You can use the following command to start the Agent via the command line (UNIX and Windows):

java -jar -Xrs -Xmx2048m ucxjcitx.jar disable_cache

You can also start the Web Service Agent using the Service Manager program. For more information, see your Automation Engine documentation.

Warning! 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 Web Service 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.