Retrieving, Installing, and Testing Upgrade Kits

This chapter discusses retrieving, installing, and testing upgrade kits. It includes the following topics:

Process of Retrieving, Installing, and Testing Upgrade Kits

After you distribute an upgrade kit to a configuration, the subscribers associated with that configuration can retrieve and install that upgrade kit. It is strongly recommended that upgrade kits be retrieved, installed, and tested by test subscribers before you distribute them to production subscribers.

To retrieve, install, and test an upgrade kit, perform the following tasks:

Retrieving and Installing Upgrade Kits. The procedure for retrieving an upgrade kit depends on its type. Distribute upgrade kits to test subscribers before you distribute them to production subscribers.
Starting the Upgrade Wizard. Install the upgrade kit using the Upgrade Wizard. The process for invoking the Upgrade Wizard depends on the subscriber type. Have test subscribers install upgrade kits before you distribute them to production subscribers.
Retrieving Upgrade Kits for Siebel Regional Node Servers.
Testing Upgrade Kits. Have upgrade kits tested by test subscribers before you distribute them to production subscribers. (Among other possible problems, incorrectly constructed upgrade kits can prevent production users from writing data to Siebel Business Applications.)

If you encounter errors in the retrieval, installation, or testing process, then see the following for more information:

Starting the Upgrade Wizard (information about client upgrade error recovery)
Retrieving Upgrade Kits for Siebel Regional Node Servers

Retrieving and Installing Upgrade Kits

This topic describes how to retrieve and install upgrade kits. This task is a step in Process of Retrieving, Installing, and Testing Upgrade Kits.

The procedure for retrieving an upgrade kit depends on its type:

Optional upgrade kits can be manually retrieved and installed by Siebel client subscribers through the Component Upgrades view.
Required upgrade kits are automatically retrieved when mobile users synchronize or log into the application and when the server starts up or Replication Agent synchronizes with Siebel Server.

For each applicable Siebel client type, upgrade kits are retrieved as follows:

Mobile Web Clients request the files from the Siebel Remote Server. The Remote Server retrieves the files from the Siebel File System.
Developer Web Clients retrieve upgrade kits (.saf files) directly from the Siebel File System or by using the File System Manager, depending on the settings defined in the active CFG file.

Subscribers use the Upgrade Wizard to install upgrade kits after they are retrieved. The process for invoking the Upgrade Wizard varies by subscriber type:

For client subscribers, the Upgrade Wizard is invoked automatically after an upgrade is retrieved.
For Siebel Server subscribers, the Upgrade Wizard is invoked manually (see Retrieving Upgrade Kits for Siebel Regional Node Servers).

The process for retrieving and installing upgrade kits by Siebel Client subscribers is described in the following topics:

Retrieving Optional Upgrade Kits for Mobile Web Clients

This topic describes how to retrieve and install an optional upgrade kit for a Mobile Web Client. Optional upgrade kits are only for client subscribers. Upgrade kits for server subscribers must always be required.

This topic is part of Retrieving and Installing Upgrade Kits.

Note: Siebel Web Clients (the client type that is not installed using a Siebel installer) are not Siebel Anywhere subscribers.

The following procedure describes how to retrieve and install an optional upgrade kit for a Mobile Web Client.

Note: The following procedure restarts the Mobile Web Client computer. It is recommended that users save their work and exit from other applications before starting this procedure.

To retrieve an optional upgrade kit for a Mobile Web Client

Invoke the Mobile Web Client.
Choose File, then Synchronize, and then Database.
In the Siebel Remote dialog box, click Synchronize.
Synchronization takes place and is complete when the opposing arrows in the corner of the screen disappear.
Navigate to the User Preferences screen, then the Component Upgrades view.
In the Component Upgrades list, select the desired upgrade component, and check the check box under the Upgrade column.
A check appears. The Status field value is Upgrade Available for those components where optional upgrade kits are available.
Click Upgrade Selected Components to display the Siebel Anywhere Kit Download dialog box, and then complete the following substeps:
1. Follow the instructions in the Siebel Anywhere Kit Download dialog box to start a Siebel Remote session and retrieve the upgrade kit necessary to upgrade your system.
2. Click OK to close the Siebel Anywhere Kit Download dialog box.
Synchronize again to retrieve the corresponding upgrade kits.
Click Upgrade Selected Components again to invoke the Upgrade Wizard for the desired upgrade component.
After the Upgrade Wizard completes, it will automatically restart the Mobile Web Client.
Log in, repeat the above Steps and, from the Component Upgrades list, verify the Status is Version OK for the desired upgrade component. The following describes the fields in the Component Upgrades list.

Field Name	Comments
Upgrade	Check this field to upgrade the component.
Component Name	The name of the upgrade component.
Status	The status of the upgrade component. Values can include the following: Upgrade Available. An optional upgrade kit is available for this component. Upgrade Required. A required upgrade kit is available for this component. Version OK. The version of this upgrade component is current. Upgrade Not Available. The upgrade component is outdated and must be updated; however, no upgrade kit is available to do this. Contact your Siebel administrator.
Current Version	The version of the component on the client computer.
Minimum Version	The minimum required version of the component.
Maximum Version	The maximum required version of the component.
Upgrade Size (bytes)	The size of the upgrade kit.
Download Time (mins)	The estimated time to download the upgrade kit.

Retrieving Optional Upgrade Kits for Developer Web Clients

Siebel Developer Web Clients can retrieve optional upgrade kits as described in the following procedure.

This topic is part of Retrieving and Installing Upgrade Kits.

To retrieve an optional upgrade kit for a Developer Web Client

Start the Developer Web Client.
Navigate to the User Preferences screen, then the Component Upgrades view.
In the Component Upgrades list, the upgrade status is Upgrade Available for those components where optional upgrade kits are available. If you do not see the Upgrade Available status for the component you want to upgrade, then contact your Siebel administrator, because this discrepancy might indicate a configuration problem.
After the administrator corrects the problem, refresh your own view of the Component Upgrades list and reinspect the upgrade status for components that have optional upgrade kits.
In the Component Upgrades list, select the desired upgrade component, and select the check box in the Upgrade column for the desired upgrade component.
Click Upgrade Selected Components.
This will download the upgrade kit, shut down the Developer Web Client application, and start the Upgrade Wizard. After the Upgrade Wizard completes, it will automatically restart the Developer Web Client application. For some Third Party Software upgrade kits, the client computer might shut down and restart.
Log in and, from the Component Upgrades list, verify the Status is Version OK for the desired upgrade component.

Retrieving Required Upgrade Kits

Both Mobile and Developer Web Clients perform a version check during login to a Siebel application. Mobile Web Clients also perform a version check during synchronization.

This topic is part of Retrieving and Installing Upgrade Kits.

If the version check detects that an upgrade is required, then a dialog box appears asking the user whether to upgrade or not. If the user chooses Yes, then the upgrade kit will be downloaded. The following procedures for both the Mobile and Developer Web Clients illustrate this point.

Upgrade kits are not automatically retrieved upon version check. A prompt appears, asking if the user would like to retrieve the upgrade kit. The upgrade kit is downloaded only if the user clicks yes to download the upgrade kit.

The version check verifies the components used by the client configuration; multiple required components can be displayed in the dialog box.

Note: Synchronizing a Mobile Web Client automatically includes copying version information for Siebel Anywhere from the server to the local database. This allows each Mobile Web Client to detect new required and optional upgrades for the client's configuration without waiting for individual database transactions concerning versions to be synchronized.

If the user answers Yes, then every required upgrade kit for the components used by the client configuration is automatically retrieved and the Upgrade Wizard is started.

If the user answers No, then the Developer Web Client starts in read-only mode against the server database, and the Mobile Web Client starts in read-only mode against the local database.

If the user answers No, then the user's session continues in read-only mode against either the local or server database, until the upgrade has been completed. A prompt notifies the user of this status.

While operating in read-only mode, both Developer and Mobile Web Client users can view screens, views and data as usual, but they cannot make changes. Mobile Web Client users can synchronize, but can only download files; they cannot send, receive, or apply database changes. Read-only mode prevents users from corrupting data with an outdated or invalid Siebel application configuration.

Both Developer and Mobile Web Client users exit read-only mode when the Siebel application is restarted following a successful upgrade. At that point, a Mobile Web Client user can perform a full synchronization, sending to the Siebel Server any local database changes that predate the upgrade.

Retrieving Required Upgrade Kits for Mobile Web Clients

If a user starts the Mobile Web Client in read-only mode, then the user is prompted to upgrade at each synchronization session.

The version check for Mobile Web Clients occurs during synchronization. If the version check detects the need for an upgrade, then the user receives a prompt indicating a possible upgrade. The remote user logs in again to synchronize the server and local database.

To retrieve required upgrade kits for Mobile Web Clients

Invoke the Mobile Web Client.
Choose File, then Synchronize, and then Database.
A dialog box appears indicating there is a required upgrade available.
From the dialog box, click Yes and follow the prompts to invoke the Upgrade Wizard.
The Upgrade Wizard will shut down the Siebel client, install the upgrade kit, and automatically restart the client unless there is an error while installing the upgrade kit.
Log in to the Siebel application.
Navigate to the User Preferences screen, then the Component Upgrades view.
Verify that the Status and Current Version columns contain the updated information.

Retrieving Required Upgrade Kits for Developer Web Clients

Retrieving Developer Web Clients is similar to that of Mobile Web Clients, except version checking only occurs during login.

To retrieve required upgrade kits for Developer Web Clients

Start the Developer Web Client.
Logging in will trigger a version check and will prompt for retrieval of a required upgrade kit. If you choose not to upgrade at this time, then you can only operate in read-only mode.
Click Yes.
The Siebel client downloads the appropriate upgrade kits.
After the retrieval is complete, the client invokes the Upgrade Wizard before exiting. After the client exits, the Upgrade Wizard applies the upgrade kits and automatically restarts the client when it is done.
Log in to the Siebel application.
Navigate to the User Preferences screen, then the Component Upgrades view.
In the Component Upgrades list, verify that Status is Version OK.

Starting the Upgrade Wizard

Subscribers use the Upgrade Wizard to install upgrade kits after they are retrieved. This task is a step in Process of Retrieving, Installing, and Testing Upgrade Kits.

The process for invoking the Upgrade Wizard varies by subscriber type:

For Siebel Server subscribers, the Upgrade Wizard is started manually (see Retrieving Upgrade Kits for Siebel Regional Node Servers).
For client subscribers, the Upgrade Wizard is started automatically after an upgrade is retrieved.
The wizard automatically shuts down the Siebel client. It then displays a progress page as it completes the upgrade kit items for the upgrade kits that were retrieved.

Note: The items displayed on the Upgrade Wizard page vary, depending on the number and type of upgrade kits.

When the Upgrade Wizard has successfully installed the upgrade kit, the Siebel client is automatically restarted.

About Client Upgrade Error Recovery

Before beginning the upgrade process, the Upgrade Wizard makes a backup copy of every file affected by the upgrade. If errors are encountered in the upgrade process, then the Upgrade Wizard stops processing. A message indicates that the Upgrade Wizard did not complete successfully and suggests that you examine the log file for details. It also indicates to restart the Siebel application and attempt the upgrade again.

The next time the user restarts the Siebel client, a prompt appears that states that there had been an upgrade in process.

After the user clicks OK, another prompt appears where the user can cancel the upgrade or restart the upgrade from the point of failure. Canceling the upgrade will result in a cleanup. The user will not be able to restart this upgrade.

The Upgrade Wizard functionality includes error recovery for upgrades on individual files, such as Siebel database schema extensions or client configurations. However, rolling back upgrades always requires manual intervention.

Retrieving Upgrade Kits for Siebel Regional Node Servers

Upgrade kits for Siebel Regional Node Server configurations are retrieved automatically by the Siebel Server. These upgrade kits might include a Siebel database schema or user-defined files to be installed with version tracking. This task is a step in Process of Retrieving, Installing, and Testing Upgrade Kits.

For regional databases, the Siebel administrator must take care to distribute the Siebel Database Schema upgrade kit under the correct configuration. The default configuration that ships with Siebel Business Applications is Siebel Regional Server. You can create your own configuration for Regional Node Servers to suit the particular needs of your organization.

For more information about working with the server components used for Siebel Replication Manager, see Siebel Remote and Replication Manager Administration Guide and Siebel System Administration Guide.

Configuring Siebel Regional Node Servers Using the Server Manager GUI

The following procedure describes how to set the correct configuration for Siebel Regional Node Servers using the Server Manager GUI.

To set the correct configuration for Siebel Regional Node Servers

Navigate to the Administration - Server Management screen, then the Servers view.
From the Siebel Servers list, select the appropriate server, and click on the Server Parameters tab.
The Server Parameters list appears.
Modify the parameters as necessary.
Modify the server parameter Upgrade Component to your configuration name. This configuration name can be Siebel Regional Server or the name of your custom configuration.

Configuring Siebel Regional Node Servers Using the Server Manager Command Line

The following procedure describes how to set the correct configuration for Siebel Regional Node Servers using the Server Manager command line.

To set the correct configuration for Siebel Regional Node Servers using command line

From the srvrmgr command line, enter:
srvrmgr.exe /g gateway_srvr_host /e enterprise /s server_name /u user_name /p password
change param UpgComponent="Siebel Regional Server" or "name of your custom configuration"

If the version check recognizes a required upgrade, then the Siebel Server fails to start and logs an error message in the siebsrvr.log or repagent_$taskid.log file similar to the following:

Please contact HQ administrator. An upgrade may be required.

With the Regional Node Server and all tasks stopped, the Siebel administrator must manually invoke the Upgrade Wizard.

Manually Invoking the Upgrade Wizard on Windows

The following procedure describes how to manually invoke the Upgrade Wizard on Microsoft Windows.

To manually invoke the Upgrade Wizard on Windows

Open a command prompt window on the Windows server where the Regional Node Server is installed.
Navigate to the SIEBSRVR_ROOT\BIN directory, where SIEBSRVR_ROOT is the root directory of the Regional Node Server installation.
Copy the file siebupg.exe to another directory, and navigate to that directory.
Execute the copy of siebupg.exe to start the Upgrade Wizard.
Follow the prompts on the wizard pages.
Restart the Regional Node Server.
Repeat the process above on any other Regional Node Server, as appropriate.

Manually Invoking the Upgrade Wizard on UNIX

The following procedure describes how to manually invoke the Upgrade Wizard on UNIX platforms.

To manually invoke the Upgrade Wizard on UNIX

Open a shell on the UNIX server where the Regional Node Server is installed.
Navigate to the SIEBSRVR_ROOT/BIN directory, where SIEBSRVR_ROOT is the root directory of the Regional Node Server installation.
Execute the file srvrupgwiz to start the Upgrade Wizard.
Follow the prompts on the wizard pages.
Restart the Regional Node Server.
Repeat the process on any other Regional Node Server, as appropriate.

If the Upgrade Wizard fails, then an error message is logged. Exit the Upgrade Wizard, correct the condition that caused the error, and restart the Upgrade Wizard using the copy of the siebupg.exe file. Upon restarting, Upgrade Wizard prompts you either to cancel the upgrade, restoring the Regional Node Server to its preupgrade state (if possible), or to retry the upgrade from the point of failure. You must restart the Regional Node Server to initiate a version check to restart the upgrade process. To restart, choose Retry.

The Regional Node Server will be down until you successfully recover from the failed upgrade. This downtime can affect many users. After a successful installation of an upgrade, it will take manual intervention to roll it back.

Testing Upgrade Kits

This topic describes how to test upgrade kits. This task is a step in Process of Retrieving, Installing, and Testing Upgrade Kits.

The recommended method for testing upgrade kits is to create and distribute an upgrade kit to a limited and controlled number of users. In this method, you can assign specific testing users to the Siebel Test Client configuration so your regular subscribers will not be allowed to install any upgrade kits in the testing phase. Distribute the upgrade kit only to the Siebel Test Client configuration. See Using the Siebel Test Client Configuration for Testing.

Caution: When testing new upgrade kits, it is strongly recommended that you perform tests using both Developer and Mobile Web Clients. If for any reason Mobile Web Client users experience problems installing or downloading the new upgrade kit, then the problems will be significant.

After an upgrade kit has been thoroughly tested under the Siebel Test Client configuration, you can then distribute it to the appropriate production configurations.

To optimize the setup process for new users, it is recommended that you create a master installation image for each configuration your Siebel Anywhere subscribers use, and keep these images up to date. If all current upgrade kits are installed to create a current image, then you can use the image to set up new subscribers, so each new subscriber will not need to download and install many upgrade kits. This method also makes it safer to deactivate old upgrade kits, since new subscribers will receive the necessary software by means of installation images, rather than being required to install old upgrade kits.

Note: Siebel Anywhere does not deliver Siebel Database Schema upgrade kits to individual Developer Web Client users, because they connect to shared databases. Test database extensions in the development environment.

Using the Siebel Test Client Configuration for Testing

Siebel Anywhere provides a special configuration called Siebel Test Client to serve as your test user. By default, the Siebel Test Client configuration is representative of the other subscriber configurations initially provided, but it can be modified to reflect your active configuration.

To test an upgrade kit

Create a user and assign this user with the Siebel Test Client configuration in one of the following ways:
- Assign the user to the configuration, as described in Assigning Employees to a Configuration.
- Install a client and set ComponentName to Siebel Test Client in the active CFG file.
Define, activate and apply the upgrade kit as an optional upgrade kit and distribute to the appropriate configuration.
Verify that the Siebel Test Client configuration contains the components being upgraded with the upgrade kit.
Notify the selected users assigned to the Siebel Test Client configuration to log in. Instruct them to use the procedures described in Retrieving and Installing Upgrade Kits to retrieve and install the upgrade kit.
After test users install the upgrade kit, have them test it by running the application that was upgraded.

Have all test users report any unexpected behavior in the application. Give special attention to areas of the application that changed due to the upgrade.

If the test is unsuccessful, then see Troubleshooting for Siebel Anywhere for possible solutions.

Note: If you want to change your optional upgrade kit to be required after testing, then see Converting an Optional Upgrade Kit to a Required Upgrade Kit.

Uninstalling a Delta Patch

Occasionally, as part of testing, troubleshooting, or as preparation before installing a new release, you might want to uninstall the client files associated with a delta patch.

Note: As an alternative to uninstalling a delta patch, you can use the uninstallation methods described in the Siebel Installation Guide for the operating system you are using or in the documentation for the Siebel Patchset release.

Uninstalling a Delta Patch but Retaining Previous Releases

As part of testing or troubleshooting, sometimes you might want to uninstall a single Siebel Innovation Pack release or Siebel Patchset release, while leaving the prior installed release or releases intact. For example, you might want to remove version 17.0, but retain version 8.1.1 and version 8.1.1.7, or retain version 8.2.2 and version 8.2.2.2. You can use the procedure in this topic to uninstall a corresponding delta patch.

Note: Using this method, you can uninstall only a delta patch, not any other type of patch release. A delta patch is software that was installed using a Siebel Anywhere upgrade kit of type Siebel Client Executables with Select Type of Installation set to Delta Install. For more information, see Roadmap for Creating a Delta Installation Siebel Client Executables Upgrade Kit.

The following procedure describes how to uninstall a delta patch.

To remove a delta patch but retain the prior installed release or releases

Navigate to the existing root directory of the client installation (SIEBEL_CLIENT_INSTALL), such as C:\Siebel\Client.
Locate the following directories, which were created when the delta patch was installed:
- PATCHBACKUP_BASE. This folder is for the base portion of the installation that was performed through the delta patch.
- PATCHBACKUP_language-code, where language-code is the code for each language that is used in the client installation. For example, the directory might be called PATCHBACKUP_ENU for U.S. English. This folder is for a language-specific portion of the installation that was performed through the delta patch.
- PATCHBACKUP_language-code, where language-code is the code for each language that is used in the client installation. SIA applies for all Siebel Industry Applications. For example, the directory might be called PATCHBACKUP_ENUSIA for U.S. English. This folder is for a language-specific portion of the installation that was performed through the delta patch.
- PATCHBACKUP_. This folder is for the base portion of the installation, plus all language-specific portions of the installation, that was performed through the delta patch.
In each of the directories that you located rename the file unpatch.bak to unpatch.bat.
In each of these directories, execute unpatch.bat.
Note: The unpatch.bat files can be executed from the various directories in any order.