When importing a managed solution, a decision is required to either upgrade or update the existing solution.
Upgrades are intended for deploying significant changes, like new features, structural changes, or adding new tables.
The ‘Stage for Upgrade’ option allows the installation of the new solution without removing the existing solution, reducing risk. Once proven, the staged solution can replace the existing version. Alternatively it can be removed, rolling back to the previous version.
An Update is intended for small, incremental changes to a solution, such as adjusting settings, amending the UI, or fixing minor issues.
The most important difference, though, is what happens to components you’ve removed. An upgrade deletes any components that are no longer in the new version of the solution, while an update never deletes anything. So if you’ve removed a column, flow or table from the solution, an update will not delete it from the target environment, and only an upgrade will clean it up.
The version number of the imported solution is defined when the solution is exported from the source environment. For details on the versioning of solutions, see my post: Solution Version Numbering.
Lets look at upgrades and updates in more detail.
Initial Import of a Solution
The first time a solution is imported, no update or upgrade options are available under Advanced Settings.
This is understandable, as an update or stage for upgrade can’t take place on a solution that doesn’t yet exist.
Once imported, the new solution with its version number can be seen in make.powerapps.com.
Updating a Solution
Now to import a new version 1.1.0.0.
All 3 options are available. I select update, to update the existing solution
Importing A Patch
A patch is a small, partial update to a solution. It’s created in the source environment from the parent solution, and contains only the components you add to it, typically the few that have changed, rather than the whole solution. Its version number keeps the parent’s major and minor numbers and increases the build or revision number. For example, a patch to version 1.1.0.0 might be 1.1.1.0.
Patches are quick to create and deploy, which makes them handy for urgent fixes. But while a solution has patches, the parent solution is locked in the source environment: you can’t edit it directly, only add further patches.
When importing a patch, no upgrade or update option is offered, because a patch is always installed on top of its parent solution, which must already exist in the target environment.
When the patch has been installed, it can be seen alongside the main solution
When the patch has been installed. It can be seen alongside the main solution
Importing A 'Clone to Solution'
Patches build up over time, and the parent solution stays locked while they exist. ‘Clone to Solution’ is how you tidy this up. In the source environment, it rolls the parent solution and all its patches into a single new version of the solution, with a higher major or minor version number, for example 1.1.0.0 becoming 1.2.0.0. The patches are removed, and the solution can be edited normally again.
When this cloned version is exported and imported into the target environment, it has to be an upgrade, so the update option is greyed out. The upgrade replaces the previous solution and all its patches with the single consolidated version, keeping both environments in step.
I select upgrade, and once imported, the previous solution and the patch have been replaced by the new solution.
I select upgrade and once imported, the previous solution and the patch have been replaced by the new solution
Stage For Upgrade
Here I have installed a new version 1.2.0.2 of the solution, and I select ‘Stage for Upgrade’.
As you can see below, both the previous solution version 1.2.0.1 and the new version 1.2.0.2 co-exist.
Once the new solution has been confirmed to be working as expected, the previous solution can be removed. This is done by selecting the previous solution and clicking ‘Apply Upgrade’
Once done, only the new version of the solution now exists in the environment
Alternatively, to remove the update, select it and click ‘Delete’ from the menu
Which leaves just the previous version in the environment
Only one Stage for Upgrade can be in an environment at any one time. To add a new Stage for Upgrade, the earlier one must first be either deleted or applied
Upgrading A Solution
Finally, I have a new major version 2.0.0.1 of the solution, and I can select any of the options, but for a major version, upgrade (or stage for upgrade) would be the appropriate choice.
Viewing History
Finally, to view the history of a solution, select ‘See history’