Managing Updates with the macOS Updater Utility: Workspace ONE Operational Tutorial

Overview

Omnissa Workspace ONE® UEM provides a comprehensive management solution for macOS devices, supporting operating systems version 10.15 and later. With the ability to manage Corporate-Dedicated, Corporate Owned, or Employee Owned (BYOD) devices, Workspace ONE UEM offers enterprises the flexibility to meet their employees’ needs at any level.

As part of the overall lifecycle management of macOS devices, it is critical to ensure that the operating system is kept up-to-date with the latest OS updates. Apple regularly releases minor updates for macOS that include enhancements, bug fixes, and security patches. Major OS updates, released less frequently, often contain new functionality, and in some cases, a completely new code base for the OS itself. Apple has included a Software Update utility within the OS that typically requires user intervention to initiate. It can be challenging for enterprise administrators who manage hundreds of macOS devices to ensure that OS updates are applied in a timely fashion.

macOS Updater Utility

The macOS Updater Utility was created to provide administrators with more granular control, as well as the ability to manage major and minor OS updates. The macOS Updater Utility provides configuration options for deferral parameters, end user notification behaviors, as well as extending the notification parameters by providing administrators with the ability to customize the message presented to the end user. The utility will, if necessary, force users to update the OS on their devices after the maximum number of deferrals has been exceeded.

After the macOS Updater Utility script and device profile have been deployed to the device, the following criteria must be met before any action is taken:

• An active user must be logged into the device
• The current OS version must be less than the desired OS version configured in the device profile

Important: The macOS Updater Utility is not a supported Omnissa product. It is a utility created by subject matter experts within Omnissa to extend the functionality of Workspace ONE UEM. It is recommended that customers do extensive testing and validation on the utility prior to introducing it into their production environment.

NOTE: The Workspace ONE UEM console now includes macOS Update Management, which provides administrators with the granular control required for deploying macOS updates to devices. This new framework performs similar tasks to the macOS Updater Utility, including scheduling, downloading, and installing OS updates. For more information on using macOS Update Management, see Using Workspace ONE to Manage Operating System Updates on macOS Devices.

macOS Updater Utility Workflow

The macOS Updater Utility steps through an iterative process during execution to confirm requirements and initiate the update. Each step contains a set of decision points that determine if the Updater Utility proceeds or exits. The following diagram and text explain the workflow for the macOS Updater Utility.

Figure 1: macOS Updater Utility Workflow

1. The macOS Updater Utility script is executed on the schedule configured during the script assignment process (See Create the macOS Updater Utility Script Resource).
2. The macOS Updater Utility script confirms that the macOS Updater Utility profile has been applied to the device. If the profile has not been applied, the script exits and runs again on the configured schedule.
3. The script checks the current version of macOS on the device. If the current version matches or is above the version configured for the update, the script will exit. Otherwise, it moves on to the next step.
4. The script checks for the installer of the macOS version required for the update. If the installer is present, the script proceeds to step 6. Otherwise, the script proceeds to the next step.
5. The script initiates the download of the macOS installer for the required version, then exits, and runs again on the configured schedule.
6. The script checks to see if there is an active user logged onto the device. If no active user is present the script will exit, and run again on the configured schedule.
7. The script sends a notification to the active user. The user has the option to defer the update. If the maximum number of deferrals has been reached, the script will proceed to step 9.
8. If the user defers the update, the script logs the deferral. Then, the script exits and will run again on the configured schedule. If the user does not respond to the prompt within the time configured in the Updater Utility (See Changing the macOS Updater Utility Settings), the non-response will be considered a deferral and the script will exit. If the maximum number of deferrals has been reached, the script will proceed to the next step.
9. The script executes the update by launching the installer. The user receives periodic progress notifications from the update installer. When the installer completes the update, the macOS device will reboot.

Purpose of This Tutorial

This tutorial will address the configuration and operation of the macOS Updater Utility. The exercises will focus on the following:

• Configuring the macOS Updater Utility in Workspace ONE UEM
• Updating macOS devices with the macOS Updater Utility
• Collecting macOS Updater Utility log files from devices

The steps in this tutorial are sequential and build upon each other. You must follow the steps as described.

Audience

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. Familiarity with macOS, XML, and basic scripting is assumed.

Knowledge of additional technologies such as Omnissa Intelligence and Omnissa Workspace ONE® UEM is also helpful.

Configuring the macOS Updater Utility

  This exercise helps you configure the macOS Updater Utility in Workspace ONE UEM. These steps walk you through the following tasks:

• Add the macOS Updater Utility script to Workspace ONE UEM
• Create the macOS Updater Utility device profile

Prerequisites

Before you can perform the exercises in this tutorial, you must meet the following requirements.

• macOS Version 11.0 (Big Sur) or higher is recommended.
• Intelligent Hub for macOS v22.12 or higher
• UEM v22.10 or higher with Freestyle Orchestrator is recommended in order to utilize "Scripts" engine.

Note: Before using the macOS Updater Utility, it is recommended that you perform validation testing on a small set of macOS devices to ensure that there are no potential issues.

Create the macOS Updater Utility Script Resource

In this exercise, you will create the macOS Updater Utility script in Workspace ONE UEM. Because this script is updated regularly, it is not included in this document. Download the latest macOS Updater Utility script.

To configure the macOS Updater Utility, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and then click Scripts.
2. Select Add, and click macOS.
3. Name the script macOS Updater Utility. Leave App Catalog Configuration deactivated. Click Next.
4. Set the Language to Bash, and the Execution Context to System.
5. Set the Timeout to 330.
   
   Note: The Timeout value can be customized to suit the requirements of your environment. It is important to note that the script timeout must be set to 30 seconds more than the promptTimer, which is explained in the next exercise. You can come back and adjust this value as needed.
6. Copy the latest version of the macOS Updater Utility script, and paste it into the Code window.

7. Click Next.
8. Click Save.
9. In the Scripts list, check the new script you just created, and click Assign.
10. Click New Assignment. Enter a name for the assignment. For example, All macOS Devices.
11. For Select Smart Group, click in the search box. From the list of Assignment Groups that appear, select the appropriate group. For example, select All macOS Devices (your@email.shown.here).
12. Click Next.
13. Check Run Periodically and select an appropriate interval for your environment. For this exercise, select 4.

14. Click Add.
15. Click Save & Publish, and then Publish.

Create Device Profile for macOS Updater Utility

A macOS device profile is used to control the end-user experience for the Updater Utility. The custom settings payload contains XML that can be edited to manage the desired OS version, user deferral behaviors, and message box configurations.

1. In the Workspace ONE UEM console, select Resources, and then click Profiles & Baselines.
2. Select Profiles.
3. From the Add drop-down menu, select Add Profile.
4. Select the Profile Platform by clicking macOS.
5. For the Context, select Device Profile.
6. Enter macOS Updater Utility for the profile name.
7. Scroll down through the list of payloads until you find Custom Settings. Click Add.
8. Copy the latest version of the macOS Updater Utility XML, and paste it into the Custom Settings textbox.

9. Click Next.
10. Scroll down to view Assigned Groups and click in the search box. From the list of Assignment Groups that appear, select the appropriate group. For example, select All Devices (your@email.shown.here).
11. Select Auto for the Assignment Type.
12. Click Save and Publish.
13. You should now see your macOS Updater Utility Device Profile within the list of the Profiles window.
14. After the device profile and Updater Utility script have been applied to your macOS device, the script will execute within the timeframe you configured earlier.
15. When the device is ready to update, the active user is prompted with the following notification.

16. The user will have the option to defer the update until the maximum number of deferrals is reached.
17. During the update process, the user will receive periodic progress notifications such as the following:
     
18. When the update process is complete, the macOS device is rebooted.

Changing the macOS Updater Utility Settings

The configurations for the macOS Updater Utility are managed through the XML in the device profile you created earlier. By modifying specific keys in the XML, you control which OS version to update to, the amount of time the user has to respond to the update prompt, how many deferrals are allowed before forcing the update, and the message presented to the end user.

Table 2 explains each key and its function.

Table 2: XML Keys and Functions

Key	Type	Default	Function
desiredOSversion	string	12.5	The version of macOS you want your devices to update to. Example: 12.4
promptTimer	string	300	The amount of time in seconds that the prompt to upgrade or defer is displayed to the user before it times out. If no action is taken and the prompt times out, it does count as a deferral to the user.
maxDeferrals	integer	10	The number of times the user can defer the update before it is forced.
buttonLabel	string	Upgrade	The text displayed on the button to the user that triggers the OS Update.
messageIcon	string	/System/Applications/App Store.app/Contents/Resources/Appicon.icns	The location of the icon to be used in the prompt to the user. Do not use escape spaces in the path.
messageTitle	string	Approved macOS Update Ready	The title of the prompt dialog box that is displayed to the user.
messageBody	string	This will upgrade your computer to the latest version of macOS. It will quit out of all open applications. Make sure to save your documents and data before proceeding. This installation will restart your computer and may take several minutes to complete. If you have questions and/or concerns, contact your IT Support team.	The message body of the prompt dialog box that is displayed to the user.
maxDays	integer	10	The maximum number of days the user can defer the update before it is forced.
deadlineTime	string	19:30	Optional setting. The time in which the update will be enforced on the given deadline date (controlled by maxDays).

The following exercise will show you how to modify the XML to change the default settings for the macOS Updater Utility. This exercise is provided as an example, and you can configure the keys in whatever manner is best for your environment.

Modify macOS Update Version and Deferral Settings

In this exercise, you set the macOS update version to 12.6, and change the maximum number of user deferrals to 5.

1. In the Workspace ONE UEM console, select Resources, and then select Profiles & Baselines.
2. Select Profiles.
3. Click the pencil icon beside the macOS Updater Utility device profile you created earlier.

4. Click Add Version.
5. Expand Custom Settings.
6. Find the key called desiredOSversion. Change the string that follows the key to 12.6.
7. Find the key called maxDeferrals. Change the string that follows to 5.

8. Click Next. Then, click Save & Publish.

macOS Updater Utility Log Files

    The macOS Updater Utility creates and appends a log file each time the utility executes. The log file can be found on the device in /Library/Logs/macOSupdater.log. You can also retrieve the log file through the Workspace ONE UEM console.

The following exercise outlines the steps for collecting the macOS Updater Utility log file and how to view the log file through the Workspace ONE UEM console.

Collect the macOS Updater Utility Log File

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Devices. Then select List View. 
2. Click the device from which you want to collect the macOS Updater Utility log file.
3. Click the More Actions menu and select Request Device Logs.
4. Set the Type to Snapshot, and Request User Consent to Disabled. Click Save.
5. The task may take a few minutes to complete. After the task completes, click More and then Attachments.
6. Click Documents.
7. You will find a new document called Hub_Complete_Report-<yyyy-mm-dd_hh-mm-ss>.zip. If you see multiple files, select the one with the most recent date. The ZIP file will download to your local device.

8. Unzip the file if it did not unzip during the download. A new folder is created with the same name as you saw in the Workspace ONE UEM console. You will find the macOS Updater Utility log file under the subfolder \data\ProductsNew. The log file is called macOSupdater.log.
9. The following is an example of the log file generated by the macOS Updater Utility. Key points in the workflow have been highlighted.

2022-10-06 11:50:37  ===== Launching macOS Updater Utility =====
2022-10-06 11:50:37    --- Revision 9 --- 
2022-10-06 11:50:37  user02 is logged in
2022-10-06 11:50:37  profile installed
2022-10-06 11:50:37  upgrade needed - currentOS: 11.7 : desiredOS: 12.5
2022-10-06 11:50:37  counter present
2022-10-06 11:50:37  major update requested
2022-10-06 11:50:37  ProductKey: _MACOS_12.5
2022-10-06 11:50:37  checking for major update download
2022-10-06 11:50:37  major update installer download started, exiting.....
2022-10-06 15:50:27  ===== Launching macOS Updater Utility =====
2022-10-06 15:50:27    --- Revision 9 --- 
2022-10-06 15:50:27  vmwuser02 is logged in
2022-10-06 15:50:27  profile installed
2022-10-06 15:50:27  upgrade needed - currentOS: 11.7 : desiredOS: 12.5
2022-10-06 15:50:27  counter present
2022-10-06 15:50:27  major update requested
2022-10-06 15:50:27  ProductKey: _MACOS_12.5
2022-10-06 15:50:27  checking for major update download
2022-10-06 15:50:27  installer downloaded
2022-10-06 15:50:27  deferrals: 0
2022-10-06 15:50:27  maxDeferrals: 10
2022-10-06 15:50:27  User status: Inactive
2022-10-06 15:50:27  user is not active so not proceeding to prompt, exiting.....
2022-10-10 11:08:27  ===== Launching macOS Updater Utility =====
2022-10-10 11:08:27    --- Revision 9 --- 
2022-10-10 11:08:27  user02 is logged in
2022-10-10 11:08:27  profile installed
2022-10-10 11:08:27  upgrade needed - currentOS: 11.7 : desiredOS: 12.5
2022-10-10 11:08:27  counter present
2022-10-10 11:08:27  major update requested
2022-10-10 11:08:27  ProductKey: _MACOS_12.5
2022-10-10 11:08:28  checking for major update download
2022-10-10 11:08:28  installer downloaded
2022-10-10 11:08:28  deferrals: 0
2022-10-10 11:08:28  maxDeferrals: 1
2022-10-10 11:08:28  User status: PresentActive
2022-10-10 11:08:28  prompting user with deferral
2022-10-10 11:08:36  installing update
2022-10-10 11:08:36  Triggering update with startosinstall
2022-10-10 11:08:36  triggering notification script
2022-10-10 11:08:36  >>>>> Exiting macOS Updater Utility <<<<<

Summary and Additional Resources

 This operational tutorial outlined the steps for deploying, configuring, and using the macOS Updater Utility to update your devices to the latest versions of macOS. It included the steps for creating the necessary script resource and the required device profile. It also detailed the configuration options available to administrators for the macOS Updater Utility. And, it outlined the process for gathering log files from the devices.

Procedures included:

•  Configuring the macOS Updater Utility in Workspace ONE UEM
• Updating macOS devices with the macOS Updater Utility
• Collecting macOS Updater Utility log files from devices

Additional Resources

For more information using Workspace ONE UEM to manage macOS devices, you can explore the following resources on Tech Zone: 

• Using Apple Automated Device Enrollment with Workspace ONE UEM 
• Configuring Basic macOS Management 
• Getting Started with Freestyle Orchestrator on macOS Devices 
• Managing Updates with the macOS Updater Utility 
• Distributing Scripts to macOS Devices 
• Deploying a Third-Party macOS App 

Changelog

The following updates were made to this guide:

Date	Description of Changes
11/05/2024	Updated links to the Updater Utility code.
06/18/2024	Updated for Omnissa docs, KB, and Tech Zone links.
01/05/2024	Removed requirements for OAuth Client and API credentials. Added new information about new XML keys. Removed script variables. Updated the prerequisites for the macOS Updater Utility.
10/13/2022	Guide was published.

About the Author and Contributors

This tutorial was written by:

• Michael Bradley, Senior Technical Marketing Architect, Omnissa.

Considerable contributions were made by the following subject matter experts:

• Matt Zaske, SME Solution Engineer, Omnissa.

Feedback

Your feedback is valuable. To comment on this paper, either use the feedback button or contact us at tech_content_feedback@omnissa.com.