Introduction

These pages provide information on the installation of Stonebranch, Inc.'s Universal Agent on Microsoft Windows operating systems. Unless otherwise specified, all references to Universal Agent for Windows refer to one of the 7.4.x versions (for example: 7.4.0.0).

Installation Packages

Universal Agent is installed with one required installation package and three optional installation packages.

To obtain a Universal Agent package, you must download the corresponding product distribution file from the Stonebranch Customer Portal.

Note

A customer user name and password - provided by Stonebranch, Inc. - are required to access this area.

The following table lists the packages available, their supported platforms, distribution file names, and whether or not the package is required.

Package	Distribution File	Required
Universal Agent (system installation)	`sb-7.4.0.LEVEL-windows-x64.exe`	Yes
Universal Agent (user mode installation)	`sb-7.4.0.LEVEL-windows-x64-um.exe`	No
Universal Enterprise Controller	`sb-UECtlr-6.3.0.LEVEL-windows-i386.exe (32-bit)`	No
Universal Enterprise Controller Client Applications	`sb-UEClient-6.3.0.LEVEL-windows-i386.exe (32-bit)`	No
Universal Agent for SOA	`sb-soa-6.7.0.LEVEL-windows-x64.exe`	No

The word LEVEL in each distribution file name is a numeric value representing the product maintenance level contained in the distribution file.

Distribution File Format

The product distribution files are in a Windows self-extracting archive file format.

The names of the distribution files have the following format:

PROD-VRML-OS-HW.exe

PROD is the package content
VRML is the version, release, modification, and maintenance levels (for example, 7.4.0.0)
OS is the name of the operating system supported
HW is the hardware type supported

Universal Agent Installation Methods

There are two installation methods available for Universal Agent for Windows packages:

Detailed information for each method can be found on the following pages.

System Installation

The system installation method uses a traditional Windows Installer-based package. This installation method "assumes" that it is the only Universal Agent instance on a system, and has the following distinguishing characteristics:

The application is listed in Programs and Features, under the Windows Control Panel.
Application files default to traditional install locations (for example, C:\Program Files).
Universal Manager and Utility components are installed in the Windows System32 directory.
Configuration and component definition files reside in in common, well-known locations (for example, C:\ProgramData).
The installation contains the logic necessary to create a new account for running the Universal Broker service.
The Universal Broker service name is not configurable. Its display name is Universal Broker, its registered service name is UBrokerService, and its Application event log message source is ubroker.
The install contains logic to support upgrades from any prior release.
Removal requires a proper Uninstall, via the Windows Control Panel.
The installation is compatible with enterprise deployment tools (for example, SMS).
The installation may install system libraries that the Universal Agent requires.
The installation can automatically configure the Agent to simplify integration with other Stonebranch applications.

Pre-Installation Guidelines

Before starting the Universal Agent for Windows system installation, it is recommended that you close all other Windows programs. Active programs may be using system files that the Universal Agent installation may update.

If a system file is in use during the installation, it is placed in a temporary location. A reboot is required to free the file and move it from the temporary location to its final destination. Closing all programs before the installation reduces the possibility that a file will be in use and that you will have to reboot your computer.

You must be able to write to the directory from which the installation is launched.

External Runtime Dependencies

Additionally, some Universal Agent components may rely on vendor-supplied resources whose runtime dependencies are not known to the Agent before execution. One such component is the Universal Connector for SAP (USAP), which relies on libraries provided by SAP. If the runtime dependencies for those libraries are not available on your Agent system, attempts to run USAP will fail. Where such dependencies exist, use information provided by the vendor to determine runtime requirements. For example, to review runtime requirements for the NetWeaver RFC SDK version 750, refer to the information on this page.

Installation Path

The default installation path for most packages is:

"C:\Program Files"

For the remaining 32-bit packages, the default installation path is:

"C:\Program Files (x86)"

Installation Summary

Step 1	Download the distribution file from the Stonebranch Customer Portal.
Step 2	Log on to Windows using an Administrative account or an account that can be elevated to Administrative authority.
Step 3	Exit all running programs to reduce the likelihood of a reboot.
Step 4	Execute the installation file.
Step 5	Follow installation instructions: Installing a Universal Agent System Install via the Graphical Interface Installing a Universal Agent System Install via the Command Line Interface

User Mode Installation

The user mode install is a lightweight installation method that results in a fully-functional Universal Agent, minus the Windows integration features that the system install offers. However, this install method permits several Universal Agents to reside on a single system, whereas the system install is limited to a single instance.

A user mode install can reside on a system that already has a system install, but an existing system install is not required.

A user mode install has the following distinguishing characteristics:

Application files can reside in any location.
Resources that the Agent requires, such as configuration and component definition files, reside under the install location.
Universal Manager and Utility components also reside under the install directory, in the .\Sys32\bin folder. To ensure that Managers and Utilities register with the correct local Broker, the SB_ConfigSetup.bat> script is provided to properly configure the environment.
By default, a user mode install provides a single working directory for Universal Server components, .\UAHome. A user mode install can still use separate directories for each Server component (as is done for the system install), but doing so requires post-install updates to configuration and component definition files.
A user mode install can configure the Universal Broker service to run as an Administrative user account, but that account must already exist.
The Universal Broker service name is configurable, and must be unique. The install creates the service and registers its Application event log as the service's display name.
A user mode install contains no upgrade logic. Consequently, all user mode installs should be installed in "clean" locations.
The user mode install does not create an entry in Programs and Features. To remove a user mode install, see Removing a Universal Agent User Mode Install.

Note

A user mode install does not provide any required system libraries. All prerequisites must exist to run the Universal Agent in user mode. If the install cannot find the appropriate Microsoft Visual C++ Runtime and the Microsoft Universal C Runtime, the install will fail with an error.

Pre-Installation Guidelines

User mode installations do not update shared system files, so it is not necessary to close all other applications first. However, we do suggest that you close the Windows Services application and the Windows Event Viewer, if open. A user mode installation will create the Universal Broker service and register its message catalog as an Application event log message source. File contention/sharing issues may occur if the Services and/or Event Viewer is open during Universal Broker service creation and configuration.

Note

Do not install a new user mode installation on top of an existing user mode installation. The installation contains no upgrade logic, so doing so can leave the installation in an indeterminate state.

External Runtime Dependencies

Additionally, some Universal Agent components may rely on vendor-supplied resources whose runtime dependencies are not known to the Agent before execution. One such component is the Universal Connector for SAP (USAP), which relies on libraries provided by SAP. If the runtime dependencies for those libraries are not available on your Agent system, attempts to run USAP will fail. Where such dependencies exist, use information provided by the vendor to determine runtime requirements. For example, to review runtime requirements for the NetWeaver RFC SDK version 750, refer to the information on this page.

Installation Path

The default installation path for user mode installs is %TEMP%\universal. However, you can install to any location.

Installation Summary

Step 1	Download the distribution file from the Stonebranch Customer Portal.
Step 2	Close the Windows Services application and the Windows Event Viewer.
Step 3	Execute the installation file, providing elevated credentials when/if asked to do so.
Step 4	Follow the instructions for your desired installation method: Installing a Universal Agent User Mode Install via the Graphical Interface Installing a Universal Agent User Mode Install via the Command Line Interface

Windows Installer

Note

All information related to Windows Installer applies only to the system installation. The user mode installation does not provide or depend on the Windows Installer.

The installation of each Universal Agent for Windows package requires Windows Installer (msiexec.exe) from Microsoft. Windows Installer is a service application that is a standard component of Windows operating systems. (It also can be obtained from Microsoft's website.)

Each Universal Agent for Windows package provides version 3.1.4000.2435 of Windows Installer.

Windows Installer Interfaces

Windows Installer provides two interfaces that you can use to install Universal Agent:

Graphical user interface
Command line

Determining Whether a Universal Agent Install Will Require a System Reboot

If Windows Installer is not present on your Windows operating system, the Universal Agent package being installed will install it before any of its own files are copied.

If Windows Installer is present on your Windows operating system, but it is a version prior to 3.1.4000.2435, the installation will upgrade it. It may be necessary to reboot your system in this situation.

Recent versions of Microsoft Windows and Microsoft Server come with a version of Windows Installer that is much newer than the one provided by the Universal Agent install. This reduces the likelihood that a reboot will be required following an Agent install.

Follow the steps below to determine whether the Universal Agent install will install or upgrade the Windows Installer.

Step 1	From the Windows File Explorer, navigate to the System32 directory (for example, C:\Windows\System32).
Step 2	Search for file msiexec.exe (Windows Installer). If the file exists, continue to the Step 3. If the file does not exist, Windows Installer is not installed on your system. The Universal Agent installation will install it.
Step 3	Right-click on the msiexec.exe file name to display a pop-up menu.
Step 4	Click Properties to display the Properties dialog for msiexec.exe.
Step 5	Click the Version tab. File Version: identifies the currently installed version of Windows Installer (see the following figure). If the version is prior to 3.1.4000.2435, the package installation will upgrade it. (In this figure, the installed Windows Installer is identified as version 3.1.4000.1823. Since this is the earlier version than the version provided by the package installation, it will be upgraded.)

Rebooting the System

If Windows Installer is installed or upgraded during the installation of the package, a reboot of the system is required.

The installation provides an option to either:

Reboot after the installation is complete.
Reboot immediately. The installation will resume automatically after Windows restarts.

If Windows Installer version 3.1.4000.2435 or above already exists on your system, it is not upgraded, and no reboot is required.

Windows Installer Package File Locations

When you install a Universal Agent for Windows package, the Windows Installer package file (*.msi) is extracted to the following locations:

Package	Location
Universal Agent for Windows package (64-bit)	`C:\Windows\Installer\<fname>.msi`
Universal Enterprise Controller for Windows package	`<LocalAppData>\UniversalEnterpriseController\<packagecode>\UECtlr.msi`
UEC Client Applications package	`<LocalAppData>\UEClient\<packagecode>\UEClient.msi`
Universal Agent for SOA for Windows Package	`<LocalAppData>\UniversalAgentforSOAx64\<packagecode>\ Stonebranch Universal Agent for SOA (x64).msi`

In these paths:

<fname> A file name generated by Windows Installer and used for the .msi file cached to C:\Windows\Installer.

<LocalAppData>

User's local Application Data folder.

For example: If the installation was performed by the built-in Administrator account, <LocalAppData> would expand - by default - to:

C:\Users\Administrator\AppData\Local.

<packagecode>

Universally Unique Identifier (UUID) in the format {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}, where X is a hexadecimal character in the range 0 (zero) - F.

For example:

{3B10285A-9602-4DC9-B0A5-4D701BEB5225}.

Detailed Information

The following pages provide detailed information for Windows Installation: