updated changelog for 1.2

* fixed links for custom schema and some minor typos

* fixed links for custom schema and some minor typos

ChangeLog.md

@@ -1,5 +1,51 @@
 #  Setup Manager - Change Log
 
+v1.2
+(2025-03-17)
+
+### New Features
+- Setup Manager can send [webhooks](Docs/Webhooks.md) on start and finish, (#70)
+  - (beta2) added [a specific webhook to send a message to Microsoft Teams](Docs/WebHooks.md#Microsoft-Teams)
+- User Entry:
+  - `email`, `endUsername`, `realname`, `position` and  `phone` fields added. These will be submitted to Jamf Pro when Setup Manager finishes and during a `waitForUserEntry` action
+  - you can set custom and localized labels for user entry fields in the profile with a `label` key
+- [User Data file](Docs/Extras.md#user-data-file) now contains a list of enrollmentActions
+- added 'restart' option to ['finalAction'](ConfigurationProfile.md#finalAction) (#38, #58)
+- [icon sources](ConfigurationProfile.md#icon-source) and [`accentColor`](ConfigurationProfile.md#accentColor) can now have [a dark mode alternative defined in the profile](ConfigurationProfile.md#dark-mode) (#61)
+- hitting the space bar while Setup Manager is the Active window will open a window with a scannable barcode of the serial number
+- `message` and help:`message` now interpret [markdown formatting](ConfigurationProfile.md#markdown) (#46)
+
+### Fixes and Improvements
+- (beta3 and release) return key connected to final action and save buttons (#93)
+- (beta3) added an `event` field to standard webhook data, (#94)
+- (beta3) "facts" in Teams message are no longer in random order
+- (beta3) improved reliablity of running at login window (#77)
+- (beta2) an empty `userEntry` dictionary in the profile no longer chokes the UI (#85)
+- (beta2) MDM check more resilient to certain profile configs (#87)
+- (beta2) the `name` field in WebHook data was shortened from `SetupManagerFinished` and `SetupManagerStarted` to `Finished` and `Started`
+- (beta2) early log entry when debug mode is enabled
+- icon for `waitForUserEntry` can be changed from the profile
+- shell actions correctly show success or failure, depending on their exit code#39)
+- Jamf Pro policy actions show success or failure in most situations. Note that there are many things a policy can potentially do. Not all failures are caught. This registers failed pkg installations and policy scripts that return a non-zero exit code, which should cover most situations. Note also, these checks will only work on macOS 13 and higher. On macOS 12, Jamf policies will always be reported as success.
+- read enrollment actions data from profile after user-initiated enrollments more reliably
+- now tries for 15 seconds to reload images with local file paths, this should help in situations were the resources file are installed after Setup Manager
+- many other fixes and improvements
+- updated included Installomator to 10.7
+- user data file will contain the enrollment user when the `userID` key is set
+- battery warning threshold is now different for Intel (%50) and Apple silicon (%20) Macs. This matches Apple's warnings before applying software updates
+
+### Deprecations and Removals
+- the minimum macOS requirement for Setup Manager will be raised to macOS 13 soon
+- `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
+- 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).
+
+### Beta Features
+
+Even though we are confident that the release is overall stable and ready to be used in production, we believe this feature may require more testing. When, after thorough testing in your environment, you conclude this works for your workflow, please let us know about success or any issues you might encounter.
+
+- Setup Manager can now run over Login Window, instead of immediately after installation. This also allows Setup Manager to work with AutoAdvance. Use [the new `runAt` key](ConfigurationProfile.md#runAt) in the profile to determine when Setup Manager runs
+
+
 ## v1.1.1
 (2025-01-28)
 

ConfigurationProfile.md

@@ -2,8 +2,8 @@
 
 The project some sample files to get you started:
 - [sample plist](Examples/sample-com.jamf.setupmanager.plist) for Jamf Pro
-- [sample plist](Examples/sample-waitForUserEntry) for Jamf Pro with [two phase workflow](Docs/JamfPro-TwoPhase.md)
-- [configuration profile](Example/sample-jamfschool.mobileconfig) for Jamf School
+- [sample plist](Examples/sample-waitForUserEntry.plist) for Jamf Pro with [two phase workflow](Docs/JamfPro-TwoPhase.md)
+- [configuration profile](Examples/sample-jamfschool.mobileconfig) for Jamf School
 
 
 ## Top-level keys
@@ -12,11 +12,11 @@ The project some sample files to get you started:
 
 (Boolean, default: `false`)
 
-When this is set to `true` any steps that actually change software on the disk will not be performed. This will also allow you to launch Setup Manager by double-clicking as the user. This can be useful to test a profile, or to take screen shots for documentation.
+When this is set to `true` any steps that actually change software on the disk will not be performed. This will also allow you to launch Setup Manager by double-clicking as the user. This can be useful to test a profile, or to take screenshots for documentation.
 
 These behaviors change in debug mode: 
 - checks for the existence of the Jamf binary and keychain are skipped
-- Jamf Setup manager will accept enrollmentActions from a non-managed preference file
+- Jamf Setup Manager will accept enrollmentActions from a non-managed preference file
 - `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
 
@@ -37,13 +37,13 @@ Example:
 
 #### `icon`
 
-(String, default: `name:AppIcon`, localized)
+(String, default: `name:AppIcon`, localized, dark mode)
 
-The icon shown at the top center of the window. There are many options to define icons, described in the [Icon Sources](#icon-sources) section later.
+The icon shown at the top center of the window. There are many options to define icons, described in the [Icon Sources](#icon-sources) section later. Images will be scaled to fit a size of 700x128 pixels (or 1400x256 @2x).
 
 #### `message`
 
-(String, default: `Setup Manager is configuring your Mac…`, localized, substitutions)
+(String, default: `Setup Manager is configuring your Mac…`, localized, substitutions, markdown)
 
 The message shown below the title.
 
@@ -54,7 +54,7 @@ Example:
 <string>Please wait a few moments while we install essential software…</string>
 ```
 
-The message can use [substitutions](#substitution):
+The message can use [substitutions](#substitution).
 
 Example:
 
@@ -63,9 +63,20 @@ Example:
 <string>Preparing your new %model%. Please be patient.</string>
 ```
 
+Markdown formatting options in the message field will be translated into rich text:
+
+Example:
+
+```xml
+<key>message</key>
+<string>Preparing your new %model%. **Please be patient.**</string>
+```
+
+`Please be patient.` will be bold. More detail on [Markdown here](#markdown).
+
 #### `background`
 
-(String, optional, localized)
+(String, optional, localized, dark mode)
 
 When this key is set, Setup Manager treats it as an image/[icon source](#icon-sources) and displays the image in a screen covering background.
 
@@ -73,11 +84,11 @@ When this key is set, Setup Manager treats it as an image/[icon source](#icon-so
 
 (String, optional, default: `enrollment`)
 
-**Beta:** We believe the run at login window feature may require more testing, especially in some edge cases. When, after thorough testing, you believe this works in your workflow, feel free to deploy it, and please let us know about success or any issues you might encounter.
+**Beta:** We believe the run at login window feature may require more testing, especially in some edge cases. When, after thorough testing, you believe this works in your workflow, feel free to deploy it, and please let us know about your success or any issues you might encounter.
 
-This value determines when Setup Manager should launch. There are two values: `enrollment` (default) and `loginwindow`. When set to `enrollment` Setup Manager will launch immediately when the pkg is installed. This is the setting to use for automated device enrollment (without AutoAdvance) and user-initiated enrollment.
+This value determines when Setup Manager should launch. There are two values: `enrollment` (default) and `loginwindow`. When set to `enrollment` Setup Manager will launch immediately when the pkg is installed. This is the setting to use for automated device enrollment (without Auto Advance) and user-initiated enrollment.
 
-When the `runAt` value is set to `loginwindow` Setup Manager will launch only when the login window is shown. This is useful for fully automated enrollments using AutoAdvance.
+When the `runAt` value is set to `loginwindow` Setup Manager will launch only when the login window is shown. This is useful for fully automated enrollments using Auto Advance.
 
 A setting of `loginwindow` will only work with enrollment setups that eventually end on the login window (i.e. a user has to be created automatically, the device is bound to a directory, etc).
 
@@ -108,7 +119,7 @@ When this key exists, Setup Manager will show a "Help" button (a circled questio
 
 #### `accentColor`
 
-(String, optional, default: system blue)
+(String or Dict, optional, default: system blue, dark mode)
 
 Sets the accent color for buttons, progress bar, SF Symbol icons, and other UI elements. You can use this to match branding. Color is encoded as a six digit hex code, e.g. `#FF0088`.
 
@@ -116,7 +127,21 @@ Example:
 
 ```xml
 <key>accentColor</key>
-<string>#FF0088</string>
+<string>#FF00AA</string>
+```
+
+If you want different accent colors depending on whether the system is in light or dark mode, provide a `dict` with two keys, for `light` and `dark` mode:
+
+Example:
+
+```xml
+<key>accentColor</key>
+<dict>
+  <key>dark</key>
+  <string>#FF00AA</string>
+  <key>light</key>
+  <string>#AA0055</string>
+</dict>
 ```
 
 #### `finalCountdown`
@@ -125,14 +150,14 @@ Example:
 
 This key changes the duration (in seconds) of the "final countdown" before the app automatically performs the `finalAction` (continue or shut down). Set to `-1` (or any negative number) to disable automated execution.
 
-Examples:
+Example:
 
 ```xml
 <key>finalCountdown</key>
 <integer>30</integer>
 ```
 
-Disable the 
+Disable the countdown: 
 
 ```xml
 <key>finalCountdown</key>
@@ -143,9 +168,18 @@ Disable the
 
 (String, optional, default: `continue`)
 
-This key sets the action and label for the button shown when Setup Manger has completed. When this key is set to `shutdown` (no space!) it will shut down the computer, other wise it will just quit Setup Manager ("continue"). This is also the action that is performed when the `finalCountdown` timer runs out.
+This key sets the action and label for the button shown when Setup Manger has completed. 
 
-When the `DEBUG` preference is set, shutdown will merely quit/continue.
+There are three options:
+- `continue`: (default) merely quits Setup Manager and allows the user to continue (probably Setup Assistant or login window)
+- `restart`: restarts the Mac
+- `shut down`: (no space!) shuts down the Mac
+
+**Warning:** `restart` and `shutdown` options will force their action immediately. If a user is logged in (after user-initiated enrollment), they may lose data from open, unsaved documents.
+
+This is also the action that is performed when the `finalCountdown` timer runs out.
+
+When the `DEBUG` preference is set, `shutdown` or `restart` will merely quit/continue.
 
 Example:
 
@@ -154,21 +188,6 @@ Example:
 <string>shutdown</string>
 ```
 
-#### `showBothButtons`
-
-(Bool, optional default: `false`)
-
-This key determines whether both the 'Shutdown' and 'Continue' are shown or just the button set in the `finalAction` key.
-
-**Warning:** this key is deprecated and will be removed in a future version of Setup Manager
-
-Example:
-
-```xml
-<key>showBothButtons</key>
-<true/>
-```
-
 #### `totalDownloadBytes`
 
 (Integer, opitonal, default: 1000000000 or 1GB, v0.8)
@@ -186,7 +205,7 @@ Example:
 
 (String, Jamf Pro only)
 
-Set this to `$JSSID` in the configuration profile and Setup Manager will be aware of its computer's id in Jamf Pro. It will be displayed in the 'About this Mac…' popup.
+Set this to `$JSSID` in the configuration profile and Setup Manager will be aware of its computer's id in Jamf Pro. It will be displayed in the 'About this Mac…' popup, when clicked with the option key.
 
 Example:
 
@@ -229,7 +248,7 @@ This will set the computer name to `Mac-DEF456` where `DEF456` are the center si
 
 (String, optional)
 
-When set, the "About this Mac" info window will show this value instead of the real serial number. This is useful when making screen shots or recordings for documentation or presentations where you do not want to expose real serial numbers.
+When set, the "About this Mac" info window will show this value instead of the real serial number. This is useful when making screenshots or recordings for documentation or presentations where you do not want to expose real serial numbers.
 
 Note: This is for display only. [Substitutions](#substitution) will still use the real serial number.
 
@@ -284,9 +303,9 @@ The label is used as the name of the action in display.
 
 #### `icon`
 
-(String, optional, localized)
+(String, optional, localized, dark mode)
 
-The icon source string used for the display of the label. Different types of actions will have different default icons, which is used when no `icon` key is present.
+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).
 
 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.
 
@@ -308,7 +327,7 @@ When the command given in `shell` requires arguments they are listed here, one i
 
 (Bool, default: `false`, optional)
 
-When this key is set to `true` Setup Manager will only run this when itself is running as root. Otherwise it will fail the action. When `DEBUG` is enabled, it will replace the action with a delay instead.
+When this key is set to `true`, Setup Manager will only run this when itself is running as root. Otherwise, it will fail the action. When `DEBUG` is enabled, it will replace the action with a delay instead.
 
 Example:
 
@@ -336,7 +355,13 @@ Example:
 
 (String, Jamf Pro only)
 
-This will run the jamf policy or polices with the given trigger name. This is the equivalent of running `jamf policy -event <triggername>`
+This will run the Jamf Pro policy or polices with the given trigger name. This is the equivalent of running 
+
+```
+jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction
+```
+
+Note: Jamf Pro policies can do a lot of different things and fail in many different ways. Setup Manager does _not_ check for all possible failure modes. It only checks for failed installer pkgs and policy scripts that return non-zero exit codes, which should cover most uses of policies for initial deployment.
 
 Example:
 
@@ -386,7 +411,7 @@ Example:
 </dict>
 ```
 
-Note: This is intended to check if app are installed from the Mac App Store or Jamf App Installers. In my experience, these installation methods are quite unreliable, hence the timeout. Since you cannot anticipate the order in which these apps may be installed, it is best to put the `watchPath` actions at the end. For large installations (Xcode) you want to set a large timeout.
+Note: This is intended to check if an app is installed from the Mac App Store or by Jamf App Installers. In my experience, these installation methods are quite unreliable during enrollment, hence the timeout. Since you cannot anticipate the order in which these apps may be installed, it is best to put the `watchPath` actions at the end. For large installations, such as Xcode, or Adobe apps, you want to set a large timeout.
 
 ### Wait
 
@@ -415,7 +440,7 @@ Example:
 
 If Setup Manager reaches this action before the user entry has been completed, it will wait until the user entry is completed and the user has clicked 'Save.'
 
-When the user entry is saved and this action is reached, it will set the computer name, according to the `computerNameTemplate` or what was entered by the user and run a recon/Update Inventory which submits the user data. It will also save the data from the user entry to the [user data file](Docs/Extras.md#user-data-file)
+When the user entry is saved and this action is reached, it will set the computer name, according to the `computerNameTemplate` or what was entered by the user and run a recon/Update Inventory which submits the user data. It will also save the data from the user entry to the [user data file](Docs/Extras.md#user-data-file).
 
 This action allows for "two phase" installation workflows where the policies in the second phase are scoped to data from the user entry. After this action, smart groups in Jamf Pro should reflect the data entered and you can use scoping in subsequent policies to choose which policies should or should not run on this device.
 
@@ -438,7 +463,7 @@ Regardless of whether there is a `waitForUserEntry` action or not, Setup Manager
 
 This will run a Jamf Inventory update.
 
-You should usually not need to add a recon step. By default Setup Manager will automatically run an inventory update before and after running the enrollment actions.
+This action exists mainly for troubleshooting. You should generally not need to add a recon step. By default, Setup Manager will automatically run an inventory update before and after running the enrollment actions. If you have a `waitForUserEntry` action configured, this will also run a recon/inventory update.
 
 Example:
 
@@ -527,7 +552,7 @@ When the icon source starts with `name:`, Setup Manager will get the icon with t
 
 ### SF Symbols:
 
-When the icon source starts with `symbol:`, Setup Manager will create the icon using that symbols name. You can look up symbol names using the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
+When the icon source starts with `symbol:`, Setup Manager will create the icon using that symbol's name. You can look up symbol names using the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
 
 Note that the availability and appearance of SF Symbols may vary with the OS version and language/region.
 
@@ -536,11 +561,37 @@ Note that the availability and appearance of SF Symbols may vary with the OS ver
 <string>symbol:clock</string>
 ```
 
+### Dark Mode
+
+Note: after enrollment, over Setup Assistant, the system is always in light mode. This is only relevant when you use Setup Manager after user-initiated enrollment 
+
+To provide alternative images for dark or light mode, change the `string` defining the image to a dictionary with a `dark` and a `light` key. This works with the `background`, `icon`, and each action's `icon`. This also works with the `accentColor` key.
+
+Note that Setup Manager does _not_ monitor the appearance mode, so if it changes _while_ Setup Manager is running, things will not update consistently.
+
+Example: 
+
+```xml
+<key>icon</key>
+<dict>
+  <key>dark</key>
+  <string>name:Jamf_white</string>
+  <key>light</key>
+  <string>name:Jamf_blue</string>
+</dict>
+```
+
+
 ## User Entry
 
 You can enable user entry for the following keys:
 
 - `userID`
+- `email`
+- `endUsername` (shown as 'Account Name')
+- `realname` (shown as 'Full Name')
+- `position`
+- `phone`
 - `department`
 - `building`
 - `room`
@@ -549,6 +600,9 @@ 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.
 
+`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.
+
+
 ### User Data file
 
 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)
@@ -557,7 +611,7 @@ Data from user entry is written, together with some other data to a file when Se
 
 (String, localized)
 
-Provide a default value in two ways:
+Provide a default value in one of two ways:
 
 Example:
 
@@ -675,11 +729,37 @@ The default validation message will show the regular expression the value is not
 </dict>
 ```
 
+#### `label`
+
+(String, localized, optional)
+
+Many Jamf Pro admins use the standard fields in ways that don't match their built-in label. For this purpose you can override the default label shown for a field in the user entry.
+
+Note that the text label in the [User Data file](Docs/Extras.md#user-data-file) will _not_ be changed.
+
+Example:
+
+```xml
+<key>room</key>
+<dict>
+  <key>label</key>
+  <string>Site</string>
+  <key>options</key>
+  <array>
+    <string>London</string>
+    <string>Paris</string>
+    <string>Amsterdam</string>
+  </array>
+</dict>
+```
+
+In this example, the 'Room' field will be shown in Setup Manager with the label 'Site.' The choice will be submitted  to the 'room' field in Jamf Pro inventory and written with the 'room' label to the [User data file](Docs/Extras.md#user-data-file). You can then pick up the data in policy scripts after Setup Manager is finished or the `waitForUserEntry` action and process it accordingly.
+
 ### Conditionally show the user entry for certain users
 
-You can configure Setup Manager to only show the user entry section when specified users have authentication in enrollment customization. This enables workflows, where certain users (techs and admins) gets the option to re-assign the device to another user, but other users don't see the option.
+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 `userID` to receive the `$EMAIL` variable. This will communicate the user who logged in with customized enrollment back into  Setup Manager. Then you add key `showForUserIDs` with an array of user emails to the `userEntry` dict. When both `userID` 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 `userID` 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 `userID` and `userEntry.showForUserIDs` are set, the user entry UI will only show for the listed users.
 
 #### `showForUserIDs`
 
@@ -718,7 +798,7 @@ When you provide a top-level `help` key with a dictionary a help button (with a
 
 #### `message`
 
-(String, optional, localized)
+(String, optional, localized, markdown)
 
 #### `url`: 
 
@@ -740,9 +820,13 @@ Example:
 </dict>
 ```
 
+## Webhooks
+
+Setup Manager can send web hooks to servers and services to trigger workflows there. You can read [details on how to configure and use WebHooks here](Docs/Webhooks.md).
+
 ## Localization
 
-The app will pick up the user choice of the UI language for the interface elements. (Table of currently available languages below) The app will fall back to English for other language choices.
+The app will pick up the user choice of the UI language for the interface elements. (Table of currently available languages below.) The app will fall back to English for other language choices.
 
 You can provide localizations for the custom texts given in the configuration profile. 
 
@@ -794,6 +878,7 @@ The following keys can be localized:
 - `default`
 - `placeholder`
 - `validationMessage`
+- `label`
 
 ### Help
 
@@ -848,3 +933,21 @@ These keys can use substitutions:
 - `message`
 - `computerNameTemplate`
 - actions: `label`
+
+## Markdown
+
+In some fields, markdown formatting can be used to generate rich, formatted text. For example:
+
+```xml
+<key>message</key>
+<string>Preparing your new Mac. **Please be patient.**</string>
+```
+
+The `Please be patient.` text will be shown bolded. You can find details on markdown formatting in the [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/).
+
+Note that while you _can_ embed links to websites in the markdown using the `[…](…)` syntax they will not work while running over Setup Assistant or Login Window.
+
+These keys can use markdown:
+
+- `message`
+- Help: `message`

Docs/Extras.md

@@ -19,7 +19,7 @@ Note that the custom schema can become confused when you switch between enrollme
 
 ## Quit
 
-The command-Q keyboard short cut to quit the app is disabled. Use `shift-control-command-E` instead. This should only be used when debugging and trouble-shooting, as it will leave the client in an undetermined state when installations are aborted.
+The command-Q keyboard shortcut to quit the app is disabled. Use `shift-control-command-E` instead. This should only be used when debugging and troubleshooting, as it will leave the client in an undetermined state when installations are aborted.
 
 ## Logging
 
@@ -73,7 +73,6 @@ computerName: MacBook-M7WGMK
 submit: 2024-08-14T13:54:37Z
 duration: 101
 ```
-
 Start time (`start`) and finish/submission time (`submit`) are given in ISO8601 format, universal time (UTC). Duration is given in seconds.
 
 Fields that were not set in user entry will not be shown at all. You can use this file in scripts or extension attributes. One possible way is to parse it with `awk`, e.g.
@@ -82,10 +81,27 @@ Fields that were not set in user entry will not be shown at all. You can use thi
 duration=$(awk -F ': ' '/duration: / {print $2}' /private/var/db/SetupManagerUserData.txt)
 ```
 
+Starting with Setup Manager 1.2, the User Data file contains a list of actions with their status:
+
+```
+enrollmentActions:
+ -action 0: finished - Microsoft 365
+ -action 1: finished - Google Chrome
+ -action 2: finished - Jamf Connect
+```
+
+The status can be `finished` or `failed`.
+
 ## "About This Mac…" window
 
 When you hold the option key when clicking on "About This Mac…" you will see more information.
 
+## Scannable Serial Number Barcode
+
+Hitting the space bar while Setup Manager is the Active window will open a window with a scannable barcode of the serial number. Hitting the space bar again will dismiss the window.
+
+Note that Setup Manager does not automatically get Key Window when it launches, while running over Setup Assistant, so you may have to click in the Setup Manager window, before hitting the space bar.
+
 ## Uninstall Setup Manager
 
 Setup Manager will unload and remove its LaunchAgent and LauchDaemon files upon successful completion. That together with the [flag file](#flag-file) should prevent Setup Manager from launching on future reboots.

Docs/FAQ.md

@@ -1,6 +1,6 @@
 #  Frequently Asked Questions
 
-## Is there are custom JSON Schema for Jamf Pro?
+## Is there a custom JSON Schema for Jamf Pro?
 
 [Yes.](Extras.md#custom-json-schema-for-jamf-pro)
 
@@ -14,29 +14,29 @@ There can be many causes for this. A few common causes are:
  
 - Jamf Pro: check that Setup Manager is added to your prestage and the package does not have the label "Availability pending" in Settings> Packages
 - Jamf Pro: do not install JamfConnect.pkg in prestage when you want to use Setup Manager. Install JamfConnect with Setup Manager instead
-- you need at least one of the 'Setup Assistant Options' in the prestage to be set to _not_ skip. Location Services or 'Choose your Look' are common choices, that you generally want to leave up the user anyway. Otherwise Setup Assistant may quit before Setup Manager can launch and do its actions.
+- you need at least one of the 'Setup Assistant Options' in the prestage to be set to _not_ skip. Location Services or 'Choose your Look' are common choices 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
 
 No.
 
-Setup Manager will run fine without Jamf Connect. You can even build 'single-touch' style workflows with Setup Manager without Jamf Connect. Some features, such as pre-assigning a device to a specific user require Jamf Connect, though.
+Setup Manager will run fine without Jamf Connect. You can even build 'single-touch' style workflows with Setup Manager without Jamf Connect. Some workflows, such as pre-assigning a device to a specific user require Jamf Connect, though.
 
 ## How can I use the icon for an app before the app is installed?
 
 - preinstall icon files with a custom package installer in prestage. Set the priority of the media/branding package lower than that for Setup Manager, or give the branding/media package a name that is alphabetically earlier than Setup Manager, so it installs before Setup Manager
 - use http(s) urls to the image files
     - you can host them on a web server/service that you have control over
-    - you can add the icon as an icon for a self service policy in Jamf and then copy the url to the icon once uploaded
+    - you can add the icon as an icon for a Self Service policy in Jamf and then copy the url to the icon once uploaded
 
 
 ## What is happening during "Getting Ready" and "Finishing"?
 
 During the "Getting Ready" phase, Setup Manager is waiting for the enrollment configuration to be complete. The steps taken during these phases depend on the version of Setup Manager and the management system.
 
-When enrolled into Jamf Pro, Setup Manager runs (among other things) a recon/Update Inventory during "Getting Ready" and "Finshing." This will make up most of the time in these phases.
+When enrolled into Jamf Pro, Setup Manager runs (among other things) a recon/Update Inventory during "Getting Ready" and "Finishing." This will make up most of the time in these phases.
 
-You can open the log window (command-L) or review the [log file](Extras.md#logging) for detail for each step. Should Setup Manager stall during one of these steps, you can [quit](#quit) out of Setup Manager and review the [log file](Extras.md#logging) after completing the setup.
+You can open the log window (command-L) or review the [log file](Extras.md#logging) for detail for each step. Should Setup Manager stall during one of these steps, you can [quit](Extras.md#quit) out of Setup Manager and review the [log file](Extras.md#logging) after completing the setup.
 
 ## Can I set the wallpaper/desktop picture or dock with Setup Manager?
 
@@ -52,3 +52,6 @@ With Jamf Pro, you can set the Setup Manager pkg to install at the `login` trigg
 
 This is not, however, the primary workflow for Setup Manager and not something that we will test or verify. We believe running right after enrollment over Setup Assistant is the preferable deployment.
 
+## Installer or Policy Script is failing with access errors
+
+For some policy scripts or installers it may be necessary to give the Setup Manager app Full Disk Access or some other exemptions with a PPPC Profile. 

Docs/JamfProConnect-SingleTouch.md

@@ -16,7 +16,9 @@ You can use a combination of Jamf Pro, Setup Manager and Jamf Connector, to get
 
 Customized Enrollment with SSO is not _required_ for this workflow. The assignment to the final user is set from the email entered in Setup Manager. Nevertheless, customized enrollment with SSO is useful in this context since restricts Mac enrollment to a group of authorized accounts.
 
-You should have Jamf Pro and Jamf Connect configured with the required SSO integrations and thoroughly tested before configuring this workflow.
+You should have Jamf Pro and Jamf Connect configured with the required SSO integrations and thoroughly tested before configuring this workflow. 
+
+Verify that "Collect User and Location information from Directory Service" is **enabled** in Settings > Computer management > Inventory collection.
 
 ## Configure Setup Manager
 
@@ -86,6 +88,8 @@ Then create a Smart Group named "Setup Manager Done" with the criteria `"Setup M
 
 ## Pre-set user for Jamf Connect
 
+Note: this step only works with Entra ID as the Identity Provider.
+
 Jamf Connect Login allows pre-configuring the user. Create a configuration profile named "Jamf Connect Enrollment User" to the preference domain `com.jamf.connect.login` with the following property list:
 
 ```xml

Docs/Webhooks.md

@@ -0,0 +1,115 @@
+# Webhooks
+
+#### `webhooks`
+
+(Dict, optional)
+
+Setup Manager can send webhooks to inform other services of its status. The configuration for the webhooks in all stored under the top-level `webhooks` key.
+
+The webhooks dict can contain two keys, both of which are again dicts. `started` defines the webhook or webhooks that are called when Setup Manager starts its workflow, and the other `finished` defines the webhook or webhooks when it finishes the workflow.
+
+When the either the `started` or `finished` key is missing, no webhook will be sent for that event.
+
+Example:
+
+```xml
+<key>webhooks</key>
+<dict>
+  <key>finished</key>
+  <string>https://example.com/webhook-finish</string>
+  <key>started</key>
+  <string>https://example.com/webhook-start</string>
+</dict>
+```
+
+### Multiple webhooks
+
+You can send multiple services per event:
+
+```xml
+<key>webhooks</key>
+<dict>
+  <key>finished</key>
+  <array>
+    <string>https://example.com/webhook-finish</string>
+    <string>https://otherservice.com/abc123456</string>
+  </array>
+  <key>started</key>
+  <array>
+    <string>https://example.com/webhook-start</string>
+    <string>https://otherservice.com/abc123456</string>
+  </array>
+</dict>
+```
+
+### WebHook Data
+
+For the `started` webhook, Setup Manager attaches this data:
+
+```json
+{
+  "name": "Started",                       // string
+  "event": "com.jamf.setupmanager.started" // string
+  "timestamp": "2025-01-14T15:11:28Z",     // time setup manager started, date as string, iso8601
+  "started": "2025-01-14T15:11:27Z",       // time webhook was sent, date as string, iso8601 
+  "modelName": "MacBook Air",              // string
+  "modelIdentifier": "Mac14,2",            // string
+  "macOSBuild": "24C101",                  // string
+  "macOSVersion": "15.2.0",                // string
+  "serialNumber": "ABCD1234DE",            // string
+  "setupManagerVersion": "1.2"             // string
+  "jamfProVersion": "11.13.0"              // optional, only for Jamf Pro, string
+  "jssID": 1234                            // optional, only when `jssID` is set in profile, string
+}
+```
+
+The data for the `finished` webhook includes the same as above, with some additional fields:
+
+```json
+{
+  "name": "Finished",                       // string
+  "event": "com.jamf.setupmanager.finished" // string
+  "duration": 53,                           // integer
+  "finished": "2025-01-14T15:12:20Z",       // time Setup Manager finished, date as string, iso8601
+  "computerName": "Mac-123456"              // computer name, only when set through Setup Manager
+  "userEntry": {                            // data entered by the user
+    "department": "IT",
+    "computerName": "IT-ABC123",
+    "userID": "a.b@example.,com",
+    "assetTag": "abc54321"
+  },
+  "enrollmentActions": [                    // array of enrollmentActions with status
+    {
+      "label": "Microsoft 365",
+      "status": "finished"                  // status: "finished" or "failed"
+    },
+    {
+      "label": "Google Chrome",
+      "status": "finished"
+    },
+    {
+      "label": "Jamf Connect",
+      "status": "finished"
+    },
+  ],
+}
+```
+
+### Microsoft Teams
+
+When you set up [an incoming webhook workflow with Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498) the json payload is expected in a certain format. 
+
+**Important Note:** _The Teams Workflow Webhook URL will contain ampersands `&`. Since configuration profiles are XML files, you need to escape/replace all ampersands in the URL with the XML escape sequence `&amp;`._
+
+Use this webhook format in the Setup Manager profile:
+
+```xml
+<dict>
+  <key>kind</key>
+  <string>teams</string>
+  <key>url</key>
+  <string>--insert url from Teams Workflows here--</string>
+</dict>
+```
+
+This `dict` replaces the simple `string` syntax.

LICENSE.md

@@ -1,2 +1 @@
-Offered under the terms of the [Jamf Concepts Use Agreement](https://resources.jamf.com/documents/jamf-concept-projects-use-agreement.pdf).
-
+Offered under the terms of the [Jamf Software License and Service Agreement](https://resources.jamf.com/documents/jamf-SLASA.pdf).

README.md

@@ -20,7 +20,7 @@ There is also a [`#jamf-setup-manager`](https://macadmins.slack.com/archives/C07
 
 There are many enrollment progress tools available for Mac admins, each with their own strengths. Jamf Setup Manager approaches the problem from the perspective of an IT service provider.
 
-Setup Manager offers many of the same features of these utilities but is especially useful for the case where an IT department or provisioning depot wants to ensure that a new Mac is properly configured and assigned before sending the device to its new user. It runs over Setup Assistant before a user is created so it won't interfere with MDM-capable user or the secure token flow for FileVault. You can control which policies and installations Setup Manager runs with a configuration profile.
+Setup Manager offers many of the same features of these utilities but is especially useful for the case where an IT department or provisioning depot wants to ensure that a new Mac is properly configured and assigned before sending the device to its new user. It runs over Setup Assistant before a user is created, so it won't interfere with MDM-capable user or the secure token flow for FileVault. You can control which policies and installations Setup Manager runs with a configuration profile.
 
 Setup Manager provides:
 
@@ -30,10 +30,10 @@ Setup Manager provides:
   - zero-touch (user-driven)
   - single-touch (tech-driven)
   - user initiated enrollment
-  - handsfree deployment with auto advance (beta)
+  - handsfree deployment with AutoAdvance (beta)
 - customized branding
-- localized interface and custom text
-- support for Jamf Pro and Jamf School
+- localized interface and localizable custom text
+- works with Jamf Pro and Jamf School
 
 ## Installation and Configuration
 
@@ -42,16 +42,17 @@ 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 auto advance and Setup Manager at login window (beta)](Docs/JamfPro-LoginWindow.md)
+  - [handsfree deployment with AutoAdvance and Setup Manager at login window (beta)](Docs/JamfPro-LoginWindow.md)
 - [Jamf School](Docs/JamfSchool-Setup.md)
 - [Extras and Notes](Docs/Extras.md)
 - [Frequently Asked Questions](Docs/FAQ.md)
+- [Webhooks](Docs/Webhooks.md)
 
 ## Configuration Profile
 
 The structure of the configuration profile [is documented here](ConfigurationProfile.md).
 
-There is also a [custom schema for Jamf Pro](Docs/Extras#custom-json-schema-for-jamf-pro).
+There is also a [custom schema for Jamf Pro](Docs/Extras.md#custom-json-schema-for-jamf-pro).
 
 ## Requirements
 
@@ -61,10 +62,7 @@ Setup Manager requires macOS 12.0.0 or higher. It will work only with Jamf Pro o
 
 - Setup Manager will **_not_** launch at enrollment with Auto-Advance enabled, use the option to run at login window
 - Setup Manager may **_not_** launch or launch and quit quickly when you disable _all_ Setup Assistant screens, leave at least one Setup Assistant option enabled, or use the option to run at login window
-- When you install **_Jamf Connect_** during the Prestage together with Setup Manager, you may see Setup Assistant for some time before Setup Manager launches or Setup Manager may not launch at all. Remove Jamf Connect from the Prestage and install it with Setup Manager policy or installomator action.
-- Policies that are triggered by `enrollmentComplete` may disrupt Setup Manager running from Prestage/Automated Device Enrollment. Disable or unscope policies triggered by `enrollmentComplete` on devices using Setup Manager.
-- In some deployments, Setup Manager attempts to start while Jamf Pro is still installing. Try adding a 30-60 second `wait` action as the first action.
-- With Jamf School, there will a few seconds after the remote management dialog where Setup Assistant shows before Setup Manager launches. With the Jamf School enrollment architecture, this is unavoidable.
+- Policies that are triggered by `enrollmentComplete` may delay or even disrupt Setup Manager running from Prestage/Automated Device Enrollment. Disable or unscope policies triggered by `enrollmentComplete` on devices using Setup Manager.
 
 ---