Jamf Pro Guide - macadmins/nudge GitHub Wiki

Deploying and Configuring Nudge with Jamf Pro

Contents

Best-effort Support

Please join us over in the MacAdmin's Slack #nudge-jamf channel where we'll do our best to help you implement Nudge in your Jamf Pro environment.

Presentations

Plan Your Deployment Strategy

Understanding Nudge

Ensure you understand what Nudge is and what Nudge is not:

Nudge is an multi-linguistic application, offering custom user deferrals, which strongly encourages macOS updates. Written in Swift 5.5 and SwiftUI 5.2, Nudge will only work on macOS Big Sur 11 and later.

Rather than trying to install updates via the macOS built-in softwareupdate binary, Nudge prompts users to install updates via Apple approved / tested methods: System Preferences > Software Update and major application upgrades via the standalone macOS installer (i.e., Install macOS Monterey.app).

While Nudge will compare a Mac's currently installed version of macOS to the value you set for Nudge's requiredMinimumOSVersion, before deploying Nudge to computers with Jamf Pro, review the computers' Inventory > Software Updates to ensure the update users are being prompted to install is available.

Configuration Methods

Configuration Profile vs. Local JSON

Carefully review Nudge Preferences and determine if deploying either a Configuration Profile (the standard approach, Option No. 2) or local JSON (a non-standard approach, Option No. 3) will best meet your needs.

Option Nudge.app LaunchAgent Preference
1
Nudge-1.1.10.x.pkg
Local Testing
2
Nudge_Suite-1.1.10.x.pkg		 Included in
Nudge_Suite-1.1.10.x.pkg
Jamf Pro JSON Schema
3
Nudge-1.1.10.x.pkg
Nudge Post-install script
Nudge Post-install script
4 JAMF App Catalog
Nudge
Nudge_LaunchAgent_1.0.1.pkg
Jamf Pro JSON Schema

Option No. 1: Local Testing

When you are first testing Nudge, please see: Local JSON > Proof-of-concept.

Once you're satisfied with your Nudge configuration on your local test Mac, it's time to deploy to your testing group.

Option No. 2: Configuration Profile

Standard Approach

Every release of Nudge includes a LaunchAgent package, which we see in Option No. 2. This LaunchAgent will open Nudge every 30 minutes — on the hour and half-past the hour. You will still need to deploy the Nudge app itself, and with this option, a Jamf Pro JSON Schema to deploy a Configuration Profile for Nudge's settings.

Option No. 3: Nudge Post-install Script

Non-standard Approach

Leverages the Nudge Post-install script deployed via the Jamf Pro Script Payload to create:

  • LaunchAgent: Opens Nudge
  • LaunchDaemon: Redirect Logs
  • Local JSON: Configures Nudge
  • Hides Nudge: Finder & Launchpad
  • Reset function: Policy Script Parameter

Note: All support for this workflow should be asked by opening an issue. Also, you should be comfortable editing scripts when using this option.

The remainder of this article focuses on the standard approach to configure Nudge, Option No. 2.

Option No. 4: JAMF App Catalog + LaunchAgent PGK

DRAFT Approach

Leverages the JAMF App Catalog to keep the main Nudge package up to date. (Nudge-xxxx.pkg)

Note: The JAMF App Catalog deployment does NOT include the Launch Agent or Logger.

  1. Deploy "Nudge" via the JAMF App Catalog too the target computer group. App Installers

  2. Deploy the "Nudge Launch Agent" via a JAMF Policy

  • Download "Nudge_LaunchAgent-xxx.pkg" from the latest github release.
  • Upload the LaunchAgent Package to your JAMF Instance
  • Create a new Policy that deploys the package
  1. Create a Configuration Profile to configure Nudge

The remainder of this article focuses on the standard approach to configure Nudge, Option No. 2.

Notifications

If you intend to use Nudge's ability (1.1.7 or later) to block application launches once the required installation date has passed, first enable macOS Notifications for com.github.macadmins.Nudge in Jamf Pro.

Application launch blocked

Jamf Pro Notification for com.github.macadmins.Nudge

Packages

Nudge is updated frequently and the latest version is always available from Nudge Releases.

Using Jamf Pro Package Management as a guide, upload the required Nudge .PKG:

  • Nudge_Suite-1.1.10.x.pkg

Smart Group

Using the Jamf Pro Administrator's Guide Smart Groups as a guide, create the following Smart Groups:

Update Smart: Nudge

And / Or Criteria Operator Value
( Application Title is Nudge.app
and Application Version is not 1.1.10.81462 )
or Application Title does not have Nudge.app
and Operating System Version greater than or equal 11.0.1

Configuration Profile

Using the Jamf Pro JSON Schema to deploy a Configuration Profile for Nudge

Resources

Procedure

  1. Log in to Jamf Pro
  2. Click Computers at the top of the page
  3. Click Configuration Profiles
  4. Click New
  5. Use the General payload to configure basic settings, including:
    • Name: Nudge
    • Description: Configures Nudge to company standards
    • Site: (Select an appropriate Site)
    • Category: (Select an appropriate Category)
    • Level: Computer Level
    • Distribution Method: Install Automatically
  6. Use the Applications & Custom Settings payload and select External Applications
  7. Click Add in the upper right corner
  8. Choose Custom Schema as Source, then enter com.github.macadmins.Nudge as Preference Domain
  9. Click Add Schema and paste in the entire contents of Jamf Pro JSON Schema for Nudge
  10. Click Save to display a list of configurable settings
  11. Add values to the managed keys to customize the app settings
    • You can view the plist of keys and values by clicking the Plist preview button
    • See Nudge Preferences for detailed information
  12. Click the Scope tab and configure the scope of the profile
  13. Click Save

When you save the settings, Jamf Pro automatically distributes the configured properties to the target computers.

Over-configuring Nudge

Some Mac Admins tend to over-configure Nudge. The following examples are designed to show a bare-minimum configuration; if this meets your needs, you're done.

Note how only two settings — requiredInstallationDate and requiredMinimumOSVersion — are required to prompt users to update.

Deadline in the past / Greater than released OS
Nudge: Deadline in the past / Greater than released OS

Plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>osVersionRequirements</key>
    <array>
      <dict>
        <key>requiredInstallationDate</key>
        <string>2021-09-15T00:00:00Z</string>
        <key>requiredMinimumOSVersion</key>
        <string>12.99</string>
      </dict>
    </array>
  </dict>
</plist>

Jamf Pro
Jamf Pro Form Editor: Deadline in the past / Greater than released OS
Jamf Pro Plist Preview: Deadline in the past / Greater than released OS
Deadline in the future / Greater than released OS
Nudge: Deadline in the future / Greater than released OS

Plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>osVersionRequirements</key>
    <array>
      <dict>
        <key>requiredInstallationDate</key>
        <string>2022-05-26T00:00:00Z</string>
        <key>requiredMinimumOSVersion</key>
        <string>12.99</string>
      </dict>
    </array>
  </dict>
</plist>

Jamf Pro
Jamf Pro Form Editor: Deadline in the future / Greater than released OS
Jamf Pro Plist Preview: Deadline in the future / Greater than released OS

Policy

Using the Jamf Pro Administrator's Guide Policies as a guide, add the following policy to Jamf Pro:

Screen Shot 2022-06-05 at 12 04 03 PM

Nudge Suite (1.1.10.x)

Options

  • General
    • Display Name: Nudge Suite (1.1.10.x)
    • Trigger: Recurring Check-in
    • Execution Frequency: Ongoing
  • Package
    • Nudge_Suite-1.1.10.x.pkg
  • Maintenance
    • Update Inventory

Scope

  • Targets: Update Smart: Nudge
  • Limitations: No Limitations
  • Exclusions: No Exclusions

Patch Management Software Title

Jamf now offers a Patch Management Software Title for Nudge.

General Resources

Reference Images

Reference Configuration Profiles

Single Language (Thanks, @emily.)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadContent</key>
			<dict>
				<key>com.github.macadmins.Nudge</key>
				<dict>
					<key>Forced</key>
					<array>
						<dict>
							<key>mcx_preference_settings</key>
							<dict>
								<key>optionalFeatures</key>
								<dict>
									<key>acceptableApplicationBundleIDs</key>
									<array>
										<string>us.zoom.xos</string>
										<string>com.apple.iWork.Keynote</string>
										<string>com.apple.Keynote</string>
										<string>com.microsoft.Powerpoint</string>
										<string>com.cisco.webexmeetingsapp</string>
										<string>com.webex.meetingmanager</string>
										<string>Cisco-Systems.Spark</string>
									</array>
									<key>aggressiveUserExperience</key>
									<true/>
									<key>attemptToFetchMajorUpgrade</key>
									<true/>
									<key>enforceMinorUpdates</key>
									<true/>
								</dict>
								<key>osVersionRequirements</key>
								<array>
									<dict>
										<key>aboutUpdateURL</key>
										<string>https://support.apple.com/HT212872</string>
										<key>requiredInstallationDate</key>
										<string>2021-10-29T17:00:00Z</string>
										<key>requiredMinimumOSVersion</key>
										<string>11.6.1</string>
										<key>targetedOSVersionsRule</key>
										<string>11</string>
									</dict>
									<dict>
										<key>aboutUpdateURL</key>
										<string>https://support.apple.com/HT212869</string>
										<key>requiredInstallationDate</key>
										<string>2021-10-29T17:00:00Z</string>
										<key>requiredMinimumOSVersion</key>
										<string>12.0.1</string>
										<key>targetedOSVersionsRule</key>
										<string>12</string>
									</dict>
								</array>
								<key>userExperience</key>
								<dict/>
								<key>userInterface</key>
								<dict>
									<key>iconDarkPath</key>
									<string>/path/to/image.png</string>
									<key>iconLightPath</key>
									<string>/path/to/other-image.png</string>
									<key>showDeferralCount</key>
									<true/>
									<key>singleQuitButton</key>
									<true/>
									<key>updateElements</key>
									<array>
										<dict>
											<key>_language</key>
											<string>en</string>
											<key>mainContentText</key>
											<string>Hey there! \n\nWe noticed this Mac has available software updates. Keeping macOS up-to-date is an important part in keeping devices and data secure.\n\nPlease update this Mac by clicking the Update Device button to install the available updates.</string>
											<key>mainHeader</key>
											<string>This Mac requires a security update</string>
											<key>subHeader</key>
											<string>A friendly reminder from IT ❤️</string>
										</dict>
									</array>
								</dict>
							</dict>
						</dict>
					</array>
				</dict>
			</dict>
			<key>PayloadDisplayName</key>
			<string>Custom Settings</string>
			<key>PayloadIdentifier</key>
			<string> </string>
			<key>PayloadOrganization</key>
			<string> </string>
			<key>PayloadType</key>
			<string> </string>
			<key>PayloadUUID</key>
			<string> </string>
			<key>PayloadVersion</key>
			<integer>1</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string></string>
	<key>PayloadDisplayName</key>
	<string>Nudge OS Update Settings</string>
	<key>PayloadEnabled</key>
	<true/>
	<key>PayloadIdentifier</key>
	<string> </string>
	<key>PayloadOrganization</key>
	<string> </string>
	<key>PayloadRemovalDisallowed</key>
	<true/>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string> </string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

Two Languages (Thanks, @colorenz.)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>optionalFeatures</key>
    <dict>
      <key>aggressiveUserExperience</key>
      <false/>
      <key>asyncronousSoftwareUpdate</key>
      <false/>
      <key>attemptToFetchMajorUpgrade</key>
      <false/>
      <key>enforceMinorUpdates</key>
      <true/>
    </dict>
    <key>osVersionRequirements</key>
    <array>
      <dict>
        <key>aboutUpdateURL</key>
        <string>https://excample.com</string>
        <key>requiredInstallationDate</key>
        <string>2021-11-10T00:00:00Z</string>
        <key>requiredMinimumOSVersion</key>
        <string>11.6.1</string>
        <key>targetedOSVersions</key>
        <array/>
        <key>targetedOSVersionsRule</key>
        <string>default</string>
      </dict>
    </array>
    <key>userExperience</key>
    <dict>
      <key>allowUserQuitDeferrals</key>
      <true/>
      <key>allowedDeferrals</key>
      <integer>30</integer>
      <key>allowedDeferralsUntilForcedSecondaryQuitButton</key>
      <integer>30</integer>
      <key>approachingRefreshCycle</key>
      <integer>3600</integer>
      <key>elapsedRefreshCycle</key>
      <integer>3600</integer>
      <key>imminentRefreshCycle</key>
      <integer>3600</integer>
      <key>imminentWindowTime</key>
      <integer>24</integer>
      <key>initialRefreshCycle</key>
      <integer>18000</integer>
      <key>maxRandomDelayInSeconds</key>
      <integer>3600</integer>
      <key>noTimers</key>
      <false/>
      <key>randomDelay</key>
      <true/>
    </dict>
    <key>userInterface</key>
    <dict>
      <key>fallbackLanguage</key>
      <string/>
      <key>forceFallbackLanguage</key>
      <false/>
      <key>forceScreenShotIcon</key>
      <false/>
      <key>iconDarkPath</key>
      <string>/Users/Shared/example.png</string>
      <key>iconLightPath</key>
      <string>/Users/Shared/example.png</string>
      <key>showDeferralCount</key>
      <true/>
      <key>simpleMode</key>
      <false/>
      <key>singleQuitButton</key>
      <true/>
      <key>updateElements</key>
      <array>
        <dict>
          <key>_language</key>
          <string>de</string>
          <key>actionButtonText</key>
          <string>Gerät aktualisieren</string>
          <key>customDeferralButtonText</key>
          <string>Zeitpunkt wählen</string>
          <key>informationButtonText</key>
          <string>Mehr Informationen</string>
          <key>oneDayDeferralButtonText</key>
          <string>Ein Tag</string>
          <key>oneHourDeferralButtonText</key>
          <string>Eine Stunde</string>
          <key>mainContentHeader</key>
          <string>Dein Gerät wird während dieses Updates neu gestartet</string>
          <key>mainContentNote</key>
          <string>Wichtiger Hinweis</string>
          <key>mainContentSubHeader</key>
          <string>Aktualisierungen können ca. 30 Minuten dauern.</string>
          <key>mainContentText</key>
          <string>Um das Update zu starten, klicke auf die Schaltfläche Gerät aktualisieren und befolge die angegebenen Schritte.\n\nEs kann notwendig sein, dass das Gerät nach Installation des Updates noch einmal neugestartet werden muss.\n\nBitte lies dir vorher weitere Informationen zur Update Installation unter Mehr Informationen durch.</string>
          <key>mainHeader</key>
          <string>Dein Gerät benötigt Sicherheitsupdates</string>
          <key>primaryQuitButtonText</key>
          <string>Später aktualisieren</string>
          <key>secondaryQuitButtonText</key>
          <string>Verstanden</string>
          <key>subHeader</key>
          <string/>
        </dict>
        <dict>
          <key>_language</key>
          <string>en</string>
          <key>actionButtonText</key>
          <string>Update Device</string>
          <key>customDeferralButtonText</key>
          <string>Custom reminder</string>
          <key>informationButtonText</key>
          <string>More Info</string>
          <key>oneDayDeferralButtonText</key>
          <string>One Day</string>
          <key>oneHourDeferralButtonText</key>
          <string>One Hour</string>
          <key>mainContentHeader</key>
          <string>Your device will restart during this update</string>
          <key>mainContentNote</key>
          <string>Important Notes</string>
          <key>mainContentSubHeader</key>
          <string>Updates can take around 30 minutes to complete</string>
          <key>mainContentText</key>
          <string>To start the update, click the Update Device button and follow the steps shown.\nIt may be necessary to restart the device after installing the update.</string>
          <key>mainHeader</key>
          <string>Moin! Your device needs security updates</string>
          <key>primaryQuitButtonText</key>
          <string>Later</string>
          <key>secondaryQuitButtonText</key>
          <string>I understand</string>
          <key>subHeader</key>
          <string/>
        </dict>
      </array>
    </dict>
  </dict>
</plist>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️