How you upgrade your Acoustic™ Tealeaf environment depends on whether you are upgrading only existing components, reconfiguring existing components, or adding or migrating components within your current environment. You can also automate the upgrade by running a silent upgrade.

• To upgrade a Tealeaf component currently installed in your network, run the Upgrader.

• To add new components to your network, or to reconfigure existing components, you must run the Installer.

• To automate the upgrade process, perform a silent upgrade

For each method, you must repeat the process on each server that hosts Tealeaf components.

Stop traffic at each canister

When you are satisfied that all preparations are complete and you are ready to begin, you must stop traffic to the processing servers in your environment and allow the Data Collector to complete data collection on the stopped Canisters.

You can begin the upgrade after traffic stops and the Data Collector completes a run.

When traffic is stopped to the canister pipeline, data is spooled to disk. Each processing server should have sufficient disk space to queue for 30 minutes.

Note: If all available disk space is consumed, hits that are forwarded to the canister are dropped.

Note: In a Health-based Routing (HBR) environment, there is no need to stop traffic. As soon as a processing server is no longer available to receive hits, traffic is diverted to other available processing servers or spooled locally to the HBR disk until servers become available.

1. Open the following URL in your web browser: http://<Machine_Name>:19000

   where <Machine_Name> is the name or IP address of the processing server

2. The Search Server web interface is displayed.
3. In the Governor pane at the lower left, click Drain STC. This step forces the pipeline to start queuing data and instructs the Short Term Canister (STC) to write out any active sessions to long-term storage.
4. Repeat the steps for each processing server before you check for Data Collection completion.

After traffic stops and immediately before you begin to upgrade platform and core applications, verify that the latest Data Collector run is complete.

Note: If the Data Collector run is not allowed to complete, there will be gaps in your reporting data after the upgrade is complete.

Remove non-global canister spool files

Acoustic Tealeaf environments that do not have Enhanced International Character Support (EICS) are considered non-global environments. You cannot migrate canister spool files from a non-global environment to a global environment. You must remove all non-global canister spool files before you upgrade.

Verify that the last run of the Data Collector is complete.

EICS support is introduced in Tealeaf version 9.0.2A.

If you are upgrading to Tealeaf Version 10.0 from Version 9.0.2A, you can skip this procedure. You do not need to remove the spool files.

However, if you are upgrading to Tealeaf Version 10.0 from Version 9.0.2 (a non-global version), you must remove all existing spool files before you begin the upgrade. By default, spool files are written to \<Tealeaf_install_directory>\spool.

1. Go to the directory where the spool files are saved in your Tealeaf environment. In the Portal, you can verify the location of the spool directory.
   1. Log in to the Portal.
   2. Go to Tealeaf > TMS > Worldview
   3. Select Transport Service > Transport Service configuration.
   4. In Config Actions, click View/Edit (Raw).
   5. In the [DecouplEx] section, the value for SpoolDir is the path to the spool directory.
2. Delete the canister spool files.

   Canister spool files have the .tsp file extension.

Running the Upgrader to upgrade existing components

You must run the Acoustic Tealeaf Upgrader to upgrade Tealeaf services that are currently deployed on an individual server. Run the upgrade separately on each server in your Tealeaf environment.

Use the Upgrader to perform a simple upgrade of existing components on an Tealeaf server. However, to add or change Tealeaf components on a server, use the Installer.

Avoid using localhost entries in the Upgrader. Instead, use a host name or fully qualified domain name. Entries that use localhost can corrupt Tealeaf portal features in the upgraded system, particularly for the Report Server. Remove all such references in the entries on the portal management page before you begin the upgrade.

Note: You can specify UNC paths in the Upgrader only if each path references a location on the local machine.

1. Back up the contents of the Tealeaf install directory on the server. Save to a different hard disk drive or different machine.

   Back up Tealeaf databases with SQL Server administration tools, as described in the SQL Server product documentation for your installation.

   If you receive an error that indicates that TLREPORTS_EVENTDATA is being used by another user, the Tealeaf databases are installed within the Tealeaf install directory. You must stop the following service through the Administration console: SQL Server (MSSQLSERVER). Then, run the copy. After the copy is completed, restart the SQL Server services.

2. From the Tealeaf distribution, copy the following directory to the machine where the upgrade is to be completed. Do not copy to the Tealeaf install directory:

   
   <software_distribution_directory>\cx\Upgrade_*
   

3. Verify that the current run of the Data Collector is complete. If it is open, close the Windows™ Event Viewer Control Panel.
4. Open a command-line shell. Navigate to the directory where you stored the upgrade distribution.
5. From the upgrade directory, run TLsetup.exe.

   If prompted for the Tealeaf Management Server (TMS) server at any point during the upgrade process, enter the machine name of the TMS master.

   1. Select the language that you want to use for the installation and click OK.
      The Upgrader checks to see whether an upgrade performed on the machine already. If so, the following message is displayed.

      
      An update has already been performed on this system.
      

   2. If the server you are upgrading is a Report server, extra dialogs may be displayed, including one in which you might choose to perform an event data migration to the new version or a migration of all data.

      Migration of all of your existing data can take significant time. If possible, perform this migration during off-peak hours through the Tealeaf Database Manager.

      During the upgrade of the Report server, you might choose to migrate reference dimensions and their data. This data is not migrated by default.

   3. On the Welcome screen, click Next to proceed to the Upgrade screen, which displays the list of components to upgrade. Click Yes to proceed.

      If your pre-upgrade system does not include Acoustic Tealeaf cxReveal, the Upgrader prompts you to choose to install this product.

      If your pre-upgrade system does not include a tracking service, the Upgrader displays a window asking if you want to configure the tracking service. The tracking service tracks Replay server logging information and delivers the logging data to Browser Based Replay (BBR).

   4. Configure the tracking service if administrators need access to real-time page load logging information in BBR. The Upgrader presents a configuration window in which you specify a server and port. The server and port information you enter is applied to the common registry used by Acoustic Tealeaf servers.

      Note: The registry is still available inside the tracking service component, but other services look at the same registry location.

   5. The upgrade process begins, during which the following occurs:
      • Install the Microsoft™ Redistributes.
      • Transfer files.
      • The Canister is rebuilt, while preserving session data. This process can take 5-10 minutes to complete. While this process is occurring, you can restart the other Canisters in the environment.

        Note: If you are upgrading the Portal Server, the Upgrader automatically disables the Interactive Services Detection service, which causes conflicts with the BBR rendering instances.

      On the Finish screen, clear the option to start Tealeaf Services and click OK/Done.

6. Restart the Windows server.

   The Data Collector resumes collection automatically. When the server restarts, check the Event Log for Error-type messages. Ignore error messages that state failure to connect to the TMS Master.

Changing components with the Installer

To add or change Tealeaf components, you uninstall all current components and then reinstall the new components with the Tealeaf Installer.

If you plan to add or change Tealeaf components on a server, use the Tealeaf Installer to make the additions or changes, as described in this procedure. However, if you want to perform a simple upgrade of all existing components on a Tealeaf server, use the Upgrader.

If you are uninstalling and reinstalling Tealeaf software on a server that hosts the Report Server, the Tealeaf databases are uninstalled and reinstalled as part of the process. Before you begin, run or verify a current backup of the Tealeaf databases.

1. Back up the Tealeaf directory, including the installation directory. Mirror the entire server, if possible.
2. Before you begin, identify the components that are going to be installed on this server. Select from the following available components:
   • CX Components - base Tealeaf CX Impact platform
   • Transport Service
   • Processor Service
   • Report Server and Portal Application
3. Download the Tealeaf CX Impact zip file from the distribution.

   Extract it in a directory on the server that is not within the Tealeaf installation directory.

4. Stop all Tealeaf services, including the ones that cannot be stopped through the menu.
5. From the downloaded package, run TLsetup.exe. When prompted, click Uninstall.
   The uninstall is completed.
6. Rerun TLsetup.exe.

Automating the upgrade process

You can automate the upgrade process by performing a silent upgrade. You performs a silent upgrade from the command line or with a .ini file.

Before you perform a silent upgrade, identify the parameters and values that you want to specify on the command line or in the .ini file that you want to use.

You can run the upgrade in either of two ways. You can run the upgrade and upgrade the database at the same time or you can run the upgrade without upgrading the database.

If the Tracking Service is installed, the following parameters are ignored during the upgrade:

• TRACKINGHOST
• TRACKINGPORT
• TRACKINGSERVICECONFIGURE

1. Log in to the server where you want to upgrade Tealeaf CX.
2. From the command line, run TLsetup.exe with parameters.

   Enter parameters for the type of upgrade you want to perform.

   1. To run an upgrade and upgrade the database from the command line, enter the TLsetup.exe installation command and the parameters on the command line. For example, you might use this command:

      "C:\src\current\Installations\Upgrade_MSI\PROJECT_ASSISTANT\Upgrader_MSI\DiskImages\DISK1\TLsetup.exe" /s /v"/qn"

   2. To run an upgrade Tealeaf CX without upgrading the database, enter the TLsetup.exe installation command and the parameters that you want to use. For example, you might use this command:

      "C:\src\current\Installations\Upgrade_MSI\PROJECT_ASSISTANT\Upgrader_MSI\DiskImages\DISK1\TLsetup.exe" /s /v"/qn DBUPGRADEOPTION=2"

If you encounter problems during the upgrade, do not attempt to run the Upgrade again. Running the Upgrader more than once corrupts the system.

Do not attempt to manually manipulate data files to resolve upgrade issues.

If event definitions do not successfully migrate during upgrading of the Report Server, Processing Servers cannot be restarted, and they continue to spool data. To prevent filling the spool space on disk and dropping of hits, this issue should be addressed as soon as possible.

Review the following logs for ERROR or _E_ entries:

• Tealeaf Installation and Upgrader log: <Experience Analytics_install_directory>\Logs\TeaLeafInstall_BBBB.log
• Event Manager log: <Experience Analytics_install_directory>\Logs\TLEventManagerYYYYMMDD.log
• Tealeaf Database Manager log: <Experience Analytics_install_directory>\Logs\TeaLeafDatabaseManagerYYYYMMDD_*.log