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.

General Upgrade Overview

When upgrading the AAI server and connectors with a new release package, you perform the following tasks:

1. Do all preparation steps and make sure all prerequisites are fulfilled.

   For information, see Preparing for the AAI Upgrade.

2. Take down the connectors that you want to upgrade.

   For information, see the topics related to your connectors under Connectors.

3. Upgrade and start your AAI system, as described in this topic, starting with Overview of an Automated Upgrade and to the end.

4. Upgrade and start each connector.

   Again, for information, see the topics related to your connectors under Connectors.

This topic covers only the steps related to C. Upgrade and start your AAI system. Use the links in the previous overview for instructions for the other tasks.

Overview of an Automated Upgrade

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.

Important Considerations Before Upgrading to V24.0.0 or Higher

If you are upgrading from an AAI version 6.x.x to version 24.0.0 or higher, and you or your users have Client or Insight reports, these will be lost. For more information, see Considerations When Upgrading to v24.x.x from v6.x.x before continuing.

Also note that there is an additional property in the upgrade.properties file, jaws.upgrade.caution.reviewed, to indicate whether you acknowledge that after the upgrade, these reports will no longer be accessible. To prevent you from unintentionally losing those reports, the upgrade will not run unless this property exists and is set to true.

If you have used the headless upgrader with a previous upgrade, and want to use the same upgrade.properties file, make sure to add the new parameter. For more information, see the table in the following prerequisites section.

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

   Important for V24!

   If you are using an upgrade.properties files from a previous upgrade, note that with V24.0.0 there is a new property that you need to add to make the upgrade work: jaws.upgrade.caution.reviewed

   Property	DBMS	Value	Description
   jaws.existing.dir	SQL Server / PostgreSQL/ Oracle	Example: /opt/Automation_Analytics_Intelligence	The full path to the AAI installation directory.
   jaws.upgrade.caution.reviewed	SQL Server / PostgreSQL/ Oracle	false	The flag to indicate whether the caution for upgrades from a v6.x.x to a v24.x.x that Insight reports will be deleted has been taken into account. If this is set to false, the upgrade will break and messages to that effect are added to the [AAI_Installation]/log/upgrade.log file. See Considerations When Upgrading to v24.x.x from v6.x.x.   If you have reviewed the warning and want to proceed, set this to "true".
   jaws.upgrade.auto	SQL Server / PostgreSQL/ 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 when using an SQL Server or PostgreSQL database

jaws.existing.dir=/opt/Automation_Analytics_Intelligence

jaws.upgrade.caution.reviewed=true

jaws.upgrade.auto=true

Example upgrade.properties file when using an Oracle database

jaws.existing.dir=/opt/Automation_Analytics_Intelligence

jaws.upgrade.caution.reviewed=true

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

• 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: V24 Failure Because the Flag to Continue and Delete Reports Is Set to False

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:44:36.886 INFO [upgrade.main.Upgradeparameters] upgrade properties file is /[AAI_Installation]/product/upgrade/build/upgrade-2' -SNAPSHOT/install/properties/upgrade.properties

[java] 12:44:36.919 ERROR [upgrade.main.SelectJawsInstallationMain] Upgrade failed.

[java] java.lang.Exception: The parameter jaws.upgrade.caution.reviewed must be ’true' to run a headless upgrade.

Corrective action

If you want to proceed with the upgrade from a v6.x.x to a v24.x.x, which will also delete all Insight reports in your installation, then in the upgrade.properties file in the <upgrade_bundle_dir>/install/properties set jaws.upgrade.caution.reviewed=true. Then re-run the script. If you do not want to lose your Insight reports,

Example: Failure Because of an Invalid AAI Installation Directory

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] 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 <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] 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.

• Because you are not prompted to confirm any required values, when you upgrade to v24.x.x from a v6.x.x version, you must indicate in advance in the jaws.upgrade.caution.reviewed property of the upgrade.properties file that it is OK to continue with the upgrade and delete all Insight reports as part of the upgrade. In the non-automated upgrade, you are prompted.

• 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.

Post V24 Upgrade Considerations

If you upgrade from an AAI version 6.x.x to version 24.0.0 or higher, after fully upgrading your production environments, you can remove the Jasper server that you used to need to produce previous AAI client and Insight reports.

In addition, please note that having a second mirroring historical database is no longer needed. That recommendation was based on the performance impact on daily processing of job and jobstream events of calls from the external JasperSoft server. Now that everything is integrated within AAI, this is no longer an issue. Therefore, you can discontinue mirroring the historical data.

See also:

• Installation and Upgrade (with a System Overview)

• Upgrading AAI in Non-Automated Mode

• Stopping, Starting, Restarting the AAI Server