Installation Workflows

This section documents various installation workflows and the logic flow a bundle installer. A bundle installer includes:

iTwin Studio
An App
App Prerequisites (optional)

Per User Installation

”First time” installation

Details installation on a “clean” machine where Studio, app and prerequisites aren’t installed.

Install App prerequisites (admin permissions might be requested)
Install iTwin Studio
- Install Studio prerequisites (admin permissions will be requested)
- Install Studio to %localAppData%
- Write Studio registry keys
- Add Studio to PATH
Install the app
- Cache App’s .zip file to %localAppData% (or %tmp% folder)
- Find Studio install location from the registry
- Invoke [installLocation]/iTwinStudio.exe apps install [path to zip file]
  - .zip file is extracted to %appData%/Bentley/iTwinStudio/v[X]/Apps/[app-id]
  - If an app has icons set in app.config.json, a shortcut is created.

Auto updates

Studio and app updates are independent, and are always performed on a per-user basis.

App auto-updates

User starts Studio and the app
Studio finds that new app version is available
- download the .zip file and cache it to %tmp% folder
- When user closes the Studio, start the update
  - new .zip file is extracted to %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
  - If an app has windows.addToAddAndRemovePrograms: true and windows.upgradeCode set in app.config.json, update the version displayed in add/remove programs.

Studio auto-updates

User starts Studio and any app
Studio finds that new version is available
- download the new installer file and cache it
- When user closes Studio, start the update
  - Update Studio in %localAppData%
  - Update Studio registry keys
  - Update Studio PATH

Manual Updates

Most minor and patch app updates will go through Studio “auto update” workflow and will not require an installer. However, it’s also possible to expose minor/patch releases in software downloads. Such an installer can then be manually invoked by a user.

Check installed App version (quit if its newer or the same)
Verify App prerequisites are installed (admin permissions might be requested if they are missing)
Check installed Studio version, update Studio if needed
- Verify Studio prerequisites are installed (admin permissions will be requested if they are missing)
- Update Studio in %localAppData%
- Update Studio registry keys
- Update Studio PATH
Update the app
- Cache App’s .zip file to %localAppData% (or %tmp% folder)
- Find Studio install location from the registry
- Invoke [installLocation]/iTwinStudio.exe apps install [path to zip file]
- .zip file is extracted to %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]

NOTE: the major update workflow is planned, but not implemented yet

Major app version changes indicate that the app prerequisites have changed, and that the app must be through software downloads. Studio itself will not auto-update between major version changes, just prompt the user to update via software downloads.

Uninstalling

Since Studio and the app have separate entries in add/remove programs, the applications will have to be uninstalled separately.

The App should never un-install Studio.

Uninstalling the App

Since the app was installed via a bundle installer, uninstallation also goes through the bundle installer. Uninstallation can be started via add/remove programs.

Remove the cached .zip file from %localAppData% (or %tmp% folder)
Invoke iTwinStudio.exe apps uninstall [app-id]
- Remove %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id] folder
- Remove shortcuts

Uninstalling Studio

Studio has a separate entry in add/remove programs, which can be used to uninstall Studio itself.

Uninstall Studio Apps installed by the user invoking iTwinStudio.exe apps uninstall --all command
- This step can be skipped by passing the “SKIPAPPS” argument to the bundle installer.
Remove the files from %localAppData%
Remove entries from the registry
Remove entries from PATH

Per machine Installation

Studio prerequisites will require admin permissions to install. Whilst most of our existing end-users will already have prerequisites like Connection Client installed, new users will not.

In addition, not all users will be able to grant admin permissions - for such cases, software might be installed/rolled out by an IT administrator instead. Since the IT administrator has no access to an end users %localAppData%, Studio installer (and an apps installer) must support machine-wide installation.

”First time” installation

For this workflow, we separate two involved personas: the “admin” (account that invoked the installer) and the “end user” (different user on the same machine)

“Admin” account

The installer will:

Request admin prerequisites
Install App prerequisites
Install iTwin Studio and the app for the current user
Install iTwin Studio for all users
- Copy iTwin Studio bundle installer to %programFiles%
- Create a new Registry RUN key: %programFiles%/[....]/iTwinStudioInstaller.exe RANBYMACHINEWIDEINSTALLER=1 /silent
Install the app for all users
- Copy App’s .zip file to %programFiles%
- Write the [location to programFiles zip file] to registry, under HKLM/Software/Bentley/iTwinStudio/Apps
- Find the “universal” Studio install location from HKLM\SOFTWARE\Bentley\iTwinStudio\ExePath. This location will contain %localAppData% string instead of the resolved location.
- Create a new Registry RUN key: [found ExePath] apps install [location to programFiles zip file] --ranByMachineWideInstaller

”End user” account

Execute Run key %localAppData%/[....]/iTwinStudio.exe apps install [location to programFiles zip file]. Command fails because Studio is not installed
Execute Run key %programFiles%/[....]/iTwinStudioInstaller.exe RANBYMACHINEWIDEINSTALLER=1 /silent.
- Install iTwin Studio and the app for the current user
- Studio installer gathers key’s from HKLM/Software/Bentley/iTwinStudio/Apps, and invokes iTwinStudio.exe apps install [array of apps found] --ranByMachineWideInstaller
  - .zip file is extracted to %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
  - If an app has windows.addToAddAndRemovePrograms: true set in app.config.json, a separate entry is created in Add/Remove Programs
  - If an app has icons set in app.config.json, a shortcut is created

Auto Updates

Auto updates work on a per-user basis, since they cannot require admin permissions. This means that the app and Studio will be updated for each user individually.

Manual Updates

”Admin” account

Check installed App version (quit if its newer or the same)
Verify App prerequisites are installed, update if needed
Update iTwin Studio and the app for the current user
Check installed “machine-wide” Studio version, update Studio if needed
- Copy the new Studio bundle installer to %programFiles%
- Update the registry RUN key if needed
Update the “machine-wide” app
- Copy App’s .zip file to %programFiles%
- Write the [location to programFiles zip file] to registry, under HKLM/Software/Bentley/iTwinStudio/Apps
- Find the “universal” Studio install location from HKLM\SOFTWARE\Bentley\iTwinStudio\ExePath. This location will contain %localAppData% string instead of the resolved location.
- Re-write Registry RUN key: [found ExePath] apps install [location to programFiles zip file] --ranByMachineWideInstaller

”End user” account

Execute Run key %localAppData%/[....]/iTwinStudio.exe apps install [location to programFiles zip file] --ranByMachineWideInstaller.
- At this point, Studio is already installed, so the command works as expected
- .zip file is extracted to %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
- If an app has windows.addToAddAndRemovePrograms: true set in app.config.json, a separate entry is created in Add/Remove Programs
- If an app has icons set in app.config.json, a shortcut is created

Uninstalling

Since Studio and the app has separate entries in add/remove programs, the applications will have to be uninstalled separately.

The App should never un-install Studio.

Uninstalling the App (“Admin” account)

To uninstall the app for all users, the app should be un-installed via the [App name] (Machine wide) entry in add/remove programs. This performs the following:

Remove the registry key from HKLM/Software/Bentley/iTwinStudio/Apps
Remove the zip file from %programFiles%
Replace the registry RUN key to [found Studio ExePath] apps uninstall [app-id] --ranByMachineWideInstaller
Uninstall the app for the current user, by invoking iTwinStudio.exe apps uninstall [app-id]
- Invoke iTwinStudio.exe apps uninstall [app-id]
- Remove %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id] folder
- Remove shortcuts
- If upgrade code was provided, find the corresponding per-user bundle installer and quietly invoke it.

Uninstalling the App (“End user” account)

Execute Run key %localAppData%/[....]/iTwinStudio.exe apps uninstall [app-id] --ranByMachineWideInstaller
App is removed from %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
Shortcuts are removed
Entry from add/remove programs is removed

Uninstalling Studio (“Admin” account)

To uninstall Studio for all users, the app should be un-installed via the iTwin Studio (Machine wide) entry in add/remove programs. This performs the following:

Uninstalls iTwin Studio and the app for the current user
Remove the installer file from %programFiles%
Replace the registry RUN key to %localAppData%/[....]/iTwinStudio.exe uninstall --ranByMachineWideInstaller

Uninstalling Studio (“End user” account)

Execute Run key %localAppData%/[....]/iTwinStudio.exe uninstall --ranByMachineWideInstaller
Find the cached per-user installer and quietly invoke it
- Remove the files from %localAppData%
- Remove entries from the registry
- Remove entries from PATH

Edge case “machine wide installation” workflows

Admin installed an app for all users, but a user uninstalled the app for themselves

Scenario:

Admin account installed App and Studio as “machine wide”
User uninstalls the app for themselves only

Workflow:

User uninstalls the app through add/remove programs (or iTwinStudio.exe apps uninstall command)
- App is removed from %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
- Shortcuts are removed
- Entry from add/remove programs is removed
- Studio “notes down” that the app was un-installed by the user themselves
User restarts their PC
- Execute Run key %localAppData%/[....]/iTwinStudio.exe apps install [location to programFiles zip file] --ranByMachineWideInstaller
- Since it was executed with the ranByMachineWideInstaller CLI flag, Studio checks the previously un-installed apps
- Operation is treated as a no-op.

Admin un-installed an app for all users, but a user re-installed the app for themselves

Scenario:

Admin account un-installed the App for all users
User installs the app for themselves only

Workflow:

User installs the app
- .zip file is extracted to %appData%/Bentley/iTwinStudio/[vX]/Apps/[app-id]
- If an app has windows.addToAddAndRemovePrograms: true set in app.config.json, a separate entry is created in Add/Remove Programs
- If an app has icons set in app.config.json, a shortcut is created
- Studio “notes down” that the app was installed by the user themselves
User restarts their PC
- Execute Run key %localAppData%/[....]/iTwinStudio.exe apps uninstall [app-id] --ranByMachineWideInstaller
- Since it was executed with the ranByMachineWideInstaller CLI flag, Studio checks the manually installed apps list
- Operation is treated as a no-op.

Admin installed Studio for all users, but a user uninstalled Studio for themselves

Scenario:

Admin account installed App and Studio as “machine wide”
User uninstalls Studio for themselves only

Workflow:

User uninstalls Studio through add/remove programs
- Studio is uninstalled
- Studio “notes down” that it was un-installed by the user themselves
User restarts their PC
- Execute Run key %programFiles%/[....]/iTwinStudioInstaller.exe RANBYMACHINEWIDEINSTALLER=1 /silent
- Since it was executed with the ranByMachineWideInstaller flag, Studio checks if it was previously uninstalled manually
- Operation is treated as a no-op.

Admin un-installed Studio for all users, but a user re-installed Studio for themselves

Scenario:

Admin account un-installed Studio for all users
User installs Studio for themselves only

Workflow:

User installs Studio
- Studio is installed on a per-user basis
- Studio “notes down” that it was installed by the user themselves
User restarts their PC
- Execute Run key %localAppData%/[....]/iTwinStudio.exe uninstall --ranByMachineWideInstaller
- Since it was executed with the ranByMachineWideInstaller CLI flag, Studio checks if the current installation was manually performed.
- Operation is treated as a no-op.

Common issues

After admin (un)installed Studio for all users, some users do not have Studio (un)installed

Commonly, this happens after a user uninstalled Studio for themselves or a user installed Studio for themselves It’s important to note that once a user installs or uninstalls Studio for themselves, they “own” their installation and machine-wide installers will not affect their installation.

The only way to get the per-user and per-machine installations back in sync is manually edit Windows registry:

In the user account, open Windows registry
If user manually (re)installed Studio:
- Open Computer\HKEY_CURRENT_USER\Software\Bentley\iTwinStudio
- Remove the ManualInstall key
- This will ensure that if “machine wide” Studio is uninstalled, Studio will be removed for this user as well
If user manually uninstalled Studio:
- Open Computer\HKEY_CURRENT_USER\Software\Bentley
- Remove the iTwinStudioPreventInstall sub-key
- This will ensure that if “machine wide” Studio is installed, Studio will be installed for this user as well

After admin (un)installed an App for all users, some users do not get the app (un)installed

Commonly, this happens after a user uninstalled app for themselves or a user installed app for themselves. It’s important to note that once a user installs or uninstalls an app for themselves, they “own” their installation and machine-wide installers will not affect their installation.

The only way to get the per-user and per-machine installations back in sync is manually edit Studio settings:

In the user account, open AppData\Roaming\Bentley\iTwin Studio folder
Open the shared-state.json file
Remove app id keys from manuallyInstalledApps or manuallyUninstalledApps
This will ensure that when the app is (un)installed as “machine wide” it will also be (un)installed for the user.