• Workspace ONE


  • Document


  • Intermediate


  • Operational Tutorial


  • Workspace ONE UEM


  • macOS


  • Manage

Managing Major macOS Updates: VMware 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 macOS Updates


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: Upgrading macOS 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 Catalina.app application when they are ready to perform the upgrade. The native OS Upgrade Wizard will walk them through the process. 

Option 2: Upgrading macOS 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 Catalina.app application. 
  3. Open the VMware AirWatch Admin Assistant application. 
  4. Drag the Install macOS Catalina.app 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

  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 Catalina.app/Contents/Resources/startosinstall.

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\ Catalina.app/Contents/Resources/startosinstall --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 On-Demand

  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: Upgrading macOS 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

  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\ Catalina.app/Contents/Resources/startosinstall --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.

Terminology Used in This Tutorial

The following terms are used in this tutorial:

application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as Workspace ONE Access (formerly VMware Identity Manager).
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile device management
(MDM) agent
Software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
service provider (SP) A host that offers resources, tools, and applications to users and devices.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

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. 


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 euc_tech_content_feedback@vmware.com.

Filter Tags

  • Workspace ONE
  • Intermediate
  • Operational Tutorial
  • Document
  • Workspace ONE UEM
  • macOS
  • Manage