targetedOSVersionsRule - macadmins/nudge GitHub Wiki

As Nudge continues to be used in organizations, more complex Nudge events are required. The Nudge v1.1.0 and later targetedOSVersionsRule key replaces the previous targetedOSVersions key, enabling multiple, concurrent Nudge events.

Rule Definitions

Rule: Default Match

By using the default rule, any detected macOS lower than the value for requiredMinimumOSVersion will be targeted. Please note that if you omit this key from your configuration, this will be the behavior Nudge honors.

Example:

"requiredMinimumOSVersion": "12.1",
"targetedOSVersionsRule": "default"

This means that if the computer is running Big Sur or Monterey 12.0, it will get nudged to 12.1

Rule: Major OS Match

If you list a number as your rule, nudge will only target devices running that major OS version.

Example:

"requiredMinimumOSVersion": "12.1",
"targetedOSVersionsRule": "12"

This means that if the computer is running macOS 11.x, it will not get nudged. If it is running 12.0, it will get nudged to 12.1

Rule: Full OS Match

If you list an exact macOS version number, you can target just one build and nothing else.

Example:

"requiredMinimumOSVersion": "12.1",
"targetedOSVersionsRule": "11.5.1"

This means that only if the computer is running 11.5.1 exactly it will get nudged to 12.1

Precedence of rules

Rules take the following precedence, in order from lowest precedence (Default Match) to highest precedence (Full OS Match):

  • Default Match
    • Device is running macOS 11.5.1
    • targetedOSVersionsRule value is default or the targetedOSVersionsRule key is missing
  • Major OS Match
    • Device is running macOS 11.5.1
    • targetedOSVersionsRule value is 11
  • Full OS Match
    • Device is running macOS 11.5.1
    • targetedOSVersionsRule value is 11.5.1

Warning of undefined behavior

Passing identical rules will result in "undefined" behavior. Currently, the last identical rule will be honored.

Bad examples

In this bad example, there are two "default" rules:

  • The first rule is missing the targetedOSVersionsRule key
  • The second rule is explicitly defined with the targetedOSVersionsRule key

The device will have an effective requiredInstallationDate of 2021-07-31T00:00:00Z

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2"
    },
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "default"
    }
  ]
}

In this bad example, there are two Major OS Match rules. The device will have an effective requiredInstallationDate of 2021-07-31T00:00:00Z

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11"
    },
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11"
    }
  ]
}

Singular Nudge event

If you are only deploying a single Nudge event, the osVersionRequirements configuration is quite simple:

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2"
    }
  ]
}

A technically identical alternative configuration:

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "default"
    }
  ]
}

Multiple Nudge events

Real-world Example 1

You may find yourself in a situation where Apple releases a minor update that you want people to install, but it is not critical to the safety of your organization. (macOS 11.5.2 might be a perfect example of this.)

If you find yourself in the middle of an active Nudge event — for example, macOS 11.5.1 — and a new version of macOS is released (i.e. 11.5.2), you may want to enforce macOS 11.5.2 for anyone who hasn't yet installed macOS 11.5.1 (end of August deadline), while giving users who have installed 11.5.1 more time to install 11.5.2 (middle of September deadline).

JSON

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-09-15T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11.5.1"
    },
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2"
    }
  ]
}

XML

<key>osVersionRequirements</key>
<array>
  <dict>
    <key>aboutUpdateURL</key>
    <string>https://support.apple.com/en-us/HT211896</string>
    <key>requiredInstallationDate</key>
    <date>2021-09-15T00:00:00Z</date>
    <key>requiredMinimumOSVersion</key>
    <string>11.5.2</string>
    <key>targetedOSVersionsRule</key>
    <string>11.5.1</string>
  </dict>
  <dict>
    <key>aboutUpdateURL</key>
    <string>https://support.apple.com/en-us/HT211896</string>
    <key>requiredInstallationDate</key>
    <date>2021-08-31T00:00:00Z</date>
    <key>requiredMinimumOSVersion</key>
    <string>11.5.2</string>
  </dict>
</array>

Real-world Example 2

With the imminent release of macOS Monterey, you may want a minimum OS version for both Big Sur and Monterey:

JSON

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11"
    },
    {
      "aboutUpdateURL": "https://www.apple.com/macos/monterey-preview/",
      "requiredInstallationDate": "2021-10-30T00:00:00Z",
      "requiredMinimumOSVersion": "12.0.1",
      "targetedOSVersionsRule": "12"
    }
  ]
}

XML

<key>osVersionRequirements</key>
<array>
  <dict>
    <key>aboutUpdateURL</key>
    <string>https://support.apple.com/en-us/HT211896</string>
    <key>requiredInstallationDate</key>
    <date>2021-08-31T00:00:00Z</date>
    <key>requiredMinimumOSVersion</key>
    <string>11.5.2</string>
    <key>targetedOSVersionsRule</key>
    <string>11</string>
  </dict>
  <dict>
    <key>aboutUpdateURL</key>
    <string>https://www.apple.com/macos/monterey-preview/</string>
    <key>requiredInstallationDate</key>
    <date>2021-10-30T00:00:00Z</date>
    <key>requiredMinimumOSVersion</key>
    <string>12.0.1</string>
    <key>targetedOSVersionsRule</key>
    <string>12</string>
  </dict>
</array>

Incorporating majorUpgradeAppPath

If the intent is to Nudge users on an older major OS to upgrade to the latest major OS, and Nudge users on an older minor version of the current major OS, you can safely pass a value to majorUpgradeAppPath and it will be honored by systems on the older OS, and safely ignored for systems on an earlier minor version of the current major OS. For example, this will do the right thing for all users on 11.x and 12.x for the relative Nudge behaviors: users on 12.2.1 will be directed to the System Preferences pane, while users on 11.x will be directed to the Install macOS Monterey app.

   "osVersionRequirements": [
    {
        "majorUpgradeAppPath": "/Applications/Install macOS Monterey.app",
        "requiredInstallationDate": "2022-04-19T12:00:00Z",
        "requiredMinimumOSVersion": "12.3",
        "targetedOSVersionsRule": "default"
      }
  ]

Deploying a configuration that is compatible with both v1.0.0.x and v1.1.0.x

For a configuration that can work with all current versions of Nudge, your primary Nudge event must be the first dictionary of your osVersionRequirements key.

Good Example

In the following good example of a configuration compatible with both v1.0.0.x and v1.1.0.x, targetedOSVersions is listed first:

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersions": [
        "11.0",
        "11.0.1",
        "11.1",
        "11.2",
        "11.2.1",
        "11.2.2",
        "11.2.3",
        "11.3",
        "11.3.1",
        "11.4",
        "11.5",
        "11.5.1"
      ],
      "targetedOSVersionsRule": "default"
    },
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11.5.1"
    }
  ]
}

Bad Example

The following is a bad example of an attempted configuration compatible with both v1.0.0.x and v1.1.0.x; targetedOSVersions is not listed first:

{
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-08-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersionsRule": "11.5.1"
    },
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-07-31T00:00:00Z",
      "requiredMinimumOSVersion": "11.5.2",
      "targetedOSVersions": [
        "11.0",
        "11.0.1",
        "11.1",
        "11.2",
        "11.2.1",
        "11.2.2",
        "11.2.3",
        "11.3",
        "11.3.1",
        "11.4",
        "11.5",
        "11.5.1"
      ],
      "targetedOSVersionsRule": "default"
    }
  ]
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️