Skip to main content

Setting up and Configuring Nudge in Jamf Pro using plist

Updated over 3 weeks ago

Description

There are a number of ways to update macOS versions on computers but finding one standard workflow that is reliable can be difficult. Nudge is an open-source, third-party application created by the MacAdmin’s Slack Community that prompts users to install updates using built in Apple methods: System Preferences/System Settings > Software Update or standalone macOS installer (note: for major upgrades using the installer, users must be admin users. Standard macOS users will not be able to run the installer). Custom user deferrals are offered so that the user can update the computer with the built-in macOS UI when it is convenient for them while not sacrificing putting off the update entirely.

Note: Nudge is extremely safe to install. Nothing will be apparent on the computer after installation until a configuration profile is deployed.

This guide covers a basic setup and deployment method of Nudge using a plist. The alternative is to upload the JSON file to Jamf Pro which allows you to use buttons to adjust customizations instead of adding plist keys; for more information see Configure Nudge using a Custom External JSON Schema. Check out Nudge's Wiki page for more info on how it works and the different configurations that can be deployed.

Article Contents

Configuring Nudge In Jamf Pro

A. Packages

  1. Download the Nudge package and Launch Agent package from https://github.com/macadmins/nudge/releases

  2. Upload the two packages to Jamf Pro: Settings > Computer Management > Packages > New > Choose File > select package from Step 1. Repeat for the second package.

  3. Create a policy in Jamf Pro to deploy the Nudge package using the steps below.

    Note: Nudge is extremely safe to install. Nothing will be apparent on the computer after installation until a configuration profile is deployed.

    1. Navigate to Computers > Policies > New.

    2. Give the policy a name.

    3. Set the execution frequency to Once per computer and choose the desired trigger (Once Per Computer is recommended in most cases).

    4. Select the Packages payload and click Configure.

    5. Click the Add button next to the Nudge installation package from step 2.

    6. Select the + symbol to the right of the Nudge installation package.

    7. Select the Add button next to the Nudge Launch Agent package.

    8. Scope the policy to a test computer.

    9. Click Save.

This photo shows where you will install Nudge.

B. Minimal Nudge Configuration

This section provides steps to create a basic Nudge configuration to check and see if Nudge is working correctly on a computer. It includes the two required keys:

  • requiredInstallationDate: the required installation date for Nudge to enforce the required operating system version. (This value is set with the format like YYYY-MM-DDTHH:MM:SSZ.)

  • requiredMinimumOSVersion: the required minimum operating system version devices must get to --- Nudge will ask people to update until they are at this version or later. If the current version of macOS is higher than or equal to the requiredMinimumOSVersion, Nudge will not open.

  1. In your preferred text editor, paste the text below.


    ​<?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-03-21T19:00:00Z</string>
    <key>requiredMinimumOSVersion</key>
    <string>13.3</string>
    </dict>
    </array>
    </dict>
    </plist>
    ​
    ​

  2. In the text editor, edit the values in red above to enter in appropriate test values. Choose a date past today's date and a value higher than the test machine is currently on.

  3. Save the file as a .plist with the file name com.github.macadmins.Nudge.plist.

  4. Create a configuration profile in Jamf Pro with the settings above by following the steps below:

    1. In Jamf Pro, go to Computers > Configuration Profiles and click New.

    2. In the General payload, name the profile something in relation to Nudge that is easily identifiable later.

    3. Click the Applications & Custom Settings payload and select Upload.

    4. Click Add.

    5. Set the Preference Domain to com.github.macadmins.Nudge.

    6. Click Upload and select the file saved in Step 6.

    7. Click Scope and add the same test computer that Nudge package was installed on. Verify in System Settings/System Preferences that the configuration profile installed.

  5. Open the Nudge app from /Applications/Utilities. If everything went well, you should be able to open Nudge.app and it should ask you to update macOS to the required version. If this did not happen, skip to the Logs section at the bottom of this article.

  6. If Nudge successfully opens, change the keys we modified to something more conducive to the production environment.

    • If there are multiple versions of OS platforms in the environment, we need separate configuration profiles for each OS and the settings should be scoped using Smart Computer groups by OS.

C. Nudge Notifications (Optional)

This profile will help users determine that if Nudge/MacOS failed to update their computer, they should receive a notification as to why like this:

This photo shows the pop-up you may be getting on your device.

  1. Create the Notification profile in Jamf Pro following the steps below.

    1. Navigate to Computers > Configuration Profiles > New.

    2. On the General payload, specify this profile as being a Nudge Notifications Profile and installing at the Computer Level.

    3. Navigate to the Notifications payload and select the +Add button.

    4. Set the App Name as Nudge. Set the Bundle ID to com.github.macadmins.Nudge.

    5. Select the desired settings for the notification payload.

    6. Scope this profile to the same test computer from Step A3.

This photo shows where you are supposed to enter the information needed above.

D. Customizing Settings (Optional)

Nudge will work as configured in the steps above, but it is highly customizable both in terms of what is displayed to the users and how frequently users will be Nudged. If adding customizations, additional testing is needed to ensure it is not over-configured causing issues for the end users. To see all the customization options available, navigate to https://github.com/macadmins/nudge/blob/main/Example%20Assets/com.github.macadmins.Nudge.mobileconfig. A file can be saved locally by clicking the Raw button and right clicking (control clicking) anywhere on the next page that opens or see the plist copied below for a moderately customized list of settings.

To simplify, here is a plist that can be use in place of Step B1 above and modified to meet 

<?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>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>
<false/>
<key>aggressiveUserFullScreenExperience</key>
<false/>
<key>asynchronousSoftwareUpdate</key>
<false/>
<key>attemptToFetchMajorUpgrade</key>
<true/>
<key>enforceMinorUpdates</key>
<true/>
</dict>
<key>osVersionRequirements</key>
<array>
<dict>
<key>aboutUpdateURL</key>
<string>https://support.apple.com/en-us/HT201222</string>
<key>requiredInstallationDate</key>
<string>2023-04-21T19:00:00Z</string>
<key>requiredMinimumOSVersion</key>
<string>13.4.1</string>
<key>targetedOSVersionsRule</key>
<string>12</string>
</dict>
</array>
<key>userExperience</key>
<dict>
<key>allowGracePeriods</key>
<true/>
<key>approachingRefreshCycle</key>
<integer>6000</integer>
<key>approachingWindowTime</key>
<integer>72</integer>
<key>elapsedRefreshCycle</key>
<integer>300</integer>
<key>gracePeriodInstallDelay</key>
<integer>48</integer>
<key>gracePeriodLaunchDelay</key>
<integer>12</integer>
<key>gracePeriodPath</key>
<string>/private/var/db/.AppleSetupDone</string>
<key>imminentRefreshCycle</key>
<integer>600</integer>
<key>imminentWindowTime</key>
<integer>48</integer>
<key>initialRefreshCycle</key>
<integer>18000</integer>
</dict>
<key>userInterface</key>
<dict>
<key>fallbackLanguage</key>
<string>en</string>
<key>forceFallbackLanguage</key>
<false/>
<key>iconDarkPath</key>
<string>/Library/Application\ Support/ACME_IT/Images/ACME-stacked-color-knockout.png</string>
<key>iconLightPath</key>
<string>Library/Application\ Support/ACME_IT/Images/ACME-stacked-color.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! We noticed this Mac has available software updates. It is important to keep macOS up to date in order to secure ACME's devices and data. \n\nClicking the "Update Device" button will redirect you to the Software Update System Preferences pane to run the available updates. Make sure your work is saved and you are ready for your computer to restart. Once there, click the "Update Now" button and follow the prompts to complete the update process. This typically takes 30-45 minutes. \n\nYou will continue to regularly see this prompt until all OS updates have been installed.</string>
<key>mainHeader</key>
<string>This Mac requires a security update</string>
<key>subHeader</key>
<string>A friendly notice from ACME_ IT ❤️</string>
</dict>
</array>
</dict>
</dict>
</plist>

Again, the minimum required keys we want to modify based on where we want to upgrade computers to are the following:

<key>requiredInstallationDate</key>
   <string>2023-04-21T19:00:00Z</string>
   <key>requiredMinimumOSVersion</key>
   <string>13.4.1</string>

E. Timing Behavior

  • The default behavior for Nudge is that user will need to click an “I Understand” button in Nudge and then choose whether to update the device, defer later, or one hour.
    ​

    • “Later” is set to 30 minutes by default. Starting at line 95 in the Configuration Profile that we downloaded the organization should be able to customize those options to better suit their needs.

  • The Launch Agent will relaunch the Nudge window if it is closed. The default is 30 minutes.

  • The refresh cycle keys in the Customization apply to the window if it is already open (but not in focus on the screen).

  • After Nudge is first launch for an event, the timing is mainly controlled by the deferral time, but the actual timing of the popup can be later than the exact deferral time set based on the timing set in the LA. If a user defers for an hour at 12:10 (deferral time set to 1:10), nudge will launch 20 minutes later at 12:30 and quit because it hasn't reached the deferral time. It will run again at 1:00 and quit again. Finally at 1:30, 20 minutes after the deferral time, nudge will launch and prompt the user.
    ​

    • It may be tempting to increase the LA frequency to have more accurate deferrals. Keep in mind that if you do, users who defer with the Later option will see more frequent popups. That option just defers until the next launch. You may want to disable the later option if you care about accurate deferral times. (I think the later option is one of the best features though, and well worth the trade-off. It can trick some of the very laziest users into being nudged more often!)"

F. Branding

  • With the following keys, we can replace the Apple symbol in the upper left hand corner of the dialog box with the organizations brand:

    <key>iconDarkPath</key>
      <string>/Library/Application\ Support/ACME_IT/Images/ACME-stacked-color-knockout.png</string>
      <key>iconLightPath</key>
      <string>Library/Application\ Support/ACME_IT/Images/ACME-stacked-color.png</string>

  • The branding images will need to be packaged and deployed via policy to the end users computers, placing them in a folder location that is specified in the strings above.

  • If we don't care to brand the dialog box, we can remove the settings or just leave the keys as is. If there is no branding icon in the location specified, the Apple Symbol will appear.

G. Logs

  • For general logging around Nudge, the go-to is the following log command: log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color none

  • Helpful tip if we do not have the ability to open Nudge, review the steps in this workflow below the Configuration Profile heading: https://github.com/macadmins/nudge/wiki/Getting-Started

Related Articles
Deploying Privilege Elevation Settings From Jamf Connect
Standardized Introduction Workflow for Jamf Connect Menu Bar
Change Password with Okta Device Trust Certificate and off-VPN/off-site
How to Install SentinelOne with Jamf Now
How to Display the Bluetooth Icon in the Menu Bar for Computers using Jamf Pro
Did this answer your question?