Upgrades#

This document describes how to implement upgradablity into your Playbook, giving you control over how updates to newer versions are handled.

Implementing Upgradability#

Upgrade functionality is controlled with two primary properties. The first is specified in your playbook.conf file, and defines previous what version(s) your new Playbook can be upgraded from. The second is defined on actions in your YAML, and specifies whether or not the action should be run when upgrading.

Allowing upgrades#

The following example assumes that your users have applied version 1.0 of your Playbook, and you want to allow upgrades to your newer 2.0 version:

<?xml version="1.0" encoding="utf-8"?>
<Playbook>
    <Name>Example PB</Name>
    <Username>Testing Inc.</Username>
    <ShortDescription>Official Example Playbook for Windows 11</ShortDescription>
    <Title>Windows 11 Example Playbook</Title>
    <Description>This Playbook will test your installation&#xD;&#xA;&#xD;&#xA;The testing process makes heavy alterations to your installation.</Description>
    <Details>Official Example Playbook for Windows 11. Testing your system.</Details>

    <Version>2.0</Version>
    <UpgradableFrom>1.0</UpgradableFrom>
</Playbook>

As you can see, the UpgradableFrom property is used to specify what your new version can be upgraded from. This property supports the following formats:

  • <UpgradableFrom>1.0.0-1.5.0</UpgradableFrom> Allows upgrades from any version between v1.0.0 and v1.5.0

  • <UpgradableFrom>any</UpgradableFrom> Allows upgrades from any previous version

  • Allows multiple individual versions:

    <UpgradableFrom>
    <string>1.0.0</string>
    <string>1.5.0</string>
    <string>1.6.0</string>
</UpgradableFrom>

Controlling upgrade behavior#

With UpgradableFrom defined, we can now control what happens if the user is upgrading. This is done by using an onUpgrade property in our YAML, which specifies whether or not an action should be run when upgrading.

On any action, the property can be defined like so:

- !run:
  exeDir: true
  exe: "restoreFiles.bat"
  onUpgrade: true

In this case, the action will only run if the user is upgrading from one of the versions specified in UpgradableFrom. Similarly, the property can be used to prevent an action from running if upgrading:

- !run:
  exeDir: true
  exe: "copyFiles.bat"
  onUpgrade: false

This concludes the basic usage of upgradablity.

Specifying version in YAML#

In some cases, you may want to specify a specific version(s) that an action applies to when upgrading. For this reason, the onUpgradeVersions property is available.

- !run:
  exeDir: true
  exe: "1.0-fix.bat"
  onUpgrade: true
  onUpgradeVersions: ['1.0']

You can also use conditional syntax like ['>=1.0', '!1.2'].

Re-application behavior#

If the same version of a Playbook is re-run, only onUpgrade: false will be triggered.

For example, actions with onUpgrade: false will not be run on subsequent runs of the same Playbook version. However, actions with onUpgrade: true will not be run like on a normal upgrade.

Note

To override this behavior, you can specify the current version in onUpgradeVersions.

Preventing unsupported upgrades#

To prevent users from upgrading from an unsupported version that’s not specified in UpgradableFrom, simply add the following property to your playbook.conf:

<AllowUnsupportedUpgrades>False</AllowUnsupportedUpgrades>

Specifying options#

Important

The following section does not apply if the version being upgraded from did not have a UniqueID defined in the playbook.conf file.

By default, AME Wizard automatically detects if a previous option was applied. For example, if on the v1.0 version the user did not choose install-software, and then when upgrading to v2.0 they did choose that option, onUpgrade will not be triggered since that option was never applied in the first place.

Note

If an option was never present in v1.0, onUpgrade will still be triggered. It will only not be triggered if v1.0 had the option available, and the user did not select it.

This functionality won’t work if an option is renamed from v1.0 to v2.0. To address this, the previousOption YAML property is available.

In the following example, consider that the v1.0 of your playbook has an option install-software defined, and in v2.0 you want to rename it to just software:

- !run:
  exeDir: true
  exe: "installSoftware.bat"
  option: 'software'
  onUpgrade: false
  previousOption: 'install-software'

This will prevent the action from running if the install-software option was chosen when running v1.0.

Ignoring previous options#

In some cases, you may want to always run an action on an upgrade regardless of what options were chosen. This can be done by using previousOption: ignore like so:

- !run:
  exeDir: true
  exe: "installSoftware.bat"
  option: 'software'
  onUpgrade: true
  previousOption: ignore