Skip to content

Commit 0e4961a

Browse files
scriptingosxscriptingosx
committed
updated docs for 1.1beta
1 parent 4aabab6 commit 0e4961a

13 files changed

+694
-290
lines changed

‎ConfigurationProfile.md

+172-96
Large diffs are not rendered by default.

‎Docs/Extras.md

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Extras and Notes
2+
3+
## Custom JSON Schema for Jamf Pro
4+
5+
- create a new profile
6+
- go to ‘Application & Custom Settings’
7+
- select ‘Jamf Applications’
8+
- click the ‘+ Add’ button
9+
- in the ‘Jamf Application Domain’ popup select ‘com.jamf.setupmanager’
10+
- for the version select the version of Setup Manager you are using
11+
- for the ‘Variant’, select ‘Setup Manager.json’
12+
- fill in your fields!
13+
14+
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.
15+
16+
## Quit
17+
18+
The command-Q keyboard short cut to quit the app is disabled. You can use shift-control-command-E instead. This should only be used when debugging as it may leave the client in an undetermined state when installations are aborted.
19+
20+
## Logging
21+
22+
Setup Manager logs to `/Library/Logs/Setup Manager.log`. While Setup Manager is running you can open a log window with command-L.
23+
24+
## Debug mode
25+
26+
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.
27+
28+
You will also be able launch the app as the user, by double-clicking the app in `/Applications/Utilities`. This is useful to test the look and feel of your custom icons, text and localization. When you use this to create screen shots for documentation, also note the `overrideSerialNumber` and `hideDebugLabel` keys.
29+
30+
## Flag file
31+
32+
Setup Manager creates a flag file at `/private/var/db/.JamfSetupEnrollmentDone` when it finishes. If this file exists when Setup Manager launches, the app will terminate immediately and without taking any action. You can use this flag file in an extension attribute in Jamf to determine whether the enrollment steps were performed. (Setup Manager does not care if the actions were performed successfully.)
33+
34+
When `DEBUG` is set to `true` in the defaults/configuration profile, the flag file is ignored at launch, but may still be created when done.
35+
36+
In Jamf Pro, you can create an Extension Attribute named "Setup Manager Done" with the script code:
37+
38+
```sh
39+
if [ -f "/private/var/db/.JamfSetupEnrollmentDone" ]; then
40+
echo "<result>done</result>"
41+
else
42+
echo "<result>incomplete</result>"
43+
fi
44+
```
45+
46+
And then create a Smart Group named "Setup Manager Done" with the criteria `"Setup Manager Done" is "done"`. This can be very useful for scoping and limitations.
47+
48+
## User Data file
49+
50+
The data from user entry is written to a file when Setup Manager reaches a `waitForUserEntry` step and again when it finishes. The file is stored at `/private/var/db/SetupManagerUserData.txt`. When `DEBUG` is enabled, the file will be written to `/Users/Shared/`.
51+
52+
The file is plain text with the following format:
53+
54+
```
55+
start: 2024-08-14T13:52:56Z
56+
userID: [email protected]
57+
department: Sales
58+
building: Example
59+
room: ABC123
60+
assetTag: XYZ888
61+
computerName: MacBook-M7WGMK
62+
submit: 2024-08-14T13:54:37Z
63+
duration: 101
64+
```
65+
66+
Start time (`start`) and finish/submission time (`submit`) are given in ISO8601 format, universal time (UTC).
67+
68+
Fields that were not set in user entry will not be shown at all. You can use this file in scripts or extension attributes. The easiest way would be to parse it with `awk`, e.g.
69+
70+
```
71+
duration=$(awk -F ': ' '/duration: / {print $2}' /private/var/db/SetupManagerUserData.txt)
72+
```
73+
74+
## Final action and shutdown
75+
76+
When the app is not running as root (for testing or from Xcode) or when the `DEBUG` preference is set, shutdown will merely quit.
77+
78+
## "About This Mac…" window
79+
80+
When you hold the option key when clicking on "About This Mac…" you will see more information.

‎Docs/FAQ.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Frequently Asked Questions
2+
3+
## Is there are custom JSON Schema for Jamf Pro?
4+
5+
[Yes.](Extras.md#custom-json-schema-for-jamf-pro)
6+
7+
## Can you block the user desktop with user initiated enrollment?
8+
9+
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.
10+
11+
## Setup Manager is not launching after enrollment
12+
13+
There can be many causes for this. A few common causes are:
14+
15+
- Jamf Pro: check that Setup Manager is added to your prestage and the package does not have the label "Availability pending" in Settings> Packages
16+
- Jamf Pro: do not install JamfConnect.pkg in prestage when you want to use Setup Manager. Install JamfConnect with Setup Manager instead
17+
- 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.
18+
19+
## Does Setup Manager require Jamf Connect
20+
21+
No.
22+
23+
Setup Manager will run fine without Jamf Connect. You can even build 'single-touch' style workflows with Setup Manager withough Jamf Connect. Some features, such as pre-assigning a device to a specific user require Jamf Connect, though.
24+
25+
## How can I use the icon for an app before the app is installed?
26+
27+
- 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
28+
- use http(s) urls to the image files
29+
- you can host them on a web server/service that you have control over
30+
- 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
31+
32+
33+
## What is happening during the "Getting Ready" steps?
34+
35+
During the "Getting Ready" phase, Setup Manager is waiting for the Jamf Pro configuration to be complete, and runs a recon, so that policies during the enrollment phase can already be scoped. You cannot change the steps in this phase. You can see the details and possibly failures in the Setup Manager log.

‎Docs/JamfPro-QuickStart.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Jamf Pro: Setup Manager Quick Start
2+
3+
## Upload Setup Manager package
4+
5+
Download the latest version of the Setup Manager installation pkg from the [releases page](https://github.com/Jamf-Concepts/Setup-Manager/releases/latest).
6+
7+
In the Jamf Pro web interface, go to Settings > Packages. Create a new package and upload the Setup Manager installer pkg file to Jamf Pro. Save the package.
8+
9+
_Note:_ when the package is marked as 'pending' it will not work in prestage deployment. Wait with testing deployments until the 'pending' flag has disappeared.
10+
11+
## Prepare a Jamf Pro policy for use with Setup Manager
12+
13+
Setup Manager can trigger policies in Jamf Pro. By triggering a sequence of Jamf Pro policies all the required software and configurations will be installed on the device.
14+
15+
## Create the Setup Manager configuration profile
16+
17+
- Go to Computers > create a new profile
18+
- Name the profile 'Setup Manager'
19+
- assign a category, ensure the Level is set to 'Computer Level'
20+
- in payload sidebar select 'Application & Custom Settings', then select 'Jamf Applications'
21+
- click the '+ Add' button
22+
- for the 'Jamf Application Domain' choose `com.jamf.setupmanager`
23+
- for the version select the version of Setup Manager you are using
24+
- for the 'Variant', select `Setup Manager.json`
25+
26+
### Profile values
27+
- for the Icon Source, enter `name:NSComputer`. This is a special value that tells Setup Manager to use an image of the computer it is running on. There are many other options you can use as an icon source [documented here](../ConfigurationProfile.md#icon-source).
28+
- for the Title, enter `Welcome to Setup Manager!`
29+
- for the Message, enter `Please be patient while we set up your new Mac…`
30+
31+
### Enrollment
32+
- under Enrollment Actions, click on 'Add Item'
33+
- for item 1, from the 'Select Action Type' popup, choose "Installomator"
34+
- for 'Action Label,' enter `Google Chrome`
35+
- for 'Action Icon Source,' enter `symbol:network`
36+
- for 'Installomator Label' enter `googlechromepkg`
37+
- click 'Add Item'
38+
- for item 2, from the 'Select Action Type' popup, choose "Shell Command"
39+
- under 'Command Arguments', click 'Add argument', enter `-setTimeZone`
40+
- click 'Add argument' again and enter your time zone in the format `Europe/Amsterdam` (the 'TZ identifier' [from this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
41+
- for 'Action Label,' enter `Set Time Zone`
42+
- for 'Action Icon Source,' enter `symbol:clock`
43+
- for 'Requires Root' select `true`
44+
- for 'Shell Command Path' enter `/usr/sbin/systemsetup`
45+
46+
You can add more actions here. There are more types of actions available, you can use a 'Jamf Policy Trigger' action to run a policy with a custom trigger. You can also use a 'Watch Path' action to wait for an app to be installed from the Mac App Store or Jamf App Installers.
47+
48+
## Scoping and Prestage
49+
50+
- Scope the configuration profile to the computers you want to run Setup Manager on
51+
- create a new Prestage or duplicate an existing one
52+
- Add the Setup Manager pkg and the configuration profile to the Prestage
53+
- if you have JamfConnect.pkg in the Prestage, remove it. You can later add an action to install JamfConnect using Setup Manager.
54+
- ensure that 'Automatically advance through Setup Assitant' is _disabled_
55+
- Have at least one option _disabled_ (so that _is_ displayed)
56+
- ensure your test Mac(s) is (are) assigned to the Prestage
57+
58+
## Wipe the Test Mac
59+
60+
- on the test mac, choose 'Erase all Contents and Settings' in the Settings app or wipe the Mac using the 'Wipe Computer' remote management command in Jamf Pro
61+
- click through the initial enrollment dialogs. After you approve the enrollment in your MDM, Setup Manger should appear and perform the actions you configured
62+
- while the installations are progressing, click on "About this Mac…" for information, click again while holding down the option key for even more information
63+
- hit command-L for a log window. You can also find this log info later at `/Library/Logs/Setup Manager.log`
64+
65+
## Next Steps
66+
67+
- add more actions to Setup Manager, you can use more Jamf Pro policies, Installomator labels, or shell actions
68+
- add a computer name template key to the profile to automate computer naming
69+
- add a `help` section to let the user know what is going on
70+
- ideally automated deployments shouldn't require manual entry, but if necessary, you can configure a user entry section in the profile
71+

‎Docs/JamfPro-TwoPhase.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Jamf Pro: extra installations based on user data entry
2+
3+
In this simple example workflow, we run certain Jamf Pro policies depending on the department. This example can be expanded to other user entry data fields.
4+
5+
- create Setup Manager configuration profile
6+
- create a `userEntry` key with a list of options for the department:
7+
8+
```xml
9+
<key>userEntry</key>
10+
<dict>
11+
<key>department</key>
12+
<dict>
13+
<key>options</key>
14+
<array>
15+
<string>Sales</string>
16+
<string>Development</string>
17+
<string>IT</string>
18+
<string>Marketing</string>
19+
</array>
20+
</dict>
21+
</dict>
22+
```
23+
24+
Note that you need to have the matching departments in Jamf Pro.
25+
26+
- add the `enrollmentActions` that should run on all computers first
27+
- then add a `waitForUserEntry` action:
28+
29+
```xml
30+
<dict>
31+
<key>label</key>
32+
<string>Submit entries</string>
33+
<key>waitForUserEntry</key>
34+
<string/>
35+
</dict>
36+
```
37+
38+
When Setup Manager reaches this action it will wait for the user data entry to be complete if it isn't already. Then Setup Manager will submit the data from the user entry to Jamf Pro and run a recon, so you can use the data for scoping subsequent policies.
39+
40+
Setup Manager also saves the data from user entry in a plain text file which you can use in policy scripts after the `waitForUserEntry` action. [See details here.](Extras.md#user-data-file)
41+
42+
- Insert this action
43+
44+
``` xml
45+
<dict>
46+
<key>icon</key>
47+
<string>symbol:plus.app</string>
48+
<key>label</key>
49+
<string>Extra Apps for %department%</string>
50+
</dict>
51+
<key>policy</key>
52+
<string>install_extra_apps</string>
53+
</dict>
54+
```
55+
56+
- for the policies you want run/install depending on the user entry:
57+
- give the policy a custom trigger matching the trigger in 'Extra Apps' action: `install_extra_apps`
58+
- scope the policy to the department(s) that should receive the installations
59+
- repeat for every extra installation that depends on the user entry
60+

‎JamfProConnect-SingleTouch.md ‎Docs/JamfProConnect-SingleTouch.md

File renamed without changes.

0 commit comments

Comments
 (0)