Setup Your Mac with SYM-Helper.app

Setup Your Mac (1.13.0) (02:00; no audio; edited for time)

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.

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.

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.

Jamf Pro Policy Pre-work (01:12; no audio; edited for time)

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.

Finally, 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.

Script Source (01:04; no audio; edited for time)

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.

In a recent addition to version 0.8.2, Leslie 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.0”.

If you have your own fork of Setup Your Mac, you may wish to try specifying it in SYM-Helper.

Note: This screencast is already outdated: The “main” branch is now version 1.13.0, but there is a “1.13.1” branch available if you’d like to test this feature for yourself.

Settings (00:43; no audio; edited for time)

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

Default Configuration (06:41; no audio; edited for time)

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 for “filevault,” which is built-in to Setup Your Mac.

{
    "listitem": "FileVault 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"
        }
    ]
},

We’ll continue adding policies from the list on the left by double-clicking.

When you use the so-called “filepath” validation, you can use the “select” button to navigate in the filesystem for the desired app, then manually enter:

/Contents/Info.plist

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",
    "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 search for policyJSON= and you’ll notice that the Validations we manually added are missing data for:

• listitem
• icon
• progresstext

(While we could have specified progresstext in SYM-Helper for the Local Validations, I purposely didn’t for the sake of this demo.)

The so-called “Welcome” screen looks good and here we see the missing information from our policyJSON.

On the left, we have a sample policyJSON from the GitHub repo, which we’ll use to copy-pasta the missing information in our customized Setup Your Mac script.

With the updates now in-place, let’s re-run the script.

… Deep, Cleansing Breath …

I don’t want to continue filling out all these fields for the rest of the demos, 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. If you look at the VS Code window in the background, you’ll see the changes we manually made are blown away when we re-generated the script in SYM-Helper.

We’ll re-copy-pasta, save and re-run the script … nice! Now we only have to enter Asset Tag.

Hey! Everything is now showing up!

“Complete” Configuration (03:25; no audio; edited for time)

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

Before we do, let’s look up the variable name for the third configuration.

Here’s the snippet of code which displays the various configuration names, based on the variable values.

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

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.

We’ll add policies from the left column to our “complete” configuration by double-clicking.

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.

Additional Configurations (05:24; no audio; edited for time)

Our previous work on the so-called “complete” configuration is already selected, so let’s use it to build what we refer to as our “recommended” configuration.

Before we do, let’s again look up 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

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

This time, we’ll remove policies from the right column by double-clicking. Wow! That was easy!

Let’s build our last configuration, but this time, we’ll clone the default.

We’ll save the file to the desktop and open it in Visual Studio Code.

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

Hey! Everything is now showing up!

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 on Leslie’s GitHub repo.

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.

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://
• Jamf Pro 10.48.2 (and earlier):
  • Jamf Pro Account Username and Password
• Jamf Pro 10.49.0 (and later):
  • API Client ID and Client Secret

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

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

• Setup Your Mac (1.13.0)
• Jamf Pro Policy Validation
• Harvest Self Service Icons
• Upgrading Setup Your Mac

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

• Introducing SYM-Helper
• Setup Your Mac (1.12.10) via swiftDialog (2.3.2)
• Upgrading SYM
• Setup Your Mac: Jamf Pro Policy Validation