From ca999349a7c714e0d02668f7d0db054195d9cb8c Mon Sep 17 00:00:00 2001
From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Date: Wed, 19 Jul 2023 09:32:21 -0400
Subject: [PATCH] MDM docs: Add instructions for triggering native macOS update
 reminders (#12816)

- Add instructions on how to trigger native macOS notifications for OS
updates
- Link to this section from the RSR section
---
 docs/Using-Fleet/MDM-macOS-updates.md | 89 ++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 2 deletions(-)

diff --git a/docs/Using-Fleet/MDM-macOS-updates.md b/docs/Using-Fleet/MDM-macOS-updates.md
index dd0e3c194c..30f2be09d3 100644
--- a/docs/Using-Fleet/MDM-macOS-updates.md
+++ b/docs/Using-Fleet/MDM-macOS-updates.md
@@ -51,7 +51,7 @@ Step 2 (installing the update) always requires end user action.
 
 Currently, end user macOS update reminders via Nudge don't support RSR versions (ex. "13.4.1 (a)"). 
 
-You can use custom MDM commands in Fleet to trigger built-in macOS update reminders for RSRs. Learn which MDM commands to use in the Apple docs [here](https://support.apple.com/guide/deployment/rapid-security-responses-dep93ff7ea78/web).
+You can use custom MDM commands in Fleet to trigger built-in macOS update reminders for RSRs. Learn how [here](#end-user-macos-update-via-built-in-macos-notifications).
 
 #### Mac is up to date
 
@@ -71,7 +71,92 @@ Sometimes after the end user clicks "update" on the Nudge window, the end user's
 
 ## End user macOS update via built-in macOS notifications
 
-Built-in macOS update reminders are available for all Fleet instances. To trigger these reminders, run the ["Schedule an OS update" MDM command](https://developer.apple.com/documentation/devicemanagement/schedule_an_os_update).
+Built-in macOS update reminders are available in Fleet Free and Fleet Premium. 
+
+To trigger these reminders, we will do the following steps:
+
+1. Force a macOS update scan
+
+2. List available macOS updates
+
+3. Trigger macOS update reminder
+
+### Step 1: force a macOS update scan
+
+Use the request payload below when running a custom MDM command with Fleet. Documentation on how to run a custom command is [here](./MDM-commands#custom-commands).
+
+Request payload:
+
+```xml
+<?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>Command</key>
+    <dict>
+        <key>ForceUpdateScan</key>
+        <true/>
+        <key>RequestType</key>
+        <string>ScheduleOSUpdateScan</string>
+    </dict>
+</dict>
+</plist>
+```
+
+### Step 2: list available macOS updates
+
+1. Run another custom MDM command using the request payload below.
+
+Request payload:
+
+```xml
+<?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>Command</key>
+    <dict>
+        <key>RequestType</key>
+        <string>AvailableOSUpdates</string>
+    </dict>
+</dict>
+</plist>
+```
+
+2. Copy the `ProductKey` from the command's results. Documentation on how to view a command's results is [here](./MDM-commands#step-4-view-the-commands-results).
+
+Example product key: `MSU_UPDATE_22F770820d_patch_13.4.1_rsr`
+
+### Step 3: trigger macOS update reminder
+
+Run another custom MDM command using the request payload below. Replace the product key with your product key.
+
+> This payload will trigger the "Install ASAP" behavior which displays a macOS notification with a 60 seconds timer before the Mac automatically restarts. The end user can dismiss the timer. To trigger different behavior, update the `InstallAction`. Options are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/scheduleosupdatecommand/command/updatesitem).
+
+Request payload:
+
+```yaml
+<?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>Command</key>
+    <dict>
+        <key>RequestType</key>
+        <string>ScheduleOSUpdate</string>
+        <key>Updates</key>
+        <array>
+            <dict>
+                <key>InstallAction</key>
+                <string>InstallASAP</string>
+                <key>ProductKey</key>
+                <string>MSU_UPDATE_22F770820d_patch_13.4.1_rsr</string>
+            </dict>
+        </array>
+    </dict>
+</dict>
+</plist>
+```
 
 <meta name="pageOrderInSection" value="1502">
 <meta name="title" value="MDM macOS updates">