Configuring the Software Updates Component - Jamf Pro Blueprints Configuration Guide

Jamf Pro Blueprints Configuration Guide
Solution
Application
Content Type
Technical Documentation
Utilities & Services
ft:locale
en-US

Use the Software Updates component in a blueprint to enforce OS updates on Apple devices using declarative device management. When deployed, Jamf sends declarations directly to each device specifying which OS version to install and by when.

This topic walks you through choosing an enforcement type, understanding how declarations are applied to devices, and interpreting deployment status reports. The number and structure of declarations sent to a device depends on which enforcement type you choose, and understanding this behavior is important for correctly configuring your blueprint and interpreting the resulting status reports.

Requirements

Verify that target devices meet the minimum OS version required for software update enforcement. Devices that do not meet the minimum will not receive declarations, will not appear as failed in deployment status reports, and will be silently skipped.

If you are deploying to a mixed-OS fleet, check device eligibility before deploying to avoid assuming enforcement is working on ineligible devices.

  1. Create a blueprint with a Software Updates component.

    For instructions, see Building a Blueprint from a Library of Components.

  2. Choose an enforcement type for the Software Updates component.

    Two enforcement types are available. Select the type that matches your organization's update policy:

    • Specific OS version and time —

      Use this when you need all devices to reach an exact OS version by a set deadline. This enforcement type is best for compliance deadlines, validated builds, or change-controlled environments. A single declaration is sent to all scoped devices with no conditions; every device is required to install the specified version by the deadline.

      This option does not update automatically when Apple releases a new version. You must manually reconfigure the blueprint for new targets.

    • Latest OS version —

      Use this when you want devices to stay current, enforcing the latest available OS version within a number of days that you specify. One declaration is generated per available OS version that meets minimum requirements, and each declaration includes a condition that determines whether it applies to a given device based on its current OS family and version.

      Note:

      When the enforcement type is set to Latest OS version, declarations for every available minor OS version are sent and the device incrementally upgrades through each version before it upgrades to the latest minor version it is eligible for.

      Two configuration options are available:

      • Include major versions —Devices update to the newest available version across all supported major versions, including new major OS releases such as moving from iOS 17 to iOS 18. Leave the Ignore major versions checkbox deselected to use this setting. This option is best for environments that prioritize devices with the latest OS at all times.
      • Ignore major versions —Devices update only within their current major version. For example, a device on iOS 17.x will update to the latest iOS 17 release, but will not be upgraded to iOS 18. Select the Ignore major versions checkbox to use this setting. This option is best for environments that want security patches applied without moving devices to a new major OS release.
  3. Review how declarations are applied to devices based on your chosen enforcement type.

    Declaration behavior differs between enforcement types. Understanding this behavior helps you predict how devices will progress through updates.

    • With Specific OS version and time, a single declaration is sent with no activation condition. It applies unconditionally to all scoped devices, which are each required to install the exact version specified by the enforcement deadline.

    • With Latest OS version, one declaration is generated per available OS version that meets minimum requirements. On each device, the following occurs:

      1. The device evaluates each declaration's activation condition against its current OS family and version. Only declarations whose conditions evaluate to true become active.
      2. Active declarations are processed in deadline order, earliest first. Each deadline is calculated by adding the number of enforcement days you configured to the date Apple posted the OS version. For example, if Apple posted a version on 01 June and you set enforcement to 14 days at 9:00 AM, the deadline is 15 June at 9:00 AM local device time. When multiple versions share the same posting date, the system enforces them from highest to lowest version so devices always progress toward the most current release.
      3. After each upgrade, conditions are re-evaluated. Declarations for versions the device has already reached or exceeded automatically become inactive.
      Example:A device on iOS 17.5 with active declarations for versions 17.7.1, 18.6.1, and 18.6.2 will first upgrade to 17.7.1 because that deadline comes earliest. After that upgrade, conditions are re-evaluated and the device proceeds to 18.6.1, then 18.6.2. This step-by-step progression reflects Apple's typical sequential release schedule and is expected behavior.

    If Apple releases multiple OS versions on the same day, their enforcement deadlines will be nearly identical. In this scenario, a device may skip intermediate versions and jump directly to the highest available version. This is expected and requires no action.

  4. Click Save.
  5. Click Deploy to deploy the blueprint to the configured device groups.
  6. After deploying your blueprint, review the deployment status of the declarations contained within the blueprint. For more information, see Viewing the Status of a Blueprint (Jamf Pro API).

    With Latest OS version, each device generates one status entry per declaration. Seeing multiple status entries per device is normal. Use the following definitions to distinguish expected states from genuine failures.

    • Success —

      All declarations scoped to the device have reported in. The device has either applied the update or correctly determined that a declaration did not apply to it.

      Important:

      You may see valid: unknown paired with Error.ActivationFailed and Info.Predicate for some declarations. This is not an error. It means the declaration's condition evaluated to false for that device. For example, because the device was already on a newer version or a different OS family. This is expected behavior.

      Do not confuse this with valid: invalid, which indicates an actual configuration failure and requires investigation.

    • Pending —At least one scoped declaration has not yet reported back. The device may not have checked in recently or may be offline. No action is needed unless the device remains in this state for an extended period.
    • Failed —At least one declaration reports valid: invalid, meaning something went wrong. Review the details for that device to determine the cause.