Upgrading AAI in Automated Mode (Headless Upgrader - UNIX)

The headless upgrader enables you to automate an upgrade for an AAI installation. It is available for UNIX operating systems only, and it allows you to invoke an AAI upgrade on the command line or as part of a script to run in automated (headless) mode. Since the automated mode requires no on-screen prompting, it gives you the following advantages:

• You can run it on a pure UNIX server.

• You can add the upgrade command as part of an overall automated upgrade process to efficiently roll out AAI updates over your organization.

Overview

To perform an automated upgrade of AAI, you basically do the following

1. Prepare an upgrade.properties file with all the necessary parameters and put it in the required directory.

2. Invoke the headless upgrader from either the command line or as part of a script. You use the -a switch in the command to run the installer in automated (quiet) mode, which means that you will not get any prompts during the installation.

3. Check for database schema upgrades and install them.

The steps for each of these phases are described in this topic.

Prerequisites and Preparation

To ensure a successful upgrade of the AAI installation in automated mode, make sure to review the prerequisites and preparation steps described here.

Prerequisite

Make sure that you have at least 1 GB available space on the virtual machine or server where your current AAI installation resides.

Prepare the upgrade.properties file

Use the steps that follow to create an upgrade.properties file, and then configure it for your database management system. The upgrader takes the necessary input from this file. You must create this file from scratch; there is no default or template for it. Later, you will move this file to the folder required by the upgrade process.

1. Create an <properties_file_folder>/upgrade.properties file in a location, preferably outside the installation, where you can retrieve it for this and future upgrades. For example, /home/aai/aai_upgrader_properties/upgrade.properties.

2. Configure it for your database management system, as described in the following table

   Property	DBMS	Value	Description
   jaws.existing.dir	SQL Server / Oracle	Example: /opt/Automation_Analytics_Intelligence	The full path to the AAI installation directory.
   jaws.upgrade.auto	SQL Server / Oracle	true	The flag for the automated upgrade. It effectively suppresses all the pop-ups and prompts. This must be defined here and set to "true" for the upgrade to work.
   oracle.data.device.name	Oracle only	Example: AAI_PROD_DATA	The name of the Oracle tablespace where the AAI data is stored.
   oracle.index.device.name	Oracle only	Example: AAI_PROD_INDICES	The name of the Oracle tablespace where the AAI index data is stored.

Example upgrade.properties file for SQL Server

jaws.existing.dir=/opt/Automation_Analytics_Intelligence

jaws.upgrade.auto=true

Example upgrade.properties file for Oracle

jaws.existing.dir=/opt/Automation_Analytics_Intelligence

jaws.upgrade.auto=true

oracle.data.device.name=AAI_PROD_DATA

oracle.index.device.name=AAI_PROD_INDICES

Upgrading AAI in Automated Mode

The automated mode (headless) installation lets you install AAI without the setup wizard and without prompts to enter property values. Instead, the upgrader accesses the upgrade.properties file that provides the required values. For more information about the properties and values in this file, see Differences to a Non-Automated Upgrade.

Follow these steps:

1. Download the relevant AAI product or solution. For more information, see Downloads.

2. Extract the necessary files.

   1. Extract the upgrade zip file into a temporary <upgrade_bundle_dir> directory (for example, /tmp/aai_upgrader).

   2. Unpack the tar.gz file.  

3. Copy the <properties_file_folder>/upgrade.properties file that you prepared before starting these steps to the <upgrade_bundle_dir>/install/properties directory. For information, see Prerequisites and Preparation.

4. Shut down the AAI server. The upgrade will not execute if the server is running.

   For information, see Stopping, Starting, Restarting the AAI Server.

5. From the <upgrade_bundle_dir> directory, run the following command: ./upgrade.sh –a

   The script detects your current version and, if there are intermediary versions before the version that you downloaded, the script upgrades those as needed until it ends with the current version. This allows you to upgrade over several versions in one step.

   Note:

   The -a switch indicates that this is to be run in automated mode. Without it, a headful GUI installation executes.

   When the upgrade completes successfully, you get a stdout message to that effect, and the upgrade ends with error code 0 (zero).

6. If you get a message that the upgrader has failed and you get an error code other than 0, check the <upgrade_bundle_dir>/install/log/upgrade.log to find out what the error was, then make the required changes and re-run the upgrade script.

   For information about the most common errors, see Examples of Failed Upgrades with Errors.

7. Check for database schema updates and install them as required.

   Important!

   You must check for these manually, as described here. There is no message provided to stdout or to the upgrade.log

   1. Open the scripts directory of your AAI installation, for example, /opt/Automation_Analytics_Intelligence/scripts/.

   2. If you see an upgradeJawsDbTo<version>.sql file for your new version, then open it to find out which database schema updates need to be applied, and apply them.

8. Restart AAI. For information, see Stopping, Starting, Restarting the AAI Server.

Examples of Failed Upgrades with Errors

When the upgrade fails, you get a message to that effect, and the script ends with an error code other than 0 (zero).

To find out the reason for the failure, open the <upgrade_bundle_dir>/install/log/upgrade.log file and look for the final error code. The following are the most common reasons that the automated upgrade fails:

• An invalid AAI installation directory path

• AAI is running

• Insufficient disk space

The following are examples of what you can see in the output with stdout and in the <upgrade_bundle_dir>/install/log/upgrade.log for each of these common fail reasons, as well as the corrective action in each case.

Example: Failure Because of an Invalid AAI Installation Directory

stdout output

Executing Automation Analytics & Intelligence upgrade to version 6.5.3

Automation Analytics & Intelligence upgrade has failed. For details, please look at the log files in the "/tmp/aai_upgrader/install/log" directory.

Entries in the <upgrade_bundle_dir>/install/log/upgrade.log

[java] 16:02:33.227 INFO [upgrade.main.UpgradeParameters] upgrade properties file is /tmp/aai_upgrader/install/properties/upgrade.properties

[java] 16:02:33.240 ERROR [upgrade.main.SelectJawsInstallationMain] Error getting http port number to check if server is running.

Corrective action

Revise the upgrade.properties file in the <upgrade_bundle_dir>/install/properties directory and correct the path entered for the jaws.existing.dir property. Then re-run the script.

Example: Failure Because AAI Is Running

stdout output

Executing Automation Analytics & Intelligence upgrade to version <New Version>

Automation Analytics & Intelligence upgrade has failed. For details, please look at the log files in the "/tmp/aai_upgrader/install/log" directory.

Entries in the <upgrade_bundle_dir>/install/log/upgrade.log

[java] 12:50:53.836 WARN [upgrade.main.SelectJawsInstallationMain] The Automation Analytics & Intelligence (AAI) server is running--this will prevent the upgrade from completing successfully. Please stop the AAI server before continuing.

[java] 12:50:53.836 DEBUG [upgrade.main.SelectJawsInstallationMain] server is apparently running--port 8080 is in use.

[java] 12:50:53.837 ERROR [upgrade.main.SelectJawsInstallationMain] Upgrade failed.

Corrective action

Stop the AAI server, and then re-run the script.

Example: Failure Because of Insufficient Disk Space

stdout output

Executing Automation Analytics & Intelligence upgrade to version 6.5.3

Automation Analytics & Intelligence upgrade has failed. For details, please look at the log files in the "/tmp/aai_upgrader/install/log" directory.

Entries in the <upgrade_bundle_dir>/install/log/upgrade.log

[java] Unable to proceed with upgrade.

[java] Directory /opt/Automic_Analytics_Intelligence needs at least one gigabyte of free space but has only 204 MB available

[java] Directory /tmp/aai_upgrader/install/backup needs at least one gigabyte of free space but has only 204 MB available

Corrective action

Free up at least 1GB space on the virtual machine that you are running the upgrader on, and then re-run the script.

Differences to a Non-Automated Upgrade

If you are used to performing a regular, non-automated upgrade, or you want help deciding which approach is better for you, here are some key differences from the automated upgrade to the non-automated upgrade.

• The automated upgrade is only available for a UNIX operating system.

• Because you are not prompted to confirm any required values, the upgrade.properties file must have all the required properties and the values must be correct. For example, the AAI installation directory must be correct, otherwise the upgrade will fail.

• You are not prompted for telemetry options. The telemetry settings are assumed to be the same as in the current installation. If you want to make changes to those settings, after the upgrade is complete, make the changes on the Telemetry tab of the AAI Configuration Tool. For information, see Configuration Tool - Telemetry Tab.

• There is no prompting or displaying of a created DB schema update script. You need to check the scripts directory of the AAI installation. This is described in the upgrade steps.

• For Oracle DB environments: The tablespace names provided in the upgrade.properties file will be used in any <aai_installation_directory>/scripts/upgradeJawsDbTo<version>.sql created by the upgrade. You should review this file for accuracy before running it against the AAI database.

• You will not be prompted for the README file. If you want to see it, you can find it in the unpacked upgrade directory.

See also:

• Installation and Upgrade (with a System Overview)

• Upgrading AAI

• Stopping, Starting, Restarting the AAI Server