Streamlining App Deployment in Workspace ONE UEM with the PsAppDeployToolkit

Deploying applications to Windows machines can be difficult in the best circumstances. Every application has its own install and uninstall parameters, some applications have dependencies, or transformations, and many applications involve multiple bundled installers. Workspace ONE (WS1) UEM helps alleviate some of these problems, but things like multiple installers and complex install parameters are still difficult to deal with. Combining WS1 UEM and the PsAppDeployToolkit (PSADT) can help with these issues. PSADT adds a plethora of useful features to help with the organization of the application installation workflows, automatic logging, and allows both an interactive install with a GUI or an entirely silent install.

What is PsAppDeployToolkit and why use it with Workspace ONE UEM?

PSADT is a free, open-source, lightweight, PowerShell-based toolkit. It allows you to encapsulate Windows installers and configuration files and add extra capabilities to the application installation process.

Some of the useful features the PsAppDeployToolkit adds are:

• Additional PowerShell commands you can easily add to your install, like copy-file, and execute-process.
• Built in error handling and logging.
• Automatically wait for the previous steps in the installation process to be completed before proceeding.
• It can automatically close instances of the app you are trying to install/upgrade.
• It can even provide a customizable GUI for users to delay the install, see the install progress.

The best part of integrating PSADT with WS1 UEM is that it does not actually require any integration. It is just a collection of scripts that you can add to any Windows application you upload to WS1 UEM. If you are already familiar with uploading apps to WS1 UEM as a zip file, the process is very easy.

In the Toolkit folder, we see sub-folders: AppDeployToolkit, Files, SupportFiles and the hidden. vscode folder. We also have files – Deploy-Application.ps1, Deploy-Application.exe and Deploy-Application.exe.config.

The most important file here is the Deploy-Application.ps1 PowerShell script. This script runs and controls everything about the toolkit.

The Files and SupportFiles sub-folders will be empty. This is the location where you will copy your application install files, and the AppDeployToolkit sub-folder contains supporting files for the script.

Step 2: Editing Deploy-Application.ps1

Everything is controlled by the Deploy-Application.ps1 PowerShell script, and we configure the install package by editing the script. I suggest using Notepad ++ to read and edit the script. There are a few places to add and edit when setting up an install package.

The essential sections within the script are pre-installation, Installation, Post-Installation, Pre-Uninstall, Uninstall, and Post Uninstall. The PSAppDeployToolkit’s structured phases give you precise control over each stage of software deployment. This breakdown allows for environmental readiness checks, smooth installations,  a thorough post-installation configuration and a clean, efficient uninstallation process. Administrators can prevent installation errors and avoid system conflicts by controlling each step. In the Pre-Installation phase, you can define actions to prepare the environment for deployment. This might include closing conflicting applications, checking for prerequisites, or creating system backups. Ensuring the system is ready before installation reduces the likelihood of installation errors or system conflicts.

I will go over each of the relevant sections below:

Variables Declaration section

Starting at line 109 there are various application variables we can set. These are not very important and are not required for the installation or uninstallation, but you can set them to version control the installer and for future reference.

Pre-Installation section

Starting at line 184, we can configure the pre-installation parameters. Line 184 allows us to set the application identifier to close the app before the installation starts. It also allows us to set the allowed deferral amounts for interactive installations. The AllowDefer and DeferTimes will only be relevant when using an interactive installer.

At line 190 you can set pre-install tasks before the installation begins. These could be tasks checking for prerequisites, creating back-ups, or copying a configuration file to a folder.

Installation section

Line 208 is the most important to add, as this is the Installation phase. It is the core of the software deployment process, where the actual application installation takes place. This is where you will define your application’s primary installation parameters. The Installation will differ, depending on the app, and may require the application documentation, but there are a few straightforward, reliable commands you can use.

Generally, if you are installing with a bat file you can use the following:
Execute-Process -Path <NameofyourInstallFile>.bat

The same command can be used for executables as well, and additional parameters can be added, as in the following example:

Execute-Process –Path ‘setup.exe’ –Parameters “/s /v`”ALLUSERS=1 /qn /L* `”C:\ProgramData\AirWatchMDM\Support\$installName.log`”`””

Additional parameters can be added as well. A list of additional parameters can be found here: https://psappdeploytoolkit.com/docs/reference/functions/Execute-Process

For MSI installers, PSADT provides the Execute-MSI command with its own parameters.
Execute-MSI –Action ‘Install’ –Path ‘<NameOfInstallFile>.msi’ –Parameters ‘/QN’

Additional parameters can be added as well. A list of additional parameters can be found here:

https://psappdeploytoolkit.com/docs/reference/functions/Execute-MSI

Note: As with all PowerShell scripts, it is important to use quotations correctly. If you use $variables, make sure you use double quotes. More information can be found in the Microsoft PowerShell rules: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.4

Post-Installation section

Line 216 allows us to add post-installation tasks. The Post-Installation section is designed to finalize and validate the software deployment, ensuring that the application is ready for immediate use. This phase is used to handle any remaining setup tasks and configure settings.

In my example I copy a configuration file to the ProgramData folder, to be used by the application for automatic configuration, but you can use this section for anything you want to do after installing the app.

Uninstall section

The Uninstall section is pretty much the same as the install section, except you define the application uninstallation process. We can add a pre and post uninstall process, but I will only focus on a simple uninstall.

At line 252 we can add the uninstall process, which if using a bat file will be the same.
Execute-Process -Path <NameofyourUnInstallFile>.bat.

An MSI would be the same, except we need to change the action from Install to Uninstall.
Execute-MSI –Action ‘Install’ –Path ‘<NameOfInstallFile>.msi’ –Parameters ‘/QN’

You can also specify a product code when creating an uninstall command.
Execute-MSI –Action ‘Uninstall’ –Path ‘{26923b43-4d38-484f-9b9e-de460746276c}’

Finishing the script
The rest of the file lets us set repair parameters, but we don’t have a reason to use that when working with WS1, so it can be safely ignored.
Once you have all your commands and variables set just save the file and do not change the name of Deploy-Application.ps1.

Step 3: Editing the Config file

A valuable addition to the application installation process is the ability to specify a dedicated folder for logging. This ensures that all the application installation logs are centralized and easily accessible by the WS1 administrators for troubleshooting and monitoring. For WS1-managed Windows devices, the application installation logs can be directed to the ProgramData\AirwatchMDM\Support folder. This folder is automatically included in the WS1 log bundle, whether collected via the WS1 UEM console or directly on the device. Administrators can easily collect installation and uninstallation logs by centralizing the logs in this location, streamlining the troubleshooting process within WS1 UEM.

In the AppDeployToolkit folder you will have a file called AppDeployToolkitConfig.xml.

We can use this file to change the App Deployment Toolkit logging to the WS1 folder.

On lines 41, 48, 102, and 104 you can change the log path to $envProgramData\AirWatchMDM\Support. This will force the toolkit to create its log files in the AirwatchMDM\Support folder which is a part of the WS1 troubleshooting log bundle, created by the Intelligent Hub client. This can make troubleshooting easier for the WS1 administrators in the future.

Step 4: Where to put your files?

As mentioned earlier, there are two empty folders, Files and SupportFiles. All the files required for installation, including the install batch file, should be copied to the Files folder. The SupportFiles folder is only used for files that are added manually to the Deploy-Application.ps1 script, like a file to be copied or a configuration file. If you have a configuration file that needs to be copied to another location on the machine, it will need to be copied to the SupportFiles folder.

Creating the ZIP
Once you have edited the Deploy-Application.ps1 script, copied all your install files to the Files Folder, and edited the config file, you are ready to zip the files and upload them to WS1 UEM.

NOTE: Always make sure when creating a zip file to select all files and folders and do not zip the containing folder. The Deploy-Application.ps1 file must not be in a folder.
The below screenshots illustrate the proper zipping of all files and folders –

Step 5: Configuring in WS1 UEM

Once you have uploaded your zip file to WS1, we need to set the installation, uninstall, and detection parameters.

Install
To perform a silent install, you can use the following command:
powershell -executionpolicy bypass -file Deploy-Application.ps1 -DeploymentType Install -DeployMode NonInteractive

Uninstall

We can use the uninstall command from the Deploy-Application.ps1 here and use the PowerShell script itself to process the uninstall command. The uninstall command in WS1 UEM can read the Deploy-Application.ps1 from C:\ProgramData\AirwatchMDM\AppDeploymentCache and execute the command we entered into the Deploy-Application.ps1 earlier, starting at line 252.

Example:
powershell -executionpolicy bypass -file Deploy-Application.ps1 -DeploymentType Uninstall -DeployMode NonInteractive

Detection Criteria

Detection criteria are a critical part of application installation, but unfortunately, the PS App Deployment Toolkit does not assist with this step. As a result, we need to determine the detection criteria manually.

The most straightforward approach is to install the application manually and locate the uninstall command in the Windows registry under:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall

Alternatively, you can refer to the application’s official documentation for accurate detection criteria.

This manual method ensures that the detection rules are precise, helping to effectively verify the application’s installation status in Workspace ONE UEM.

Editing the Interactive Installer:

PSADT also gives an option to use an interactive installer. This allows a user to see the installation progress and can allow the user to defer the installation. The interactive will look like the example below. You can edit the text, the icon, and the banner.

It is configured starting at line 183. This line is where we set the number of times a user can defer the install. It will also pull the name and version information from the metadata entered in the Variable Declaration section at lines 109 – 111.

You can also edit the specific text in the GUI if you want to customize it. This is in the AppDeployToolkitConfig.xml, starting at line 176. This amount of customization should not be necessary for most use cases, but it is there and easy to change if you need it.

The last bit of customization is the banner and icon files. The default banner and icon files are found in the AppDeployToolkit folder and are called AppDeployToolkitBanner.png and AppDeployToolkitLogo.ico. To replace them, all you need to do is replace the files with your desired images, with the exact same name. For the best results on the banner, you should make your banner the same dimensions as the default AppDeployToolkitBanner.png, which is 900 x 125 pixels.

Conclusion

The PS App Deployment Toolkit is a versatile, lightweight tool that seamlessly integrates into any application deployment process. By packaging the toolkit alongside the application installation files and configuring its PowerShell script and XML file, WS1 administrators can unlock a range of powerful features.

These features significantly enhance application deployments, making them easier to manage, more robust, and highly standardized. Leveraging this toolkit can streamline workflows and ensure consistency across deployments, ultimately saving time and effort.