Deploying a Third-Party macOS App: Workspace ONE Operational Tutorial

VMware Workspace ONE UEM 2107 and later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment. In this tutorial, you learn how to deploy applications to macOS and enable the unified application catalog in Intelligent Hub.  

Deploying Store vs Non-Store macOS Apps

Workspace ONE UEM supports delivering macOS apps that originate from both the Mac App Store and outside the store.

You can use Workspace ONE UEM to deliver a macOS application using any of the following software delivery methods:

  • Apple Business Manager or Apple School Manager — Delivers macOS App Store applications to devices as volume-licensed, purchased applications.
  • Software Distribution — Delivers non-store applications as internal apps in Workspace ONE UEM 9.3 and later. We cover the procedure to deliver a non-store macOS application as an internal app in this exercise.   

The type of macOS app being delivered determines the appropriate delivery method. The following table lists different types of software and their recommended delivery method.  


macOS App Store Applications Non macOS App Store Applications
Delivery Method Apple Business Manager Software Distribution
Examples
  • xCode 
  • Slack 
  • Microsoft Office for macOS
  • Microsoft Remote Desktop
  • Apple's iWork suite
  • TextWrangler
  • F5 Access (VPN)
  • iBooks Author
  • Microsoft OneDrive
  • Microsoft OneNote
  • Quickbooks
  • VMware Tunnel


  • Adobe Creative Suite
  • Microsoft Office (Legacy Versions or Insiders)
  • BlueJeans
  • Camtasia
  • Audacity 
  • Shell scripts, Python scripts


Supported Capabilities
  • Automatic Updates
  • Automatic Metadata Refresh
  • User or Device Licensing
  • Terms Of Use Management
  • Automatic or On-Demand (Catalog-Requested) Installation
  • NSUserDefaults and CFPreferences Configuration via Custom Settings
  • Version Management and Beta Testing
  • Pre/Post [Un]Install Scripting
  • End-User Blocking App Messaging
  • Terms Of Use Management
  • Restart Management
  • Automatic or On-Demand (Catalog-Requested) Installation
  • NSUserDefaults and CFPreferences Configuration via Custom Settings

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 VMware Workspace ONE® Intelligence and VMware Workspace ONE® UEM is also helpful.

Prerequisites

This tutorial was developed on the latest version of Workspace ONE UEM and Intelligent Hub at the time of publishing: 

  • Apple device running macOS version 11.4 (Big Sur)
  • VMware Workspace ONE Intelligent Hub for macOS version 2105.1
  • Workspace ONE UEM version 2105

For more information, see VMware Workspace ONE Access Documentation and VMware Workspace ONE UEM Documentation.

Configuring the Hub Catalog

Activating Hub Services

The unified app catalog in Intelligent Hub for macOS is the Workspace ONE modern application catalog driven by Hub Services. Hub Services co-exist with a Workspace ONE Access tenant but does not require Workspace ONE Access licensing. With Hub Services configured and enabled, users get access to their Applications via the Workspace ONE Intelligent Hub for macOS. This section walks you through activating Hub Services integration with Workspace ONE UEM. This integration is a prerequisite for enabling the app catalog within Intelligent Hub for macOS.

For more information, see Workspace ONE Hub Services.

Note: If you already have a Workspace ONE Access tenant, you can substitute that information in the following steps.

1. Browse to Configurations

In the Workspace ONE UEM admin console:

  1. Click Groups & Settings.
  2. Click Configurations.
  3. Scroll down through the list if required.
  4. Select Intelligent Hub.

2. Get Started

Click Get Started.

3. (Optional) Activate Using Workspace ONE Access

If you have a Workspace ONE Access tenant, follow these steps to set up Hub Services with Workspace ONE UEM.  

  1. Enter the URL for your Workspace ONE Access tenant. For example, https://myaccessurl.vidmpreview.com.
  2. Enter a username with administrative privileges for Workspace ONE Access.
  3. Enter the password for the administrative user.
  4. Click Test Connection and ensure the test succeeds.
  5. Click Save.
  6. Skip to View Hub Services Configuration.

4. Activate by Requesting Cloud Tenant

Groups & Settings > Configurations

If you do not have a Workspace ONE Access cloud tenant, click Request Cloud Tenant.

5. Accept Terms of Services

Review the Terms of Services and if you agree, click Accept.

6. Enter Administrator Details

Enter the details for the administrator account that will be created for your HUB instance:

  1. Enter the Username.
  2. Enter the First Name.
  3. Enter the Last Name.
  4. Enter a valid email address.
  5. Click Next.

7. Select Data Center Location

  1. Select your data center location.
  2. Click Next.

8. View Tenant Name

  1. Observe the Hub Services tenant name that has been created on your behalf.
  2. Click Save.

9. View Hub Services Configuration

  1. Ensure Hub Services activates successfully.
  2. Note the Hub Services URL as populated by entering your Workspace ONE Access credentials or by requesting a tenant.

Configuring the Hub Services App Catalog

With Hub Services enabled for Intelligent Hub for macOS, Workspace ONE administrators can customize the Hub Services App Catalog. The following procedure focuses on the Catalog, but administrators can access other Hub Services settings from the same location.

1. Browse to Intelligent Hub

Groups & Settings > Groups

In the Workspace ONE UEM admin console:

  1. Click Groups & Settings.
  2. Click Configurations.
  3. Select Intelligent Hub.

2. Launch Hub Services

Click Launch.

3. Configure App Catalog



Click App Catalog (or Configure if the checklist is still showing).

4. Configure Global App Catalog Settings



  1. Ensure the version is set to Version: Global.
  2. Ensure macOS is enabled.
  3. Note the Grab area which allows you to rearrange sections in the catalog layout.
  4. Note the X's which allow you to remove sections from the catalog layout.
  5. Click Add Section to add sections to the app catalog (such as sections for a specific app category).
  6. Enable Show Favorites Tab to allow users to select the apps they want to display in their favorites list.
  7. Enable Show Virtual Apps On Devices to show virtual apps on mobile devices and small screens.
  8. Enable App Ratings if you want to collect data from users on which apps they like and/or are working well. You can optionally click the Download button to download a report of the ratings.
  9. Click Save to set the global default app catalog settings.

Note: The Version link (1) allows you to create multiple sets of App Catalog settings, which can be useful if you want the App Catalog to appear differently for different sets of devices or users.

(Optional) Configuring Additional Hub Services

With Hub Services enabled, Workspace ONE administrators can optionally enable and customize additional Hub Services. The following provides a quick overview of available Hub Services and the requirements to enable them.

1. Browse to Intelligent Hub

Groups & Settings > Groups

In the Workspace ONE UEM admin console:

  1. Click Groups & Settings.
  2. Click Configurations.
  3. Select Intelligent Hub.

2. Launch Hub Services

Click Launch.

3. Dismiss Introductory Page

Click Begin if shown the introductory page.

4. (Optional) Configure Hub Services without Enabling Workspace ONE Access



Within the Hub Services console, you can configure Hub Services per your organization's requirements. Out of the box, the Hub functions without any Hub Services configuration changes. If Workspace ONE Access is not configured, you can manage and modify the following Hub Services settings:

  1. App Catalog: Modify the layout and presentation of apps in the Hub catalog.
  2. Branding: Modify the branding settings for the native Intelligent Hub applications and the Hub webpage.
  3. Custom Tab: Define a web page to be shown in the Hub app, such as the company homepage or benefits homepage.
  4. Employee Self-Service: Enable self-service device management for employees via Intelligent Hub.
  5. Notifications: Send basic notifications to employees, such as a notification that email is malfunctioning, and Teams or Slack should be used instead.

Warning: If you are Using Hub Services Without Enabling Workspace ONE Access, you cannot configure or use People or Virtual Assistance functionality.

Deploying Volume-Purchased macOS Apps

Adding Location Token to Workspace ONE UEM

An Apple Business Manager (or Apple School Manager) location is a container that ties a set of books and apps to one or more content managers. Each location has a token that can be uploaded to Workspace ONE to allow App and Book management within the Workspace ONE UEM organization group. The token provides the credentials by which Workspace ONE authenticates to Apple Business Manager to sync assets and manage license assignments.

1. Download Token from Apple Business Manager

App and Books in Apple Business Manager

Within Apple Business Manager (or Apple School Manager):

  1. Click Settings.
  2. Click Apps and Books.
  3. Click Download for the Server Token next to your Location.
  4. For macOS Catalina and later, click Allow to allow the download from Apple Business Manager.

2. Select VPP Managed Distribution

In Workspace ONE UEM:

  1. Click Groups & Settings.
  2. Click Configurations.
  3. Scroll down through the list of Configurations.
  4. Select VPP Managed Distribution.

3. Upload Location Token

  1. Ensure the Current Setting is set to Override.
  2. Enter a friendly name for the Location.
  3. Click Upload.
  4. In the dialog box, click Choose File. Browse to and select the vpptoken file downloaded in Download Token from Apple Business Manager, and select Choose.
  5. Click Save.
  6. Click Save.

4. Cancel Warning About License Usage in Other Environments

If you unexpectedly receive a message about the sToken being used in another environment, click Cancel. An Apple Business Manager (or Apple School Manager) location can be managed by only one (1) MDM or UEM system at a time. You should resolve the reason for this message before attempting to upload the Token. Alternatively, create a new location in Apple Business Manager.

Note: Instead of uploading the same Token in both your Testing and Production Workspace ONE UEM instance, you should create a second location in Apple Business Manager. Within Apple Business Manager, you can allocate unused licenses between locations allowing you to purchase additional licenses (or move a subset) into your second Location for testing.

For questions regarding Apple Business Manager, refer to Apple Support.

Syncing Volume Purchase Licenses

By default, Workspace ONE syncs managed distribution licenses for custom apps and volume-licensed public apps daily. The sync is scheduled automatically, allowing Workspace ONE to reconcile newly purchased licenses and updated metadata (descriptions and images). When you upload a location token, you can speed up this process by manually initiating a license sync.

Sync Licenses from Apple Business Manager

Custom Apps in Workspace ONE UEM

In the Workspace ONE console:

  1. Click Resources.
  2. Expand Apps and click Native.
  3. Click Purchased.
  4. Click Sync Assets.
  5. Click Refresh  to view assets that have been updated from the sync.

Tip: For license and metadata sync to work for on-premises Workspace ONE customers, admins must allow access to *.itunes.apple.com over TCP port 80 and 443. Refer to Use Apple Products on Enterprise Networks for the full list of hosts and ports required to manage and use Apple products on enterprise networks.

Bulk-Enabling Device-Based Licensing

Managed distribution licenses can be assigned on a per-user, or per-device basis. For the per-user licensing model, the end-user of the device is prompted to enter their Apple ID credentials into the device to assign the license. In other words, per-user license distribution requires that all users have an Apple ID. In the per-device licensing model, managed distribution licenses are assigned directly to the device regardless of whether the user has entered Apple ID information. The end-user is not required to have an Apple ID in order for the app to be assigned to the device and installed from the App Store.

For more information, refer to Managed Distribution by Device Serial Number.

Note: If a device is supervised, the user does not get prompted to participate in volume-purchased app management.

Warning: If you convert an application to device-based licensing, you cannot revert it back to user-based licensing.

Bulk-Enable Device-Based Licensing


Custom Apps in Workspace ONE UEM

In the Workspace ONE UEM Console:

  1. Click Resources.
  2. Expand Apps and click Native.
  3. Select Purchased.
  4. Select one or more Public and/or Custom Apps.
  5. Click Enable Device Assignment.
  6. Click OK to enable device-based licensing for the selected apps.

Assigning Volume-Purchased Apps to Devices

In this activity, you select the volume-purchased apps you want to assign to your devices and configure distribution for that assignment.

1. Browse to Purchased App



In the Workspace ONE UEM admin console:

  1. Click Resources.
  2. Expand Apps and Click Native.
  3. Click Purchased.
  4. Optionally, click Filters, expand Platform and select Apple macOS to constrain the list to ONLY macOS apps.
  5. Click the Volume-Licensed App you want to assign (Tunnel - Workspace ONE in this example).

2. Configure Categories

  1. Click Details.
  2. Click to select one or more categories.

3. Optionally Select Terms of Use

  1. Select Terms of Use.
  2. Select an Application Terms of Use if one has been created.

4. Save & Assign

Click Save & Assign.

5. Add Assignment



Click Add Assignment.

6. Configure Distribution

  1. Enter a name for the Distribution. For example, All Devices.
  2. Enter a name of an assignment group to allocate licenses.
  3. Enter the number of licenses to allocate to the Assignment group.
  4. If required, click Add and repeat steps 2 and 3 to allocate licenses to another assignment group.
  5. Select Auto to deliver the app automatically or On Demand (to deliver the app when requested by the user from the catalog).
  6. Click Create.

7. Prioritize Assignments

  1. If necessary, click Add Assignment to add another assignment for the app.
  2. Click to modify the priority of the assignment. This helps determine how the app is assigned if a device has membership to multiple assignments.
  3. Click Save.

8. Publish Assignments

Click Publish.

Updating Volume-Purchased Apps

Volume-purchased applications (iOS, macOS, and tvOS) always install the current App Store version of the application at the time the install occurs.   Imagine the following scenario where the current App Store version of an application is 1.0 on Monday, but then becomes 1.1 on the following Monday.  Any device where Workspace ONE UEM triggers an application install from Monday through Sunday would install version 1.0.  However, on the following Monday (and going forward until the next version update), any devices where Workspace ONE UEM triggers an application install would install version 1.1.  Put differently, Workspace ONE administrators must update pre-existing application installs as developers publish updated application versions in the App Store.   While end-users may have the ability to perform the application updates, they may not perform the updates consistently as desired by the organization's administrator(s).

With Workspace ONE UEM, administrators can configure Volume-Purchased apps to update on a one-time basis or automatically.   When an app is set to automatically update, Workspace ONE continuously monitors for updated app versions in the App Store and triggers install commands to devices with an older version installed.

NOTE:   As of Workspace ONE UEM 20.03 and newer, Auto-Update is supported for Custom Apps (iOS) also.  

1. Browse Purchased Apps



In the Workspace ONE UEM admin console:

  1. Click Resources.
  2. Expand Apps and Click Native.
  3. Click Purchased.
  4. Optionally, click Filters, expand Platform and select Apple macOS to constrain the list to ONLY macOS apps.

2. Update App to Latest Version Once



  1. Note if an app displays Update Available indicating there is a newer version on the App Store than what is installed on some or all enrolled devices.
  2. Select the Volume-Licensed App you want to assign (Tunnel - Workspace ONE in this example).
  3. Click Update App
  4. Click OK when prompted to confirm the action.

3. Configure App for Auto-Update



  1. Select the Volume-Licensed App you want to assign (Tunnel - Workspace ONE in this example).
  2. Click More Actions
  3. Click Enable Auto Updates
  4. Click OK when prompted to confirm the action

4. View Update Commands in Queue



  1. Select the App to verify
  2. Click Manage Devices
  3. Observe the Install commands
  4. Close the window when complete

NOTE:  The command remains queued for the device until it is processed successfully or fails with an unknown error.  If the device cannot immediately process the command, Workspace ONE will continue to queue the command.  Upon the next notification to check-in (or after the device is unlocked), the device will attempt to re-process the command.

Troubleshooting Volume-Purchased App Installs

Volume Purchase App Troubleshooting

As organizations deliver volume-purchased apps from Apple Business Manager, some unexpected issues may arise. This article addresses some common issues affecting volume-purchased app delivery.

1. Newly Purchased Apps Not Syncing to Workspace ONE UEM

This error is typically the result of one of the following issues:

  • Delays in Apple Business Manager from when you purchase the app to when the licenses are allocated to the Location Token.
  • Apple has released new Terms & Conditions in Apple Business Manager. 
    • To resume syncing, log in to Apple Business Manager with an account granted the Administrator role, and accept the updated Terms & Conditions.
  • The location token downloaded from Apple Business Manager and uploaded to Workspace ONE UEM has expired. 
    • Download a new server token from Apple Business Manager (under Settings > Apps & Books) and upload it to Workspace ONE UEM.

2. Device-Based Licensed Apps Not Installing

If you have assigned an app to a device using device-based assignment, one of the following could be an issue:

  • If the user is getting a prompt to log in with an Apple ID, there is most likely an assignment that was made to the user before the device-based assignment was created. 
    • Unassign the app from the user completely before you attempt to reassign the app to the device.
  • Ensure that an adequate number of licenses are available to assign to the device.
  • Ensure that the device has access to vpp.itunes.apple.com.
  • The location token downloaded from Apple Business Manager and uploaded to Workspace ONE UEM has expired. 
    • Download a new location token for that same location from Apple Business Manager (under Settings > Apps & Books) and upload it to Workspace ONE UEM.

3. Volume-Purchased Apps Not Removing from macOS

When a VPP app for macOS is no longer scoped to the device or user, or the device is enterprise wiped, the app is not removed from macOS. This is by design in macOS versions prior to macOS 11 (Big Sur), as these earlier versions of macOS did not support any commands to remove the application.

For More Information on Troubleshooting

If you are still experiencing issues with volume-purchased applications, refer to the Volume Purchase Program (VPP) Troubleshooting Guide or contact VMware support directly.

Deploying a Non-Store macOS App

Enabling 3rd Party macOS App Delivery

In this section, you configure file storage and macOS software management settings in the Workspace ONE UEM console. These settings enable 3rd party macOS app delivery.

1. Access All Settings

All Settings in WS1 UEM console

Log in to the Workspace ONE UEM Console as an administrator and view the Global Organization Group:

  1. Click Groups & Settings.
  2. Click All Settings.

2. Enable File Storage (On-Premises Only)


enable file storage for macOS

If your Workspace ONE UEM instance is SaaS-based, you can skip this procedure as it is already done on your behalf by VMware.

  1. Ensure you are at the Global Organization Group unless your particular setup requires configuring at child Organization Groups.  
  2. Expand Installation.
  3. Select File Path.
  4. Scroll through the file paths pane and select Enabled for File Storage Enabled.
  5. Enter the path of a file share accessible from your Device Services and Console servers.
  6. Select Disabled for File Storage Caching Enabled unless you have planned and sized your Device Services server accordingly.
  7. Select Enabled for File Storage Impersonation Enabled.
  8. Enter the impersonation username credentials to access the file storage path.
  9. Enter the password for the impersonation user.
  10. Confirm the password for the impersonation user.
  11. Click Test Connection and ensure you see Connection Succeeded.
  12. Click Save.

3. Enable Software Management


enable software management for 3rd party macOS app delivery

In the Settings screen, perform the following steps at your top-level Organization Group.

  1. Expand Devices & Users.
  2. Expand Apple.
  3. Expand Apple macOS.
  4. Select Software Management.
  5. Select Override.
  6. Select Enabled for Enable Software Management.
  7. Click Save.
  8. Ensure settings are Saved Successfully.

4. Optional: Enable Content Delivery Network for On-Premises

When planning for non-store macOS application management in an on-premises Workspace ONE install, administrators should consider enabling Akamai Content Delivery Network (CDN) integration. With CDN integration enabled, non-store macOS application install binaries are replicated to the CDN. Devices will be redirected by Workspace ONE Device Services servers to an authenticated CDN location to download the binaries from a geographically local content cache.  

For more information, refer to Integrate Workspace ONE UEM with Akamai CDN.

Preparing a macOS App for Deployment

In this section, learn how to download the VMware Workspace ONE Admin Assistant tool and use it to prepare a 3rd party macOS app for deployment. For the purposes of this document, this procedure uses the Chrome ESR browser application.

1. Open New Browser Tab

On your macOS device, open a new Safari tab (File > New Tab).

2. Download Chrome Enterprise


Click Download Skitch on the Mac App Store
  1. In Safari, navigate to https://chromeenterprise.google/browser/download/
  2. Click Download next to the  Chrome PKG Universal Installer.   
  3. If prompted, click Accept and Download to begin downloading Chrome.
  4. If prompted by macOS, click Allow to allow Safari to download the file from Google.

The PKG file for Chrome will download to the Downloads folder.

3. Download VMware AirWatch Admin Assistant Tool

  1. In the same tab as you downloaded Chrome, paste the link to the VMware Workspace ONE Admin Assistant tool (https://getwsone.com/AdminAssistant/VMwareWorkspaceONEAdminAssistant.dmg) and press Enter. The DMG file will download to the Downloads folder.
  2. If prompted, click Allow to allow Safari to download the installation package.

4. Begin VMware AirWatch Admin Assistant Tool Installation

Download the VMware AirWatch Admin Assistant tool and use it to prepare a third-party macOS app for deployment.

On the dock, perform the following steps:

  1. Click the Downloads folder (next to the Trash).
  2. Click VMwareWorkspaceOneAdminAssistant.dmg.

5. Launch Installer Package

Open the VMware AirWatch Admin Assistant.pkg file.

Double-click the VMware Workspace ONE Admin Assistant.pkg file.

6. Continue Installer

Click Continue.

7. Review and Continue Installer

VMware AirWatch Admin Assistant installer prompts
  1. Review the License Agreement and click Continue.
  2. Click Agree if you agree to the license agreement.

8. Install VMware Workspace ONE Admin Assistant Tool

Install the VMware AirWatch Admin Assistant Tool.

Click Install.

9. Enter Admin Credentials

If prompted for administrative credentials, enter the credentials required to install.

  1. Enter your Admin User Name on the macOS device.
  2. Enter your password for the admin user.
  3. Click Install Software.

10. Close the Installer

  1. Click Close when the installer completes.
  2. Click Move to Trash to clean up the installer.

11. Launch VMware Admin Assistant Tool

Open VMware AirWatch Admin Assistant Tool
  1. Click the Launchpad on the Dock.
  2. Click VMware Workspace ONE Admin Assistant.

12. Drag and Drop Chrome


Drag Skitch into the AirWatch Admin Assistant
  1. Click the Downloads folder on the Dock.
  2. Click and HOLD Chrome.
  3. Drag-and-drop Chrome onto the VMware Workspace ONE Admin Assistant in the box.

The VMware Workspace ONE Assistant Tool begins parsing the file to extract information necessary to deploy the software.

NOTE: MPKG, PKG, DMG, and .APP files are all supported input file types

13. Monitor Process and Reveal Files

Wait for AirWatch Admin Assistant to parse Skitch, a third-party macOS app.
  1. Monitor the progress of the parsing. When it is complete, the wheel changes to a green checkmark.
  2. In the pop-up window, click Reveal in Finder.

14. Review Generated Files


Review Skitch files using munki framework.

In the Finder window:

  1. Change to Column view.
  2. Note the Path of the Output for the Google Chrome files:  ~/Documents/Workspace ONE Admin Assistant/GoogleChrome-<Version>
  3. Note the output from the Assistant tool as described here:
GoogleChrome-<version>.pkg -- The PKG installer file.   (NOTE:  This could also be a DMG or MPKG depending on the file type originally input to Workspace ONE Admin Assistant.)
GoogleChrome-<version>.plist -- A metadata filewhich contains information used by the Workspace ONE Intelligent Hub to determine how to install/uninstall the software
GoogleChrome_<number>.png -- An icon image extracted from the app used for user-friendly display in the console and Workspace ONE Intelligent Hub for macOS

Important: All output for the Admin Assistant tool follows the convention ~/Documents/Workspace ONE Admin Assistant/{AppName-Version}.  

Deploying a 3rd Party macOS App

In this exercise, deploy Skitch, a third-party macOS application, as an internal application in Workspace ONE UEM.

1. Add Native Internal Application

In the Workspace ONE UEM console:

  1. Click Apps & Books.
  2. Expand Applications.
  3. Click Native.
  4. Select Internal.
  5. Click Add.
  6. Click Application File.

2. Upload the Application File

Click Upload.

3. Choose File

Click Choose File.

4. Select Application File



  1. Select the Documents folder.
  2. Select Workspace ONE Admin Assistant.
  3. Select GoogleChrome-{version} (for example, GoogleChrome-92.0.4515.131).
  4. Select GoogleChrome-{version}.pkg
  5. Click Open.

5. Save Local File

Click Save.

6. Continue Adding Application



Click Continue.

7. Upload Metadata File

  1. Select Full Software Management.
  2. Note the link to directly download the VMware Workspace ONE Assistant (in case you forgot to generate the metadata file and are working from a computer where the VMware Workspace ONE Assistant is not installed).
  3. Click Upload.

8. Choose File

Click Choose File.

9. Find and Select the Plist File



  1. Select the Documents folder.
  2. Select Workspace ONE Admin Assistant.
  3. Select GoogleChrome-{version}.
  4. Select GoogleChrome-{version}.plist.
  5. Click Open.

10. Save Plist File

Click Save.

11. Continue Adding Application

  1. Verify that the Application File is shown.
  2. Verify that the Plist File is shown.
  3. Click Continue.

12. Add Image File

  1. Select the Images tab.
  2. Select Click or Drag Files Here.

13. Navigate to Image File

  1. Select the Documents folder.
  2. Select Workspace ONE Admin Assistant.
  3. Select GoogleChrome-{version}
  4. Select one of the PNG files if any exist.
  5. Click Open.

Note: If the Admin Assistant is unable to find a graphic in the package, you can supply your own.

14. Review Scripts Tab

  1. Select the Scripts tab.
  2. The Pre-Install Script runs before the Workspace ONE Intelligent Hub runs the dmg/pkg/mpkg file that installs the application. The pre-install script can be used to set up prerequisite items before the installer runs. The pre-install script must have an exit code of zero (0) for the install to proceed.
  3. The Post-Install Script runs after the Workspace ONE Intelligent Hub runs the dmg/pkg/mpkg file. This can be useful for applying configurations after the software completes the installation.
  4. The Pre-Uninstall Script runs before the Workspace ONE Intelligent Hub initiates the uninstall. The pre-uninstall script must have an exit code of zero (0) for the uninstall to proceed.
  5. The Uninstall Method defines how the Workspace ONE Intelligent Hub uninstalls software. Typically, Remove Copied Items is used for a DMG installer, and Remove Packages is used for a PKG installer.  
  6. The Post-Uninstall Script provides a method to validate an uninstall was completed and potentially handle any cleanup for the uninstall.
  7. The Install Check script assists the Workspace ONE Intelligent Hub with determining whether an install needs to happen. This script can be useful for desired state purposes and ensuring that a software install remains intact on a user's machine. If the script has an exit code of zero (0), the agent assumes an Install is needed.
  8. The Uninstall Check Script validates whether an uninstall has occurred. If the script has an exit code of zero (0), the agent determines an uninstall is (or is still) required.

Note: Use the pre and post install scripts to avoid repackaging installers. By including scripts, you can automate tasks that would normally require user input before/after an install.

For more information, see Pre And Postinstall Scripts on the Munki wiki.

Important: Scripts must include the shebang (#!) statement on the first line. Examples include the following:

#!/bin/bash
#!/bin/sh

15. Review Deployment Tab

  1. Select the Deployment tab.
  2. Note the section for Blocking Apps. If you select Yes, enter the name for any apps that should be closed before an app install or upgrade can proceed.
  3. Note the different Restart actions.
  4. Note the section to include conditions which can further constrain the deployment.

For more information, see Conditions on the Munki wiki.

16. Save and Assign Application

  1. Select Terms of Use.
  2. Review the ability to add terms of use to a software title.  
  3. Click Save & Assign.

17. (Optional) Open Assignment Settings



If shown the Assignments screen, click Add Assignment.

18. Configure Assignment Settings



  1. Enter a name for the assignment. For example, All Devices.
  2. Click in the Assignment Group section and select an assignment group. The selected group appears underneath the text box.
  3. Select a time and date to begin the deployment if you do not want to begin immediately.
  4. Select Auto to deliver the app automatically or On Demand (to deliver the app when requested by the user from the catalog).
  5. Enable Display in App Catalog if you want to display the app in the user's app catalog.

19. Configure Restrictions Settings



  1. Click Restrictions.
  2. Enable Remove on Unenroll if you want the Intelligent Hub to remove the application on Unenroll.
  3. Enable Desired State Management if you want the desired state management feature to re-install the app if the user removes it.
  4. Click Create.

20. Save the Assignment



  1. If additional assignments are required, click Add Assignment and repeat the process starting at Configure Assignment Settings.
  2. Click Save.

21. Publish the Application



Click Publish.

22. Review Published Application Information



Review the newly published application.

Validating macOS App Installation

With the macOS device enrolled, the published application should begin downloading and installing immediately if set to Automatic deployment. This exercise helps you to manually validate the application is installing and/or installed.

1. Launch Terminal

  1. Click the LaunchPad on the Dock.
  2. Enter terminal to filter the LaunchPad apps.
  3. Click Terminal.

2. Review ManagedSoftwareUpdate Log



  1. Tail the ManagedSoftwareUpdate.log file by running the following command. Note: The -F parameter means the tail command continually monitors the file for updates (displaying progress as the software installation continues).
tail -n 20 -F /Library/Application\ Support/AirWatch/Data/Munki/Managed\ Installs/Logs/ManagedSoftwareUpdate.log 
  1. Search for a line in the results stating Google Chrome version [version] (or newer) is already installed. This indicates the software has been installed.

Note: The agent initiates a Managed Software Update within the Munki framework multiple times. Depending on where the agent is within the process of the install, the tail command may output lines similar to the following:

[Date/Time]    Need to install GoogleChrome
[Date/Time]    Downloading GoogleChrome-2-92.0.4515.131.pkg from GoogleChrome-2-92.0.4515.131.pkg
[Date/Time]     The following items will be installed or upgraded:
[Date/Time]         + GoogleChrome-92.0.4515.131
[Date/Time]      Processing installs
[Date/Time]      Installing GoogleChrome-2 (1 of 1)
[Date/Time]     The software was successfully installed.

3. Check for App in the Launchpad

  1. Click the Launchpad icon on the Dock.
  2. Search for your installed app, for example, Chrome.
  3. Check if the Google Chrome application is present.

4. Open Workspace ONE Intelligent Hub

  1. Click the Launchpad icon.
  2. If necessary, swipe or click additional pages. Search for hub.
  3. Click the Workspace ONE Intelligent Hub to launch the Hub.

5. (Optional) Trigger Application Install from Catalog



  1. Click Apps.
  2. Click Install.
  3. If not shown, you might need to click on the category where you assigned the app.
  4. Click the Activity Monitor button.
  5. Review the list of recent activity to see the status of your app.
  6. Click the X to close the Activity Monitor.

Note: The Install button changes to Installing during the app installation and then changes to ReInstall when the installation completes.

Note: The Activity Monitor displays the status of both Internal and Volume-Purchased app installation.

Key Takeaways

  • macOS applications can be deployed using volume-purchased licenses from the Mac App Store or via internal deployment processes.
  • Detailed status on installation progress is delivered to the end-user using the Workspace ONE native application for macOS (not covered in this exercise).
  • Workspace ONE UEM provides an application catalog to allow user and device-specific self-service requests for application installation.

Troubleshooting Non-Store App Deployments

Introduction to Troubleshooting Non-Store Apps

Non-store macOS applications are delivered from Workspace ONE UEM by the Workspace ONE Intelligent Hub. As such, there are some basic prerequisites for macOS software delivery to work. If the prerequisites are not met, there might be unexpected behavior due to the specific installer package that must be worked around.

1. Prerequisites

Non-store macOS apps require the following to work correctly:

Note: AWCM provides notifications to the Intelligent Hub to trigger real-time non-store app installation. In the absence of AWCM, the Intelligent Hub reverts to a scheduled interval to check for new app installation commands.

Gathering Logs

VMware Workspace ONE Intelligent Hub facilitates easy log collection for administrators.  

1. Gather Logs locally on Device

Help
  1. With Intelligent Hub open and the active/focused Window, click the Help menu.
  2. If necessary, expand Debug Session and click Start Session to enable debug (verbose) logging
  3. To collect hub/debug logs, click Show Logs in Finder.
  4. After Hub collects the logs, Finder opens to /private/tmp/  Note the Hublogs folder, and the pre-zipped archive file (containing the contents of the Hublogs folder)
  5. Review the ManagedSoftwareUpdate.log file for errors.

2. Send Hub Logs to Console

Help
  1. With Intelligent Hub open and the active/focused Window, click the Help menu.
  2. Click Collect & Send Logs.

After the logs are collected, administrators can download the logs in the Workspace ONE UEM console by browsing to Devices > List View > {Specific Device} > Attachments  > Documents. Click the specific log set to download locally on your computer.

Determining When to Install Non-Store Apps

When determining whether to install a non-store macOS application, Workspace ONE uses the following information from the manifest PLIST (or the configuration in the console).

Note: The Install Check Script and Installs Arrays are the most flexible methods for determining installation status.

1. Install Check Script

Whether entered in the Scripts tab in the console or entered manually in the PLIST file, the script should exit with a zero (0) return code to trigger an install. The script should include a shebang statement (such as #!/bin/zsh) at the beginning.

2. Installs Array

This key-value pair in the PLIST file specifies identifying information about a binary or file which should be directly compared to determine if the correct version of an app is installed. The installs list can contain any number of items. These can be applications, Preference Panes, Frameworks, or other bundle-style items, Info.plists, or simple directories or files. For more information, see How Munki Decides What Needs To Be Installed.

3. Receipts Array

When a package is installed, the installer leaves a receipt and bill of materials file on the machine. Some packages parsed by the Workspace ONE Admin Assistant will include detail on what receipts will be dropped by the installer in the PLIST file. When a PLIST file lacks the install check script or installs array, the lack of specified receipt(s) triggers an install. For more information, see How Munki Decides What Needs To Be Installed.

 

Troubleshooting Non-Store App Installer Problems

This section lists some of the common problems you might encounter when installing a non-store macOS app.

1. Incorrect Application Name in the Application Catalog

Sometimes an installer package parsed by the VMware Workspace ONE Admin Assistant generates a PLIST file where the application name is incorrect. It is also possible that organizations refer to software by a common or colloquial name that is easily recognized by end users. In either case, administrators can change the name displayed in the Intelligent Hub application catalog before uploading the PLIST to Workspace ONE UEM.

1.1. Open the PLIST Generated by Admin Assistant

Using Admin Assistant to help troubleshoot macOS.
  1. In Finder, browse to the PLIST file for the app in question (usually in ~/Documents/Workspace ONE Admin Assistant/<app name>-<version> ).  
  2. Right-click the PLIST file and select Open With and then select an editor (such as BBEdit).

1.2. Modify PLIST File

Modify the string value for the name key-value pair.  

2. Installers with No Package Version

Sometimes an installer package parsed by the VMware Workspace ONE Admin Assistant generates a PLIST file where the version shows Please Edit Me. This problem must be fixed before uploading the PLIST to Workspace ONE UEM.

2.1. Open the PLIST Generated by Admin Assistant

Using Admin Assistant to help troubleshoot mac OS.
  1. In Finder, browse to the PLIST file for the app in question (usually in ~/Documents/Workspace ONE Admin Assistant/<app name>-<version> ).  
  2. Right-click the PLIST file and select Open With and then select an editor (such as BBEdit).

2.2. Modify Plist File

Modify the string value for the version key-value pair.  

3. Installation is Looping (Always "Installing")

In some instances, an application successfully installs but the Intelligent Hub continually reports the app as "Installing". If you look in the ManagedSoftwareUpdate.log file (see Gathering Logs and Validating macOS App Installation), you'll see the app is constantly marked for installation each time the Hub checks for installed software. This is typically the result of a metadata PLIST that doesn't contain the correct receipt or installs arrays. In this instance, you must make one of the following changes to the metadata PLIST generated by Workspace ONE Admin Assistant:

  1. Validate or Add an Installs Array as discussed in Determining When to Install Non-Store Apps.
  2. Add an Install Check Script (and ensure it returns a zero (0) value return code when an install should proceed).

Common Non-Store App Deployment Use-Cases

ChoiceChanges XML for Complex Installers

Some packages (such as Cisco's AnyConnect client and McAfee's Endpoint Security) deploy multiple components in a single installer package. As an administrator, you might not want to deploy all the components from the package. In this case, you can leverage a feature of the installer known as the ChoiceChanges XML to customize the Installation Type delivered to an individual machine by using the original installer from the vendor (no repackaging required)!

Run ShowChoicesXML Installer Command

With the installer package downloaded, run the following commands:

  1. If necessary, mount the DMG to gain access to the PKG installer:   hdiutil attach ~/Downloads/anyconnect-macos-4.8.00175-predeploy-k9.dmg
  2. Show the ChoiceChanges XML and redirect to a file for reference:  installer -showChoicesXML -pkg /Volumes/AnyConnect\ 4.8.00175/AnyConnect.pkg -target / > ~/Downloads/anyconnect_choices.xml

You now have a file named anyconnect_choices.xml in your ~/Downloads/ folder.

Open Installer Choices XML



  1. Open Finder and select Downloads.
  2. Right-click anyconnect_choices.xml.
  3. Select Open With.
  4. Select your text editor (such as BBEdit or Visual Studio Code).

Examine Installer Choices XML



  1. Note the presence of a number of "Dictionaries" which correlate to each "Choice" on the Installation Type screen in the Installer.
  2. Note the choiceIdentifier key-value pair denoting which specific choice is selected.

Build ChoiceChanges XML

Using the following template, create a new file and start building your ChoiceChanges XML.   Be sure to create a dictionary for each choiceIdentifier, and modify the value for attributeSetting to either 0 (do not install) or 1 (install). In the case of my previous example for Cisco AnyConnect, I would need dictionaries for each of the choiceIdentifiers:

  • choice_vpn
  • choice_websecurity
  • choice_fireamp
  • choice_dart
  • choice_posture
  • choice_iseposture
  • choice_nvm
  • choice_umbrella

ChoiceChanges XML Template:

<key>installer_choices_xml</key>
<array>
    <dict>
        <key>attributeSetting</key>
        <integer>1</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>INSERT_CHOICE_IDENTIFIER_HERE</string>
    </dict>
    <dict>
        ...
    </dict>
</array>

Fully-Built ChoiceChanges XML for Cisco AnyConnect (installing ONLY vpn):

<key>installer_choices_xml</key>
<array>
    <dict>
        <key>attributeSetting</key>
        <integer>1</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_vpn</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_websecurity</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_fireamp</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_dart</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_posture</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_iseposture</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_nvm</string>
    </dict>
    <dict>
        <key>attributeSetting</key>
        <integer>0</integer>
        <key>choiceAttribute</key>
        <string>selected</string>
        <key>choiceIdentifier</key>
        <string>choice_umbrella</string>
    </dict>
</array>

Modify Metadata Plist from Admin Assistant

  1. Remove any references to receipts for components you will not be installing. This prevents Workspace ONE from attempting to reinstall when it discovers those receipts are missing.
  2. Insert the key-value pair for the ChoiceChanges XML to change your Installation Type.

Review Modified Metadata Plist

  1. Note the presence of the new installer_choices_xml key-value pair which uses the ChoiceChanges XML you built earlier
  2. Note the reduced receipts key-value pair which specifies the receipt(s) for ONLY the component(s) being installed

Note:  At this point, you can upload the metadata PLIST and application file as documented earlier in this guide.

Installers Requiring Configuration Files

Rather than reading configuration data from CFPreferences or NSUserDefaults (which can be managed by profiles), some installers look for configuration information in specific, hardcoded file locations to pre-configure the software for the end user. This section shows how you can accomodate this scenario in Workspace ONE UEM.

1. Option 1: Create a Pre-Install Script


Enter pre-install script to help with mac OS troubleshooting.

Use a Pre-Install script to create the file and populate the contents of that file dynamically. This method eliminates the need to repackaging software to include the configuration file. In the following example script, edit the following:

  1. PATH string.
  2. The ini or xml file name in lines 4 through 6.
  3. The file contents (between the EOM lines).
#!/bin/sh
PATH="/tmp/your-app"
/bin/mkdir -p "$PATH"
/usr/bin/touch "$PATH/cfg.ini"
/bin/chmod 644 "$PATH/cfg.ini"
/bin/cat > "$PATH/cfg.ini" <<- EOM
[customer]
Code=COMPANY_CODE
EOM

2. Option 2: Use Items_To_Copy Array

For DMG-style installers that use scripts with hard-coded paths, use the items_to_copy array in the PLIST. To make this work, you must include the following XML content in the PLIST and make the following modifications:

  1. Include the destination directory where you want to copy the files from the mounted DMG (basically, a staging area on the file system).
  2. Include the mode value to set permissions on the copied file.
  3. Include the source item on the mounted DMG.
    Note: You might need to include folder structures if the item is in a subfolder on the mounted DMG.
<key>installer_type</key>
<string>copy_from_dmg</string>
<key>items_to_copy</key>
<array>
    <dict>
        <key>destination_path</key>
        <string>/tmp/</string>
        <key>mode</key>
        <string>644</string>
        <key>source_item</key>
        <string>Installer.pkg</string>
    </dict>
    <dict>
        <key>destination_path</key>
        <string>/tmp/</string>
        <key>mode</key>
        <string>755</string>
        <key>source_item</key>
        <string>scripts/install_unattended.sh</string>
    </dict>
</array>

App-Specific Deployment Guidance

Deploying Microsoft Office for macOS

In January 2019, Microsoft announced the Office apps for Mac available on the Mac App Store. A common question we receive is whether to deploy the apps from the Mac App Store or via Internal Apps (using the downloaded *.pkg installers). This section aims to provide guidance as to which version to deploy.

Note: Review Deploy Office for Mac from the Mac App Store for official guidance from Microsoft.

Using Mac App Store Deployment (Volume-Purchased) Using Internal Apps (*.pkg) Deployment
  • Deploy the most recent current channel release
  • Users MUST be Office 365 or Microsoft 365 licensed on a plan that includes downloadable apps
  • Large installer caching via macOS Caching Services
  • Automated software updates via Mac App Store
  • Deploy specific non-current Office versions, or beta/preview (Insiders) versions
  • Deploy to users with O365, M365, or Microsoft Volume Licenses (using the VL Serializer)
  • Scripted Updates via Microsoft AutoUpdate (MAU) tool
  • Scripted install directly from Microsoft CDN.

Summary and Additional Resources

Conclusion

This operational tutorial provided steps to deploy macOS apps for two scenarios:

  • Deploy macOS store applications to devices as volume-purchased apps.
  • Deploy non-store macOS apps as internal apps in Workspace ONE UEM.

Basic troubleshooting for each method was also provided.

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.

For information about deployment, see Deploying Workspace ONE Intelligence and VMware Carbon Black Cloud: Workspace ONE Operational Tutorial.

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 Managing Windows 10 Devices with Workspace ONE, see the Understanding Windows 10 Management activity path. The content in this path helps you establish a basic understanding of Windows 10 management in the following categories:

Change Log

The following updates were made to this guide. 

Date Change
8/27/2021 Updates to all sections
  • Updated Screenshots
  • Clarifications and Minor Verbiage changes

Added the following chapters/articles

  • Configuring the Hub Catalog
  • Common Non-Store App Deployment Use-Cases
08/12/2020

Removed the following chapters

  • Deploying a 3rd Party macOS App 
  • Deploying a 3rd Party macOS App as a Product (Legacy)

Added the following chapters/articles

  • Deploying Store vs Non-Store macOS Apps
  • Deploying Volume-Purchased macOS Apps
  • Troubleshooting Volume-Purchased macOS App Installs
  • Deploying a Non-Store macOS App
  • Troubleshooting Non-Store App Deployments
3/16/2021 Added the following chapters/articles
  • App-Specific Deployment Guidance
06/2/2021 Adding the following chapters/articles
  • Common Non-Store App Deployment Use-Cases

About the Authors

This tutorial was written by:

  • Robert Terakedis, Senior Technical Marketing Manager, End-User-Computing Technical Marketing, VMware
  • Hannah Jernigan, Technical Marketing Manager, End-User-Computing Technical Marketing, VMware

Filter Tags

Workspace ONE Workspace ONE UEM Document Operational Tutorial Advanced macOS Deploy App & Access Management Business Continuity Office365