Stopping Silent Profile Failures with Declarative Management

A user reports that their VPN stopped connecting the morning after a macOS update. The technician opens System Settings, checks the Profiles pane, sees the payload is still listed, deletes it anyway, waits for the next MDM check-in, and hopes the reinstall sticks. Multiply that by every device that picked up the same OS build, and you have a queue of nearly identical tickets with no shared root cause visible to anyone until someone finally reads a sysdiagnose. That is the old way: profile failures are invisible until a human notices something broken, and diagnosis starts from zero every single time.

The new way uses the status reporting built into Declarative Device Management (DDM) to catch a failing configuration the moment it happens, not at the next scheduled check-in. Instead of technicians polling for symptoms, the Mac itself pushes a status report when a subscribed item changes state. Pair that push with an automated remediation script and an API-driven redeploy, and the failure is corrected before the user even notices the payload dropped.

#Why Configuration Profile Failures Go Quiet

Classic MDM check-ins are reactive. The device receives an APNs push telling it commands are waiting, contacts the server, and reports command status as a flat Acknowledged, Error, or NotNow. There is no ongoing feedback loop describing whether a Wi-Fi payload is still valid, whether a certificate reference resolved, or whether a VPN configuration silently detached after a profile edit. If nobody is watching the Profiles pane on that specific Mac, the failure sits there until the user complains.

Declarative Device Management, introduced with macOS 13 Ventura and expanded through Sonoma and Sequoia, changes the model. The device evaluates declarations locally and autonomously enforces them, then proactively sends a Status Report whenever a subscribed StatusItem changes, rather than waiting to be asked. That means a broken certificate reference, a duplicate identifier collision, or a Wi-Fi payload that failed validation gets reported within seconds of the failure, not at the next scheduled poll. The most common silent-failure causes worth automating around are: certificate rotation breaking a PayloadCertificateUUID reference, Smart Group flapping causing repeated profile removal and reinstallation, a profile edited without a version bump so the device thinks nothing changed, and scope conflicts where a locally installed profile shares an identifier with a server-pushed one.

#Prerequisites and Permissions

• Target devices running macOS 13 or later, ideally macOS 14+ for full StatusItem coverage.
• Devices enrolled through Automated Device Enrollment via Apple Business Manager or Apple School Manager for full supervised DDM behaviour. User-approved enrolments receive partial declarative support only.
• An MDM server with documented DDM support: Jamf Pro 10.44 or later exposes a Declarative Device Management tab in computer inventory; Microsoft Intune supports declarative compliance signal ingestion for supported profile types.
• A Jamf Pro API role scoped to Send Computer Remote Commands, Read and Update Smart Computer Groups, and Create Webhooks. Do not use a full administrator token for this automation.
• An API client secret stored in a secrets manager, never committed to a script file or repository.
• A pilot Smart Group capped at 25 devices for the first rollout. Blast radius for this automation is limited to reinstalling or reissuing configuration declarations; it must never touch FileVault, firmware password, or account payloads.
• A monitoring signal already wired up: Smart Group membership count for a group named something like DDM Configuration Failed, and webhook delivery success rate from your MDM platform.

#Implementation Steps

1. Confirm DDM capability on target devices.
   Action: run a local capability check before subscribing to status.

   Terminal

   1/usr/bin/profiles status -type enrollment
   2/usr/sbin/system_profiler SPConfigurationProfileDataType | grep -i "Declarative"

   Expected result: enrollment status returns MDM enrollment: Yes (User Approved) and the device reports a valid management client capability. Evidence: capture the raw command output as a text log named after the device serial number, stored with the pilot rollout ticket.

2. Publish a Status Subscriptions declaration to the pilot group.
   Action: push a DeclarativeConfiguration command containing a status-subscriptions declaration so the device knows which items to report on.

   JSON payload

   1{
   2  "Identifier": "0BB7E38A-4C1B-4B3E-9C2A-STATUSSUB01",
   3  "Type": "com.apple.management.status-subscriptions",
   4  "Payload": {
   5    "StatusItems": [
   6      "device.identifier.serial-number",
   7      "management.declarations",
   8      "management.client-capabilities",
   9      "security.certificate-list"
   10    ]
   11  }
   12}

   Expected result: the device acknowledges the declaration and it appears under Active Declarations for that host in your MDM console. Evidence: the declaration acknowledgement timestamp in the MDM server log.

   

3. Surface DDM status inside Jamf Pro inventory.
   Action: enable Declarative Device Management data collection under Computer Inventory Collection settings, then build a Smart Group.

   Smart Group criteria: Declarative Device Management Status is Failed OR Configuration Profile Status is Error. Expected result: the Smart Group populates automatically the next time a subscribed device reports an invalid state. Evidence: a screenshot-free log export of the Smart Group membership list showing at least one device during your simulated failure test (see Verification).

4. Build the remediation script.
   Action: write a script that forces a declarative refresh and checks the resulting state before exiting.

   Terminal

   1#!/bin/bash
   2set -euo pipefail
   3
   4LOG="/var/log/ddm-selfheal.log"
   5echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) starting remediation" >> "$LOG"
   6
   7/usr/bin/profiles renew -type enrollment
   8STATUS=$(/usr/bin/profiles status -type enrollment)
   9
   10if echo "$STATUS" | grep -q "MDM enrollment: Yes"; then
   11  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) remediation succeeded" >> "$LOG"
   12  exit 0
   13else
   14  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) remediation failed" >> "$LOG"
   15  exit 1
   16fi

   Expected result: exit code 0 on success, exit code 1 on failure, both written to the local log. Evidence: policy run history in Jamf Pro showing the script’s captured stdout and exit status, or the equivalent Intune shell script run report.

5. Wire the Smart Group to an automated redeploy via webhook.
   Action: configure a Jamf Pro webhook for the SmartGroupComputerMembershipChange event, pointed at a small receiver that calls the API to reissue the failed declaration.

   Python

   1from flask import Flask, request
   2import requests
   3
   4app = Flask(__name__)
   5JAMF_URL = "https://yourinstance.jamfcloud.com"
   6TOKEN = "REPLACE_WITH_SCOPED_BEARER_TOKEN"
   7
   8@app.route("/ddm-webhook", methods=["POST"])
   9def handle_membership_change():
   10    payload = request.get_json()
   11    group_name = payload.get("event", {}).get("smartGroup", {}).get("name", "")
   12    if group_name != "DDM Configuration Failed":
   13        return "", 204
   14    computer_id = payload["event"]["computer"]["id"]
   15    resp = requests.post(
   16        f"{JAMF_URL}/api/v1/mdm/commands",
   17        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
   18        json={
   19            "clientData": [{"managementId": computer_id}],
   20            "commandData": {"commandType": "DECLARATIVE_MANAGEMENT_REFRESH"}
   21        },
   22        timeout=15
   23    )
   24    return {"status": resp.status_code}, 200

   Note: confirm the exact command type identifier against your MDM vendor’s current API reference before production use, since command catalogues change between releases. Expected result: the flagged computer drops out of the failed Smart Group within one re-evaluation cycle, typically five minutes. Evidence: webhook receiver log entry paired with the Smart Group’s next membership snapshot showing the device removed.

6. Add an offline-first fallback with a LaunchDaemon.
   Action: deploy a LaunchDaemon so the remediation script also runs on a fixed interval regardless of server reachability, covering devices that are intermittently off the corporate network.

   Terminal

   1cat << 'EOF' > /Library/LaunchDaemons/com.company.ddmselfheal.plist
   2<?xml version="1.0" encoding="UTF-8"?>
   3<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   4<plist version="1.0">
   5<dict>
   6  <key>Label</key>
   7  <string>com.company.ddmselfheal</string>
   8  <key>ProgramArguments</key>
   9  <array>
   10    <string>/usr/local/bin/ddm-selfheal.sh</string>
   11  </array>
   12  <key>StartInterval</key>
   13  <integer>14400</integer>
   14  <key>RunAtLoad</key>
   15  <true/>
   16</dict>
   17</plist>
   18EOF
   19chown root:wheel /Library/LaunchDaemons/com.company.ddmselfheal.plist
   20chmod 644 /Library/LaunchDaemons/com.company.ddmselfheal.plist
   21launchctl bootstrap system /Library/LaunchDaemons/com.company.ddmselfheal.plist

   Expected result: the daemon fires every four hours (14400 seconds) and on load, writing to the local log even when the device cannot currently reach the MDM server. Evidence: /var/log/ddm-selfheal.log showing periodic entries independent of server contact.

   

7. Configure escalation alerting.
   Action: add an attempt counter as a custom extension attribute, and alert when it crosses a threshold.

   Terminal

   1ATTEMPTS_FILE="/var/db/ddm_attempts.count"
   2COUNT=$(cat "$ATTEMPTS_FILE" 2>/dev/null || echo 0)
   3if [ "$COUNT" -ge 3 ]; then
   4  curl -s -X POST -H "Content-Type: application/json" 
   5    -d '{"text": "DDM remediation failed 3x on this host, needs L2 review"}' 
   6    "https://hooks.example.com/services/REPLACE_WITH_WEBHOOK_PATH"
   7fi

   Expected result: an alert lands in the on-call channel within 60 seconds of the third consecutive failure. Evidence: the Slack or Teams message timestamp and the corresponding attempt count logged locally.

#Verification and Expected Evidence

Before trusting this automation on the full fleet, force a controlled failure on a pilot device: intentionally break a certificate reference by revoking a test certificate tied to a Wi-Fi or VPN payload, then confirm the following chain of evidence in order:

1{
2  "StatusItems": {
3    "management": {
4      "declarations": {
5        "configurations": [
6          {
7            "identifier": "com.company.vpn.zero-trust",
8            "active": false,
9            "valid": "invalid",
10            "server-token": "def456",
11            "reasons": [
12              { "code": "InvalidPayload", "description": "Certificate reference not found" }
13            ]
14          }
15        ]
16      }
17    }
18  }
19}

1. The status report above arrives at the MDM server within seconds of the break, showing valid: invalid and a reason code.
2. The device appears in the DDM Configuration Failed Smart Group within one inventory update cycle.
3. The webhook receiver log shows a POST call fired and a 200 or 202 response from the MDM command endpoint.
4. The local self-heal log on the device shows a remediation attempt and either success or a recorded failure with an incrementing attempt counter.
5. The Smart Group membership refreshes and the device is removed once the certificate reference is restored, or an escalation alert fires if it is not.

Keep the JSON status report, the Smart Group export, and the webhook log together as your evidence bundle for the pilot sign-off.

#Rollback

If the automation misbehaves, for example redeploying commands in a loop or flooding the webhook receiver, roll back in this order:

1. Disable the Jamf Pro webhook subscription for SmartGroupComputerMembershipChange immediately to stop further automated calls.
2. Send a RemoveDeclaration command for the status-subscriptions identifier to the pilot group so devices stop pushing status reports that trigger the loop.
3. Unload and remove the LaunchDaemon:
   Terminal

   1launchctl bootout system /Library/LaunchDaemons/com.company.ddmselfheal.plist
   2rm /Library/LaunchDaemons/com.company.ddmselfheal.plist

4. Restore the previous configuration profile version from your MDM’s version history if a bad edit caused the original failure.
5. Document the rollback reason and the device count affected before re-attempting the pilot.

#Failure and Escalation Conditions

• Wake a human immediately if the fleet-wide failure rate for any single declaration identifier exceeds 5 percent of the enrolled population within one hour, this indicates a systemic certificate, network, or profile authoring problem rather than a device-level issue.
• Escalate to L2 if a single device fails remediation three times within 30 minutes, since repeated local retries without success usually mean a hardware, keychain, or Secure Enclave issue that scripting cannot fix.
• Escalate to L3 if APNs push delivery errors persist for more than 15 minutes across multiple devices, since this points at a certificate expiry or push connectivity problem upstream of any single Mac.
• Treat any Status Report showing a server-token mismatch that persists after a clean redeploy as a signal to manually inspect the profile’s raw XML for malformed payload references before re-pushing again.

#Measuring Ticket Deflection

Baseline your current ticket volume for categories tagged with terms like profile missing, VPN not connecting, or Wi-Fi keeps dropping over a rolling 90-day window before deployment. After the automation is live for one full patch cycle, compare the same categories against the same device population size. A useful deflection formula is: deflection rate equals (baseline tickets minus post-deployment tickets) divided by baseline tickets, expressed as a percentage. Track it alongside two supporting metrics: mean time from failure detection to remediation, which should fall from hours or days down to single-digit minutes, and the ratio of auto-resolved failures to escalated ones, which tells you whether the threshold in the escalation step needs tuning. Review both numbers monthly during the first quarter after rollout, then quarterly once the baseline stabilises.