Menu Close

Setup Your Mac (1.15.0) with SYM-Helper (1.2.0) via swiftDialog (2.5.0)

Optimized to leverage SYM-Helper (1.2.0), Setup Your Mac (1.15.0) leverages new features of swiftDialog (2.5.0)

Introduction

Apple’s Automated Device Enrollment helps streamline Mobile Device Management (MDM) enrollment and device Supervision during activation, enabling IT to manage enterprise devices with “zero touch.”

Setup Your Mac is a script which aims to simplify initial device configuration by leveraging swiftDialog and Jamf Pro Policy Custom Events to allow end-users to self-complete Mac setup post-enrollment.

SYM-Helper is a stand-alone macOS app to help Jamf Pro admins more easily deploy Setup Your Mac.

Setup Your Mac (1.14.0) screencast (01:51; no audio; edited for time)

About …

Let’s level-set with a few about slides …

Setup Your Mac with SYM-Helper: About (04:33); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

swiftDialog

None of this would be possible without Bart and swiftDialog!

Bart Reardon has provided the Mac Admin community swiftDialog: An open-source utility written in SwiftUI — which requires macOS Monterey 12, or later — that displays a popup dialog which can include content-rich messages for your end-users.

dialog --icon /Library/Application\ Support/Dialog/Dialog.app --title "About swiftDialog" --message "**An open source admin utility app for macOS 12+**  \n\nWritten in SwiftUI, swiftDialog displays the content to your users in a modern UI with support for markdown, images, videos and much more …  \n\n\![Sun](https://pngimg.com/uploads/sun/sun_PNG13449.png)\![Moon](https://cdn-icons-png.flaticon.com/256/4445/4445942.png)" --height 500 --infotext

While Bart is fond of saying that swfitDialog itself has “no brains,” swiftDialog can return various values from user input, on which your script can act and continue processing.

The project is available on GitHub, and Bart has an extensive Wiki with detailed examples.

Additionally, there’s built-in help when you need a quick answer.

dialog --help title

   -t,  --title <text>

	Set the Dialog title

        Text beyond the length of the title area will get truncated
        Default Title is "An Important Message"
        Use keyword "none" to disable the title area entirely
Setup-Your-Mac.bash

Setup Your Mac is a 3,000 plus line Bash script which was originally inspired by Adam’s code and then James’ code, on which it still relies.

Some recent heavy-lifting has been provided by Bart himself, for which I’m personally grateful.

While we prompt users to initiate Setup Your Mac via Self Service, you can have Setup Your Mac execute automatically immediately after enrollment via a PreStage Enrollment package (and thanks to Andrew Clark for documenting his approach for using Setup Your Mac with Jamf Pro enrollmentComplete trigger.)

Users are presented with an estimated duration of the entire process — based on their current Internet connection and users can see detailed information on the progress of application installations, including if there are any failures.

Test-drive

If you’d like to immediately test-drive SYM, the following one-liner will download a time-stamped copy of the latest release of Setup-Your-Mac.bash and execute it with elevated privileges:

timestamp=$( date '+%Y-%m-%d-%H%M%S' ) ; curl -o ~/Downloads/Setup-Your-Mac-via-Dialog-$timestamp.bash https://raw.githubusercontent.com/setup-your-mac/Setup-Your-Mac/main/Setup-Your-Mac-via-Dialog.bash ; sudo bash ~/Downloads/Setup-Your-Mac-via-Dialog-$timestamp.bash
SYM-Helper.app

Leslie Helou has outdone himself yet again with SYM-Helper.

SYM-Helper a standalone macOS app which makes the always tedious work of building your custom policyJSON an absolute delight!

SYM-Helper makes it a breeze to customize which fields initially display, so you can prompt your users for the exact information dictated by your business requirements.

But Leslie didn’t stop there: Many variables — but not all — can be modified or toggled in SYM-Helper.

Jamf Pro Policy Pre-work

Jamf Pro Policy Pre-work (02:33); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

Each Jamf Pro policy you wish to execute with Setup Your Mac needs to first have a Custom Trigger. (Take some time on a naming convention and use it consistently; whomever follows you when you land your next “big gig” will be glad you did.)

Next, please be aware that SYM-Helper leverages a few fields from a policy’s Self Service tab, even if the policy is disabled from being displayed in Self Service:

  • Jamf Pro Policy
    • Self Service
      • Display Name
      • Description
      • Icon

Pro Tip: Ensure your Self Service Description fields don’t contain any special characters or single quotes (smart quotes work as expected and look better, too).

My personal recommendation is that you have dedicated enrollment policies.

A number of MacAdmins have recently reported issues with their customized Setup Your Mac script going sideways and the root cause was too many “racing-stripes” in the polices being executed by Setup Your Mac.

SYM-Helper.app
Download

Pro Tip: Run SYM-Helper.app on an enrolled, fully configured Mac

The latest version of SYM-Helper.app is available on GitHub.

Connections

When you first launch SYM-Helper, you’ll be prompted to establish a connection to your Jamf Pro server.

  • Display Name: User-friendly name for the Jamf Pro server (i.e., “Stage”, “Production”)
  • Server URL: The Jamf Pro URL for this server, including https://
  • For Jamf Pro 10.49.0 (and later), the recommended approach is to leverage the new API Roles and Clients, granting:
    • Read Buildings
    • Read Departments
    • Read Policies
Jamf Pro 10.49.0 (and later): Create a dedicated API Role for SYM-Helper
Jamf Pro 10.49.0 (and later): Assign the SYM-Helper API Role to a dedicated SYM-Helper API Client

Pro Tip: The list of configured servers is shared among Leslie’s apps and is available at the following location:

~/Library/Group Containers/group.PS2F6S478M.jamfie.SharedJPMA/Library/Preferences/group.PS2F6S478M.jamfie.SharedJPMA.plist

Script Source

SYM-Helper: Script Source (01:15); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

As just one example of how Leslie outdid himself with SYM-Helper, one of my favorite features is the ability to specify a script source.

Click the Settings icon in the bottom, left-hand corner to quickly access the default source, which is the “main” branch.

Leslie recently added an icon to both easily see which script version you’re using and to display the raw script in your default browser with a single click.

Let’s change to a different branch, in this case, “1.13.1”. (See branches for a current list; If you have your own fork of Setup Your Mac, you may wish to try specifying it in SYM-Helper.)

Let’s change to a different branch, in this case, “1.15.1”. (See branches for a current list.)
Settings

SYM-Helper: Settings (00:41); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

Click the Settings icon in the bottom, left-hand corner and populating your customized list of Buildings and Departments is just a click away.

  • SYM-Helper
    • Settings
      • Script Source
      • Branding
        • Banner Image
        • Banner Display Text
        • Light Icon
        • Dark Icon
      • Support
        • Team Name
        • Team Phone
        • Team Email
        • KB
        • Error KB
        • Team Website
      • Prompt For …
        • Username
          • Prefill
        • RealName
          • Prefill
        • Computer Name
          • Prefill
        • Email
          • Prefill
          • Domain Name
        • Asset Tag
          • Disable regex
        • Room
        • Building
        • Department
        • Position
        • Configuration
        • Movable in Production
      • Buildings
      • Departments
Default Configuration

SYM-Helper: Default Configuration (05:09); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

A default Configuration is required before being able to generate a customized script with SYM-Helper.

We’ve already completed our Jamf Pro policy pre-work and have dedicated enrollment policies, so let’s filter on “enrollment.”

You can easily add policies from the left column to the selected configuration by double-clicking.

Click the plus button to add a validation.

Multiple triggers can be displayed to the user as a single item by first selecting them, then clicking “group.”

Next, we’ll add a Local validation of filevault.

While the validation for FileVault is built-in to Setup Your Mac, you’ll still need to actually enable FileVault via Jamf Pro; we’re using a Configuration Profile as part of our PreStage.

{
    "listitem": "FileVault Disk Encryption",
    "subtitle": "FileVault provides full-disk encryption",
    "icon": "https://ics.services.jamfcloud.com/icon/hash_f9ba35bd55488783456d64ec73372f029560531ca10dfa0e8154a46d7732b913",
    "progresstext": "FileVault is built-in to macOS and provides full-disk encryption to help prevent unauthorized access to your Mac.",
    "trigger_list": [
        {
            "trigger": "filevault",
            "validation": "Local"
        }
    ]
},

You’ll always want to end with a Local Validation of recon and also specify the command of recon to update your Jamf Pro server for the newly enrolled Mac.

{
    "listitem": "Computer Inventory",
    "subtitle": "The listing of your Mac’s apps and settings",
    "icon": "https://ics.services.jamfcloud.com/icon/hash_ff2147a6c09f5ef73d1c4406d00346811a9c64c0b6b7f36eb52fcb44943d26f9",
    "progresstext": "A listing of your Mac’s apps and settings — its inventory — is sent automatically to the Jamf Pro server daily.",
    "trigger_list": [
        {
            "trigger": "recon",
            "validation": "recon"
        }
    ]
}

Let’s copy-pasta data from our Self Service Update Inventory policy.

We’ll click “Generate Script,” save the file to the desktop and in a previously elevated Terminal window on an enrolled Mac, we’ll execute the script.

The so-called “Welcome” screen looks good …

… Deep, Cleansing Breath …

… but I don’t want to continue filling out all these fields for the rest of the demos, so let’s turn off most of the fields in SYM-Helper.

We’ll toggle off most of the prompts and then click “Generate Script” and replace our previous script, save and re-run the script.

Nice! Now we only have to enter Asset Tag.

OK, this is working, but it isn’t doing too much; let’s add some more policies in SYM-Helper.

Add policies from the left column to the selected configuration by double-clicking; Drag-and-drop to reorder.

New in version 1.13.1, you can specify an app or a complete filepath.

We’re using a Remote Validation to confirm the Sophos Endpoint services are running, so we’ll manually enter Remote for the Validation.

We’ll group these two list items so that they’re displayed as a single item to the user.

We’ll repeat for GlobalProtect.

After double-checking our work, we’ll click “Generate Script,” save the file to the desktop and in a previously elevated Terminal window on an enrolled Mac, we’ll execute the script.

Hey! This is looking good!

“Complete” Configuration

SYM-Helper: “Complete” Configuration (02:29); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

Our previous work on the default configuration is here, so let’s use it to build what we refer to as our “complete” configuration.

We’ll grab the variable name for the third configuration and then clone the existing “Default” Configuration.

You’ll make it easy on yourself if you use these exact variables names when naming your configurations in SYM-Helper.

Later, you can manually edit the display names as required in your preferred code editor.

if [ "$promptForConfiguration" == "true" ] && [ -z "${presetConfiguration}" ]; then
    configurationJSON='{
            "title" : "Configuration",
            "style" : "radio",
            "default" : "'"${configurationOneName}"'",
            "values" : [
                "'"${configurationOneName}"'",
                "'"${configurationTwoName}"'",
                "'"${configurationThreeName}"'"
            ]
        }'
fi

We’ll add policies from the left column to our “complete” configuration by double-clicking; policy order can be changed via drag-and-drop.

Pro Tip: I’ve found it easiest to build and test my customized Setup Your Mac script by running SYM-Helper on an enrolled, fully configured Mac.

Looks like I forgot to group these two Office items; we’ll generate the script and the run in our previously elevated Terminal.

Nice! This is looking good.

Additional Configurations

SYM-Helper: Additional Configuration (02:37); Music: Bensound.com/royalty-free-music (License code: SL9XDAB28DEXQSON)

Let’s use the so-called “complete” configuration to build what we refer to as our “recommended” configuration.

Before we do, let’s again copy-pasta the variable name for the second configuration.

if [ "$promptForConfiguration" == "true" ] && [ -z "${presetConfiguration}" ]; then
    configurationJSON='{
            "title" : "Configuration",
            "style" : "radio",
            "default" : "'"${configurationOneName}"'",
            "values" : [
                "'"${configurationOneName}"'",
                "'"${configurationTwoName}"'",
                "'"${configurationThreeName}"'"
            ]
        }'
fi

This time, we’ll remove policies from the right column by double-clicking.

Wow! That was easy!

We’ll check our work in a previously elevated Terminal window; this is looking good.

Let’s repeat the process for the “required” configuration.

Let’s execute the script as-is in a previously elevated Terminal window.

Again, you’ll make it easy on yourself if you use these exact variables names when naming your configurations in SYM-Helper.

All three Configurations are looking good.

Setup-Your-Mac.bash

Work-in-process; please see: Setup Your Mac (1.14.0): Under-the-hood

Support
SYM-Helper.app

Best-effort support for SYM-Helper is offered in the  #setup-your-mac Channel on the Mac Admins Slack (free; registration required.)

Feature Requests & Bug Reports

Please submit feature requests and report bugs via GitHub.

Setup-Your-Mac-via-Dialog.bash

Best-effort support for the Setup-Your-Mac-via-Dialog.bash script is offered in the  #setup-your-mac Channel on the Mac Admins Slack (free; registration required.)

Feature Requests

Submit feature requests on GitHub.

Please note that while all requests are welcome, finding available cycles to custom-code a feature we won’t use in our production environment is always challenging.

Bug Reports

Before submitting a Setup Your Mac bug report on GitHub, please review the open swiftDialog issues to help determine the source of the issue.

Resources
Screencasts

The following screencasts may prove helpful during your Setup Your Mac implementation:

Posts

The following blog posts may prove helpful during your Setup Your Mac implementation:

FAQ
Who authored SYM-Helper?

Leslie Helou

Where can I download SYM-Helper?

The latest release of SYM-Helper is available on GitHub.

Which versions of Setup Your Mac are supported with SYM-Helper?

SYM-Helper 1.0.0 supports Setup Your Mac versions 1.13.0 (and later).

Can SYM-Helper “open” my existing Setup Your Mac script?

In the traditional sense, SYM-Helper doesn’t open files, it generates Setup-Your-Mac.bash (based on a GitHub-hosted source script, merged with settings you specify with the SYM-Helper app).

Settings > Script Source can be changed to any GitHub-hosted URL; in the following example, the development branch has been manually specified.

How does SYM-Helper “save” my customized Setup Your Mac script?

At any time, click Generate Script to “save” your customized Setup Your Mac script.


Pro Tip: The various SYM-Helper settings files — where in-progress work is automatically saved — can be accessed by holding down Option while clicking the Settings icon.

What is meant by “SYM-Helper quickly builds a near production-ready, customized Setup Your Mac script” ?

The original goal of SYM-Helper was to help MacAdmins with the tedious work of adding Jamf Pro policies to a Configuration’s policyJSON (a.k.a. the “main” Setup Your Mac dialog).


Then, over-achiever Leslie also added an easy way to enable / disable items in the “Welcome” dialog (i.e., SYM-Helper > Settings > Prompt For …)


Near production-ready” means that not every Setup Your Mac setting is currently exposed to the SYM-Helper GUI and, you, the Jamf Pro administrator, are responsible to use your favorite editor to modify the SYM-Helper-generated Setup-Your-Mac.bash for your production environment.

For example, when a Jamf Pro policy includes data in the Self Service fields, SYM-Helper can fully populate a policyJSON‘s steps.

SYM-Helper crashes immediately after entering server credentials

The list of configured servers is shared among Leslie’s apps and is available at the following location:

~/Library/Group Containers/group.PS2F6S478M.jamfie.SharedJPMA/Library/Preferences/group.PS2F6S478M.jamfie.SharedJPMA.plist

Please backup then delete the above file then try again.

See Issue No. 5.

Where can I obtain support for SYM-Helper?

Best-effort support for SYM-Helper is offered in the  #setup-your-mac Channel on the Mac Admins Slack (free; registration required.)

Please report bugs and submit feature requests on GitHub.

Posted in Jamf Pro, Setup Your Mac, swiftDialog

Related Posts

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.