minor fixes for 1.3beta

ChangeLog.md

@@ -1,5 +1,97 @@
 #  Setup Manager - Change Log
 
+## v1.3beta
+(2025-05-27)
+
+### New Features
+- Logging
+    - log output format has been cleaned up
+    - Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78)
+    - now also logs to macOS unified logging
+    - new top-level default key to control action output logging
+- Network Monitoring
+    - changes to network interfaces are now logged, see the Notes section for details (#15)
+    - network status can be shown in the top-right corner of the Setup Manager window
+- new flag file `/private/var/db/.JamfSetupStarted`, which is created when Setup Manager starts
+- added [a specific webhook to send a message to Slack](Docs/WebHooks.md#Slack) (#104)
+- two new defaults keys `finishedScript` and `finishedTrigger` allow to run custom behavior when Setup Manager has finished
+- new option `none` for `finalAction` (#115)
+
+### Fixes and Improvements
+- Jamf Pro: improved monitoring for Jamf Pro to complete its setup after enrollment
+- webhook log entries correctly show status
+- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions
+- Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
+
+### Deprecations and Removals
+- (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
+- 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
+
+#### Logging
+
+The format of the Setup Manager log file (in `/Library/Logs/Setup Manager.log`) has changed. The new format should be easier to parse with other tools. There are four columns:
+
+- timestamp (in ISO8601)
+- log level (default, error or fault)
+- category (general, install, network, jamfpro)
+- message
+
+Setup Manager 1.3 also logs to the macOS unified system log. The subsystem is `com.jamf.setupmanager`. You can use the `log` command line tool to read the log.
+
+For example:
+
+```
+sudo log show --last 30m --predicate 'subsystem="com.jamf.setupmanager"'
+```
+
+To clean up the log a little, Setup Manager 1.3 will only write the output of actions to the Setup Manager log file when an error occurred. You can control this behavior with a new top-level preference key `actionOutputLogging`.
+
+
+#### Network change logging
+
+Setup Manager 1.3 adds logging for changes to network interfaces. it is possible that there will multiple entries in the log with regards to the same network change. Most changes logged will be neutral and should not affect your deployment negatively.
+
+However, it is possible that changes to the network configuration of a device can influence the deployment workflow. For example, when a configuration profile with the access information for a secure corporate Wifi is installed on the device, then the download access to  required resources might change. Another example are security that might lead to restricted access for downloads (Installomator uses `curl` to download data, which might trigger security tools.) 
+
+Knowing that network changes or outages occurred during enrollment can be useful for troubleshooting.
+
+#### Network Status icon/menu
+
+Network status is also shown with a new icon in the top-right corner of the Setup Manager window.  
+ 
+Note that Network Relay will only protect traffic to certain configured servers and services, not all traffic.
+
+By default, the network icon will _not_ be shown. You can activate it manually with the command-N keystroke.
+
+When you click on the Network status icon, a popup will show:
+ - the current active network interface
+ - IPv4 and IPv6 addresses
+ - download and upload bandwidth (will take a while to appear)
+ - Network Relay hosts (when network relay profile is present)
+ - list of additional custom hosts, configured in the profile
+
+Note that the connectivity is very basic and might not catch all functionality that is required for a service to work. It should provide an indication whether a service is available, but deeper trouble-shooting and monitoring might be required for reliable diagnostics.
+
+## v1.2.2
+(2025-04-17)
+- signed a helper script that could lead to unexpected background item prompts
+- disabled command-W keystroke
+- fixed a stall in `waitForUserEntry` with Jamf School
+- fixed link to computer record in Teams message (#110)
+- minor documentation fixes
+
+## v1.2.1
+(2025-04-02)
+
+- updated included Installomator script to [v10.8](https://github.com/Installomator/Installomator/releases/tag/v10.8)
+- now tries for 15 seconds to reload local `background` image file (#105), this should help in situations where the image file is installed after Setup Manager
+- improved monitoring of Jamf Pro enrollment process and completion during the "Getting Ready" phase
+- minor documentation fixes (#106)
+
+
 v1.2
 (2025-03-17)
 

ConfigurationProfile.md

@@ -5,6 +5,7 @@ The project some sample files to get you started:
 - [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
 
+**Important:** all keys and values are **case-senstive**.
 
 ## Top-level keys
 
@@ -84,11 +85,9 @@ 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 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 its installation package is installed. This is the setting to use for automated device enrollment (without Auto Advance) 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 Auto Advance.
+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 and some workflows involving Jamf Connect or similar tools.
 
 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).
 
@@ -115,7 +114,7 @@ When this key exists, Setup Manager will prompt for user data while the enrollme
 
 (Dict of Strings, optional)
 
-When this key exists, Setup Manager will show a "Help" button (a circled question mark) in the lower right corner while it is running. You can add sub-keys with content for the help, which are described in [Help](#help). When Setup Manager has completed, the "Help" button will be replaced with the "Continue" and/or "Shutdown" button.
+When this key exists, Setup Manager will show a "Help" button (a circled question mark) in the lower right corner while it is running. You can add sub-keys with content for the help, which are described in [Help](#help-1). When Setup Manager has completed, the "Help" button will be replaced with the "Continue" and/or "Shutdown" button.
 
 #### `accentColor`
 
@@ -148,7 +147,7 @@ Example:
 
 (Number/integer, optional, default: `60`)
 
-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.
+This key changes the duration (in seconds) of the "final countdown" before the app automatically performs the `finalAction`. Set to `-1` to disable automated execution.
 
 Example:
 
@@ -170,13 +169,16 @@ Disable the countdown:
 
 This key sets the action and label for the button shown when Setup Manger has completed. 
 
-There are three options:
+There are four 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
+- `shutdown`: (no space!) shuts down the Mac
+- `none`: no button shown. (see note below)
 
 **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.
 
+**Note on `none`:** the `none` option exists for workflows where the restart or continue is controlled by a process other than Setup Manager. For example, when installing additional software with a `finishedScript` or `finishedTrigger` which forces a restart. Having a `continue` or `restart` button would be confusing and might interrupt the installation in the finished process. However, having no button to end Setup Manager at all, might leave the user 'stuck' there, so be sure to always restart or kill Setup Manager. You can always use the keyboard shortcut `shift-control-command-E` to quit Setup Manager.
+
 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.
@@ -188,6 +190,25 @@ Example:
 <string>shutdown</string>
 ```
 
+#### `finishedScript`
+
+(String, optional)
+
+A full path to a script file which will be executed _after_ Setup Manager has finished its workflow. This process runs independently of Setup Manager, so it can run installers or scripts that affect Setup Manager.
+
+The script has to fulfill these criteria to be executed:
+
+- owner: `root`, group: `wheel`
+- executable bit set
+- not writable for group or other (file mode `755` or `555`)
+- no quarantine flag attached
+
+#### `finishedTrigger`
+
+(String, optional, Jamf Pro only)
+
+A custom policy trigger which will be executed _after_ Setup Manager has finished its workflow. This process runs independently of Setup Manager, so it can run installers or scripts that affect Setup Manager.
+
 #### `totalDownloadBytes`
 
 (Integer, opitonal, default: 1000000000 or 1GB, v0.8)
@@ -218,7 +239,7 @@ Example:
 
 (String, Jamf Pro only)
 
-Set this to `$EMAIL` in the configuration profile. This communicates the user who logged in to customized enrollment to Setup Manager. This can be used together with the `userEntry.showForUserIDs` key to control which users see the user entry UI.
+Set this to `$EMAIL` in the configuration profile. This communicates the user who logged in to customized enrollment to Setup Manager. This can be used together with the [`userEntry.showForUserIDs`](#conditionally-show-the-user-entry-for-certain-users) key to control which users see the user entry UI.
 
 Example:
 
@@ -291,6 +312,19 @@ Example:
 
 When debug mode is enabled, you can set the `simulateMDM` preference key to `Jamf Pro` or `Jamf School`. This allows you to do test runs on un-enrolled Macs.
 
+#### `actionOutputLogging`
+
+(string, optional, default: `error`)
+
+This key controls whether the output of actions is written to the Setup Manager log file.
+
+There are three options:
+- `always`: output and exit code are always written to the log file
+- `error`: (default) output and exit code are only written on errors
+- `never`: output and exit are never written to the log file
+
+Setup Manager's log window will always show the output, regardless of this setting.
+
 ## Actions
 
 All actions should have these keys:
@@ -358,7 +392,7 @@ Example:
 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
+jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction -skipAppUpdates
 ```
 
 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.
@@ -376,6 +410,20 @@ Example:
 </dict>
 ```
 
+Note: You can trigger policies attached to "Recurring Check-in" by leaving the string value empty:
+
+
+```xml
+<dict>
+  <key>icon</key>
+  <string>symbol:arrow.trianglehead.2.clockwise.rotate.90</string>
+  <key>label</key>
+  <string>Check-in</string>
+  <key>policy</key>
+  <string/>
+</dict>
+```
+
 ### Watch Path
 
 #### `watchPath`
@@ -478,7 +526,7 @@ Example:
 
 This will run [Installomator](https://github.com/Installomator/Installomator) to install a given label.
 
-Note: by default, Setup manager will add `NOTIFY=silent` to the arguments to suppress notfications. You can override this in the `arguments`.
+Note: by default, Setup manager will add `NOTIFY=silent` to the arguments to suppress notifications. You can override this in the `arguments`.
 
 #### `installomator`
 
@@ -824,6 +872,10 @@ Example:
 
 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).
 
+## Network Connectivity
+
+Setup Manager can check and display the network status and connectivity to a list of hosts.
+
 ## 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.

Docs/Extras.md

@@ -108,3 +108,42 @@ Setup Manager will unload and remove its LaunchAgent and LauchDaemon files upon
 
 If you still want to remove Setup Manager after successful enrollment, there is [a sample uninstaller script in the Examples folder](../Examples/uninstall.sh).
 
+## (Jamf Pro): Useful Smart Groups 
+
+You can create smart groups to coordinate installations of Configuration profiles. Some useful examples are:
+
+### Setup Manager Installed
+
+Criteria: 'Application Bundle ID' is `com.jamf.setupmanager`
+
+You can use this smart group to scope or limit configuration profiles, Mac App Store/VPP apps, and Jamf App Installer apps. This way their installation will not occur immediately after enrollment, potentially slowing down the installation of essential Jamf Pro components and extending the "Getting Ready" phase.
+
+### Setup Manager Done
+
+Create an Extension attribute named "Setup Manager Done" with the script code:
+
+```sh
+if [ -f "/private/var/db/.JamfSetupEnrollmentDone" ]; then
+  echo "<result>done</result>"
+else
+  echo "<result>incomplete</result>"
+fi
+```
+
+Then create a Smart Group named "Setup Manager Done" with the criteria `"Setup Manager Done" is "done"`.
+
+You can use this to scope configuration profiles and policies so that they are installed or run _after_ Setup Manager is complete.
+
+##  Running Scripts and Policies when Setup Manager finishes
+
+Generally, you want to coordinate tasks, configurations, and installations with Setup Manager actions. However, in some situations the installations might interfere with the Setup Manager workflow itself. This is most relevant with software that needs to reload the login window process, which will also kill Setup Manager.
+
+Setup Manager provides a LaunchDaemon which monitors the `.JamfEnrollmentSetupDone` flag file. It then launches a script or a custom Jamf Pro policy trigger. Since this LaunchDaemon runs independently from Setup Manager, so it can run installers or scripts that might quit login window or Setup Manager.
+
+However, if you have set Setup Manager to automatically shut down or restart at the end, this will interrupt the finished script or policy, unless the automated delay is long enough. Use the [`finalAction`](../ConfigurationProfile.md#finalAction) value of `none` to remove the button and countdown from the Setup Manager UI. However, now it the responsibility of the finishing process to restart the Mac or quit the Setup Manager process, otherwise Setup Manager will keep blocking the UI.
+
+The finished script or custom trigger are configured in the Setup Manager configuration profile, with the [`finishedScript`](../ConfigurationProfile.md#finishedScript) and [`finishedTrigger`](../ConfigurationProfile.md#finishedTrigger) keys.
+
+The SetupManagerFinished daemon logs its output (and the output of the policy and scripts to `/private/var/log/setupManagerFinished.log`.
+
+

Docs/FAQ.md

@@ -38,11 +38,23 @@ When enrolled into Jamf Pro, Setup Manager runs (among other things) a recon/Upd
 
 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.
 
+## (Jamf Pro) Getting Ready is taking very long (several minutes). What is happening and can I do something to make it faster?
+
+The "Getting Ready" phase prepares some steps and waits for all essential Jamf Pro components (the jamf binary, certificates, Jamf.app, etc.) to be installed and configured before starting with the actual enrollment workflow. Depending on the network connection this might take a while.
+
+Note that you can see the individual steps and the timing for each step in the [Setup Manager log file](Extras.md#logging)].
+
+Once Jamf Pro's enrollment workflow is complete, Setup Manager runs a full update inventory/recon. In general, if the recon takes a long time, you should review the inventory collection settings. Calculating home directory sizes and gathering fonts can take a lot of time and CPU power, and speed up things significantly when turned off, not just during enrollment with Setup Manager.  You should also review extension attributes, for whether they are used and how long each one runs.
+
+Mac App Store/VPP and Jamf App Installer apps that are scoped to the computer will also begin installing _immediately_ after enrollment. Since macOS will only perform one installation at a time, these might delay the installation of essential Jamf Pro components. You can create smart groups to defer these installations.
+
+
+
 ## Can I set the wallpaper/desktop picture or dock with Setup Manager?
 
 The settings for the dock and wallpaper/desktop picture are _user_ settings. Since the user account usually does not yet exist when Setup Manager runs, you cannot affect those settings.
 
-What you can do is run a script at login which sets the desktop (using [desktoppr](https://github.com/scriptingosx/desktoppr) ) or the dock (using [dockutil](https://github.com/kcrawford/dockutil) or a similar tool). You can use the Jamf Pro login trigger for this, or create a custom LaunchAgent or use [outset](https://github.com/macadmins/outset/)
+What you can do is run a script at login which sets the desktop (using [desktoppr](https://github.com/scriptingosx/desktoppr) ) or the dock (using [dockutil](https://github.com/kcrawford/dockutil) or a similar tool). You can use the [Jamf Pro login trigger](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Login_Events.html) for this, or create a custom LaunchAgent or use [outset](https://github.com/macadmins/outset/)
 
 ## Can Setup Manager run at first login, rather than right after enrollment?
 
@@ -52,6 +64,8 @@ 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.
 
+With Jamf Pro, you should consider [macOS Onboarding in Self Service](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/macOS_Onboarding.html) or a [login trigger](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Login_Events.html) instead.
+
 ## 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/Network.md

@@ -0,0 +1,6 @@
+#  Network Connectivity
+
+Setup Manager can display the current network status in the top right corner of the main window.
+
+By default, 
+

Docs/Webhooks.md

@@ -113,3 +113,18 @@ Use this webhook format in the Setup Manager profile:
 ```
 
 This `dict` replaces the simple `string` syntax.
+
+### Slack
+
+You can also [configure Slack to receive messages on webhook url](https://api.slack.com/messaging/webhooks).
+
+Use this webhook format in the Setup Manager profile:
+
+```xml
+<dict>
+  <key>kind</key>
+  <string>slack</string>
+  <key>url</key>
+  <string>--insert url from Slack here--</string>
+</dict>
+```

README.md

@@ -4,7 +4,7 @@
 
 _"Every Assistant has a Manager"_
 
-![Setup Manager Logo](https://img.shields.io/badge/macOS-12%2B-success)
+![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.