Menu Close

Introducing SYM-Helper

A stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac

SYM-Helper is a stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac
SYM-Helper is 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.

Prior to SYM-Helper, MacAdmins had to painstakingly convert their Jamf Pro policies to perfectly formatted JSON
Prior to SYM-Helper, MacAdmins had to painstakingly convert their Jamf Pro policies to perfectly formatted JSON

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.

JNUC 2023 SYM-Helper Overview (08:30); no spoken audio; music: bensound.com (License Code: 1FJ0PLD3S6YITNMD)

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:

  1. 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
  1. 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): 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
Jamf Pro 10.49.0 (and later): Assign the SYM-Helper API Role to a dedicated SYM-Helper API Client
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

SYM-Helper: Adding Policies to the Default Configuration (08:48); music: bensound.com (License Code: WWVE5XLQ6CDWAOCE)

Procedure

Complete the following steps to add policies to the default Configuration using SYM-Helper.

  1. Launch SYM-Helper and login to your Jamf Pro server
Launch SYM-Helper and login to your Jamf Pro server
Launch SYM-Helper and login to your Jamf Pro server
  1. Confirm the selected Configuration; Default is the so-called “catch-all” Configuration
Confirm the selected Configuration
Confirm the selected Configuration
  1. 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
  1. Various validations can be added to a Configuration (See: 5.D. Validations.)
  1. Multiple items can be grouped together in a single trigger_list
C. Managing Configurations

Managing multiple Configurations is easy with SYM-Helper.

  1. From the Configuration menu, select:
    • Add New…
    • Clone Existing…
Use the Configuration pop-up menu in SYM-Helper to add or clone Configurations
Use the Configuration pop-up menu in SYM-Helper to add or clone Configurations
  1. 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}
  1. 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
Use the Configuration Action menu to clear or remove Configurations
Use the Configuration Action menu to clear or remove Configurations
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:

  1. Absolute File Path (i.e., any individual file; not a directory)
    • "/Applications/Microsoft Teams.app/Contents/Info.plist"
  2. None (for triggers which don’t require validation; always evaluates as successful)
  3. 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 your policyJSON)
  4. Remote (i.e., validation via a single-script Jamf Pro policy)

Screencast

SYM-Helper: Validations (12:32); music: bensound.com (License Code: ESVBL9FWA2YZQTLC)

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

Who authored SYM-Helper?

Leslie Helou

When will SYM-Helper be available?

An open-beta version of SYM-Helper 0.7.6 was officially released on 19-Sep-2023 in conjunction with JNUC 2023.

Where can I download SYM-Helper?

See: 2. Download

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

SYM-Helper 0.7.6 supports Setup Your Mac versions 1.10.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.


However, for a Local Validation, there’s (currently) no way to enter a stepslistitem 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.)

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, macOS, Setup Your Mac

Related Posts