Menu Close

Setup Your Mac with SYM-Helper.app (1.0.0)

Jump-start your users’ on-boarding experience with SYM-Helper (1.0.0), a stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac

Recording

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

Jump-starting
Setup Your Mac (1.13.0)

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

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:

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

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

Script Source (00:55; 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.

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.13.1”. (See branches for a current list.)
Settings

Settings (00:38; 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.

  • 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
        • Email
        • Position
        • Computer Name
        • Asset Tag
          • Disable regex
        • Building
        • Department
        • Configuration
      • Buildings
      • Departments
Default Configuration

Default Configuration (05:01; 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 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",
    "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",
    "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

“Complete” Configuration (02:24; 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.

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

Additional Configurations (02:35; no audio; edited for time)

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.

Hand-coding

While the current version of SYM-Helper handles much of the heavy-lifting, it hasn’t yet replaced your preferred code editor.

Specifically when testing locally via Terminal, you’ll need to manually change the defaults for the various Script Parameters, like debugMode.

New in version 1.13.0 is the Armin-inspired # SYM-Helper comment which will hopefully tell you which settings you can — and can’t yet — modify in SYM-Helper.

Last on this list — which is by no means comprehensive — is Configuration Variables. (Unless you like the three names we’re using, you’ll want to make some modifications here, too.)

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

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
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://
  • 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

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 Device Management, Jamf Pro, macOS, Setup Your Mac, swiftDialog, Tips & Tricks

Related Posts