targetedOSVersionsRule

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.

Precedence of rules

Rules take the following precedence:

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

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

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

Real-world Example 2

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

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

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