Available Software
Available Software is a standalone macOS app that gives users two things: a self-service catalog for installing optional software titles approved by IT, and a management view for every app currently under patcher control. It is installed to /Applications/Available Software.app as part of the Third Party Patcher package.
Available Software can be launched from:
-
PatcherMenu — the Available Software button appears in the Actions section when
OptionalLabelshas at least one entry. -
Directly — from
/Applications/Available Software.app, Spotlight, or the Dock.
The window opens to a NavigationSplitView: a fixed-width sidebar (220 pt) on the left and a scrollable detail area on the right. The default window size is 720×560 pt (minimum 740×680 pt).
A ▶ Run Now menu button in the toolbar lets anyone trigger patcher phases directly from the window. An optional ? help button to its right opens the Support Info panel when ShowHelpButton is true.
See Toolbar for details on both buttons.
The sidebar header displays a branding icon, optional company name, and app title. Below it, two navigation sections provide access to all views.
The header icon (CatalogHeaderIcon) follows the same DialogIcon preference used by swiftDialog prompts. It supports:
-
Empty
DialogIcon: shows a cached icon fromConfig/dialog_icon.pngif present, otherwise the system computer icon. - File path: loads the image from disk.
-
SF=<symbolName>: renders an SF Symbol.
An MDM overlay badge appears in the lower-right corner of the icon when UseOverlayIcon is true (the default). The overlay is auto-detected from common MDM agent paths (Jamf, Intune, Company Portal, Kandji, Workspace ONE, Addigy, FileWave) or set explicitly via OverlayIcon.
Below the icon, CompanyName is shown as a bold title and AppTitle is shown as a secondary subtitle.
| Sidebar item | Badge | Description |
|---|---|---|
| All Applications | Total catalog count | Every title in OptionalLabels
|
| Installed | Count with detected version | Titles where the app is found on disk |
| Not Installed | Count without detected version | Titles not yet installed |
When catalog metadata includes a Category field for at least one title, a Categories section appears below Available Software, with one row per unique category and a count badge. Clicking a category filters the grid to that category only. Categories are sourced from the metadata repository and cannot be edited directly.
| Sidebar item | Badge | Description |
|---|---|---|
| Managed Software | Count of discovered apps | All apps known to patcher |
| Pending Updates | Count of staged installers | Updates downloaded and ready to apply |
| Pending Downloads | Count of detected-but-unstaged updates | Updates found but not yet downloaded |
| Update History | (none) | Chronological log of patch events |
| About | (none) | Version info, statistics, and diagnostics |
The catalog requires OptionalLabels to be configured. Each label in the list that has a corresponding label file on disk and is not in a broken state appears as a tile in the grid.
A search bar and sort control appear above the grid for the All, Installed, Not Installed, and category filter modes. Search matches against:
- App display name
- Installomator label key
- Publisher name
- Description text
- Keywords
- Category
The Sort segmented control toggles between Default (preserves the order from OptionalLabels) and A–Z (alphabetical by display name).
Each tile shows the app icon, display name, a short description (if available), and an Install or Installed button. Only one install can run at a time; all Install buttons are disabled while any install is in progress.
Install button states:
| State | Label | Behavior |
|---|---|---|
| Not installed, idle | Install | Enabled; triggers install |
| Not installed, another installing | Install | Disabled (greyed out) |
| Queued (waiting for active install to finish) | Queued… | Non-interactive |
| Actively installing this app | Progress spinner + status text | Non-interactive |
| Installed | Installed | Disabled |
Clicking any tile opens an inline detail view (replaces the grid; no new window). A Back button returns to the grid.
The detail view shows:
- Large (80×80 pt) app icon
- App name, publisher, category
- Installation status (version number if installed, "Not installed" otherwise)
- Install button (or progress state if installing)
- About section — description from metadata
- Links section — Homepage, Documentation, and Privacy Policy clickable links
- History section (shown only if the app is installed) — discovered, updated, and self-service install events with timestamps
| Condition | Message |
|---|---|
No OptionalLabels configured |
"No Software Available — Your IT team hasn't configured any optional software titles." |
| Filter has no matches (no search) | Filter-specific message (e.g. "All Apps Installed" for the Not Installed filter) |
| Search returns nothing | "No Results for "…"" |
When a user clicks Install, the following happens:
- The label is marked as queued. All other Install buttons disable.
- An XPC call is sent to
com.gilburns.patcher.xpc, invokinginstallLabel(<label>). - The scheduler runs
patcher ensure <label>— scan, stage, and apply in sequence for that single label. This bypasses the bandwidth limit and theIgnoreAppsInHomeFolderpreference so the app always installs to/Applications. - While the install is running,
active_phase.jsonin the config folder is watched. The label's tile (and detail view) shows a live status string from this file (e.g. "Downloading…", "Installing…"). - When the phase file disappears (install complete), the catalog reloads.
- If
AddToDockOnSelfServiceInstallistrue(the default), the newly installed app is added to the user's Dock automatically.
Only one install can run at a time. If the user clicks Install while something else is installing, the request is queued and begins immediately after the first install finishes.
Icons and metadata are resolved from three sources in priority order:
| Priority | Source | Path |
|---|---|---|
| 1 (highest) | Admin-managed | /Library/Application Support/Patcher/Managed/Icons/<label>.png |
| 2 | Synced metadata repo | /Library/Application Support/Patcher/Installomator-Metadata/Icons/<label>.png |
| 3 (fallback) | Remote GitHub | Fetched from the configured metadata repository at launch |
Metadata (description, publisher, homepage, documentation, privacy, keywords, category) follows the same priority. Admin-managed metadata lives in /Library/Application Support/Patcher/Managed/Metadata/<label>.plist.
The remote fetch is only used when no local file exists — either before the first metadata sync or for labels that have no local metadata file. After the first sync, the app operates entirely from local files.
Language support: Available Software checks the user's preferred language first. For a user with French set as their first language, it looks for Metadata/fr/<label>.plist before falling back to Metadata/<label>.plist. This applies to both admin-managed and synced metadata.
See Installomator Integration for how to configure the metadata sync and how to create admin-managed overrides.
The Managed Software view shows every app that patcher has discovered — the full set of apps known to be installed and under management. This is independent of the Optional Labels catalog; an app does not need to be in OptionalLabels to appear here.
Each tile shows the app icon, name, and update status:
| Status | Label | Meaning |
|---|---|---|
upToDate |
Up to Date (green) | Installed version matches the latest available |
updateRequired |
Update Available (orange) | A newer version has been detected |
userSpace |
Out of Scope (gray) | App is installed in a user's home folder; IgnoreAppsInHomeFolder is on |
unknown |
Status Unknown (gray) | No update check has run yet for this app |
An Open button appears on the tile when the app's install path is known.
A search bar filters by name, label key, publisher, description, keywords, and category.
Clicking a tile opens a detail view showing:
- App icon, name, publisher, label key, update status
- Open button (if path is known)
- About and Links sections from metadata (if available)
-
Location section — all install paths from
foundInstalls, each with a magnifying glass button to reveal it in Finder - History section — patch events for this app
The Pending Updates view lists all apps with a staged (downloaded and verified) installer waiting to be applied. This mirrors what the scheduler will act on at the next apply cycle.
An Apply All Updates button at the top triggers the apply phase immediately via XPC.
Clicking a tile opens a detail view showing the new version number, publisher, About/Links metadata, and an Apply All Updates button.
When nothing is staged, a green "No Pending Updates — All managed software is up to date." message fills the view.
The Pending Downloads view lists apps where an update has been detected but the installer has not yet been downloaded and staged.
A Download Now button at the top triggers the stage phase immediately via XPC.
Clicking a tile opens the Managed App detail view for that app (with a Pending Downloads back label).
When nothing is pending, a green "No Pending Downloads — Nothing to download at the moment." message fills the view.
The Update History view shows a chronological log of all patch events, grouped by month and sourced from the history.json files in each label's cache folder.
A segmented filter at the top narrows the list:
| Filter | What it shows |
|---|---|
| All | Every event type |
| Updates | Daemon-applied updates (applied events) |
| Self-Service | User-initiated installs from the catalog |
| Discovered | First-time app discovery events |
Event appearance:
| Event | Icon color | Title format |
|---|---|---|
| Daemon update | Green | Updated: v1.2 → v1.3 |
| Self-service install | Blue | Self-service install: v1.3 |
| Discovered | Gray | Discovered: v1.2 |
Clicking any row opens a full history detail view for that app, showing all its events in chronological order along with metadata (publisher, About, Links).
The About panel shows identity, statistics, and system information at a glance.
| Section | Contents |
|---|---|
| Label Library | Installomator label version, Managed Labels version, catalog count, installed count |
| Update Statistics | Apps under management, all-time applied update count, unique apps updated, pending update count |
| Last Activity | Last run time for Scan, Check, Stage, and Apply phases |
| System | macOS version, computer name |
Preferences Diagnostic: Holding Control+Option+Shift while clicking the app icon in the About panel opens a diagnostic sheet listing every active preference key and its current value. This is useful for verifying that MDM profiles or config file preferences have been applied correctly.
Available Software has two optional toolbar buttons in the upper-right corner of the window.
The play.circle icon opens a drop-down menu for triggering patcher phases on demand — the same actions available in PatcherMenu's Run Now button. It is always visible.
| Menu item | Phase triggered | When disabled |
|---|---|---|
| Apply pending updates | apply |
No staged updates are waiting |
| Download new Updates | stage |
No detected-but-unstaged updates exist |
| Check for Updates | check |
Never disabled |
| Full Discovery Scan | scan |
Never disabled |
Apply pending updates always appears. The three additional items are individually controlled by preference keys:
| Item | Preference key | Default |
|---|---|---|
| Download new Updates | ShowMenuDownloadAction |
false |
| Check for Updates | ShowMenuCheckAction |
false |
| Full Discovery Scan | ShowMenuScanAction |
false |
The ? button opens the same support info popover used by PatcherMenu. It shows the IT team name, email (clickable mailto), and optional phone number and website link. Hidden when ShowHelpButton is false.
Available Software supports a custom app icon configured via CustomAppIconPath. The path should point to a PNG or ICNS file accessible at runtime. The icon is applied in two ways:
- Dock and app switcher: set in-process at launch; takes effect immediately.
-
Finder icon (shown in
/Applicationsand the Dock when the app is not running): set via XPC to the daemon (requires root). Requires a relaunch to update the Dock tile.
When the preference value changes while the app is running, Available Software detects the change on the next data reload and prompts the user to relaunch.
The following preferences affect Available Software. See Preference Keys for the full reference.
| Key | Default | Purpose |
|---|---|---|
OptionalLabels |
(empty) | Comma-separated list of Installomator label keys to show in the catalog |
CompanyName |
Patcher Corp. |
Company/org name in the sidebar header |
AppTitle |
Third Party Patcher |
Subtitle in the sidebar header and window title |
DialogIcon |
(empty) | Icon shown in the sidebar header |
UseOverlayIcon |
true |
Show an MDM badge on the sidebar icon |
OverlayIcon |
(empty) | Path to a custom overlay icon (auto-detected if empty) |
CustomAppIconPath |
(empty) | Path to a PNG/ICNS used as the app's Dock and Finder icon |
AddToDockOnSelfServiceInstall |
true |
Add newly installed apps to the user's Dock |
ShowHelpButton |
true |
Show the ? support info button in the toolbar |
ShowMenuDownloadAction |
false |
Show Download new Updates in the Run Now toolbar menu |
ShowMenuCheckAction |
false |
Show Check for Updates in the Run Now toolbar menu |
ShowMenuScanAction |
false |
Show Full Discovery Scan in the Run Now toolbar menu |
SupportTeamName |
IT Support Team |
Support panel team name |
SupportTeamEmail |
support@company.com |
Support panel email |
SupportTeamPhone |
None |
Support panel phone number |
SupportTeamWebsite |
None |
Support panel website URL |