Distributing Scripts to macOS Devices: Workspace ONE Operational Tutorial

Overview

Although Omnissa Workspace ONE® UEM provides extensive endpoint management capabilities for macOS devices, there might be situations where an IT admin needs to deploy a script to a group of endpoints to do advanced management or customization processes. Using the Scripts resource within Workspace ONE UEM, you can easily deploy and execute Bash, Python 3, and Zsh scripts to macOS devices.

Variables are supported within the Scripts resource to protect sensitive data, such as passwords and API keys. Scripts can also use UEM lookup values to determine things like device ID or username. Once integrated with Workspace ONE Intelligent Hub, IT admins can even make various scripts available to end-users as part of their App catalog.

The Scripts resource is included in the Workspace ONE Advanced and Enterprise licensing tiers, as well as an Add-On SKU. For customers who are not licensed to use the Scripts resource, there is an alternative mechanism for deploying scripts into your environment. This alternative mechanism leverages internal apps as payload-free packages. This tutorial will discuss the process for deploying scripts to endpoint devices using the Scripts resource, as well as outline the alternative payload-free package method for those not licensed to use the Scripts resource.

Purpose of This Tutorial

This tutorial takes you through the steps to deploy scripts to macOS devices using the Scripts resource within Workspace ONE UEM. The tutorial will also offer an alternative method for delivering scripts as payload-free packages for customers who are not licensed to use the Scripts resource.

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.

Deploying Scripts Using the Scripts Resource

  For customers that have either the Workspace ONE UEM Advanced or Enterprise licensing tier, Scripts is an easy way to run Bash, Python 3, or Zsh for endpoint configurations on macOS devices. This exercise will guide you through the process of deploying a script to an endpoint using Workspace ONE UEM Scripts functionality. The steps are sequential and build upon one another, so make sure that you complete each step before going to the next step.

For this exercise, you will use a simple script that creates a text file on the desktop of the device’s logged-in end user. However, this process is just as useful for advanced scripts that perform complex administrative tasks.

Prerequisites

The procedures in this tutorial were validated on the following macOS and application versions. The results of these procedures may vary if you use older versions.

  • Apple device running macOS version 13.1 (Ventura) or later
  • Workspace ONE Intelligent Hub for macOS version 2310 or later
  • Workspace ONE UEM version 2310 (SaaS) or later

For more information, see the Omnissa Workspace ONE UEM Documentation.

Procedure

To get the desired result, perform the following steps:

  1. In the Workspace ONE UEM console, select Resources. Then select Scripts.
  2. Click Add, and select macOS from the dropdown.

Graphical user interface, text, application Description automatically generated

  1. Name the script Create-File-On-Desktop. Leave App Catalog Configuration deactivated. Click Next.
  2. Set the Language to Bash, and the Execution Context to System.
  3. Paste the following script sample into the Code window. 
#!/bin/sh
loggedInUser="root"
while [[ "$loggedInUser" == "root" ]];
do
sleep 10
loggedInUser=`/bin/ls -l /dev/console | /usr/bin/awk '{ print $3 }'`
done
touch /Users/$loggedInUser/Desktop/textfile.txt

 

Graphical user interface, application Description automatically generated

  1. Click Next, then click Save.
  2. Click Save.
  3. In the Scripts list, check the new script you just created, and click Assign.
  4. Click New Assignment. Enter a name for the assignment. For example, All macOS Devices.
  5. 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).
  6. Click Next.
  7. Check Run Once Immediately.

Graphical user interface, text, application Description automatically generated

  1. Click Add.
  2. Click Save & Publish, and then Publish.

Validate Successful Execution of the Script

  1. To validate that the script has successfully executed, log into a macOS device that is included in the assignment you configured earlier. Look on the desktop for a file called textfile.txt.

    Note: If you have just logged into your macOS device, it may take a few minutes for the script to execute.
  2. You can also check the execution status in the Workspace ONE UEM console by selecting Devices, and then List View.
  3. Click a macOS device in the list, and then select Scripts.
  4. Look for the script you created earlier. Check the Status of the script. If it was successful, the status will be Executed.

Graphical user interface, text, application, email Description automatically generated

Note: If the script does not appear on the list, try refreshing the screen. It might take a moment for Intelligent Hub to update Workspace ONE UEM on the status of the script’s execution.

Distributing Scripts as Internal Apps

Workspace ONE UEM provides a method to distribute non-app store software packages to macOS devices. This delivery method can be used to deliver and execute scripts on endpoint devices. This tutorial focuses on leveraging Internal Apps to deliver scripts as payload-free packages. This method is valid for customers who are not licensed to use the Scripts resource or who are using an on-premises version of Workspace ONE UEM.

For this exercise, you will use a simple script that creates a text file on the desktop of the logged-in end user. However, this process is just as useful for advanced scripts that perform complex administrative tasks. As part of this exercise, you will create a payload-free package, and use the Install Scripts option for Internal Apps to run the script during installation of the package.

Note: In this tutorial, you will use options within Workspace ONE UEM to deploy and execute your script. It is possible to embed your script within the payload-free package and execute it from there. However, that will require you to re-package the payload-free package every time you make a change to the script. For this tutorial, you will not include the script in the payload-free package, but the method is available as an option if you need it.

Prerequisites

The procedures in this tutorial were validated on the following macOS and application versions. The results of these procedures may vary if you use older versions.

  • Apple device running macOS version 13.1 (Ventura) or later
  • Workspace ONE Intelligent Hub for macOS version 2310 or later
  • Workspace ONE UEM version 2310 (SaaS) or later

Ensure you are logged in to the machine used to create the internal app using a payload-free package and install the following:

Note: Although a macOS Developer ID Installer Certificate is not required to build a payload-free package, it is considered a best practice.

For more information, see the Omnissa Workspace ONE UEM Documentation.

Determine the Developer ID Installer Certificate Common Name

Before you begin creating a payload-free package, you must acquire the Developer ID Installer Certificate common name. The Developer ID Installer Certificate is not required to perform the steps in this section, but it is recommended for production environments.

Note: If you do not have a macOS Developer ID Installer certificate, you can skip this section.

To find your macOS Developer ID Installer Certificate common name, follow the steps:

  1. Copy the Developer ID Installer Certificate common name from your device’s keychain. On the macOS device that you will use to create the payload-free package, go to Applications, click the Utilities folder, and launch Keychain Access.
  2. Click the login keychain.
  3. Find your Developer ID Installer certificate.
  4. Copy the title of the Developer ID Installer certificate (this will match the Common Name). Paste this somewhere for safekeeping. You will need it later.

Create a Payload-Free Package

In a macOS installer package, scripts and files are executed and installed by the installer process on the macOS device. The installer process within macOS also supports packages that do not contain a list of files to install (for example, payload-free). In these payload-free packages, the package defines a format whereby scripts can be executed within macOS. In this exercise, you will create a payload-free package that will be used in Workspace ONE UEM to facilitate the execution of your script.

To create a payload-free package:

  1. On your macOS device, select the Finder icon on the dock.
  2. Create a new folder with the script's intended function in the location of your choice.

    In the example shown, the package folder structure is located in ~/Desktop/Create-Text-File.
  3. Create the necessary folder structure for the payload-free package as shown in the below screenshot.

Graphical user interface, table Description automatically generated

Folder descriptions are as follows:

  • Build - This folder contains the output (for example, the payload-free package) created by the pkgbuild commands.
  • Payload - This folder contains a blank set of folders (private, var, and tmp) to force the package to leave a receipt.
  • Scripts - This folder contains the preinstall and postinstall scripts (for example, you can place scripts in this folder that you wish to execute on devices).

    Note: Although a true payload-free package contains only the pre/post install script, the lack of a payload prevents the installer from generating a receipt file when the package is installed. Without a receipt file, the underlying framework of Workspace ONE UEM's Internal Apps for macOS will continually execute the package (for example, re-run the script). As such, we can supply a basic set of filesystem folders so the resultant payload-free package leaves a receipt file when it completes successfully.

    Note: If you wanted to include a script in the payload-free package, you would need to create a script called postinstall and place it in the scripts folder. Then, you would need to make the script executable using the command, chmod a+x postinstall. This option will not be covered in the following steps.
  1. In Finder, select Applications. Click into the Utilities folder. Launch Terminal.
  2. Now you will build the payload-free package. Enter the following command into Terminal. Enter the administrative password when prompted. 
sudo pkgbuild --install-location / --identifier “<package_identifier>” --version “<package_version>” --root <package_root_directory> --scripts <package_scripts_directory> --sign “<developer_ID_installer_certificate>” <output_package_name>

Note: In the pkgbuild command line, supply the following modified values as appropriate (bolded in the previous command line):

<package_identifier> - Generally in the format of com.<company>.<script purpose>. For this example, you will use com.omnissa.create-text-file.

<package_version> - The version of the package being deployed. For this example, you will use 1.0.0

<package_root_directory> - Filesystem location of the payload folder. For this example, you will use ~/Desktop/create-text-file/payload.

<package_script_directory> - Filesystem location of the scripts folder. For this example, you will use ~/Desktop/create-text-file/scripts.

<developer_ID_installer_certificate> - Use the common name of the appropriate developer ID installer certificate that you copied in Determine Developer ID Installer Certificate Common Name. Although it is considered a best practice, the Developer ID Installer Certificate common name is optional. If you do not have a Developer ID Installer Certificate, you can exclude this value from the command.

<output_package_name> - Filesystem location and name of the built package. For this example, you will use ~/Desktop/create-text-file/build/Create-Text-File.pkg.

Important: When modifying the content of the package, it is critical to increment the <package_version> number in the pkgbuild command line. Failure to increment the version with each rebuild may result in problems during testing, particularly for devices that have already installed a previous version of the package.

Prepare a Payload-Free Package for Deployment

Now that you have created a payload-free package, the next step is to prepare the package for deployment as an internal app. This section covers generating the necessary metadata for the package and reviewing key pieces of the metadata that could be modified.

  1. In Finder, click Applications, and double-click the Omnissa Workspace ONE Admin Assistant.
  2. Locate the package you created in the previous section. Drag and drop the package onto the Omnissa Workspace ONE Admin Assistant.
  3. After parsing is complete, click Reveal in Finder.

Graphical user interface, text Description automatically generated

  1. In the Finder window, expand the folder named after your <Package Name>-<Version>. (Create-Text-File-1.0.0 in this example). Note the existence of the PKG and the corresponding .plist files.
  2. Right-click the plist file and select Open With.
  3. Select your script editor (such as BBEdit or Xcode).
  4. Scroll down through the file until you find the receipts key.

A screen shot of a computer code Description automatically generated

The receipts key determines if the payload-free package has been executed. By adding a payload in the package (even though it is an empty folder structure), the package outputs a BOM and plist file to the receipts folder. When the package is executed on a device, bom and plist files are created when the package completes successfully.

Note: Receipts are added to /private/var/db/receipts when a package with a payload (folder structure -- even if empty) is executed. If a payload structure is not included (or the --root parameter is excluded from the pkgbuild command), no receipts are left when the package is installed.

Deploy a Payload-Free Package in Workspace ONE UEM

In this exercise, you will add the payload-free package as an internal app in the Workspace ONE UEM Console. This sends the package to the enrolled devices in the appropriate assignment groups and executes your script with root privileges.

  1. In the Workspace ONE UEM console, select Resources. Then select Apps.
  2. Select Native, and then click Internal.
  3. From the Add dropdown menu, select Application File.

Graphical user interface, application, Word Description automatically generated

  1. Click Upload and select Choose File. Navigate to the folder that was created by the Workspace ONE Admin Assistant. Choose the PKG file and click Upload.
  2. Click Save.
  3. After the upload has completed, click Continue.
  4. To upload the Metadata file, click Upload and choose the .plist file from the same folder. Click Save.

A picture containing background pattern Description automatically generated

  1. After the upload has completed, click Continue.
  2. Click Scripts.

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 installation to proceed.

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.

Graphical user interface, application, email Description automatically generated

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.

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.

The Post-Uninstall Script provides a method to validate that an uninstall was completed and potentially handle any cleanup for the uninstall.

Graphical user interface, application Description automatically generated

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.

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.

Graphical user interface, application Description automatically generated

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 installation.

  1. Under Install Scripts, paste the following script sample into the Post Install Script window. 
#!/bin/sh
loggedInUser="root"
while [[ "$loggedInUser" == "root" ]];
do
sleep 10
loggedInUser=`/bin/ls -l /dev/console | /usr/bin/awk '{ print $3 }'`
done
touch /Users/$loggedInUser/Desktop/textfile.txt

Graphical user interface, text, application, email Description automatically generated

  1. Click Deployment.
  2. Note the section for Blocking Applications. If you select Yes, enter the name of any apps that should be closed before an app install or upgrade can proceed. For this exercise, you will select No.
  3. Note the different Restart actions. For this exercise, you will select None.
  4. Note the section to include conditions that can further constrain the deployment.

Graphical user interface, application Description automatically generated

  1. Optionally, you can assign an Application Terms of Use by clicking Terms of Use, and selecting an existing Terms of Use from the dropdown. You can also create a new Terms of Use by clicking the Manage Terms of Use button. You will not create Terms of Use for this exercise.
  2. Click Save & Assign.
  3. Enter a name for the assignment. For example, All macOS Devices.
  4. Click in the Assignment Group section and select an assignment group. The selected group appears underneath the text box.
  5. Select a time and date to begin the deployment if you do not want to begin immediately.
  6. Select Auto to deliver the app automatically or On Demand (to deliver the app when requested by the user from the catalog). For this exercise, select Auto.
  7. Enable Display in App Catalog if you want to display the app in the user's app catalog. For this exercise, leave this option deactivated.

Graphical user interface, text, application Description automatically generated

  1. Click Create.
  2. If additional assignments are required, click Add Assignment and repeat the process you just stepped through. When all assignments have been created, click Save.
  3. Click Publish.

Validate Successful Execution of the Payload-Free Package

  1. To validate that the payload-free package has successfully installed, log into a macOS device that is included in the assignment you configured earlier. Look on the desktop for a file called textfile.txt.

    Note: If you have just logged into your macOS device, it might take a few minutes for the app install to complete.
  2. You can also check the installation status in the Workspace ONE UEM console by selecting Devices, and then List View.
  3. Click a macOS device in the list, and then select Apps.
  4. Look for the app you created earlier. In this example, you will look for Create-Text-File. Check the App Status. If it was successful, the status will be Installed.

Note: If the App Status is Not Installed, try refreshing the screen. It may take a few minutes for Intelligent Hub to update Workspace ONE UEM on the status of the installation.

Summary and Additional Resources

 This operational tutorial provided steps to distribute scripts using two different methods available in Workspace ONE UEM. The methods discussed included using the Scripts resource to execute scripts on devices and using Internal Apps to deploy a payload-free package that executes your script.

Procedures included: 

  • Creating and assigning scripts using the Scripts resource.
  • Creating a payload-free package.
  • Preparing a payload-free package for deployment.
  • Deploying a payload-free package in Workspace ONE UEM.

Additional Resources

 For more information on managing macOS devices with Workspace ONE UEM, see Configuring Basic macOS Management.

You may also wish to read these additional operational tutorials from macOS on Omnissa Tech Zone.

Changelog

The following updates were made to this guide:

Date

Description of Changes

06/05/2024

  • Updated for Omnissa docs, KB, and Tech Zone links. 

03/27/2024

  • Validated and updated procedures on newer OS and Workspace ONE platforms.
  • Added additional available resources for managing macOS.

12/09/2022

  • Added a section discussing how to use the Scripts resource in Workspace ONE UEM to deploy scripts to macOS endpoints.
  • Added steps to validate the successful execution of scripts and payload-free packages.
  • Updated procedures and screenshots to align with the latest version of Workspace ONE UEM.

03/30/2019

  • Guide was published.

About the Author and Contributors

The latest version of this tutorial was written by:

This tutorial was originally written by:

  • Robert Terakedis, EUC alumni.

Feedback

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


Filter Tags

Workspace ONE Workspace ONE UEM Document Operational Tutorial Intermediate macOS