updated for v1.3

Author: scriptingosx

ChangeLog.md

@@ -1,27 +1,36 @@
 #  Setup Manager - Change Log
 
-## v1.3beta
-(2025-05-27)
+## 1.3
+(2025-07-08)
+
+Notes added since 1.3beta are marked with '(release)'
 
 ### 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)
+    - Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78, #130)
     - 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
+- new flag file `/private/var/db/.JamfSetupStarted`, which is created when Setup Manager starts. You can use this to scope Mac App Store apps and Jamf App Installers, which prevents these apps from installing early in the enrollment, slowing down the Jamf Pro configuration
 - 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)
+- (release) Polish localization (Thanks to @bsojka)
 
 ### 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
+- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions, this should avoid some false "error 57" reports
 - Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
+- (release) added name for macOS Tahoe 26
+- (release) minor localization and UI fixes
+- (release) disabled some undesirable keyboard shortcuts (#125)
+- (release) arguments in `installomator` actions are now processed correctly
+- (release) output to log is flushed immediately to avoid truncation on restart/shutdown (#129)
+- (release) MDM Server address shown in extended "About this Mac" (#127)
 
 ### Deprecations and Removals
 - (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
@@ -32,7 +41,7 @@
 
 #### 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:
+The format of the Setup Manager log file (in `/Library/Logs/Setup Manager.log`) has changed. The new format should be easier to read and parse with other tools. There are four columns:
 
 - timestamp (in ISO8601)
 - log level (default, error or fault)
@@ -49,18 +58,25 @@ 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`.
 
+#### Installation and Jamf Pro logs and summaries
+
+The Log window (open with command-L) gained a new "Install" tab, which shows the system's installation log file (`/var/log/install.log`). When enrolling with Jamf Pro, there is another new "Jamf" tab, which shows the Jamf log (`/var/log/jamf.log`). By default, the Log window will be summarized to events relevant to the enrollment workflow. You can see the full log content by unchecking the 'Summarize' option.
+
+Note that both logs will show events that were not initiated by Setup Manager. Nevertheless, these events may be relevant to your enrollment workflow.
+
+These summarized events will also appear in the Setup Manager log tab and file, as well as the universal log entries. Having these events in context at the time they occur in the Setup Manager log is very helpful when trouble-shooting enrollment workflows.
 
 #### 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.
+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.) 
+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 tools 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.
+Checking the log for network changes or outages 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.  
+Network status can also show 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.
 
@@ -73,7 +89,45 @@ When you click on the Network status icon, a popup will show:
  - 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.
+Note that the connectivity check is quite basic and might not catch all functionality that is required for a service to work. It should provide an indication whether a service is reachable, but deeper trouble-shooting and monitoring might be required for reliable diagnostics.
+
+Seen["Network Connectivity"](https://github.com/jamf/Setup-Manager/Docs/Network.md) for more detail.
+
+#### Finished Script and Trigger
+
+Setup Manager now includes functionality to launch a script or Jamf Pro custom policy trigger in a separate process when the main Setup Manager process is finished. This is useful for installations that might unexpectedly restart the computer or the context that Setup Manager is running in (most commonly, Setup Manager is running at login window, which the Jamf Connect installer will kill).
+
+There are two keys relevant for this: `finishedScript` and `finishedTrigger`. 
+
+See ["Running Scripts and Policies when Setup Manager finishes"](https://github.com/jamf/Setup-Manager/Docs/Extras.md#running-scripts-and-policies-when-setup-manager-finishes) for detail.
+
+## 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)
 
 ## v1.2.2
 (2025-04-17)

ConfigurationProfile.md

@@ -75,6 +75,20 @@ Example:
 
 `Please be patient.` will be bold. More detail on [Markdown here](#markdown).
 
+During the "Getting Ready" phase up to three lines of text will be shown. When the action icon progress list is shown, text will be truncated to a single line.
+
+Use actual line breaks in the XML for line breaks in this text. (`\n` escape sequence will _not_ work in XML)
+
+Example:
+
+```xml
+<key>message</key>
+<string>Please be patient…
+
+This line of text will be truncated when the action icon list is shown.</string>
+```
+
+
 #### `background`
 
 (String, optional, localized, dark mode)
@@ -203,17 +217,35 @@ The script has to fulfill these criteria to be executed:
 - not writable for group or other (file mode `755` or `555`)
 - no quarantine flag attached
 
+The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
+
+Example:
+
+```xml
+<key>finishedScript</key>
+<string>/Library/Management/finishedScript.sh</string>
+```
+
 #### `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.
 
+The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
+
+Example:
+
+```xml
+<key>finishedTrigger</key>
+<string>setup_manager_finished</string>
+```
+
 #### `totalDownloadBytes`
 
 (Integer, optional, default: 1000000000 or 1GB, v0.8)
 
-Use this value to provide an estimate for the total size of all items that will be downloaded. Setup Manager will display and estimated download time for this sum in the "About this Mac..." popup window.
+Use this value to provide an estimate for the total size of all items that will be downloaded. Setup Manager will display an estimated download time for this sum in the "About this Mac..." popup window.
 
 Example:
 
@@ -325,6 +357,13 @@ There are three options:
 
 Setup Manager's log window will always show the output, regardless of this setting.
 
+Example:
+
+```xml
+<key>actionOutputLogging</key>
+<string>always</string>
+```
+
 ## Actions
 
 All actions should have these keys:
@@ -524,9 +563,9 @@ Example:
 
 ### Installomator
 
-This will run [Installomator](https://github.com/Installomator/Installomator) to install a given label.
+Setup Manager includes the [Installomator](https://github.com/Installomator/Installomator) script to simplify installations. This action 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 notifications. 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 these variables and add more with the `arguments` key.
 
 #### `installomator`
 
@@ -553,6 +592,21 @@ Example:
 </dict>
 ```
 
+with arguments: 
+
+```xml
+<dict>
+  <key>label</key>
+  <string>Example App</string>
+  <key>installomator</key>
+  <string>example</string>
+  <key>arguments</key>
+  <array>
+    <string>downloadURL=https://example.com/alternativeURL</string>
+  </array>
+</dict>
+```
+
 
 ## Icon Sources
 
@@ -950,9 +1004,10 @@ Use these two-letter codes for these languages:
 | Dutch (Nederlands) | nl              |
 | French             | fr              |
 | German             | de              |
-| Italian            | it              |
 | Hebrew             | he              |
+| Italian            | it              |
 | Norwegian          | nb              |
+| Polish             | pl              |
 | Spanish            | es              |
 | Swedish            | sv              |
 

Docs/Extras.md

@@ -1,5 +1,19 @@
 # Extras and Notes
 
+
+## Keyboard Shortcuts
+
+Note that the Setup Manager window does not activate to receive keystrokes automatically when running over Setup Manager. You have to click in the Setup Manager window first.
+
+| shift-control-command E | ["exit"/quit Setup Manager](#Quit), use only in emergencies as it will leave installations in an  indeterminate state |
+| command-L | open [Log window](#Logging) |
+| command-B | toggle Battery status icon in Setup Manager window |
+| command-N | toggle [Network status icon](Network.md) in Setup Manager window |
+| space | show [serial number bar code window](#scannable-serial-number-barcode) |
+| i | show "About this Mac" popup |
+| h | show "Help" popup, when present |
+| hold option key when clicking "About this Mac" | shows more info |
+
 ## Custom JSON Schema for Jamf Pro
 
 - create a new profile
@@ -23,7 +37,30 @@ The command-Q keyboard shortcut to quit the app is disabled. Use `shift-control-
 
 ## Logging
 
-Setup Manager logs to `/Library/Logs/Setup Manager.log`. While Setup Manager is running you can open a log window with command-L.
+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` and (Jamf Pro only) one tab showing output from `/var/log/jamf.log`. By default, these 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 both logs will show events that were not initiated by Setup Manager. Nevertheless, these events may be relevant to your enrollment workflow.
+
+These summarized events will also appear in the Setup Manager log tab and log file, as well as the universal log entries. Having these events in context at the time they occur in the Setup Manager log is very helpful when trouble-shooting enrollment workflows.
+
+Setup Manager logs to `/Library/Logs/Setup Manager.log`. There are four columns:
+
+- timestamp (in ISO8601)
+- log level (default, error or fault)
+- category (general, install, network, jamfpro)
+- message
+
+To clean up the main log a little, Setup Manager 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`.
+
+Setup Manager 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"'
+```
 
 ## Debug mode
 
@@ -136,7 +173,7 @@ You can use this to scope configuration profiles and policies so that they are i
 
 ##  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.
+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. (e.g Jamf Connect Login)
 
 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.
 
@@ -146,4 +183,3 @@ The finished script or custom trigger are configured in the Setup Manager config
 
 The SetupManagerFinished daemon logs its output (and the output of the policy and scripts to `/private/var/log/setupManagerFinished.log`.
 
-