A stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac
Introduction
As announced during JNUC 2023, BIG-RAT (a.k.a. Leslie Helou), does it yet again by providing the MacAdmins community SYM-Helper, a stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac.
Previously, when configuring Setup Your Mac, MacAdmins had to painstakingly convert their Jamf Pro policies to perfectly formatted JSON
, cross their fingers — but not too many — and hope for the best.
Now, with SYM-Helper, a familiar, intuitive interface helps administrators build a near production-ready, customized Setup Your Mac script — with double-click and drag-and-drop ease — in minutes.
Usage
Learn how to use SYM-Helper to quickly build a near production-ready, customized Setup Your Mac script.
1. Account
Before SYM-Helper can securely connect to your Jamf Pro server, consider creating a dedicated account using one of the following methods:
- For Jamf Pro servers prior to 10.49.0, create a Jamf Pro User Account with the following Privileges:
- Jamf Pro Server Objects
- Buildings
- Read
- Departments
- Read
- Policies
- Read
- Buildings
- Jamf Pro Server Objects
- 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
2. Download
3. 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
4. Settings
The SYM-Helper Settings includes the following sections.
Script Source
In the Script Source field, enter your preferred source for the Setup-Your-Mac-via-Dialog.bash
script, which defaults to the main branch on GitHub.
Prompt For…
Easily enable (or disable) the various user-input fields displayed in the so-called “Welcome” dialog when executing Setup Your Mac.
Buildings and Departments
SYM-Helper can add the Buildings and Departments configured in your Jamf Pro server to your customized Setup Your Mac script with a single click.
5. Configurations
A. Jamf Pro Policy Pre-work
First, determine if you will repurpose existing Jamf Pro policies for Setup Your Mac, or create new, enrollment-specific policies.
With either approach, please be aware that SYM-Helper leverages the fields from the Self Service tab of Jamf Pro polices, even if “Make the policy available in Self Service” is disabled.
(After you’ve populated the Self Service fields, you can disable “Make the policy available in Self Service” and SYM-Helper will still use the fields’ values.)
B. Adding Policies to the default Configuration
Screencast
Procedure
Complete the following steps to add policies to the default Configuration using SYM-Helper.
- Launch SYM-Helper and login to your Jamf Pro server
- Confirm the selected Configuration; Default is the so-called “catch-all” Configuration
- Double-click a policy on the left to add it the selected Configuration on the right, then double-click again to remove; drag-and-drop to reorder
- Various validations can be added to a Configuration (See: 5.D. Validations.)
- Multiple items can be grouped together in a single
trigger_list
trigger_list
C. Managing Configurations
Managing multiple Configurations is easy with SYM-Helper.
- From the Configuration menu, select:
- Add New…
- Clone Existing…
- Provide a name for the Configuration and click OK
- Note: The recommend approach is to name Configurations with the variable names included in the Setup Your Mac script
${configurationOneName}
${configurationTwoName}
${configurationThreeName}
- Note: The recommend approach is to name Configurations with the variable names included in the Setup Your Mac script
${configurationOneName}
- Use the Configuration Action menu to:
- Clear the policies listed in a Configuration
- Remove an entire Configuration
- Note: The default, catch-all Configuration cannot be removed
D. Validations
Overview
Validations are a powerful feature of Setup Your Mac which answer the question:
I can see it’s installed; is it running?
Four validation options are available:
- Absolute File Path (i.e., any individual file; not a directory)
"/Applications/Microsoft Teams.app/Contents/Info.plist"
None
(for triggers which don’t require validation; always evaluates as successful)Local
(validation within the Setup Your Mac script)rosetta
filevault
sophosEndpointServices
globalProtect
recon
(required for updating a computer’s inventory with your Jamf Pro server; most frequently included as the last item in yourpolicyJSON
)
Remote
(i.e., validation via a single-script Jamf Pro policy)
Screencast
Support
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.
FAQ
An open-beta version of SYM-Helper 0.7.6
was officially released on 19-Sep-2023 in conjunction with JNUC 2023.
See: 2. Download
SYM-Helper 0.7.6
supports Setup Your Mac versions 1.10.0
(and later).
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.
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.
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
.
However, for a Local Validation, there’s (currently) no way to enter a steps
‘ listitem
or icon
in the SYM-Helper GUI:
(Local validations are but just one example, there are certainly other examples which will require manual editing; see: Setup Your Mac > Configuration.)
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.
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.