Skip to content

Companion scripts

Small scripts that run next to App Auto-Patch. Two report on it to your MDM; they only read and change nothing on the Mac. Two more add an App Auto-Patch tile to the Root3 Support App.

Script For What it does
AAPCompliance.jamf.ea.sh Jamf Pro extension attribute Reports one value from App Auto-Patch’s patch status
AAPCompliance.intune.sh Microsoft Intune custom attribute The same, for Intune
aap_pending_updates.zsh Root3 Support App Shows how many updates are pending on the tile
aap_pending_apps_dialog.zsh Root3 Support App Opens App Auto-Patch’s deferral dialog when the tile is clicked

With them you can build a smart group of Macs that are overdue, chart how many updates are pending across the fleet, or find Macs where App Auto-Patch has not checked for updates. To keep App Auto-Patch itself current with Jamf Pro, see the Jamf Pro patch source.

The root helper keeps /Library/Application Support/AppAutoPatch/compliance.json current, readable by every user (build 105 and later). It checks once a minute and rewrites the file when something changes, and at least every hour. The scripts read one field from that file each; they do not run App Auto-Patch or Installomator, and they send nothing anywhere.

Field Meaning
status Not checked (no update check yet), No applicable applications discovered (the last discovery found no app to patch), Compliant (nothing pending), Pending, Deadline approaching (hard deadline within 2 days) or Overdue (hard deadline passed)
pendingCount, pendingLabels Apps with an update, as Installomator labels. An app App Auto-Patch installed since the last check is not counted
oldestPendingSince, oldestPendingDays When the oldest pending update was first seen, and how many whole days ago
hardDeadline, daysUntilHardDeadline The hard deadline while updates are pending, and the days left (negative once it has passed)
brokenLabels Labels whose check is skipped because they keep reporting no latest version
lastDiscovery, lastSuccessfulPatch When updates were last checked, and when App Auto-Patch last installed an app or found it already current
appVersion App Auto-Patch version and build

A value that is not set is left out of the file. Dates are ISO 8601 text.

Without a hard deadline, status never goes past Pending. Set DeadlineDaysHard to get Deadline approaching and Overdue.

While the cycle’s patching is complete, an update found after the completion waits for the next cycle, so it is Pending, with no hardDeadline (build 116). With a managed hard deadline, an update that was already pending before the completion still counts against that cycle’s deadline, because App Auto-Patch still enforces it.

Download AAPCompliance.jamf.ea.sh or copy the script below, then:

  1. In Jamf Pro open Settings, then Computer management, then Extension attributes, and add a new one.
  2. Name it, for example, App Auto-Patch status. Set Data type to String (use Integer for pendingCount, oldestPendingDays and daysUntilHardDeadline) and Input type to Script.
  3. Paste the script, check the FIELD line, and save. Jamf Pro collects the value at the next inventory update.

The script reports one field, named on the FIELD line at the top. Make one extension attribute per value you want, each with its own FIELD. Use String for the date fields: Jamf’s Date type expects a different format.

AAPCompliance.jamf.ea.sh
#!/bin/bash
#
# Jamf Pro extension attribute: App Auto-Patch patch status.
#
# Reads /Library/Application Support/AppAutoPatch/compliance.json, which App Auto-Patch's root
# helper writes after each discovery and patch run, and prints one value from it. Nothing else is
# run. Set FIELD to the value this extension attribute reports; make one extension attribute per
# value you want:
#
# status Not checked, No applicable applications discovered, Compliant, Pending,
# Deadline approaching or Overdue (default)
# pendingCount Number of pending updates
# pendingLabels Pending Installomator labels, separated by spaces
# oldestPendingDays Days since the oldest pending update was first seen
# daysUntilHardDeadline Days left before the hard deadline (negative once passed)
# brokenLabels Labels that report no latest version, separated by spaces
# lastDiscovery When updates were last checked (ISO 8601)
# lastSuccessfulPatch When App Auto-Patch last installed or confirmed an app (ISO 8601)
#
# Prints "Not reported" when the file is missing, and an empty result when the value is not set.
#
FIELD="status"
FILE="/Library/Application Support/AppAutoPatch/compliance.json"
if [ ! -f "${FILE}" ]; then
echo "<result>Not reported</result>"
exit 0
fi
case "${FIELD}" in
pendingLabels|brokenLabels)
value="$(/usr/bin/plutil -extract "${FIELD}" json -o - "${FILE}" 2>/dev/null \
| /usr/bin/tr -d '[]"' | /usr/bin/tr ',' ' ')"
;;
*)
value="$(/usr/bin/plutil -extract "${FIELD}" raw -o - "${FILE}" 2>/dev/null)"
;;
esac
echo "<result>${value}</result>"

A Mac that has no compliance.json reports Not reported. That means App Auto-Patch is not installed, is older than build 105, or its root helper has not run yet.

For example, a smart group of Macs that need attention uses the criteria App Auto-Patch status is Overdue, and one for early warning uses is Deadline approaching.

Jamf Pro reads the extension attribute only at an inventory update. To have it, and the Mac’s app versions, catch up right after App Auto-Patch installs updates, set JamfReconAfterPatching to true (build 115 and later). The root helper then runs jamf recon after each patch run that updates an app, at most once every JamfReconMinimumIntervalMinutes (default 30).

Download AAPCompliance.intune.sh or copy the script below, then:

  1. In the Intune admin center open Devices, then macOS, then Custom attributes, and add one.
  2. Give it a name and choose the data type String (or Integer for pendingCount, oldestPendingDays and daysUntilHardDeadline).
  3. Upload the script with the FIELD line set to the value to report, and assign it to your Macs. Add one custom attribute per value.
AAPCompliance.intune.sh
#!/bin/bash
#
# Microsoft Intune custom attribute: App Auto-Patch patch status.
#
# Reads /Library/Application Support/AppAutoPatch/compliance.json, which App Auto-Patch's root
# helper writes after each discovery and patch run, and prints one value from it. Nothing else is
# run. Add it in Intune under Devices > macOS > Custom attributes, with the data type String
# (or Integer for the counts and day values). Set FIELD to the value to report; add one custom
# attribute per value:
#
# status Not checked, No applicable applications discovered, Compliant, Pending,
# Deadline approaching or Overdue (default)
# pendingCount Number of pending updates
# pendingLabels Pending Installomator labels, separated by spaces
# oldestPendingDays Days since the oldest pending update was first seen
# daysUntilHardDeadline Days left before the hard deadline (negative once passed)
# brokenLabels Labels that report no latest version, separated by spaces
# lastDiscovery When updates were last checked (ISO 8601)
# lastSuccessfulPatch When App Auto-Patch last installed or confirmed an app (ISO 8601)
#
# Prints "Not reported" when the file is missing, and nothing when the value is not set.
#
FIELD="status"
FILE="/Library/Application Support/AppAutoPatch/compliance.json"
if [ ! -f "${FILE}" ]; then
echo "Not reported"
exit 0
fi
case "${FIELD}" in
pendingLabels|brokenLabels)
/usr/bin/plutil -extract "${FIELD}" json -o - "${FILE}" 2>/dev/null \
| /usr/bin/tr -d '[]"' | /usr/bin/tr ',' ' '
echo
;;
*)
/usr/bin/plutil -extract "${FIELD}" raw -o - "${FILE}" 2>/dev/null
;;
esac

This script prints the bare value, with no <result> tags. A Mac with no compliance.json reports Not reported.

The Root3 Support App can show an App Auto-Patch tile with the number of pending updates, which opens App Auto-Patch’s deferral dialog when clicked. Download aap_pending_updates.zsh and aap_pending_apps_dialog.zsh (build 119 and later), or copy them below.

Script Support App key What it does
aap_pending_updates.zsh OnAppearAction Each time the popover appears, shows 2 Updates Pending, Up to Date or Not Checked Yet, with the warning badge while anything is pending. It reads pendingCount and status from compliance.json.
aap_pending_apps_dialog.zsh Action Opens App Auto-Patch’s deferral dialog for the person at the Mac, then refreshes the count. With nothing pending, it only refreshes the count.

The dialog is the one App Auto-Patch opens by itself when updates are due. It lists each pending app with its installed and new version, and has the install button, the deferral menu and the defer button. App Auto-Patch checks those apps again just before the dialog opens, and its settings apply as usual: deadlines, the deferral menu, the button text and the dialog timeout. Deferring here counts as a deferral. Once this cycle’s patching is complete, App Auto-Patch opens its dashboard instead.

To set it up:

  1. Deploy both scripts to the same folder on each Mac, owned by root with 755 permissions, as the Support App requires for privileged scripts. They expect /Library/Application Support/AppAutoPatch/SupportApp/. That folder stays through App Auto-Patch updates and is removed with it. To use another folder, change refresh_script_path in aap_pending_apps_dialog.zsh.
  2. In your Support App configuration profile (domain nl.root3.support), add an Extension item to a row’s Items, like the one below. The Support App runs a privileged script only when a configuration profile names it; a value set with defaults write is ignored.
<dict>
<key>Type</key>
<string>Extension</string>
<key>ExtensionID</key>
<string>aap_pending_updates</string>
<key>Title</key>
<string>App Updates</string>
<key>Subtitle</key>
<string>Update Now</string>
<key>Symbol</key>
<string>arrow.down.circle</string>
<key>ActionType</key>
<string>PrivilegedScript</string>
<key>Action</key>
<string>/Library/Application Support/AppAutoPatch/SupportApp/aap_pending_apps_dialog.zsh</string>
<key>OnAppearAction</key>
<string>/Library/Application Support/AppAutoPatch/SupportApp/aap_pending_updates.zsh</string>
</dict>
#!/bin/zsh --no-rcs
# Support App Extension - App Auto-Patch Pending Updates Count
#
# Populates a Root3 Support App Extension with the number of apps that have
# an update pending, read from App Auto-Patch 4's patch status file,
# /Library/Application Support/AppAutoPatch/compliance.json. Its pendingCount
# takes the place of the ItemsToInstall array in 3.x's
# xyz.techitout.appAutoPatchReport.plist.
#
# REQUIREMENTS:
# - App Auto-Patch 4.0.0 (105) or later, with its root helper approved (the
# helper writes compliance.json)
# - Deployed as a Privileged Script referenced by a Support App Extension's
# OnAppearAction, via a Support App Configuration Profile
#
# Intended to run every time the Support App popover appears, so the count is
# always current. It only reads compliance.json, which the root helper checks
# once a minute and rewrites when something changes. See the companion script,
# aap_pending_apps_dialog.zsh, for the action that opens App Auto-Patch's
# dialog and then runs this script again to refresh the count.
# ------------------ edit the variables below this line ------------------
# Extension ID - must match the ExtensionID configured for this Extension in
# the Support App Configuration Profile
extension_id="aap_pending_updates"
# Text shown when there are zero pending updates
uptodate_text="Up to Date"
# Text shown before App Auto-Patch has checked for updates on this Mac
notchecked_text="Not Checked Yet"
# --------------------- do not edit below this line ----------------------
# Support App preference plist
preference_file_location="/Library/Preferences/nl.root3.support.plist"
# App Auto-Patch's patch status, written by its root helper
compliance_file="/Library/Application Support/AppAutoPatch/compliance.json"
# Start spinning indicator
defaults write "${preference_file_location}" "${extension_id}_loading" -bool true
# Show placeholder while loading
defaults write "${preference_file_location}" "${extension_id}" -string "KeyPlaceholder"
# pendingCount leaves out labels the settings ignore and apps App Auto-Patch
# has installed since its last check. With no file yet (the helper hasn't run)
# or no check yet, say so rather than "Up to Date".
aap_status=""
pending_count=""
if [[ -f "${compliance_file}" ]]; then
aap_status=$(/usr/bin/plutil -extract status raw -o - "${compliance_file}" 2> /dev/null)
pending_count=$(/usr/bin/plutil -extract pendingCount raw -o - "${compliance_file}" 2> /dev/null)
fi
[[ "${pending_count}" == <-> ]] || pending_count=0
# Build the display string
if [[ ! -f "${compliance_file}" || "${aap_status}" == "Not checked" ]]; then
display_text="${notchecked_text}"
elif [[ "${pending_count}" -eq 0 ]]; then
display_text="${uptodate_text}"
elif [[ "${pending_count}" -eq 1 ]]; then
display_text="1 Update Pending"
else
display_text="${pending_count} Updates Pending"
fi
# Set output value
defaults write "${preference_file_location}" "${extension_id}" -string "${display_text}"
# Trigger the warning badge whenever there's at least one pending update
if [[ "${pending_count}" -gt 0 ]]; then
defaults write "${preference_file_location}" "${extension_id}_alert" -bool true
else
defaults write "${preference_file_location}" "${extension_id}_alert" -bool false
fi
# Stop spinning indicator
defaults write "${preference_file_location}" "${extension_id}_loading" -bool false
#!/bin/zsh --no-rcs
# Support App Extension - App Auto-Patch Pending Apps Dialog
#
# Opens App Auto-Patch 4's own deferral dialog for the person at the Mac,
# through its appautopatch://show-deferral-prompt link, then refreshes the
# pending-updates count Extension (aap_pending_updates.zsh).
#
# The dialog is the one App Auto-Patch opens by itself when updates are due:
# it lists each pending app with its installed and new version, and has an
# install button, a deferral menu and a defer button. App Auto-Patch checks
# the pending apps again just before it opens, and applies its settings as
# usual: deadlines, the deferral menu, button text, AppTitle and the dialog
# timeout. Deferring here counts as a deferral, as in that dialog. After this
# cycle's patching is complete, App Auto-Patch shows its dashboard instead.
#
# REQUIREMENTS:
# - App Auto-Patch 4.0.0 (105) or later
# - Deployed as a Privileged Script referenced by an Extension's Action, via a
# Support App Configuration Profile (ActionType: PrivilegedScript)
#
# App Auto-Patch 4 has no equivalent of 3.x's --workflow-install-now, which
# patched without a dialog, so this is the only Action script for 4.0.
# ------------------ edit the variables below this line ------------------
# Extension ID - must match the ExtensionID configured for the pending-updates
# Extension in the Support App Configuration Profile
extension_id="aap_pending_updates"
# Path to the companion script that refreshes the pending-updates count.
# Update this if you deploy aap_pending_updates.zsh to a different location.
refresh_script_path="/Library/Application Support/AppAutoPatch/SupportApp/aap_pending_updates.zsh"
# --------------------- do not edit below this line ----------------------
# Support App preference plist
preference_file_location="/Library/Preferences/nl.root3.support.plist"
# App Auto-Patch's patch status, written by its root helper
compliance_file="/Library/Application Support/AppAutoPatch/compliance.json"
app_bundle_id="xyz.techitout.appAutoPatch"
app_process_name="App Auto-Patch"
prompt_url="appautopatch://show-deferral-prompt"
refresh_count() {
if [[ -x "${refresh_script_path}" ]]; then
"${refresh_script_path}"
else
echo "ERROR: ${refresh_script_path} not found or not executable." >&2
# Fall back to at least clearing the loading indicator so the tile
# doesn't get stuck spinning if the refresh script is missing.
defaults write "${preference_file_location}" "${extension_id}_loading" -bool false
fi
}
# App Auto-Patch runs in the session of the person at the Mac, and this script
# runs as root, so open the link as that person.
console_user=$(/usr/bin/stat -f %Su /dev/console)
if [[ -z "${console_user}" || "${console_user}" == "root" || "${console_user}" == "loginwindow" ]]; then
echo "No one is logged in at the Mac; not opening App Auto-Patch."
refresh_count
exit 0
fi
console_uid=$(/usr/bin/id -u "${console_user}")
run_as_console_user() {
/bin/launchctl asuser "${console_uid}" /usr/bin/sudo -u "${console_user}" "$@"
}
# With nothing pending, App Auto-Patch has no dialog to show. Refresh the
# tile, which then reads "Up to Date".
pending_count=$(/usr/bin/plutil -extract pendingCount raw -o - "${compliance_file}" 2> /dev/null)
[[ "${pending_count}" == <-> ]] || pending_count=0
if [[ "${pending_count}" -eq 0 ]]; then
echo "No pending updates in ${compliance_file}; not opening the dialog."
refresh_count
exit 0
fi
# Show a brief loading state on the Support App tile while App Auto-Patch
# opens the dialog.
defaults write "${preference_file_location}" "${extension_id}_loading" -bool true
defaults write "${preference_file_location}" "${extension_id}" -string "Opening App Auto-Patch…"
# The link is handled by a running App Auto-Patch. If it isn't running, start
# it and give it a moment to finish launching before sending the link.
if ! /usr/bin/pgrep -u "${console_uid}" -x "${app_process_name}" > /dev/null; then
echo "App Auto-Patch isn't running for ${console_user}; starting it."
run_as_console_user /usr/bin/open -b "${app_bundle_id}"
for _ in {1..30}; do
/usr/bin/pgrep -u "${console_uid}" -x "${app_process_name}" > /dev/null && break
sleep 1
done
sleep 5
fi
run_as_console_user /usr/bin/open "${prompt_url}"
open_exit=$?
if [[ "${open_exit}" -ne 0 ]]; then
echo "ERROR: could not open ${prompt_url} for ${console_user} (exit ${open_exit})." >&2
fi
# Refresh the pending-updates count. The dialog stays open on its own, and the
# count catches up the next time the popover appears.
refresh_count
exit "${open_exit}"
  • The 3.x scripts read ItemsToInstall from /Library/Management/AppAutoPatch/xyz.techitout.appAutoPatchReport.plist and run /usr/local/bin/appautopatch. Neither exists with 4.0. Its installer removes App Auto-Patch 3.x, and with it /Library/Management/AppAutoPatch, along with any scripts deployed there. Deploy the 4.0 scripts to their new folder and change the profile’s two paths.
  • The ExtensionID and the keys the tile reads are the same, so the rest of the profile item can stay as it is.
  • There is no 4.0 aap_install_now.zsh. App Auto-Patch 4 has no command that installs updates without a dialog, so the dialog’s install button takes its place.
  • pendingCount leaves out labels your settings ignore and apps App Auto-Patch installed since its last check.
  • While App Auto-Patch is checking for or installing updates, it ignores a request to open the dialog, as it does for Update All. Click the tile again once it’s done.
  • If App Auto-Patch isn’t running, the script starts it and waits a few seconds before asking for the dialog.
  • The script logs to the Support App’s log. In App Auto-Patch’s log, the request is a line with Received notification deep-link.

The Intune script prints just the value, so it also fits another tool that reports the output of a script. The file is plain JSON that any tool or script can read.

To see exactly what the scripts see:

Terminal window
cat "/Library/Application Support/AppAutoPatch/compliance.json"

and to run a script by hand, which prints the value your MDM would receive:

Terminal window
bash AAPCompliance.jamf.ea.sh

If the file does not exist, check that App Auto-Patch is installed, is build 105 or later, and that its root helper is approved (see Approving the helper).