Web Updates

Once you have distributed your application and have many live copies on the field, inevitably the time will come when you will need to issue updates. These updates may be minor improvements and bug fixes, best served as patches, or full blown major new versions, best served as upgrades.

InstallAware provides a very convenient and customizable mechanism that serves updates directly to end-user desktops, no matter what the size or content of the update. InstallAware implements this Web Update mechanism in its entirety using MSIcode, accessible directly in the script editor. While the pertinent sections of the IDE have been built around the default behavior of the Web Update system, and this document discusses that default functionality, remember that you can always custom tailor aspects of the system, minor or major, to suit your own needs - simply by editing the pre-built dialogs and scripts.

What's in an Update?

InstallAware defines an update as an executable file that is downloaded and run on the end-user system. An update could be a patch, or it could be a full new version. An update could be a setup that doesn't update application binaries at all, but just runs, for instance, a SQL script to refresh a database. An update could even be a document that is opened with the default application it has been associated on the end-user system!

The Update Information File

Updates are defined in Update Packs. An Update Pack consists of the name of the update, its long description, download URL, and other similar attributes. You may serve the same update packs to more than one version of your application. You choose which applications receive which update packs on the Versions page, where you associate particular versions of your application on the field with specific update packs.

Once this information has been provided in the InstallAware IDE, every time you build a setup, an update information file, called updates.ini, will be automatically created in your build folder. This regular INI-format file contains all the information on the various update packs and the application versions that receive them. A copy of this file is also available in the project folder, and may be edited directly. The IDE will display your changes when you manually edit the file.

How Do Updates Work?

The first step in enabling your application to receive updates is to check the Receive Application Updates box in the Project Properties page, and specify your update information URL in the Monitor URL field (this URL should serve the update information file mentioned above). The IDE then does the following:

• Adds pre-built update dialogs to your setup project,
• Adds the pre-built update script to your setup project,
• Calls the pre-built update script from your main setup script.

You may, of course, customize both the pre-built dialogs and the update script using the Dialog Editor and the script editor. Nothing is hard coded, and even though the base dialogs and update script cover most usage scenarios and work out of the box, they are still fully extensible to suit your own requirements and update scenarios.

Web Update Modes

InstallAware provides three built-in web update modes as of version 15:

Automatic Web Updates

Your setup performs these additional tasks while installing your application:

• Checks if any web updates are available.
• If any web updates are found, they are all are downloaded with progress display visible to the end-user.
• The end-user is not presented with a choice regarding which of the updates to install - all of them are installed.
• The original setup does not install at all if any web updates are found.
• The original setup does install only when web updates are unavailable.
• A shortcut is created in the Start Menu program group for the application which enables on-demand update checking once setup has installed your application.
• Running the web update shortcut presents the end-user with the opportunity to download and install any further updates, with the ability to choose the updates that are downloaded and installed.
• When setup is running in maintenance mode (repair, change, or uninstall), even if any web updates are available, they will not be downloaded or installed - this helps your end-user uninstall your application without having to update it first.

Because of the above workflow, when you are designing your update packs for your various application versions under the automatic web update mode, it is recommended that you only serve the latest version full installer of your application for each of your old versions, and that you serve that installer in non-silent (interactive) installation mode. This ensures that any time any version of your setup is run, the latest version will dynamically download and execute interactively, as long as an Internet connection is available. The only possible exception to this rule could be if you wish to bundle one or more applications with your main application; in this case you would define additional update packs for the bundled applications and install them (possibly silently).

In the automatic web update mode, unless setup is running in maintenance mode, it will not keep a history of updates that were previously installed. This ensures that only the latest version of your application will be made available at all times.

Once your application has been installed and updates are checked for manually, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they already installed.

Manually Triggering Update Checks

To explicitly run setup in web update mode once your application has been installed, for instance in response to a menu item in your main application user interface, you may use the following command line:

<setup.exe> /update

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update check" mode.

Manual Web Updates

Your setup performs these additional tasks while installing your application:

• A shortcut is created in the Start Menu program group for your application which enables on-demand update checking once setup has installed your application.
• Running the web update shortcut presents the end-user with the opportunity to download and install any updates, with the ability to choose the updates that are downloaded and installed.

Since the above workflow allows end-users to choose which updates they download, you may elect to serve full version installers, patches, or any other custom executable/process/document as your updates when using manual web updates.

In the manual web update mode, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they had already installed.

Triggering Update Checks

To explicitly run the web update client, for instance in response to a menu item in your main application user interface, you may use the following command line:

<setup.exe> /update

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update check" mode.

Scheduled Web Updates

Your setup performs these additional tasks while installing your application:

• During installation, an additional registry key is written to run setup once in "update scheduler" mode.
• On the next logon of the user, setup runs in "update scheduler" mode. This mode allows the end-user to configure a schedule to check for updates online. The user can also elect to not receive updates at all. If the user does choose a schedule, the Windows Task Scheduler is used to create a new task that runs setup in "update" mode at the desired interval.
• The Windows Task Scheduler starts setup in "update" mode at the scheduled time. Setup connects to the URL specified in the Monitor URL field of the Project Properties page to download the update information file.
• If the file is successfully downloaded, setup continues running in "update" mode and first downloads, then installs the available updates. The user may be prompted during the process in accordance with the preferences set in the "update scheduler" mode.
• Updates that have been previously installed for an application version are not installed again, even if the application version has not changed between updates.

Since the above workflow allows end-users to choose which updates they download, you may elect to serve full version installers, patches, or any other custom executable/process/document as your updates when using manual web updates.

In the scheduled web update mode, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they had already installed.

Re-Triggering Update Scheduling

Because end-users have only one opportunity to schedule web updates with the above workflow, and will not be presented with another opportunity should they cancel the scheduling at that first time; you may wish to manually launch setup in update scheduler mode once your application has been installed (for instance, from a menu item available in your primary application user interface).

To enter the "update scheduler" mode, you may use the following command line:

<setup.exe> /updatesetup

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update scheduler" mode.

Enabling Scheduled Web Updates with the Native Code Setup Engine

If you are using the Native Engine to install your application, you will need to explicitly enable the Native Engine installation mode in the update script by following the steps below:

1. Switch to the MSIcode view.
2. Switch to the Updates tab in the MSIcode editor. This tab displays your fully customizable web update script.
3. Comment-in (enable) line number 8: Set Variable NATIVE_ENGINE to TRUE.
4. Please keep in mind that the line number above may vary if you have customized your web update script.

Customizing the Web Update Script

You may fully customize the web update script (and dialogs) to inject your business logic - filtering updates that are served by your product editions, languages, subscription status, and more. Please keep the following in mind when editing the update script.

The following variables control some high level behavior in the update script:

• UPDATE_DOWNLOAD: Set to TRUE to offer a list of updates that are available for download, set to FALSE to automatically download all available updates.
• UPDATE_AUTO: Set to TRUE to automatically install updates, set to FALSE to offer a list of downloaded updates ready for installation.
• UPDATE_LOG: Set to TRUE to filter out previously installed updates from the list of available updates (even if their installation failed or was cancelled), and to record the list of updates that were installed (even if their installation failed or was cancelled). Set to FALSE to always present all available updates, and to never record updates that were previously installed.

The compiler variable UPDATE_SCHEDULING conditionally compiles the update script according to the corresponding web update mode:

• TRUE: Scheduled web update mode.
• FALSE (or undefined): Manual web update mode.
• THIRD: Automatic web update mode.