Managing Major macOS Updates: Workspace ONE Operational Tutorial



On macOS, deploying major OS updates (for example, macOS 10.14 Mojave to macOS 10.15 Catalina) is best handled as a two-step process: 

  1. Deploy an Install macOS {name}.app file to the end user’s device.
  2. Run the installer with various parameters to update the device. 

Depending on the level of automation, user approval, and network considerations that you want, there are different ways to approach each of these steps. In some cases, you may decide to handle both steps in a single automated flow. In other cases, you may decide to deploy the install app first but provide the user some flexibility on when and how to update the device.

This tutorial walks through several deployment scenarios and demonstrates how to configure VMware Workspace ONE® UEM to upgrade a fleet of macOS devices (such as from 10.14 to 10.15). 


This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Both current and new administrators can benefit from using this tutorial. Knowledge of additional technologies such as scripting, Apple Business Manager and VMware Workspace ONE® UEM is also helpful.

Validation Environment

The content created for this operational tutorial used the following software and hardware versions for testing:

  • Workspace ONE UEM version 2001
  • Workspace ONE Intelligent Hub version 2001
  • Apple hardware compatible with the macOS upgrade

The content in this tutorial may be applicable to earlier Workspace ONE UEM and Hub versions but this was not specifically tested.


There are many different ways you can approach deploying major macOS updates to end-user devices through Workspace ONE. In any of the methods discussed in this tutorial, the first step is to create a smart group that only targets devices that are not yet on the target OS version. This way, you can assign the appropriate apps and packages to those target devices, and you will avoid updating any devices that have already run through the update process.

When defining your smart group, make sure to specify the Platform and Operating System that includes Apple macOS devices with an OS version less than the target version. Beyond that, feel free to include any additional filters in the smart group to target the appropriate devices. 

1. Add Smart Group

upgrade macOS and add smart group in Workspace ONE UEM admin console
  1. Click Groups & Settings.
  2. Expand Groups.
  3. Click Assignment Groups.
  4. Click Add Smart Group.

2. Create New Smart Group

Upgrade macOS and create a new smart group
  1. Enter a Smart Group Name (such as Pre-Catalina).
  2. Expand Platform and Operating System.
  3. Select Apple macOS | Less Than | macOS Catalina 10.15.0.
  4. Optionally, click Enabled to preview a list of devices targeted by this Smart Group.
  5. Click Save.

Managing Major OS Updates for Mac


One of the easiest ways to get the macOS Update Installer is to deploy the app through Apple Business Manager, which can be integrated with Workspace ONE. The installer app distributed through Apple Business Manager, which we refer to in this document as the online installer, is very lightweight (approximately 20 MB for macOS Catalina), and can be installed with minimal issues even on devices with unreliable network connections. 

This online installer downloads the rest of the software required (approximately 8 GB) after the update is initiated, and can take advantage of Apple content distribution servers and Apple Caching services to do so. In Apple Business Manager, find the macOS Catalina installer. Make sure the purchased quantity is greater than the total number of devices you will deploy the update to and make sure that the Apple Business Manager location the licenses are assigned to, matches the correct Location Token synced into Workspace ONE. 

Option 1: Deploying macOS Upgrade from Apple Business Manager

Depending on the path chosen to plan the upgrade, you may need to distribute the Installer bundle directly from the App Store. This allows Workspace ONE administrators to leverage the power of Apple's Content Distribution network to help deliver the upgrade bits globally. Also, leveraging the App Store and macOS Caching Services helps reduce upgrade-related WAN traffic.

1. Purchase macOS Upgrade Installer in Apple Business Manager

Upgrade macOS from Apple Business Manager
  1. Click Apps and Books.
  2. Search for the OS Upgrade, for example, macOS Catalina.
  3. Select the OS Upgrade in the results list. 
  4. Select the ABM Location that is synced with Workspace ONE. 
  5. Enter the Quantity of licenses needed. 
  6. Click Get to purchase the licenses. 

2. Sync Purchased macOS Upgrade App to Workspace ONE

Upgrade macOS with Workspace ONE
  1. In the Workspace ONE UEM Console, click Apps & Books.
  2. Expand Applications. 
  3. Click Native.
  4. Select Purchased.
  5. Click Sync Assets.
  6. When the sync completes, the app purchased in the previous section should appear in the app list view. 

3. Enable Device Assignment for macOS Upgrade

Upgrade macOS from Workspace ONE Admin Console
  1. From the app list view, select the macOS Catalina app. 
  2. Click Enable Device Assignment.
  3. Click OK.
  4. Click Save & Assign then click Add Assignment.

4. Assign to Pre-Catalina Devices

Upgrade macOS settings
  1. Select the Smart Group created in the Prerequisites.
  2. Change the Allocated number to the appropriate value based on the total purchased licenses. This should be at least the amount of devices you are deploying the update to. 
  3. Set the Assignment Type to Auto.
  4. Click Save.
  5. Click Save and Publish then click Publish.

Note: Workspace ONE administrators may also elect to set the Assignment Type to On-Demand. This advertises the availability of the installer to the user but does not automatically force the installer to download. Rather, the user must choose to install the installer from their App catalog to initiate installer download.  

5. User Experience

If the app is distributed through the Volume Purchase Program (VPP), the user will receive a notification after the app installs on the device. In reality, the install is simply a software download triggered by Workspace ONE UEM against Apple Business Manager and the device. Rather, the user must execute the Install macOS application when they are ready to perform the upgrade. The native OS Upgrade Wizard will walk them through the process. 

Option 2: Deploying macOS Upgrade from Workspace ONE Software Distribution

Instead of deploying the online macOS Upgrade Installer directly through Apple Business Manager, Workspace ONE administrators can choose to deploy it through Workspace ONE software distribution. Using this method provides additional capabilities in customizing the deployment, including a better user experience.

1. Complete Prerequisites for Option 2

  1. Follow the instructions in Option 1: Deploying macOS Upgrade from Apple Business Manager to deploy the installer to a single administrative Mac.
  2. Install the VMware AirWatch Admin Assistant app on the same Mac.

2. Prepare the OS Installer with VMware AirWatch Admin Assistant

Upgrade macOS Applications
  1. On the target device, open Finder and navigate to the /Applications/ folder. 
  2. Find the Install macOS application. 
  3. Open the VMware AirWatch Admin Assistant application. 
  4. Drag the Install macOS file from the Finder window onto the VMware AirWatch Admin Assistant application.

3. Reveal VMware AirWatch Admin Assistant Output

VMware AirWatch Admin Assistant
  1. When parsing is complete, a pop-up window appears. Select Reveal in Finder.
  2. Verify that three files have been created: a .plist, a .dmg, and an image.

Note: By default, the plist contains a generic Install macOS name for the package/installer. Workspace ONE administrators can manually specify the install name by changing the name value in the plist: 

Install mac OS-15.3.00.plist

4. Add Internal App

Upgrade macOS in Workspace ONE Admin Console
  1. In the Workspace ONE UEM Console, click Apps & Books.
  2. Expand Applications and click Native.
  3. Click Add Application on the Internal tab.

5. Upload macOS Application to Workspace ONE

Upgrade macOS and upload to Workspace ONE
  1. Click Upload.
  2. Click Choose File, browse to and select the dmg file output by VMware Admin Assistant and click Choose.
  3. Click Save.
  4. Click Continue.

6. Upload Metadata File

Upgrade macOS and upload metadata file
  1. Click Upload
  2. Click Choose File. Navigate to the folder containing the files exported from the VMware AirWatch Admin Assistant. Select the .plist file and click Choose.
  3. Click Save
  4. Click Continue.

7. Add Image to App

Upgrade macOS and add image to app
  1. Select the Images tab. 
  2. Select Click or drag files here. Navigate to the folder containing the files exported from the VMware AirWatch Admin Assistant. Select the image file. 
  3. Click Save & Assign.

8. Assign the Application On-Demand

Upgrade macOS and enter assignment details in Workspace ONE Admin Console
  1. Click Add Assignment.
  2. Select the Smart Group created in the Prerequisites. 
  3. Set the App Delivery Method to On Demand.
  4. Set Display in App Catalog to Show. 
  5. Set Desired State Management to Disabled.
  6. Set Remove on Unenroll to Disabled.
  7. Click Add.
  8. Click Save and Publish, then click Publish.

9. User Experience

With this setup, the Install macOS [version] application appears inside the assigned user’s Workspace ONE Intelligent Hub catalog. With Hub Services configured, the end-user receives an alert when the app becomes available to them on-demand. When the user selects to install the app, it is placed within the /Applications/ folder, just as if it was deployed directly through Apple Business Manager. 

Similar to Option 1, this does not auto-launch the upgrade. Rather, the user must still launch the upgrade app installed to the /Applications/ folder. 

However, one advantage of using Workspace ONE software distribution to deploy the macOS Upgrade Installer itself, is that it allows further customization of the upgrade process through the use of scripting, which can be configured in the Scripting tab within the application configuration. This will be discussed in the following sections. 

Option 3: Automatically Updating after macOS Update Downloads

For Option 3, a Workspace ONE administrator aims to deploy the macOS Upgrade Installer to the target device, and then to automatically initiate the upgrade without any further user interaction. Background information about the startosinstall command in the macOS installer is included in the first section—Understand the startosinstall Command.    

1. Understand the startosinstall Command

This section discusses the startosinstall command.

1.1. What is startosinstall?

rterakedis — -zsh — 121×23

startosinstall is a command line utility built into the macOS installer which performs scripted OS upgrades. The command supports a few flags which control the behavior of the upgrade. The most commonly used flags include:

  • --nointeraction : Bypasses standard user prompts during upgrade process. 
  • --agreetolicense : Automatically agree to the macOS installer license. 
  • --eraseinstall : Erases the current OS install, including any user files. 
  • --forcequitapps : Force quits any apps that could halt the restart process. 
  • --usage : Lists out all available arguments. 

Note: The –eraseinstall argument should never be used in cases where you want to preserve the file system on the machine. Only use this flag in cases requiring a factory fresh volume after the upgrade. When the online installer is used, initiating the startosinstall command (particularly with the –nointeraction tag), will first download the remaining upgrade files before initiating a reboot to complete the upgrade process. 

1.2. Where is startosinstall?

The startosinstall command is only available when a macOS installer application has been delivered to the device.   Find the utility at /Applications/Install macOS

1.3. How Long Does startosinstall Take?

The startosinstall command could take anywhere from 15 minutes or longer before the reboot occurs. The timing and experience depends on a few different factors:

  • A device’s network connection, such as Wi-Fi versus Ethernet.
  • A device's Internet connection speed (when components are downloaded from Apple's CDN and not from a local, on-network caching server).
  • The arguments used as users may not be directly notified when the reboot is about to occur if the nointeraction flag is used.

2. Complete Prerequisites for Option 3

Start by following Option 2 until Step #7. After uploading the app icon, follow the next step—Step 3: Configure Post-Install Script in Workspace ONE.

3. Configure Post-Install Script in Workspace ONE

Upgrade macOS and edit Scripts in Workspace ONE Admin Console
  1. Select the Scripts tab
  2. Paste the following script into the Post Install Script section
  3. Click Save & Assign

if [[ $(sw_vers -productVersion) != *"10.15"* ]]; then

/Applications/Install\ macOS\ --agreetolicense --nointeraction


Note:  The previous example is making use of the –-agreetolicense and –-nointeraction arguments to bypass all user interaction of the upgrade.

4. Assign the Application for Automatic Delivery

Applications > Native
  1. Click Add Assignment.
  2. Select the Smart Group created in the Prerequisites. 
  3. Set the App Delivery Method to Auto.
  4. Set Display in App Catalog to Show.
  5. Set Desired State Management to Disabled.
  6. Set Remove on Unenroll to Disabled.
  7. Click Add.
  8. Click Save and Publish, then click Publish.

5. User Experience

The Post Install Script executes as soon as the .dmg file is fully installed. With this setup, the Install macOS [Version] application appears inside the assigned user’s Workspace ONE Intelligent Hub catalog. When the user selects to install the app, Workspace ONE immediately begins the upgrade process, including restarting the machine, without additional user interaction.

If the Deployment Type is set to Automatic in Step 3, the upgrade is deployed to and performed on all assigned devices without any user interaction at all. This can be useful when you know devices are not actively in use, or if you can no longer allow end users the ability to defer the upgrade. Note that if this approach is taken, users will not be notified to save their current progress within active apps before the reboot occurs.

Option 4: Deploying macOS Upgrade with Repeat User Notifications

In this option, the goal is not to directly initiate the OS Upgrade without any user interaction at all, but to leverage notifications to encourage end users to perform the upgrade when ready. A great way to support the use of periodic notifications is through the Custom Attributes profile payload.

A script included as a Custom Attribute will run either on a pre-defined schedule or after certain events (such as a user login). By including a hubcli notification as part of a Custom Attribute, you can occasionally ask users to initiate the upgrade, without forcing them to do so. For example, Option 4 creates a Workspace ONE notification asking the users to upgrade, and also store the current OS version in the defined custom attribute.

1. Complete Prerequisites for Option 4

To begin, a Workspace ONE admin should deploy the macOS Upgrade Installer using the Automatic deployment type as outlined in either Option 1 or Option 2. This downloads the installer on the end-user devices, but does not initiate the upgrade. From this point, the remaining steps provide detail on how to create a notification that regularly prompts users to initiate the upgrade.

2. Add New Profile to Workspace ONE

Upgrade macOS and add profile to Workspace ONE
  1. In the Workspace ONE UEM Console, click Devices.
  2. Expand Profiles & Resources and click Profiles.
  3. Click Add.
  4. Click Add Profile.

3. Select Profile Platform and Context

Upgrade macOS and select profile in Workspace ONE
  1. Select Apple macOS.
  2. Select Device Profile

4. Configure General macOS Device Profile Settings

Upgrade macOS and add a new macOS profile in Workspace ONE
  1. In the General tab, enter a Name for your profile, such as macOS Upgrade Check
  2. Ensure the Assignment Type is Auto.
  3. Select the Smart Group created in the Prerequisites. 

5. Configure Custom Attributes Payload

Getting Started > Getting Started
  1. Select the Custom Attributes payload from the list and click Configure.
  2. Enter an Attribute Name such as macOS Upgrade Check. 
  3. Paste the following code into the Script/Command section:
if [[ $(sw_vers -productVersion) != *"10.15"* ]]; then 
/usr/local/bin/hubcli notify -t "Upgrade to macOS Catalina" -s "This may take up to 1 hour." -i "Your machine will restart automatically." -a "Begin" -b "/Applications/Install\ macOS\ --agreetolicense --nointeraction" -c "Cancel" 
sw_vers -productVersion

Note: Customize the text and behavior of the hubcli command as needed, including any modifications to the startosinstall command.

  1. Set the Execution Interval to Schedule.
  2. Set Report Every to 8 Hours.
  3. Click Save and Publish, then click Publish.

6. User Experience

Managing major macOS updates with Workspace ONE.docx

In this example, the user receives the notification to upgrade once every 8 hours. If they select Begin, the upgrade initiates, including the reboot, without any further user interaction. 

Summary and Additional Resources


This operational tutorial provided four different deployment scenarios and demonstrated how to configure Workspace ONE UEM to upgrade a fleet of macOS devices.

The deployment options included:

  • Deploying macOS upgrades from Apple Business Manager
  • Deploying macOS upgrades from Workspace ONE software distribution
  • Automatically updating when macOS update downloads
  • Deploying macOS upgrades with repeat user notifications

Check out the Understand macOS Management Activity Path on Digital Workspace Tech Zone.

Additional Resources

For more information about Workspace ONE, explore the VMware Workspace ONE Activity Path. The activity path provides step-by-step guidance to help you level-up in your Workspace ONE knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon. 

For more information on macOS, see Understanding macOS Management

About the Authors

This tutorial was written by:

  • Paul Evans, EUC Solution Engineer, End-User Computing, VMware
  • Robert Terakedis, Senior Technical Marketing Manager, End-User-Computing Technical Marketing, VMware


Your feedback is valuable. 

To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at

Filter Tags

Workspace ONE Workspace ONE UEM Document Operational Tutorial Intermediate macOS Manage