Supporting Downloadable Updates for an Advanced UI or Suite/Advanced UI Installation

InstallShield 2019

Project • This information applies to the following project type:

Suite/Advanced UI

Edition • The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.

Depending on whether an Advanced UI or Suite/Advanced UI installation is running in install mode or maintenance mode, the installation has the ability to check for an updated Advanced UI or Suite/Advanced UI setup launcher that you host on your Web site, and either download it or give end users an option to download it:

If the installation is running in install mode, it automatically checks for an updated Advanced UI or Suite/Advanced UI setup launcher that you host on your Web site. If an update is available, the installation downloads and launches it.
If the installation is running in maintenance mode, it checks for an updated Advanced UI or Suite/Advanced UI setup launcher that you host on your Web site. If an update is available, the maintenance wizard page that the installation displays includes an Update button. If the end user clicks that button, the Suite engine downloads it and launches it.

Requirements and Recommendations for Supporting Downloadable Updates

If you want to include support for downloadable updates in your Advanced UI or Suite/Advanced UI installations, the following guidelines are recommended when you are preparing your base setup launchers and your update setup launchers for your Advanced UI or Suite/Advanced UI projects.

Decide the URL that you will use for hosting a metadata file called isupdate.xml file.

At build time, InstallShield creates this isupdate.xml file and places it in an UpdateMetadata subfolder in your project’s build folder. This isupdate.xml file identifies the different versions of your Advanced UI or Suite/Advanced UI installation and their download locations. You can update this file manually as needed before uploading it to your site.

You will need to specify an update URL path in your base Advanced UI or Suite/Advanced UI project.

When you are ready to release an update, upload the isupdate.xml file and your update to your site.
At a minimum, the update setup launcher must be digitally signed. For the best end-user experience, the same digital signature should be used to sign the update setup launcher and the base setup launcher.
When you are configuring the Advanced UI or Suite/Advanced UI project for the update setup launcher, the run-time location of the packages must be either extracted from the setup launcher or downloaded from the Web. The update setup launcher cannot rely on packages that are stored on the source media.

Note that your base setup launcher can use packages that are stored on the source media.

For instructions on how to specify the run-time location for specific packages in an Advanced UI or Suite/Advanced UI project, see Specifying a Run-Time Location for a Specific Package in an Advanced UI or Suite/Advanced UI Project.

Note that you can override the run-time location for all packages in an Advanced UI or Suite/Advanced UI project. To learn more, see Specifying the Run-Time Location for Advanced UI or Suite/Advanced UI Packages at the Release Level.

The Advanced UI or the Suite/Advanced UI installation must have an Add or Remove Programs entry. For more information, see Add or Remove Program Entries for an Advanced UI or Suite/Advanced UI Installation.
The Suite GUID in the update Advanced UI or Suite/Advanced UI project must match that in the base project. This setting is in the General Information view.

Enabling Downloadable Update Support

To enable downloadable update support to a base Advanced UI or Suite project:

1. Open the Advanced UI or Suite/Advanced UI project for which you want to enable future downloadable updates.
2. In the View List under Media, click Releases.
3. In the Releases explorer, select the release that you want to configure.
4. On the Updates tab, in the Enable Updates setting, select the appropriate value:
No—Disable the Downloadable Updates.
Yes—Enable the Downloadable Updates.

Configuring a Newer Version of Downloadable Updates

To configure downloadable update support for a newer version to a base Advanced UI or Suite project:

1. Open the Advanced UI or Suite/Advanced UI project.
2. In the View List under Media, click Releases.
3. In the Releases explorer, select the release that you want to configure.
4. On the Updates tab, in the Prompt User setting, select the appropriate value:
Force Install—The end users can forcibly download and install the new version of the Suite package (if available).
Prompt User—The end users receive an option to either download a newer version or skip and proceed with the current installation process.

Configuring a Prompt Message

To configure a prompt message for a newer version to a base Advanced UI or Suite project:

1. On the Updates tab, in the Prompt Message setting:
Either enter the message you want to show the end users.
Or click the ellipsis button (...) to create a new message or select a message from the localized available list of strings.

2. On the Updates tab, in the Prompt Message setting, click the ellipsis button (...) that displays the Select String dialog.
3. On the Select String dialog, click New to create a new string and click OK.

Note • The end users will see this prompt message with ‘Yes’ and ‘No’ options to download a newer version or skip and proceed with the current installation process.

Adding Downloadable Update Support

To add downloadable update support to a base Advanced UI or Suite project:

1. Open the Advanced UI or Suite/Advanced UI project for which you want to enable future downloadable updates.
2. In the View List under Media, click Releases.
3. In the Releases explorer, select the release that you want to configure.
4. On the Updates tab, in the Update URL setting, enter the absolute path URL (starting with either http:// or https:/) that you want to use for the future path to the update setup launcher that you will make available for download to target systems.

The isupdate.xml file will need to be uploaded to the same path that you specify in the Update URL setting. For example, if the value of the Update URL setting is http://MyWebSite.com/path/setup.exe, the metadata URL would need to be http://MyWebSite.com/path/isupdate.xml.

Note that you can override the location of the setup launcher that you specify in the Update URL setting by specifying the appropriate path in the isupdate.xml file. However, the isupdate.xml file must be present in the same folder as the .exe file that you specify in the Update URL setting. Otherwise, the downloadable update will not be available to end users.

5. On the Signing tab, it is recommended that you enter digital signature information and configure the release to sign the Setup.exe launcher.

Preparing Setup Launcher

To prepare an update setup launcher for an Advanced UI or Suite/Advanced UI project:

1. Open the Advanced UI or Suite/Advanced UI project that you want to update, and update it as necessary.
2. In the View List under Media, click Releases.
3. In the Releases explorer, select the release that you want to configure.
4. On the Signing tab, enter digital signature information and configure the release to sign the Setup.exe launcher. It is recommended that you use the same digital signature that was used to sign the base Setup.exe launcher.
5. Build the release.

InstallShield creates the isupdate.xml file and places it in an UpdateMetadata subfolder in your project’s build folder. The XML file contains an element such as the following to identify different versions and locations of your Advanced UI or Suite/Advanced UI installation:

<Update Url="http://www.mysite.com/MyProduct/Setup.exe" Version="1.00.0000" Id="{8E23F36C-5EA8-475D-8EAE-09FA36103975}"/>

You can edit the file as needed before uploading it to your site.

For example, if you want to change the path to the update setup launcher after launch, you can change the value of the Url attribute and then reupload the isupdate.xml file to the designated location.

If you interested in using the same isupdate.xml file to define the upgrades for multiple products, you can add the Update element for each of your products to that file.

6. Upload the isupdate.xml file and the update setup launcher to your site.

Run-Time Behavior for Downloadable Updates

The run-time behavior for an installation that includes support for downloadable updates varies, depending on the mode in which the installation is running.

Install Mode Behavior

If the base Advanced UI or Suite/Advanced UI setup launcher runs in install mode, the setup launcher checks for the isupdate.xml file in the update URL path:

1. If the isupdate.xml file is present and it references a newer version of the installation that is available in the specified path, the base Advanced UI or Suite/Advanced UI setup launcher downloads it automatically and then verifies its digital signature.
2. If the isupdate.xml file does not include a reference to a newer version of the installation, or if the isupdate.xml file is not present, the Advanced UI or Suite/Advanced UI setup launcher checks for a download in the update URL path that was configured in the base project. If the download is available, the base Advanced UI or Suite/Advanced UI setup launcher downloads it automatically and then verifies its digital signature.
3. If a download is not present in the update URL path that was configured in the base project, the base Advanced UI or Suite/Advanced UI setup launcher continues without downloading any updates.

Maintenance Mode Behavior

If the Advanced UI or Suite/Advanced UI setup launcher runs in maintenance mode, the Advanced UI or Suite/Advanced UI setup launcher checks for the isupdate.xml file in the update URL path:

1. If the isupdate.xml file is present and it references a newer version of the installation that is available in the specified path, the installation sets the ISUpdateAvailable property to 1 and displays the MaintenanceUpdateWelcome wizard page—a maintenance wizard page that includes an Update button. In addition, the installation sets the ISUpdateVersion property equal to the version of the Suite/Advanced UI or Advanced UI installation that is available for download.

If the end user clicks the Update button, the setup launcher downloads it and then verifies its digital signature.

2. If the isupdate.xml file does not include a reference to a newer version of the installation, or if the isupdate.xml file is not present, the installation displays the MaintenanceWelcome wizard page—the standard maintenance wizard page that does not include an Update button.

Digital Signature Verification

If an Advanced UI or Suite/Advanced UI installation downloads an update, it verifies its digital signature before launching it:

1. If the digital signature in the update setup launcher matches that in the base setup launcher, the update setup launcher runs automatically.
2. If the digital signature does not match, or if the base setup launcher is not digitally signed, a security warning is displayed, allowing the end user to choose whether to proceed with the update setup launcher.
3. If the update setup launcher is not digitally signed, the installation fails, and the debug log reports the digital signature problem.

See Also