updated for Setup Manager 1.4.2

ChangeLog.md

@@ -1,5 +1,127 @@
 #  Setup Manager - Change Log
 
+## 1.4.1
+
+(2025-12-22)
+
+- `finishedScript` and `finishedTrigger` now respect when `DEBUG` key is set and do nothing (#181)
+- improved error detection and reporting in `DEBUG` mode (#150, #180)
+- adjusted recon/Update Inventory workflow, to adapt to a change in `jamf` binary (#177)
+- fixed custom JSON for Jamf Pro profile for Webhooks (#184)
+- localization fixes
+
+## 1.4
+
+(2025-12-03)
+
+While making sure that Setup Manager looks nice with macOS Tahoe and Liquid Glass, we have added a few more features to improve customization.
+
+### New Features
+- User Interface
+  - macOS Tahoe/Liquid Glass adaptions
+  - new `banner` key allows you to provide a banner image that cover the top part of the Setup Manager window ([details](ConfigurationProfile.md#banner))
+  - `title` and `icon` keys are now optional, when a `banner` key is set
+  - action tiles can have a background color set with the top-level or per-action 'tileColor'key
+  - `banner` and `background` can use hex or system colors
+  - where colors are defined, you can use system color names. See ['Defining Colors'](ConfigurationProfile.md#defining-colors) for details
+- new profile keys:
+  - `networkQualityCheck` suppresses network bandwidth calculation when set to `false` (#135)
+  - `finishedMessage` for a customized message when Setup Manager workflow is complete (#128)
+- logging:
+  - new tab for configuration profiles in the log
+  - detection of configuration profile installation and removal
+  - image/icon load errors are now logged
+  - logs a warning when Setup Manager detects it is launched for a second time
+- switched launch tracking to a new service (see [Launch Tracking](Docs/LaunchTracking.md) for details)
+
+### Fixes and Improvements
+
+- disabled check for Jamf.app as it could fail in some challenging network configs
+- enrollmentUserID added to webhook data (#140)
+- localization fixes (#149)
+- elapsed time in Mac Info window stops counting when workflow is finished 
+- link to computer in Slack and Teams messages should work with Jamf School
+- setting computer name with user entry or `computerNameTemplate` works with Jamf School
+- updated uninstall.sh script (#156)
+- (beta2) Localization:
+  - added UK English (en-GB) localization (thanks to @philipross)
+  - various localization fixes (#171)
+- (beta2) fixed Network Info font color (#166)
+- (beta2) `waitForUserEntry` action correctly runs a recon/Update Inventory (#168)
+- (beta2) `accentColor` affects all items and controls (#170)
+- (beta2) UI adjustments (#169)
+
+
+### Changes, deprecations and removals
+- (1.4) `userID` top-level key name changed to `enrollmentUserID`
+- (1.4) `jssID` key has been renamed to `computerID`
+- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
+- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
+- (1.1)the method for providing localized texts in the configuration profile changed in version 1.1. The previous method (by appending the two letter language code to the key) is considered deprecated. It will continue to work for the time being but will be removed in a future release. It is _strongly_ recommended to change to the [new dictionary-based solution](ConfigurationProfile.md#localization)
+
+### Notes
+
+There are quite a few new options in Setup Manager 1.4 beta to configure and customize the new UI. There is a new option for a color or image banner across the top of the Setup Manager window. Action tiles can now be colored automatically or with specific colors. Colors can now be set anywhere that image sources are used and you get a list of named system colors.
+
+While the [description of all the keys in the repo](ConfigurationProfile.md) has been updated, many of the keys, old and new, now work together for a variety of useful combinations.
+
+#### Updating the profile to use 1.4 (beta) features
+
+The good news first: we designed the update so that you can keep using the same profile from earlier versions and the Setup Manager window will look mostly the same on macOS Sequoia and earlier, and have the new “Liquid Glass” look and feel on macOS Tahoe.
+
+To use the new UI options, set the new keys.
+
+#### Banner
+
+Setup Manager 1.4 introduces the option to show a color or image banner in the top of the Setup Manager window. This is controlled by the top-level [`banner` key](ConfigurationProfile.md#banner). The `banner` value is an [image source](ConfigurationProfile.md#icon-sources), so it can be a reference to local image file, an image file hosted on a web server, or (also new in 1.4) a [color designation](ConfigurationProfile.md#defining-colors).
+
+Colors can be set with hex codes, e.g. `#f00` or `#f900a2` or with (new in 1.4) system color names, e.g. `##gray`, `##red`, etc.
+
+The size of the banner area is 800x233 pixels (1600x466 @2x) on Sequoia and earlier and 800x247 (1600x494 @2x) on Tahoe (the liquid glass tool bar is taller). The image will be displayed with bottom-center alignment and _not_ scaled, so you can add a few extra pixels at the top and the same image should work for all macOS versions.
+
+The behavior of the `icon` and `title` keys changes depending on whether the `banner` has a value.
+
+When _no_ `banner` value is set, Setup Manager will show its app icon when an `icon` key is missing or empty. It will also show ‘Welcome’ or the localized equivalent when the `title` key is missing or empty.
+
+When the `banner` _is_ set, an empty or missing `title` or `icon` will simply not be shown. This lets you use the banner image for a completely customized experience.
+
+Note that the `banner` value can be localized.
+
+#### Action Tile Colors
+
+Setup Manager 1.4 allows you to set a color for the action tiles. Use the [top-level `tileColor` key](ConfigurationProfile.md#tilecolor) to set the color for all action tiles. You can also set the tile color for an individual action with [a `tileColor` key in the action](ConfigurationProfile.md#tilecolor-1).
+
+When no `tileColor` is set, the default behavior is to use the window background color (gray on Sequoia and earlier, white on Tahoe, or the dark mode equivalent).
+
+You can set the `tileColor` value (top-level and action level) to [a hex color or system color name](ConfigurationProfile.md#defining-colors). There are a few special color names:
+
+- `##automatic`: calculates each tile's color from the average color of each action’s icon, icons defined with `symbol:…` will use the default color
+- `##background`: system window background (gray on Sequoia and earlier, white on Tahoe)
+- `##clear`: transparent or no background, works best when `hideActionLabels` is set to false
+
+See [`tileColor`](ConfigurationProfile.md#tilecolor-1) and [‘Defining Colors’](ConfigurationProfile.md#defining-colors) in the documentation for details.
+
+#### Profile Installation and Removal Logging
+
+A new tab has been added to logging window which logs the installation and removal of configuration profiles. These events will also be logged to the main Setup Manager log, which allows you to see them in context of the entire workflow.
+
+This can be especially useful to determine whether a particular profile disrupts the network and possibly the download of an important component. In the unified system log, these entries will have the `profile` category.
+
+
+## 1.4beta2
+
+(2025-11-24)
+
+Same as [the previous beta](https://github.com/jamf/Setup-Manager/releases/tag/v1.4beta) with these additional changes:
+
+- Localization:
+  - added UK English (en-GB) localization
+  - various localization fixes (#171)
+- fixed Network Info font color (#166)
+- `waitForUserEntry` action correctly runs a recon/Update Inventory (#168)
+- `accentColor` affects all items and controls (#170)
+- UI adjustments (#169)
+
 ## v1.4beta
 (2025-10-28)
 

ConfigurationProfile.md

@@ -21,7 +21,7 @@ These behaviors change in debug mode:
 - `policy`, `recon`, and `shell` actions that require root are replaced with a delay (and will always complete successfully)
 - `watchPath` and `wait` actions timeout and fail after 10 seconds
 
-When in debug mode, you can also set the `simulateMDM` preference key to `Jamf Pro` or `Jamf School`. This allows you to do test runs on un-enrolled Macs.
+When in debug mode, you can also set the `simulateMDM` preference key to `Jamf Pro` or `Jamf School`. This is _necessary_ for test runs on un-enrolled Macs and to launch Setup Manager as a local user.
 
 #### `title`
 
@@ -447,10 +447,12 @@ The label is used as the name of the action in display.
 
 (String, optional, localized, dark mode)
 
-The [icon source](#icon-sources) used for the display of the label. Different types of actions will have different default icons, which are used when no `icon` key is present. The icons will be scaled to fit 64x64 pixels (or 128x128 @2x).
+The [icon source](#icon-sources) used for the display of the label. Different types of actions will have different default icons, which are used when no `icon` key is present. The icons will be scaled to fit 120x120 pixels.
 
 There are several different types of actions, and these are defined by additional keys. These keys will be on the same level as the keys above.
 
+**Note on icon margins:** when you use a path to an app for the icon, or when you use an icon generated by copying the icon from an app in Finder or by a tools such as the [SAP Icon Generator](https://github.com/SAP/macOS-icon-generator), there will be a margin around the icon. Since these are very common ways of getting icons, the layout of the icons in the action tile is designed around the assumption that there will be a margin. Icons without such a margin will look quite big fill most of the space available in the tile.
+
 #### `tileColor`
 
 (String, optional, dark mode, v1.4)
@@ -840,7 +842,7 @@ Example:
 
 ## User Entry
 
-You can enable user entry for the following keys:
+You can enable user entry for the following fields:
 
 - `userID`
 - `email`
@@ -856,6 +858,8 @@ You can enable user entry for the following keys:
 
 Any of the fields will only be shown when its key exists. If you were to create an empty `userEntry` dict, you get an empty user input screen with a 'Save' button - not a good user experience.
 
+For each field, you need to provide at least one of `default`, `placeholder`, or `options`.
+
 `userID` and `email` can be somewhat confusing and depending on which Cloud directory you have configured in Jamf Pro, you may need one or the other or both. Because of this Setup Manager 1.1 and older would only prompt for 'User email' and set both `userID` and `email` from that value. To maintain compatibility with this behavior, Setup Manager will continue to set _both_ `userID` and `email` when only one of the two values is requested and entered. If you request both fields, both will be set individually in the recon.
 
 
@@ -863,6 +867,9 @@ Any of the fields will only be shown when its key exists. If you were to create
 
 Data from user entry is written, together with some other data to a file when Setup Manager reaches a `waitForUserEntry` action and again when it finishes. The file is stored at `/private/var/db/SetupManagerUserData.txt`. [More details.](Docs/Extras.md#user-data-file)
 
+
+### Keys
+
 #### `default`
 
 (String, localized)
@@ -1015,7 +1022,7 @@ In this example, the 'Room' field will be shown in Setup Manager with the label
 
 You can configure Setup Manager to only show the user entry section when specified users have authenticated in enrollment customization. This enables workflows, where certain users (techs and admins) get the option to re-assign the device to another user, but other users don't see the option.
 
-For this, you need to setup the top-level `enrollmnetUserID` to receive the `$EMAIL` variable. This will communicate to SetupManager the user who logged in with customized enrollment. Then you add key `showForUserIDs` with an array of user emails to the `userEntry` dict. When both `enrollmentUserID` and `userEntry.showForUserIDs` are set, the user entry UI will only show for the listed users.
+For this, you need to setup the top-level `enrollmentUserID` to receive the `$EMAIL` variable. This will communicate to SetupManager the user who logged in with customized enrollment. Then you add key `showForUserIDs` with an array of user emails to the `userEntry` dict. When both `enrollmentUserID` and `userEntry.showForUserIDs` are set, the user entry UI will only show for the listed users.
 
 #### `showForUserIDs`
 
@@ -1111,7 +1118,7 @@ can be localized like this:
   <key>de</key>
   <string>Willkommen!</string>
   <key>fr</key>
-  <string>Bienvenu!</string>
+  <string>Bienvenue!</string>
   <key>nl</key>
   <string>Welkom!</string>
 </dict>
@@ -1150,11 +1157,12 @@ The following keys can be localized:
 
 - `label`
 
-Use these two-letter codes for these languages:
+Use these codes for these languages:
 
 | Language           | two-letter code |
 |--------------------|-----------------|
 | English            | en (default)    |
+| English (UK)       | en-GB           |
 | Dutch (Nederlands) | nl              |
 | French             | fr              |
 | German             | de              |
@@ -1162,8 +1170,10 @@ Use these two-letter codes for these languages:
 | Italian            | it              |
 | Norwegian          | nb              |
 | Polish             | pl              |
+| Portuguese (Brazil)| pt-BR           |
 | Spanish            | es              |
 | Swedish            | sv              |
+| Turkish            | tr              |
 
 The [plist and profile example files](Examples) contain localizations for many of the custom text elements.
 

Docs/Extras.md

@@ -31,7 +31,13 @@ The custom schema does not contain all keys and options available in the [config
 
 When you reach the limits of the custom schema, use the XML it generates as a starting to building a custom XML.
 
-Note that the custom schema can become confused when you switch between enrollment action types and you will need to clean up extra empty fields.
+Note that the custom schema can become confused when you switch between enrollment action types and you will need to clean up extra empty fields. It is best to delete the action type you don't need any more and create a new action of the desired type.
+
+While the Jamf Pro interface offers different schemas for different versions of Setup Manager, you _only_ have to upgrade to the latest version when you need to use new features only available in that version.
+
+## iMazing Profile Editor
+
+There is also a manifest for Setup Manager in [iMazing Profile Editor](https://imazing.com/profile-editor).
 
 ## Quit
 
@@ -41,7 +47,7 @@ The command-Q keyboard shortcut to quit the app is disabled. Use `shift-control-
 
 While Setup Manager is running you can open a log window with command-L.
 
-There are two or three tabs, one for the main Setup Manager log, one showing output from `/var/log/install.log`, one showing configuration profile installation and removal, and (Jamf Pro only) one tab showing output from `/var/log/jamf.log`. Some log tabs will be summarized to events relevant to the enrollment workflow. You can see the full log content by unchecking the 'Summarize' option.
+There are several tabs, one for the main Setup Manager log, one showing output from `/var/log/install.log`, one showing configuration profile installation and removal, and (Jamf Pro only) one tab showing output from `/var/log/jamf.log`. Some log tabs will be summarized to events relevant to the enrollment workflow. You can see the full log content by unchecking the 'Summarize' option.
 
 Note that the extra logs (Install, Profiles, and Jamf) show events that were not initiated by Setup Manager. Nevertheless, these events can be relevant to your enrollment workflow.
 
@@ -64,6 +70,8 @@ For example:
 sudo log show --last 30m --predicate 'subsystem="com.jamf.setupmanager"'
 ```
 
+There is a button at the top of the log window which creates a new folder named `SetupManagerLogs-<timestamp>` in `/Users/Shared` and copies Setup Manager, install, and (when present) jamf log files there. Hold the option key to select a different location. Note the logs are copied in their current state, so wait until Setup Manager is done before exporting. 
+
 ## Debug mode
 
 When you set the `DEBUG` key to `true` in the profile or locally with the `defaults` command Setup Manager will not perform any tasks that actually perform installations or otherwise change the system. When in DEBUG mode, Setup Manager will also read settings from the local settings (i.e. `~/Library/Preferences/com.jamf.setupmanager.plist`) which simplifies iterating through different settings. If you want to run Setup Manager on an unmanaged Mac, you may need to provide a `simulateMDM` key with a value of either `Jamf Pro` or `Jamf School`.

Docs/FAQ.md

@@ -8,20 +8,23 @@
 
 Yes, use the top-level `background` key and point it to a local image file or a http URL to an image file. If you don't want custom branding, you can set `background` to `/System/Library/CoreServices/DefaultDesktop.heic` for the default image.
 
-## Setup Manager is not launching after enrollment
+## Setup Manager is not launching after enrollment?
 
-There can be many causes for this. A few common causes are:
+There can be many causes for this.
+
+First, check whether the Setup Manager.app exists at `/Applications/Utilities/Setup Manager.app` and a Setup Manager log file gets created at `/Library/Logs/Setup Manager.log`. When the app and the log file exist, read the log file for errors and messages which should give you a hint as to what is going on. When you have no user account to log in, you can boot to Recovery to check on these files.
+
+If neither of those files exist, then the download and/or installation of Setup Manager is failing or not occurring in the first place. A few common causes are:
  
-- when running at 'enrollment,' you need at least one of the 'Setup Assistant Options' in the Prestage to be set to _not_ skip. 'Location Services' or 'Terms & Conditions' are a good choice that you generally want to leave up the user anyway. Otherwise, Setup Assistant may quit before Setup Manager can launch and do its actions.
-- when using a distribution point other than Jamf Cloud Distribution Point, you need [to provide a manifest](https://appleshare.it/posts/use-manifest-file/)
-- Jamf Pro: 
-    - check that Setup Manager is added to your Prestage and the package does not have the label "Availability pending" in Settings> Packages
-    - in Prestage > Enrollment Packages verify that the Distribution Point is set correctly (it resets to "none" when you remove the last enrollment package, so this is easy to miss)
-    - you can try deleting the Setup Manager pkg from Packages and re-uploading it
-    - verify that the pkg is not installed during Prestage by checking for the presence of `Setup Manager.app` in `/Applications/Utilities`, if the app does not exist, the Prestage is not installing Setup Manager
-    - when the above steps do not remedy the issue, please engage Jamf Support.
+- Jamf Pro:
+    - when using a distribution point other than Jamf Cloud Distribution Point, you need [to provide a manifest](https://appleshare.it/posts/use-manifest-file/)
+    - check that Setup Manager is added to your Prestage and the package does **not** have the label "Availability pending" in Settings> Packages. Pending packages will not install during prestage. Wait a few minutes to see if the pending label updates
+    - in Prestage > Enrollment Packages verify that the Package is added and the Distribution Point is set correctly (the DP resets to "none" when you remove the last enrollment package from Prestage, so this is easy to miss)
+    - you can try deleting the Setup Manager pkg from Packages, re-uploading the package and re-adding it to the Prestage. (and verify that the Distribution Point is set correctly in the Prestage)
+- when the above steps do not remedy the issue, please engage Jamf Support.
+- when running at 'enrollment,' Setup Manager requires Setup Assistant to be running in the background. When you are using standard macOS user account creation, Setup Assistant will be showing that pane "behind" Setup Manager, so you should be fine. But if you are using Jamf Connect Login or a similar tool for account creation, you need at least one of the 'Setup Assistant Options' in the Prestage to be set to _not_ skip. 'Location Services' or 'Terms & Conditions' are a good choice that you generally want to leave up the user anyway. Otherwise, Setup Assistant may quit before Setup Manager can launch and do its actions.
 
-## Does Setup Manager require Jamf Connect
+## Does Setup Manager require Jamf Connect?
 
 No.
 

Docs/JamfPro-QuickStart.md

@@ -51,7 +51,7 @@ You can add more actions here. There are more types of actions available, you ca
 - create a new Prestage or duplicate an existing one
 - add the Setup Manager pkg and the configuration profile to the Prestage
 - when installing and using Jamf Connect Login, ensure you have the latest version
-- ensure that 'Automatically advance through Setup Assitant' is _disabled_
+- ensure that 'Automatically advance through Setup Assistant' is _disabled_
 - have at least one Setup Assistant option which shows before user creation _disabled_ (so that _is_ displayed), we recommend the Location Services or Terms and Conditions pane
 - ensure your test Mac(s) is (are) assigned to the Prestage
 

Docs/LaunchTracking.md

@@ -24,4 +24,4 @@ No signals are sent when `DEBUG` is set to `true`. The signal is sent to `nom.te
 
 We use this data to determine the usage of Setup Manager and where to focus future development, so we appreciate when you let us gather this data.
 
-You can suppress the tracking signal by setting the `PLEASE_DO_NOT_TRACK' boolean key to `true` in the configuration profile.
+You can suppress the tracking signal by setting the `PLEASE_DO_NOT_TRACK` boolean key to `true` in the configuration profile.

Examples/sample-com.jamf.setupmanager.plist

@@ -113,7 +113,7 @@
 		<key>es</key>
 		<string>¡^[^[Bienvenido](inflect: true)](inflectionAlternative: &apos;Te damos la bienvenida&apos;)!</string>
 		<key>fr</key>
-		<string>Bienvenu!</string>
+		<string>Bienvenue!</string>
 		<key>he</key>
 		<string>ברוכים הבאים!</string>
 		<key>it</key>

Examples/sample-jamfschool.mobileconfig

@@ -101,7 +101,7 @@
 									<key>en</key>
 									<string>Welcome!</string>
 									<key>fr</key>
-									<string>Bienvenu!</string>
+									<string>Bienvenue!</string>
 									<key>nl</key>
 									<string>Welkom!</string>
 								</dict>

Examples/sample-waitForUserEntry.plist

@@ -131,7 +131,7 @@
 		<key>es</key>
 		<string>¡Bienvenido!</string>
 		<key>fr</key>
-		<string>Bienvenu!</string>
+		<string>Bienvenue!</string>
 		<key>he</key>
 		<string>ברוכים הבאים!</string>
 		<key>it</key>

README.md

@@ -4,13 +4,18 @@
 
 _"Every Assistant has a Manager"_
 
-![Setup Manager Logo](https://img.shields.io/badge/macOS-13.5%2B-success)
- 
-Updates are published in the '[Releases](https://github.com/jamf-concepts/setup-manager/releases)' section of the repo. There you can also [download the latest pkg installer](https://github.com/jamf-concepts/setup-manager/releases/latest). You can subscribe to notifications for the repo using the 'Watch' button above.
+![minOS](https://img.shields.io/badge/macOS-13.5%2B-success)
+![GitHub Release](https://img.shields.io/github/v/release/jamf/setup-manager?color=green)
+![GitHub Pre-Release](https://img.shields.io/github/v/release/jamf/setup-manager?include_prereleases&label=pre-release)
+![GitHub Downloads total](https://img.shields.io/github/downloads/jamf/setup-manager/total)
+![GitHub Downloads latest](https://img.shields.io/github/downloads/jamf/setup-manager/latest/total)
 
-Please report issues, feature requests [as an issue.](https://github.com/jamf-concepts/setup-manager/issues)
 
-We have opened the [discussions](https://github.com/jamf-concepts/setup-manager/discussions) area for questions and more generic feedback.
+Updates are published in the '[Releases](https://github.com/jamf/setup-manager/releases)' section of the repo. There you can also [download the latest pkg installer](https://github.com/jamf/setup-manager/releases/latest). You can subscribe to notifications for the repo using the 'Watch' button above.
+
+Please report issues, feature requests [as an issue.](https://github.com/jamf/setup-manager/issues)
+
+We have opened the [discussions](https://github.com/jamf/setup-manager/discussions) area for questions and more generic feedback.
 
 There is also a [`#jamf-setup-manager`](https://macadmins.slack.com/archives/C078DDLKRDW) channel on the [MacAdmins Slack](https://macadmins.org).
 
@@ -42,7 +47,7 @@ Setup Manager provides:
   - zero-touch and user-initiated deployments (forthcoming)
   - [extra installations based on user data entry](Docs/JamfPro-TwoPhase.md)
   - [Single-touch workflow with user re-assignment using Jamf Connect](Docs/JamfProConnect-SingleTouch.md)
-  - [handsfree deployment with AutoAdvance and Setup Manager at login window (beta)](Docs/JamfPro-LoginWindow.md)
+  - [handsfree deployment with AutoAdvance and Setup Manager at login window](Docs/JamfPro-LoginWindow.md)
 - [Jamf School](Docs/JamfSchool-Setup.md)
 - [Extras and Notes](Docs/Extras.md)
 - [Frequently Asked Questions](Docs/FAQ.md)
@@ -67,4 +72,4 @@ Setup Manager requires macOS 13.5 or higher. It will work only with Jamf Pro or
 
 ---
 
-Please report issues, feature requests, and feedback (positive and negative) [as an issue.](https://github.com/Jamf-Concepts/Setup-Manager/issues)
+Please report issues, feature requests, and feedback (positive and negative) [as an issue.](https://github.com/jamf/Setup-Manager/issues)