03. Setup Your Mac - setup-your-mac/Setup-Your-Mac GitHub Wiki

Setup Your Mac

Author: Dan K. Snelson
Published: 05-Feb-2024
Categories: Jamf Pro, Setup Your Mac, swiftDialog

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

Setup Your Mac Under the Hood

Screencast

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

Jump-start with SYM-Helper

MacAdmins can jump-start their users' on-boarding experience with SYM-Helper, a stand-alone macOS app to help MacAdmins more easily deploy Setup Your Mac.

SYM-Helper Hero

Key Features

  • Visual Interface: Drag-and-drop policy configuration
  • Real-time Preview: See how your setup will appear to users
  • Export Functionality: Generate ready-to-use configuration files
  • Template Support: Pre-built configurations for common scenarios

Getting Started: See SYM-Helper Application for detailed setup and usage instructions.

swiftDialog Integration

swiftDialog is a utility created by @bartreardon which allows you to present content-rich dialogs on macOS Monterey 12+, that can return a variety of user-input values.

Key Features

  • Native macOS Appearance: Integrates seamlessly with macOS design language
  • Rich Content Display: Support for images, videos, and formatted text
  • User Input Collection: Forms, dropdowns, checkboxes, and text fields
  • Extensive Customization: Branding, colors, icons, and layout options
  • Real-time Updates: Dynamic content updates during script execution
  • Return Values: Capture user selections and input for processing

Requirements

  • macOS Monterey 12.0 or later
  • Administrative privileges for installation
  • Compatible with both Intel and Apple Silicon Macs

Script Features & Architecture

Setup Your Mac is a comprehensive 3,547-line Bash script that provides extensive customization and automation capabilities.

Core Capabilities

  • Estimated Installation Duration: Shows users how long the setup process will take
  • Real-time Progress Updates: Live feedback during application installations
  • Detailed Application Information: Rich descriptions and progress indicators
  • Customizable Branding: Organization-specific welcome screens and assets
  • Failure Handling: Graceful error handling and retry mechanisms
  • Network-aware Configuration: Bandwidth testing and time estimation

⚙️ Configure: See Jamf Pro Parameters for script configuration and Advanced Customization for detailed implementation options

Script Architecture

The Setup Your Mac script (v1.15.1) is a comprehensive 3,547-line Bash script organized into distinct functional areas:

  • Bash-based: Native macOS scripting with POSIX compliance
  • Modular Design: 40+ discrete functions for specific operations
  • Logging Framework: Multi-level logging with timestamps and categorization
  • Error Handling: Robust failure management with graceful degradation
  • JSON Processing: Native JavaScript for Automation (JXA) parsing
  • Dialog Management: Real-time swiftDialog interface updates

⚙️ Configure: Set scriptLog location in Parameter 4 and debug verbosity in Parameter 5

Core Function Categories

  • System Utilities: 8 functions for user management and system operations - See Developer Reference
  • Dialog Interface: 6 functions for swiftDialog management and updates
  • Policy Engine: 4 functions for Jamf Pro policy execution and validation
  • Network Operations: 3 functions for quality testing and download estimation
  • Configuration Management: 2 functions for JSON parsing and policy selection
  • Logging System: 12 specialized logging functions with different output levels

Configuration Architecture

  • 11 Jamf Pro Parameters: Complete script configuration via GUI parameters
  • JSON-based Policies: Dynamic policy configuration with validation methods
  • Variable Inheritance: Centralized configuration with local overrides
  • Validation Framework: Local, Remote, and None validation options

⚙️ Configure: See Policy JSON Structure for policy configuration and Jamf Pro Parameters for parameter setup

Execution Flow

  1. Pre-flight Checks - System validation, user session, dependencies
  2. Configuration Loading - Parameter processing, JSON parsing
  3. Welcome Dialog - User input collection, network testing
  4. Policy Execution - Sequential policy processing with validation
  5. Progress Tracking - Real-time dialog updates, error handling
  6. Completion - Final validation, cleanup, completion actions

One-liner Installation Test

To quickly download and test Setup Your Mac:

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

Jamf Pro Script Parameters

Configure these 11 parameters when creating the Setup Your Mac policy in Jamf Pro.

Parameter 1: Policy JSON

  • Variable: policyJSON
  • Default: Built-in default configuration
  • Purpose: Defines the complete policy configuration including applications, validation methods, and execution order
  • Format: JSON string or path to JSON file
  • Example: See Configuration Guide for detailed examples

Parameter 2: Configuration One (Required)

  • Variable: configurationOneName
  • Default: Required
  • Purpose: Name of the first/minimal configuration option
  • Example: Essential, Basic, Minimal

Parameter 3: Configuration Two (Recommended)

  • Variable: configurationTwoName
  • Default: Recommended
  • Purpose: Name of the second/standard configuration option
  • Example: Standard, Professional, Business

Parameter 4: Script Log Location

  • Variable: scriptLog
  • Default: /var/log/org.churchofjesuschrist.log
  • Purpose: Defines where the script writes log entries
  • Example: /var/log/setup-your-mac.log

Parameter 5: Debug Mode

  • Variable: debugMode
  • Default: verbose
  • Options:
    • verbose - Detailed logging with line numbers
    • true - Basic debug output with sleep delays
    • false - Standard operation mode
  • Purpose: Controls logging verbosity and debugging features

Parameter 6: Welcome Dialog Type

  • Variable: welcomeDialog
  • Default: userInput
  • Options:
    • userInput - Full user input form with customizable fields
    • video - Video-based welcome with minimal input
    • messageOnly - Simple message dialog
    • false - Skip welcome dialog entirely
  • Purpose: Determines the type of welcome screen presented to users

Parameter 7: Completion Action

  • Variable: completionActionOption
  • Default: Restart Attended
  • Options:
    • wait - Wait for user action
    • sleep (with seconds) - Wait specified time then continue
    • Shut Down - Immediate shutdown
    • Shut Down Attended - User-prompted shutdown
    • Shut Down Confirm - Confirmation dialog for shutdown
    • Restart - Immediate restart
    • Restart Attended - User-prompted restart
    • Restart Confirm - Confirmation dialog for restart
    • Log Out - Immediate logout
    • Log Out Attended - User-prompted logout
    • Log Out Confirm - Confirmation dialog for logout

Parameter 8: Required Minimum Build (Optional)

  • Variable: requiredMinimumBuild
  • Default: disabled
  • Purpose: Enforces minimum macOS build requirements
  • Examples:
    • 23F - macOS 14.5 (Sonoma)
    • 22G - macOS 13.6 (Ventura)
    • 21H - macOS 12.7 (Monterey)

Parameter 9: Pre-Stage Configuration (Optional)

  • Variable: presetConfiguration
  • Purpose: Automatically selects configuration without user input
  • Options:
    • Name of configuration (e.g., "Required", "Recommended", "Complete")
    • Must match configurationOneName, configurationTwoName, or configurationThreeName

Parameter 10: Webhook URL (Optional)

  • Variable: webhookURL
  • Purpose: Microsoft Teams or Slack notifications for completion/failure
  • Examples:
    • Teams: https://outlook.office.com/webhook/your-webhook-url
    • Slack: https://hooks.slack.com/services/your-webhook-url

Parameter 11: Additional Options (Optional)

  • Purpose: Extended configuration options for special deployments
  • Uses: Client identification, custom branding paths, environment-specific settings

💡 For Advanced Configuration: See the complete Configuration Guide for detailed setup instructions, real-world examples, and advanced customization options.

Basic Customization Options

Essential customization settings built into the script for branding and user experience.

Support Team Information

Configure support contact information displayed throughout the setup process:

# Basic support information
supportTeamName="IT Support Team"
supportTeamPhone="+1 (555) 123-4567"
supportTeamEmail="[email protected]"
supportTeamHours="Monday through Friday, 8 a.m. to 5 p.m."

# Web resources
supportTeamChat="chat.company.com"
supportTeamWebsite="support.company.com"
supportKB="KB123456"

User Input Field Controls

Control which fields appear in the Welcome dialog:

# Enable/disable user input fields
promptForUsername="true"      # Show username field
promptForRealName="true"      # Show full name field
promptForEmail="true"         # Show email field
promptForComputerName="true"  # Show computer name field
promptForAssetTag="true"      # Show asset tag field
promptForRoom="true"          # Show room field
promptForBuilding="true"      # Show building dropdown
promptForDepartment="true"    # Show department dropdown
promptForPosition="true"      # Show position field
promptForConfiguration="true" # Show configuration dropdown

# Auto-populate fields
prefillUsername="true"      # Use current username
prefillRealname="true"      # Use current user's full name
prefillEmail="true"         # Construct email from username + domain
prefillComputerName="true"  # Use current computer name

# Email configuration
emailEnding="@company.com"

Organizational Data Lists

Configure dropdown lists for organizational structure:

# Buildings list
buildingsListRaw="Headquarters,Branch Office North,Branch Office South,Remote Office"

# Departments list
departmentListRaw="Information Technology,Sales,Marketing,Finance,Human Resources,Operations"

# Positions list (can be dropdown or free text)
positionListRaw="Manager,Director,Analyst,Specialist,Coordinator"
# Set to empty string "" for free text input

Configuration Options

Define the available setup configurations:

# Configuration 1
configurationOneName="Essential"
configurationOneDescription="Critical business applications only"
configurationOneSize="25"  # Size in Gibibits for time estimation

# Configuration 2
configurationTwoName="Standard"
configurationTwoDescription="Business apps plus productivity suite"
configurationTwoSize="74"

# Configuration 3
configurationThreeName="Complete"
configurationThreeDescription="Full application suite with extras"
configurationThreeSize="149"

💡 For Complete Setup Instructions: See the Configuration Guide for comprehensive setup procedures, advanced customization options, and real-world deployment examples.

Configuration & Customization

Setup Your Mac provides extensive configuration options to match your organization's requirements and branding.

Dialog Types

Setup Your Mac supports three primary welcome dialog modes:

⚙️ Configure: See Welcome Dialog Customization in the Configuration Guide

1. Video Dialog

  • Displays a welcome video to users
  • Provides engaging visual introduction
  • Can include custom branding and messaging

Configure: Set welcomeDialog="video" in Advanced Customization

2. Message Only Dialog

  • Simple text-based welcome message
  • Lightweight and fast loading
  • Ideal for minimal setup scenarios

Configure: Set welcomeDialog="messageOnly" in Advanced Customization

3. User Input Dialog (Most Comprehensive)

  • Collects user information during setup
  • Customizable input fields
  • Supports organizational data collection

Configure: Set welcomeDialog="userInput" and customize fields in User Input Field Controls

Welcome User Input Dialog

Configuration Management

Setup Your Mac uses JSON-based configuration files that define:

  • Policy Execution Order: Sequence of Jamf Pro policies
  • User Interface Elements: Dialog appearance and branding
  • Validation Methods: How to verify successful installations
  • Progress Indicators: Real-time feedback to users

⚙️ Configure: See Policy JSON Structure for policy configuration and Jamf Pro Parameters for basic setup

Configuration Types

Required Configuration

Essential policies that must complete successfully:

  • Core security applications
  • Mandatory corporate software
  • System configuration profiles

⚙️ Configure: Set configurationOneName and size in Configuration Options

Recommended Configuration

Optional but suggested policies:

  • Productivity applications
  • Utility software
  • Department-specific tools

⚙️ Configure: Set configurationTwoName and size in Configuration Options

Complete Configuration

Comprehensive setup including:

  • All required and recommended items
  • Additional customization options
  • Advanced feature configurations

⚙️ Configure: Set configurationThreeName and size in Configuration Options

Visual Customization Options

  • Organization Logo: Custom branding in dialogs
  • Color Schemes: Match corporate identity
  • Welcome Messages: Personalized user greeting
  • Progress Indicators: Branded progress bars and icons

⚙️ Configure: See Visual Branding and Assets for banner and icon setup

Light and Dark Mode Icons

Light Mode Icon Dark Mode Icon

Custom Branding Banner

Branding Banner Example

Support Information Integration

  • Help Desk Contact: Display support team information
  • Knowledge Base Links: Direct access to documentation
  • Escalation Procedures: Clear guidance for issues

⚙️ Configure: Set support team details in Support Team Information

Custom Fields

  • Asset Tagging: Automated asset management
  • User Information: Collect organizational data
  • Department Assignment: Automatic group membership
  • Location Details: Building and room information

⚙️ Configure: Enable and customize fields in User Input Field Controls and Organizational Data Lists

Configuration Examples

Basic Configuration JSON

{
  "welcomeDialog": {
    "title": "Welcome to Your Organization",
    "message": "We'll help you get started with your new Mac",
    "button1text": "Continue"
  },
  "setupYourMacPolicyArrayIconPrefixUrl": "https://yourserver.com/icons/",
  "policy": [
    {
      "trigger": "install-office",
      "path": "/Applications/Microsoft Word.app",
      "displayName": "Microsoft Office",
      "description": "Essential productivity suite"
    }
  ]
}

Advanced Configuration with Validation

{
  "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"
    }
  ]
}

Failure Dialog Handling

Error Management

Setup Your Mac includes sophisticated error handling:

  • Graceful Failures: Continue setup when non-critical policies fail
  • User Notification: Clear communication about issues
  • Retry Mechanisms: Automatic retry for transient failures
  • Support Escalation: Direct paths to IT assistance

⚙️ Configure: Set debug mode and error handling in Jamf Pro Parameters (Parameter 5: Debug Mode)

Customizable Failure Messages

Administrators can customize:

  • Error dialog appearance
  • Support contact information
  • Troubleshooting steps
  • Recovery procedures

⚙️ Configure: Customize support information in Support Team Information

Technical Implementation

Integration Points

⚙️ Configure: Set webhook notifications in Parameter 10 and visual branding in Visual Branding and Assets

  • Jamf Pro API: Policy execution and reporting
  • swiftDialog: User interface presentation
  • macOS Services: System integration
  • Network Services: Download and validation

Performance Considerations

⚙️ Configure: Set configuration sizes and network estimation in Download Estimation Customization and Network Quality Testing

  • Network Estimation: Bandwidth-aware downloads
  • Resource Management: Efficient system utilization
  • Progress Tracking: Real-time status updates
  • Memory Usage: Optimized for various Mac configurations

Data Flow Overview

The following diagram illustrates the flow of data and control through the Setup Your Mac process:

flowchart TD
    JamfPro[Jamf Pro Parameters]
    ScriptVars[Script Variables]
    JSONConfig[JSON Configuration]
    Dialog[Dialog Interface]
    Policy[Policy Execution]
    Validation[Validation Engine]
    Progress[Progress Tracking]
    Logging[Logging System]
    Webhook[Webhook Notifications]
    Completion[Completion Actions]

    JamfPro --> ScriptVars --> JSONConfig --> Dialog
    ScriptVars --> Policy
    JSONConfig --> Validation
    Dialog --> Progress
    Policy --> Logging
    Validation --> Policy
    Progress --> Validation
    Logging --> Webhook --> Completion

Best Practices

Pre-Implementation Testing

⚙️ Configure: Enable debug mode in Parameter 5: Debug Mode and see Configuration Testing and Validation for testing procedures.

  1. Perform a dry-run validation: Test configurations without executing changes.
  2. Verify each policy: Ensure all policies function correctly when run individually.
  3. Test network performance: Validate download speeds and reliability.
  4. Review user experience: Walk through the process as an end user to identify issues.

Production Deployment

⚙️ Configure: See Integration Examples for real-world deployment scenarios and Webhook Integration for monitoring setup.

  1. Roll out in stages: Deploy to test groups before full deployment.
  2. Monitor deployment: Track success and failure rates using logs and webhooks.
  3. Gather user feedback: Collect suggestions and issues from end users.
  4. Update configurations regularly: Continuously improve based on feedback and monitoring.

Troubleshooting

⚙️ Configure: Set logging verbosity in Parameter 5: Debug Mode and see Developer Reference: Troubleshooting Guide for comprehensive troubleshooting procedures.

  1. Analyze logs: Review detailed logs for errors and warnings.
  2. Test policies in isolation: Identify problematic policies by running them separately.
  3. Validate network connectivity: Ensure all required network resources are accessible.
  4. Train users: Provide clear instructions and support resources.

Resources and Support

Documentation

Community Support

  • Mac Admins Slack: #setup-your-mac channel
  • GitHub Issues: Bug reports and feature requests
  • MacAdmins.org: Community discussions and resources

Related Blog Posts

GitHub Repositories

Technical Reference Documentation

Implementation and Configuration

  • Configuration Guide - Complete setup guide from basic parameters to advanced organizational integration
  • Developer Reference - Functions, troubleshooting, and technical implementation details
  • Best Practices - Security, performance, operational guidelines, and compliance considerations

Validation and Testing

Getting Started