07. Configuration Guide - setup-your-mac/Setup-Your-Mac GitHub Wiki

Configuration Guide

Complete guide for configuring, customizing, and deploying Setup Your Mac from basic parameters to advanced organizational integration.

Getting Started with Configuration

This guide is organized to take you from basic setup to advanced deployment:

  1. Jamf Pro Parameters - Essential script configuration
  2. Basic Customization - User interface and branding
  3. Advanced Features - Organizational integration and complex setups
  4. Real-World Examples - Complete configurations for different environments

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 Policy JSON Structure 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

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"

Advanced Customization

Advanced branding, behavior modification, and organizational integration features.

Visual Branding and Assets

Banner Configuration

# Remote banner image
brandingBanner="https://company.com/images/setup-banner.jpg"

# Local banner image
brandingBanner="/Library/Application Support/Company/banner.png"

# Banner text overlay
brandingBannerDisplayText="true"  # Show text overlay
brandingBannerDisplayText="false" # Hide text overlay

Icon Configuration

# Light mode icon
brandingIconLight="https://company.com/icons/logo-light.png"
# Or local file path
brandingIconLight="/Library/Application Support/Company/logo-light.png"

# Dark mode icon
brandingIconDark="https://company.com/icons/logo-dark.png"
# Or local file path
brandingIconDark="/Library/Application Support/Company/logo-dark.png"

Image Requirements

Banner Images:

  • Dimensions: 1200x300px recommended
  • Format: PNG, JPG, or HEIC
  • Size: Under 2MB for performance
  • Aspect Ratio: 4:1 ratio works best

Icons:

  • Dimensions: 512x512px recommended
  • Format: PNG with transparency
  • Size: Under 500KB
  • Style: Clean, recognizable at small sizes

Welcome Dialog Customization

Dialog Types

User Input Dialog (Recommended):

welcomeDialog="userInput"
  • Full user input form
  • Organizational data collection
  • Asset tag assignment
  • Configuration selection
  • Network quality testing

Video Dialog:

welcomeDialog="video"
  • Video-based welcome message
  • Minimal user input
  • Company introduction
  • Simplified setup process

Message Only Dialog:

welcomeDialog="messageOnly"
  • Simple text message
  • Minimal user interaction
  • Quick setup start

No Welcome Dialog:

welcomeDialog="false"
  • Skip welcome entirely
  • Direct to main setup
  • Automated scenarios

Policy Configuration and JSON

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

Basic Policy JSON Structure

{
  "trigger": "install-office",
  "path": "/Applications/Microsoft Word.app",
  "displayName": "Microsoft Office",
  "description": "Office productivity suite",
  "validation": "Local",
  "estimatedInstallTime": "300"
}

Advanced Policy JSON with Custom Validation

{
  "trigger": "install-adobe-creative",
  "path": "/Applications/Adobe Photoshop 2024/Adobe Photoshop 2024.app",
  "displayName": "Adobe Creative Suite",
  "description": "Creative design and editing applications",
  "validation": "Remote",
  "validationScript": "/usr/local/bin/validate-adobe.sh",
  "estimatedInstallTime": "900",
  "icon": "https://cdn.company.com/icons/adobe.png"
}

Download Estimation Customization

Size Calculations

# Convert GB to Gibibits: GB * 7.451
configurationOneSize="25"      # ~3.4 GB total
configurationTwoSize="74"      # ~10 GB total
configurationThreeSize="149"   # ~20 GB total

Time Estimation Accuracy

# Correction coefficient for estimation accuracy
correctionCoefficient="1.15"  # Add 15% to estimates for safety

# Installation time buffers
configurationOneInstallBuffer="300"    # 5 minutes additional
configurationTwoInstallBuffer="600"    # 10 minutes additional
configurationThreeInstallBuffer="1200" # 20 minutes additional

Network Quality Testing

# Enable/disable network testing
configurationDownloadEstimation="true"   # Test network quality
configurationDownloadEstimation="false"  # Skip network testing

# Correction coefficient for variable connections
correctionCoefficient="1.25"  # 25% buffer for home networks

Completion Actions and Behavior

Standard Completion Actions

completionActionOption="Restart"           # Immediate restart
completionActionOption="Restart Attended"  # User-prompted restart
completionActionOption="Restart Confirm"   # Confirmation dialog

Custom Completion Actions

# Custom script execution
completionActionOption="/usr/local/bin/post-setup-script.sh"

# Launch specific application
completionActionOption="open '/Applications/Self Service.app'"

# Wait periods
completionActionOption="sleep 300"  # Wait 5 minutes
completionActionOption="wait"       # Wait for user action

Webhook Integration

Microsoft Teams Configuration

webhookURL="https://outlook.office.com/webhook/your-webhook-url"

Slack Configuration

webhookURL="https://hooks.slack.com/services/your-webhook-url"

Webhook Security

# Store webhook URL securely
webhookURL=$(security find-generic-password -s "sym-webhook" -w)

# Validate webhook before using
if curl -s --max-time 10 "${webhookURL}" > /dev/null; then
    webHookMessage "success"
fi

Integration Examples

Real-world deployment scenarios and complete configurations for different organization types.

Small Business (50-200 employees)

Basic Configuration

# Jamf Pro Parameters
scriptLog="/var/log/company-setup.log"
debugMode="false"
welcomeDialog="userInput"
completionActionOption="Restart Attended"
webhookURL="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"

Simplified User Input

# Basic information only
promptForUsername="true"
prefillUsername="true"
promptForRealName="true"
prefillRealname="true"
promptForEmail="true"
prefillEmail="true"
emailEnding="@smallbusiness.com"

# Skip complex organizational fields
promptForAssetTag="false"
promptForRoom="false"
promptForBuilding="false"
promptForDepartment="false"
promptForPosition="false"
promptForConfiguration="true"

Single Configuration Setup

configurationOneName="Standard"
configurationOneDescription="All business applications"
configurationOneSize="45"

# Hide other configurations
configurationTwoName="Standard"
configurationTwoDescription="All business applications"
configurationTwoSize="45"

configurationThreeName="Standard"
configurationThreeDescription="All business applications"
configurationThreeSize="45"

Policy JSON Example

[
  {
    "trigger": "install-office365",
    "path": "/Applications/Microsoft Word.app",
    "displayName": "Microsoft 365",
    "description": "Office productivity suite"
  },
  {
    "trigger": "install-chrome",
    "path": "/Applications/Google Chrome.app",
    "displayName": "Google Chrome",
    "description": "Web browser"
  },
  {
    "trigger": "install-zoom",
    "path": "/Applications/zoom.us.app",
    "displayName": "Zoom",
    "description": "Video conferencing"
  },
  {
    "trigger": "install-security",
    "path": "/Applications/CrowdStrike Falcon.app",
    "displayName": "Security Software",
    "description": "Endpoint protection"
  }
]

Enterprise Corporation (1000+ employees)

Advanced Configuration

# Comprehensive user data collection
promptForUsername="true"
prefillUsername="true"
promptForRealName="true"
prefillRealname="true"
promptForEmail="true"
prefillEmail="true"
emailEnding="@enterprise.com"
promptForComputerName="true"
prefillComputerName="false"  # Let users customize
promptForAssetTag="true"
promptForRoom="true"
promptForBuilding="true"
promptForDepartment="true"
promptForPosition="true"
promptForConfiguration="true"

Organizational Structure

buildingsListRaw="Headquarters NY,Boston Office,Chicago Office,Austin Office,London Office,Tokyo Office,Remote Worker"

departmentListRaw="Engineering,Product Management,Sales,Marketing,Customer Success,Finance,Legal,Human Resources,Information Technology,Operations,Executive"

positionListRaw="Individual Contributor,Senior Individual Contributor,Team Lead,Manager,Senior Manager,Director,Senior Director,Vice President,Executive"

Multiple Configurations

configurationOneName="Essential"
configurationOneDescription="Core business applications"
configurationOneSize="35"

configurationTwoName="Professional"
configurationTwoDescription="Business apps plus development tools"
configurationTwoSize="75"

configurationThreeName="Power User"
configurationThreeDescription="Complete suite with creative tools"
configurationThreeSize="120"

Enhanced Support Information

supportTeamName="Global IT Service Desk"
supportTeamPhone="+1 (800) 555-HELP"
supportTeamEmail="[email protected]"
supportTeamChat="teams.enterprise.com/it-support"
supportTeamWebsite="servicedesk.enterprise.com"
supportKB="KB789456"
supportTeamHours="24/7 Global Support"

Healthcare Organization (HIPAA Compliance)

Security-Focused Configuration

# Enhanced security requirements
requiredMinimumBuild="23F"  # Latest security updates required
completionActionOption="Restart Confirm"  # Ensure proper restart

# Comprehensive user tracking for compliance
promptForUsername="true"
prefillUsername="true"
promptForRealName="true"
prefillRealname="true"
promptForEmail="true"
prefillEmail="true"
emailEnding="@hospital.org"
promptForAssetTag="true"  # Required for compliance
promptForBuilding="true"
promptForDepartment="true"
promptForPosition="true"
promptForConfiguration="true"

Medical Organizational Data

buildingsListRaw="Main Hospital,Outpatient Clinic,Emergency Department,Surgery Center,Administrative Building,Research Facility"

departmentListRaw="Emergency Medicine,Surgery,Cardiology,Radiology,Laboratory,Pharmacy,Nursing,Administration,Information Technology,Compliance"

positionListRaw="Physician,Nurse,Technician,Administrative Staff,IT Staff,Compliance Officer,Research Staff"

HIPAA Compliance Branding

brandingBanner="/Library/Application Support/Hospital/hipaa-compliance-banner.png"
supportTeamName="IT Security & Compliance"
supportTeamPhone="+1 (555) 555-HELP"
supportTeamEmail="[email protected]"
supportKB="HIPAA-COMPLIANCE-001"

Educational Institution (University/School District)

Academic Configuration

# Educational user input
promptForUsername="true"
prefillUsername="true"
promptForRealName="true"
prefillRealname="true"
promptForEmail="true"
prefillEmail="true"
emailEnding="@university.edu"
promptForBuilding="true"
promptForDepartment="true"
promptForPosition="true"
promptForConfiguration="true"

# Skip corporate fields
promptForAssetTag="false"
promptForRoom="false"
promptForComputerName="false"

Academic Organizational Data

buildingsListRaw="Library,Student Center,Engineering Building,Business School,Liberal Arts,Science Complex,Administration,Residence Hall A,Residence Hall B"

departmentListRaw="Computer Science,Engineering,Business Administration,Liberal Arts,Natural Sciences,Education,Medicine,Law,Student Services,IT Services,Facilities"

positionListRaw="Undergraduate Student,Graduate Student,Faculty,Adjunct Faculty,Research Staff,Administrative Staff,IT Staff"

Academic Configurations

configurationOneName="Student"
configurationOneDescription="Essential applications for students"
configurationOneSize="25"

configurationTwoName="Faculty"
configurationTwoDescription="Teaching and research applications"
configurationTwoSize="50"

configurationThreeName="Research"
configurationThreeDescription="Advanced research and analysis tools"
configurationThreeSize="85"

Remote Workforce

Remote-Optimized Configuration

# Network-aware configuration
configurationDownloadEstimation="true"
correctionCoefficient="1.25"  # Account for variable home internet

# Simplified for remote setup
promptForUsername="true"
prefillUsername="true"
promptForRealName="true"
prefillRealname="true"
promptForEmail="true"
prefillEmail="true"
emailEnding="@remotecompany.com"
promptForBuilding="false"  # Not applicable
promptForDepartment="true"
promptForPosition="true"
promptForConfiguration="true"

# Skip physical location fields
promptForRoom="false"
promptForAssetTag="false"

Remote Organizational Structure

# Use regions instead of buildings
buildingsListRaw="North America,Europe,Asia Pacific,Remote - Other"

departmentListRaw="Engineering,Product,Sales,Marketing,Customer Success,Operations,Finance,Human Resources"

positionListRaw="Individual Contributor,Senior Individual Contributor,Team Lead,Manager,Director,VP"

VPN and Security Focus

supportTeamName="Remote IT Support"
supportTeamPhone="+1 (888) 555-REMOTE"
supportTeamEmail="[email protected]"
supportTeamChat="slack.company.com/channels/it-support"
supportTeamWebsite="help.company.com"
supportTeamHours="Extended hours: 6 a.m. to 10 p.m. PT"

Multi-Tenant Service Provider (MSP)

Client-Specific Configuration

# Variables set per client deployment
clientName="${11}"  # Use Parameter 11 for client identifier
brandingBanner="https://msp.com/client-assets/${clientName}/banner.png"
brandingIconLight="https://msp.com/client-assets/${clientName}/logo-light.png"
brandingIconDark="https://msp.com/client-assets/${clientName}/logo-dark.png"
emailEnding="@${clientName}.com"

MSP Support Configuration

supportTeamName="Managed IT Services"
supportTeamPhone="+1 (800) 555-MSP1"
supportTeamEmail="[email protected]"
supportTeamWebsite="portal.msp.com"
supportTeamHours="24/7 Technical Support"

# Client-specific webhook
webhookURL="https://msp.com/webhooks/${clientName}/notifications"

Dynamic Organizational Data

# Client-specific data loaded from external source
buildingsListRaw=$(curl -s "https://msp.com/api/clients/${clientName}/buildings")
departmentListRaw=$(curl -s "https://msp.com/api/clients/${clientName}/departments")

Standardized MSP Configurations

configurationOneName="Essential MSP"
configurationOneDescription="Core managed services applications"
configurationOneSize="30"

configurationTwoName="Business MSP"
configurationTwoDescription="Business productivity with managed services"
configurationTwoSize="55"

configurationThreeName="Premium MSP"
configurationThreeDescription="Complete suite with premium support"
configurationThreeSize="85"

Organization-Specific Customizations

Examples of advanced customizations for specific organizational needs.

Department-Based Configuration Selection

Automatic Configuration Based on Department

# Different configurations based on department selection
if [ "${selectedDepartment}" == "Engineering" ](/setup-your-mac/Setup-Your-Mac/wiki/-"${selectedDepartment}"-==-"Engineering"-); then
    presetConfiguration="Developer"
elif [ "${selectedDepartment}" == "Sales" ](/setup-your-mac/Setup-Your-Mac/wiki/-"${selectedDepartment}"-==-"Sales"-); then
    presetConfiguration="Business"
elif [ "${selectedDepartment}" == "Creative" ](/setup-your-mac/Setup-Your-Mac/wiki/-"${selectedDepartment}"-==-"Creative"-); then
    presetConfiguration="Design"
else
    presetConfiguration="Standard"
fi

Building-Based Policies

# Different policies based on building location
if [ "${selectedBuilding}" == "Secure Facility" ](/setup-your-mac/Setup-Your-Mac/wiki/-"${selectedBuilding}"-==-"Secure-Facility"-); then
    # Enhanced security policies
    presetConfiguration="HighSecurity"
elif [ "${selectedBuilding}" == "Research Lab" ](/setup-your-mac/Setup-Your-Mac/wiki/-"${selectedBuilding}"-==-"Research-Lab"-); then
    # Research-specific applications
    presetConfiguration="Research"
fi

Role-Based Access Control

# Different access based on position
case "${selectedPosition}" in
    "Executive"|"VP"|"Director")
        presetConfiguration="Executive"
        ;;
    "Manager"|"Team Lead")
        presetConfiguration="Management"
        ;;
    "Individual Contributor")
        presetConfiguration="Standard"
        ;;
    *)
        presetConfiguration="Basic"
        ;;
esac

Compliance-Specific Configurations

Financial Services (SOX Compliance)

# Enhanced audit requirements
requiredMinimumBuild="23F"  # Latest security patches
acPowerCheck="required"     # Must be connected to power
webhookURL="https://compliance.bank.com/webhook/sox-notifications"

# Comprehensive tracking for audit purposes
promptForAssetTag="true"    # Required for asset tracking

Healthcare (HIPAA Compliance)

# HIPAA-specific requirements
brandingBanner="/Library/Application Support/Hospital/hipaa-banner.png"
supportTeamName="IT Security & Compliance"
supportKB="HIPAA-COMPLIANCE-001"

# Enhanced security messaging
configurationOneName="HIPAA Workstation"
configurationOneDescription="HIPAA-compliant clinical applications"

Configuration Testing and Validation

Best practices for testing your Setup Your Mac configuration before deployment.

Pre-Deployment Testing Checklist

Configuration Validation

# Enable debug mode for testing
debugMode="verbose"

# Use test webhook for notifications
webhookURL="https://hooks.slack.com/services/TEST/WEBHOOK/URL"

# Test with minimal policies first
# Verify all custom modifications work

Test Matrix

  • Different macOS versions: Test on Monterey, Ventura, Sonoma
  • Various Mac models: Intel and Apple Silicon
  • Network conditions: Fast, slow, intermittent connections
  • User scenarios: New employee, existing employee, power user
  • Error conditions: Network failure, policy failure, user cancellation

Automated Testing Script

#!/bin/bash
# Basic configuration validation script

# Test 1: Validate JSON syntax
echo "Testing configuration JSON syntax..."
if echo "${policyJSON}" | jq . >/dev/null 2>&1; then
    echo "✅ JSON syntax valid"
else
    echo "❌ JSON syntax invalid"
    exit 1
fi

# Test 2: Verify required variables
echo "Testing required variables..."
required_vars=("supportTeamName" "supportTeamEmail" "emailEnding")
for var in "${required_vars[@]}"; do
    if [ -n "${!var}" ](/setup-your-mac/Setup-Your-Mac/wiki/--n-"${!var}"-); then
        echo "✅ $var is set"
    else
        echo "❌ $var is not set"
        exit 1
    fi
done

# Test 3: Validate webhook URL
if [ -n "${webhookURL}" ](/setup-your-mac/Setup-Your-Mac/wiki/--n-"${webhookURL}"-); then
    if curl -s --max-time 10 "${webhookURL}" >/dev/null; then
        echo "✅ Webhook URL accessible"
    else
        echo "⚠️ Webhook URL not accessible"
    fi
fi

echo "Configuration validation complete!"

Staged Deployment Strategy

  1. Development Environment: Test with IT team
  2. Pilot Group: Deploy to 5-10 volunteer users
  3. Department Rollout: Deploy by department
  4. Organization-wide: Full deployment after validation

See Also

Technical Implementation

Core Documentation

Getting Started