# How DDM Works

> The building blocks of Apple Declarative Device Management — declarations, activations, assets, status reporting — and how they map to what you see in CapaOne.

Source: https://docs.capaone.com/capaone/mobile-manager/apple-ddm/how-ddm-works/  
Product: CapaOne — a separate CapaSystems product; do not apply this page to any other.

This article explains what happens on an Apple device when CapaOne manages it with Declarative Device Management (DDM), and how Apple's DDM building blocks map to what you see in **Apple → Configurations → DDM**. Read it before you migrate, so the statuses and errors you see later make sense.

You don't need this article to create a DDM configuration. You need it when you want to understand *why* a configuration applied, didn't apply, or combined with another one in a way you didn't expect.

## Legacy MDM vs. DDM

Legacy MDM is **command-and-response**. CapaOne sends a command (install this profile, report this inventory, schedule this update), the device runs it once, answers, and forgets. If the device is offline, changes later, or a user undoes a setting, CapaOne only finds out the next time it asks.

DDM is **state-based**. CapaOne describes the state the device should be in — as a set of *declarations* — and the device is responsible for reaching that state and keeping it. When something changes on the device, the device reports it back on its own.

| | Legacy MDM | DDM |
|---|---|---|
| Model | Server sends commands, device answers | Server describes desired state, device enforces it |
| Who keeps the setting in place | The server, by re-sending commands | The device, continuously |
| Status | Server polls (inventory queries) | Device pushes status changes when they happen |
| Offline devices | Commands queue until the device checks in | Device already holds its declarations and acts on them offline (for example, enforcing an update deadline) |
| Unit of configuration | Configuration profile (`.mobileconfig`) with one or more payloads | Declaration (JSON), one setting area per declaration |
| Software updates on iOS 27 / macOS 27 | No longer functions | Required — see [iOS 27 and Software Update Management](/capaone/mobile-manager/apple-ddm/ios-27-and-software-update-management/) |

DDM doesn't replace the MDM enrollment. The device still enrolls with the same MDM profile, push certificate, and Apple Business Manager setup. DDM is turned on *on top of* that enrollment, and both channels stay open: CapaOne can still send Legacy commands (lock, erase, inventory, install a Legacy profile) to a device that runs DDM.

## The four kinds of declarations

Apple defines four kinds of declarations. CapaOne creates and manages most of them for you — you only build two of them yourself.

| Declaration kind | What it does | Where you see it in CapaOne |
|---|---|---|
| **Configuration** | Describes one area of device policy, for example passcode rules, a mail account, or software update settings. | **Apple → Configurations → DDM → New → Configurations** tab. |
| **Asset** | Holds data a configuration needs but that isn't policy by itself, for example a certificate, a SCEP identity, or a username and password. Assets can be shared between configurations and updated independently of them. | **Apple → Configurations → DDM → New → Assets** tab. See [DDM Assets](/capaone/mobile-manager/apple-ddm/ddm-assets/). |
| **Activation** | Tells the device *which* configurations to apply. An activation can also contain a *predicate* — a condition the device evaluates locally — so configurations only apply when the condition is true. | Created by CapaOne from your assignments. You don't edit activations directly. |
| **Management** | Information about the organization and the management server, such as server capabilities and organization details. | Handled by CapaOne. |

### What happens when you assign a configuration

1. You assign a DDM configuration to a group or endpoint in CapaOne.
2. CapaOne updates the device's declaration set and sends the device a push notification.
3. The device connects, compares its current declarations with the new set, and downloads only what changed. Each declaration carries a server token — a revision marker — so unchanged declarations aren't downloaded again.
4. The device validates each declaration. A declaration that isn't supported on that OS version, platform, or enrollment type is marked **invalid** and not applied. Other declarations are unaffected.
5. The device applies the valid configurations and downloads any assets they reference.
6. The device sends a status report to CapaOne with the result for every declaration: whether it's **valid**, whether it's **active**, and — if it failed — a reason code. CapaOne shows that result on the device's **Configurations** tab.

When you remove an assignment, the device removes the configuration and its settings in the same way. For configuration types that combine (see below), the device recalculates the combined result from the configurations that remain.

## Status reporting

A DDM device reports status in two ways:

- **Declaration status** — for every configuration, asset, and activation: whether the device accepted it (`valid`, `invalid`, or `unknown`), whether it's currently `active`, and the **reasons** if something went wrong. This is what CapaOne uses to show the error icon and reason on the device's **Configurations** tab. See [DDM Status Reason Codes](/capaone/troubleshooting/ddm-status-reason-codes/) for what each reason means.
- **Status items** — facts about the device, such as OS version, software update install state, pending update version, and passcode compliance. The device sends a new value as soon as it changes, without waiting to be asked.

In CapaOne, open the device in **Apple → Endpoints** and select the **Configurations** tab. **Assigned** lists the configurations, with a **DDM** label on DDM configurations, and **Applied** shows the settings the device received from each configuration. You can also open the configuration and select its **Endpoints** tab, which shows each endpoint's **Status** and how the configuration is assigned.

![Apple device Applied configurations with Software Update Settings selected](/attachments/capaone/how-ddm-works--device-applied.png)

CapaOne doesn't show the raw status items below as separate fields. They're listed so you know what the device reports to CapaOne. Status items that matter most day to day:

| Status item | What it tells you |
|---|---|
| `device.operating-system.version` / `build-version` | The OS version and build the device runs. |
| `softwareupdate.install-state` | `none`, `downloading`, `prepared`, `installing`, or `failed`. |
| `softwareupdate.pending-version` | The OS version and build that's pending, and — if it's being enforced — the enforcement date and time. |
| `softwareupdate.failure-reason` | How many times the pending update failed, the last reason, and when. |
| `softwareupdate.install-reason` | Why an update is pending: for example `declaration` (a DDM enforcement), `system-settings` (the user started it), or `auto-update`. |
| `passcode.is-present` / `passcode.is-compliant` | Whether the device has a passcode, and whether it meets every passcode policy on the device. |
| `mdm.enrollment-type` | `supervised`, `device`, or `user` — iOS 27 and later. |

## How configurations of the same type interact

Every DDM configuration type follows one of three rules for what happens when more than one configuration of that type reaches the same device. This is defined by Apple, not by CapaOne.

| Rule | What happens | Examples |
|---|---|---|
| **Combined** | All configurations of the type are merged into one effective policy. Each setting has its own merge rule — usually the most restrictive value wins. | Passcode Settings, Software Update Settings, App Settings, Safari Settings, Intelligence Settings, Siri Settings |
| **Multiple** | Each configuration applies on its own, side by side. | Account Mail, Account Exchange, Security Certificate, Security Identity, Network VPN IKEv2, Software Update Enforcement Specific |
| **Single** | Only one configuration of the type can be active on the device. | Network VPN Always On, Content Caching |

See [How Multiple DDM Configurations Combine](/capaone/mobile-manager/apple-ddm/how-ddm-configurations-combine/) for the per-setting merge rules and how to avoid conflicts.

If the same setting is delivered both by a Legacy profile and a DDM configuration, Apple's rule is the same as for overlapping profiles: the device merges them and enforces the strictest setting. The exception is software updates: DDM software update configurations take precedence over the equivalent Legacy MDM commands.

## Enrollment type decides what a device accepts

Apple defines, per configuration type and per setting, which enrollment types it supports. A device rejects a configuration — or ignores individual settings in it — when its enrollment type isn't supported.

| Apple enrollment type | In CapaOne | Typical use |
|---|---|---|
| `supervised` | **Supervised** | Company-owned devices enrolled through Apple Business Manager (Automated Device Enrollment). |
| `device` | **Unsupervised (BYOD)** | Personally owned devices where the user installs the enrollment profile manually. |
| `user` | Not offered | Apple User Enrollment (account-driven). CapaOne enrollment configurations are either **Supervised** or **Unsupervised (BYOD)**. |

The [DDM Configuration Types Reference](/capaone/mobile-manager/apple-ddm/ddm-configuration-types-reference/) shows whether each type works on Unsupervised devices. Some types are accepted on Unsupervised devices but have individual settings that only work on Supervised ones — for example, deferrals in **Software Update Settings**. On those devices, the device applies the rest of the configuration and reports the unsupported settings back (`Info.UnsupportedSettings`).

## Legacy profiles inside DDM

Apple lets a Legacy configuration profile be delivered *through* DDM, wrapped in a **legacy profile declaration**. This is how a setting without a native DDM equivalent can still be managed declaratively. **Home Screen Layout** in CapaOne works this way.

A legacy profile declaration can also *take over* a profile that Legacy MDM already installed, without removing and reinstalling it, when the profile's identifiers and payload structure match exactly. While DDM owns the profile, Legacy MDM commands can't install, update, or remove it.

## Good to know

- **DDM is per device, not per configuration** — once a device runs DDM, it accepts both DDM configurations and Legacy profiles. You migrate configurations at your own pace.
- **A failed declaration doesn't block the others** — if one configuration is invalid on a device, every other configuration still applies.
- **The device keeps enforcing while offline** — declarations are stored on the device. A software update deadline, for example, is enforced even if the device can't reach CapaOne at that moment.
- **Status arrives on the device's schedule** — status is sent when it changes, so a configuration's status can show as pending for a short time after assignment while the device processes it.
- **Source:** Apple's [device management schema](https://github.com/apple/device-management/tree/release/declarative) (Release v27.0, September 2026) and Apple Platform Deployment: [Use declarative device management to manage Apple devices](https://support.apple.com/guide/deployment/declarative-device-management-manage-apple-depc30268577/web).