osVersionRequirements - macadmins/nudge GitHub Wiki

• osVersionRequirements
• aboutUpdateURL
• aboutUpdateURLs
• actionButtonPath
• majorUpgradeAppPath
• requiredInstallationDate
• requiredMinimumOSVersion
• targetedOSVersions (Deprecated as of v1.1.0)
• targetedOSVersionsRule
• Example (JSON)
• Example (Mobile Configuration)

The required components necessary to enforce an Operating System version through Nudge.

Specify one array to enforce a single Operating System version across all machines or specify multiple arrays for specific enforcements.

A single URL, enabling the More Info button URL path.

Note: If this value is passed with aboutUpdateURLs, the aboutUpdateURLs key will be ignored.

A list of arrays, enabling localization of the More Info button URL path. Please see the aboutUpdateURLs wiki article for more information.

Note: If this value is not passed, the more_info button will be hidden.

v1.1.6 and higher only

A path to a URI for opening alternative actions, like Jamf Self Service items or Munki Self Service items.

• When using this key, you will lose the dynamic capability for updateDevice supporting minor / major upgrades, so it will be up to your separate tool to handle this logic.

Do not pass an empty string with this key or you will get the following error in the nudge logs

actionButtonPath contains empty string - actionButton will be unable to trigger any action required for major upgrades

You can have multiple actionButtonPath per osVersionRequirement dictionary, allowing you to have multiple paths for minor and major upgrades.

Note: If you use actionButtonPath in both osVersionRequirements and the original one in userInterface, Nudge v1.1.6 will ignore the one in userInterface

v1.1.3 and higher only

The full path to a standalone macOS installer for a major upgrade.

*For Mac computers with Apple silicon, the user must be a Volume Owner. (See also: Schedule an OS Update)

1. When using userInterface : actionButtonPath, you will lose the dynamic capability for updateDevice supporting minor / major upgrades, so it will be up to your separate tool to handle this logic.
2. Requires a major macOS installer to be pre-cached and for the user to have local administrative rights
3. Leverages softwareupdate --fetch-full-installer to download the macOS standalone installer and requires the user to have local administrative rights

The required installation date for Nudge to enforce the required operating system version.

You must follow a standard date format as YYYY-MM-DDTHH:MM:SSZ - Example: "2023-03-31T17:00:00Z"

• JSON configuration: A string is required and deadlines are in UTC time.

• Jamf Pro Custom Schema: A string is required for jamfs's JSON Schema Manifest and deadlines are in local timezones.

• Configuration Profile: Either a date key (for a UTC deadline) or a string key (for a local timezone deadline) will work.

Configuration Profile examples:

Deadline in UTC time (all computers worldwide have the same deadline at 5:00 p.m. UTC)

<key>requiredInstallationDate</key>
<date>2023-03-31T17:00:00Z</date>

Deadline in local time (e.g. all computers have a deadline of 5:00 p.m. in their local timezone)

<key>requiredInstallationDate</key>
<string>2023-03-31T17:00:00</string>

The required minimum operating system version.

Note: When passing versions such as 11.2.0 it will be normalized to 11.2. It is recommended to remove the trailing zero from the version number.

v1.0.0 only The versions of macOS that require a security update.

You can specify single version or multiple versions, but they must be within an array.

Examples:

"targetedOSVersions": [
  "11.0"
]

"targetedOSVersions": [
  "11.0",
  "11.0.1",
  "11.1",
  "11.2"
]

v1.1.0 and higher only

For more documentation please see the targetedOSVersionsRule wiki article

The required minimum operating system version. Rules take the following precedence:

• full OS match (example: device is running 11.5.1 and rule is 11.5.1)
• major OS match (example: device us running 11.5.1 and rule is 11)
• default match (example: device is running 11.5.1 and rule is default or targetedOSVersionsRule key is not present)

Note: Passing identical rules will result in "undefined" behavior. Currently with v1.1.0, the last identical rule will be honored. Passing a value of "default" is identical to not passing this key, allowing concurrent deployments of Nudge v1.0 and v1.1.0 in the same environment.

Examples:

"targetedOSVersionsRule": "11.5.2"

"targetedOSVersionsRule": "11"

"targetedOSVersionsRule": "default"

This example allows an admin to support both v1.0 and v1.1.0 behavior

{
    "osVersionRequirements": [
      {
        "aboutUpdateURL": "https://apple.com",
        "requiredInstallationDate": "2021-07-30T00: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"
      }
    ]
}

This example allows an admin to support both v1.0 and v1.1.0 behavior

<?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>PayloadDescription</key>
        <string>Configures osVersionRequirements preferences</string>
        <key>PayloadDisplayName</key>
        <string>Nudge Preferences</string>
        <key>PayloadIdentifier</key>
        <string>com.github.macadmins.Nudge.preferences.example.osVersionRequirements</string>
        <key>PayloadOrganization</key>
        <string></string>
        <key>PayloadType</key>
        <string>com.github.macadmins.Nudge</string>
        <key>PayloadUUID</key>
        <string>CA02957C-7472-446B-9F77-3E0414405556</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>aboutUpdateURL</key>
            <string>https://apple.com</string>
            <key>requiredInstallationDate</key>
            <date>2021-07-30T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.5.2</string>
            <key>targetedOSVersions</key>
            <array>
              <string>11.0</string>
              <string>11.0.1</string>
              <string>11.1</string>
              <string>11.2</string>
              <string>11.2.1</string>
              <string>11.2.2</string>
              <string>11.2.3</string>
              <string>11.3</string>
              <string>11.3.1</string>
              <string>11.4</string>
              <string>11.5</string>
              <string>11.5.1</string>
            </array>
            <key>targetedOSVersionsRule</key>
            <string>default</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Nudge application</string>
    <key>PayloadDisplayName</key>
    <string>Nudge</string>
    <key>PayloadIdentifier</key>
    <string>com.github.macadmins.Nudge.example.osVersionRequirements</string>
    <key>PayloadOrganization</key>
    <string>Nudge</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>2F54F734-132D-4539-B583-F1DCF23DB5EB</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
  </dict>
</plist>