Skip to main content
Jamf Nation, hosted by Jamf, is a knowledgeable community of Apple-focused admins and Jamf users. Join us in person at the ninth annual Jamf Nation User Conference (JNUC) this November for three days of learning, laughter and IT love.

Configuring and Deploying the Jamf Setup App

Overview

Jamf Setup is an iOS app that enables end users to quickly setup and configure a mobile device. You can configure and customize Jamf Setup using Jamf Pro with Managed App Configuration. End users can then select a configuration without having to log in or contact IT, making shared device deployment quick and easy.

Requirements

To use Jamf Setup, you need the following:

  • Jamf Pro 10.0.0 or later
  • Supervised mobile devices with iOS 10 or later that are connected to the internet.
  • A Jamf Pro user account with the following Jamf Pro Server Object privileges enabled, which the app will use to make API calls:
    • Update Mobile Devices Extension Attributes (Navigate to Jamf Pro User Accounts & Groups > Privileges > Jamf Pro Server Objects)
    • Update Mobile Devices (Navigate to Jamf Pro User Accounts & Groups > Privileges > Jamf Pro Server Objects)
    • Update Users (Navigate to Jamf Pro User Accounts & Groups > Privileges > Jamf Pro Server Objects)

Note: To preserve device settings and restrictions, a Jamf Pro user account dedicated to using this application and excludes additional privileges is recommended.

For more information about Jamf Pro user accounts, see Jamf Pro User Accounts and Groups in the Jamf Pro Administrator's Guide.

Configuring and Deploying Jamf Setup

Configuring and deploying Jamf Setup involves the following steps:

  1. Configure Jamf Setup in Jamf Pro.
  2. Define the extension attribute display name.
  3. Create smart groups.

Configuring Jamf Setup in Jamf Pro

This section explains how to add the Jamf Setup app to Jamf Pro and how to configure the app using Managed App Configuration. For more information about the key-value pairs you must enter in Managed App Configuration, see the Customizing Jamf Setup with Managed App Configuration section.

  1. Log in to Jamf Pro.
  2. Click Devices at the top of the page.
  3. Click Mobile Device Apps, and then click New.
  4. Select App Store app or VPP store app, and then search for Jamf Setup.
  5. On the General tab, ensure that the Make App managed when possible checkbox is selected.
  6. Click the App Configuration tab and enter something similar to the following Managed App Configuration in the Preferences field:
<dict>
       <key>com.jamf.config.jamfpro.url</key>
       <string>https://instancename.jamfcloud.com</string>
       <key>com.jamf.config.jamfpro.username</key>
       <string>jamfpro-API-username</string>
       <key>com.jamf.config.jamfpro.password</key>
       <string>jamfpro-API-password</string>
       <key>com.jamf.config.jamfpro.device-id</key>
       <string>$JSSID</string>
       <key>com.jamf.config.setup.extension-attribute.name</key>
       <string>insert-name-here</string>
       <key>com.jamf.config.setup.extension-attribute.options</key>
              <array>
                     <string>insert-option-one-here</string>
                     <string>insert-option-two-here</string>
                     <string>insert-option-three-here</string>
                     <string>insert-option-four-here</string>
              </array>
       <key>com.jamf.config.ui.header-image.url</key>
       <string>https://resources.jamf.com/images/logos/Jamf-color.png</string>
       <key>com.jamf.config.ui.main-page.title</key>
       <string>Make a Selection</string>
       <key>com.jamf.config.ui.main-page.text</key>
       <string>Select the appropriate role below, and then tap Submit to configure your device</string>
       <key>com.jamf.config.ui.text.color</key>
       <string>#444444</string>
       <key>com.jamf.config.ui.main-page.button.text</key>
       <string>Submit</string>
       <key>com.jamf.config.ui.main-page.button.color</key>
       <string>#37BB9A</string>
       <key>com.jamf.config.ui.main-page.button.text.color</key>
       <string>#F8F8F8</string>
       <key>com.jamf.config.ui.success-page.title</key>
       <string>Success</string>
       <key>com.jamf.config.ui.success-page.text</key>
       <string>You have selected: $SELECTION. Press the home button or swipe up to begin using this device.</string>
       <key>com.jamf.config.ui.background.color</key>
       <string>#F8F8F8</string>
</dict>

7. Use the Scope, Self Service, and VPP tabs to configure app distribution settings as needed. For more information, see App Store Apps in the Jamf Pro Administrator’s Guide.
8. Click Save.

Defining the Extension Attribute Display Name

You must create a mobile device extension attribute for Jamf Setup. Only one extension attribute is required.

  1. Log in to Jamf Pro.
  2. In the top-right corner of the page, click Settings.
  3. Click Device Management.
  4. Click Extension Attributes.
  5. Click New and enter an extension attribute name in the Display Name field. Note: The Display Name field must match the extension attribute name defined on the App Configuration tab discussed in the previous section.
  6. Select "String" in the Data Type pop-up menu.
  7. Select "Text Field" in the Input Type pop-up menu.
  8. Click Save.

Creating Smart Groups

A smart group must be created for each extension attribute option.

  1. Log in to Jamf Pro.
  2. Click Devices at the top of the page.
  3. Click Smart Device Groups.
  4. Create a new smart group for your first extension attribute option. For more information, see Smart Device Groups in the Jamf Pro Administrator’s Guide.
  5. Click the Criteria tab and add criteria to the group: a. Click Add. b. Click Show Advanced Criteria. c. Click Choose for the extension attribute name you defined above. d. Type the name of the role that corresponds with the extension attribute option in the Value field.
  6. Choose an operator from the And/Or pop-up menu(s) to specify the relationships between criteria.
  7. To group criteria and join multiple operations, choose parentheses from the pop-up menus around the criteria you want to group. Operations in the group take place in the order they are listed (top to bottom).
  8. Click Save.
  9. Repeat this process to create a smart group for each extension attribute option.

Note: To preserve device settings and restrictions, the following settings in the Restrictions Payload of a mobile device configuration profile should not be allowed for devices using Jamf Setup.
- "Allow Erase All Content and Settings"
- "Allow modifying account settings"
- "Allow modifying passcode"
- "Allow modifying restrictions"
- "Allow modifying wallpaper"

For a list of recommended configurations for devices using Jamf Setup, see the Tips for Configuring the Jamf Setup App Knowledge Base article.

Customizing Jamf Setup with Managed App Configuration

You can use Managed App Configuration to customize Jamf Setup for your organization. Managed App Configuration is a set of key-value pairs used to configure iOS applications.

Note: If optional configurations are not used, the app's default settings will display.

For more information, see the AppConfig Community website: AppConfig for iOS.

Required Key-Value Pairs

Key-Value Pair Description
<key>com.jamf.config.jamfpro.url</key>
<string>https://instancename.jamfcloud.com/</string>

Jamf Pro URL
The Jamf Pro URL is the Jamf Pro server instance in which mobile devices are enrolled. Your full Jamf Pro URL must be entered in the string. This includes the correct protocol, fully qualified domain name (FQDN), and port of the server. For example:
<key>com.jamf.config.jamfpro.url</key> <string>https://jss.mycompany.com:8443/>
<key>com.jamf.config.jamfpro.device-id</key>
<string>$JSSID</string>
Jamf Pro Device ID
The Jamf Pro Device ID is used to enable API calls. This can be dynamically supplied by Jamf Pro using the variable [JSSID].
<key>com.jamf.config.jamfpro.username</key>
<string>jamfpro-API-username</string>
Jamf Pro Username
The username of the Jamf Pro user account is required and used to make API calls.
<key>com.jamf.config.jamfpro.password</key>
<string>jamfpro-API-password</string>
Jamf Pro Password
The password of the Jamf Pro user account is used to make API calls.
<key>com.jamf.config.setup.extension-attribute.name</key>
<string>insert-name-here</string>
Extension Attribute
The extension attribute name is used to make the API call to update inventory. The extension attribute name in the Managed App Configuration is not displayed to end users.
Note: The name included in the Managed App Configuration must match the mobile device extension attribute name in Jamf Pro.
<key>com.jamf.config.setup.extension-attribute.options</key>
<array>
<string>insert-option-one-here</string>
<string>insert-option-two-here</string>
<string>insert-option-three-here</string>
<string>insert-option-four-here</string>
</array>
Extension Attribute Options
The extension attribute options display in the Jamf Setup app as menu options to the end user. When an end user selects an option and taps Submit, the extension attribute value for that mobile device is set to the value selected.
Note: There is no limit on the number of menu options you can make available to end users in Jamf Setup.

Optional Key-Value Pairs

Key-Value Pair Description
<key>com.jamf.config.ui.header-image.url</key>
<string>https://resources.jamf.com/images/logos/Jamf-color.png</string>
Header Image URL
You can choose a header image by specifying the desired image URL. The image should be a banner-style image that fits the display area of the devices you will be deploying. The image must be in PNG or JPEG format, and a maximum height of 740 pixels is recommended. The header image will be stretched or shrunk to best fit devices, but the aspect ratio of the original image will be maintained.
Note: The image must be hosted on a secured domain (using https).
Text:
<key>com.jamf.config.ui.main-page.title</key>
<string>Make a Selection"</string>
<key>com.jamf.config.ui.main-page.text</key>
<string>Select the appropriate role below, and then tab Submit to configure your device.</string>

Color:
<key>com.jamf.config.ui.text.color</key>
<string>#444444</string>
Main Page Text
You can edit the default title and text on the app's main page. The default title is "Make a Selection", and the default text is "Select the appropriate role below, and then tab Submit to configure your device." You can also edit the title and text color. The default color is "#444444".
Text:
<key>com.jamf.config.ui.main-page.button.text</key>
<string>Submit</string>

Color:
<key>com.jamf.config.ui.main-page.button.text.color</key>
<string>#F8F8F8</string>
<key>com.jamf.config.ui.main-page.button.color</key>
<string>"37BB9A</string>
Button
You can edit the default button text, button text color, and button color. The default text is "Submit" in white, and the default button color is "#37BB9A".
Note: Color values must be written as a hex value.
<key>com.jamf.config.ui.success-page.title</key>
<string>Success</string>

<key>com.jamf.config.ui.success-page.text</key>
<string>You have selected: $SELECTION. Press the Home button or swipe up to begin using this device.</string>

Success Page Text
You can edit the title and text that appears after successful completion of mobile device setup. The default title is "Success", and the default text is "You have selected: [Selection]. Press the home button or swipe up to begin using this device."
<key>com.jamf.config.ui.background.color</key>
<string>#F8F8F8</string>
Background Color
You can edit the background color of the app. Default color is "#F8F8F8".
Note: Color values must be written as a hex value.
<key>com.jamf.config.setup.error.general</key>
<string>There was an error submitting your selection. Contact your IT administrator.</string>
Error Page Text
You can edit the text that displays when an error occurs. If the Managed App Configuration is empty, the default text is "App Configuration is empty. Contact your IT administrator. Jamf Setup is a component of Jamf Pro, developed by Jamf. This app must be associated with a Jamf Pro Server.
Contact you IT administrator for more information.” If the Managed App Configuration is not empty but is missing required values, the default text is "App Configuration is invalid. Contact your IT administrator."
If a submission error occurs, the default text is “There was an error submitting your selection. Contact your IT administrator."
Note: If an http code exists for the type of submission error, it will display at the end of the message.

Jamf Setup User Experience

When a user accesses the Jamf Setup app from a mobile device, they are guided through two simple steps to set up the device:

  1. The user selects an option from the Jamf Setup app display menu. For example, a user may choose their specific role.

  2. The user taps Submit. A success message is displayed, and the device is ready for use.

End User Error Messaging

If the Jamf Setup app fails to set up the device, end users will receive an error message that will look similar to the following:

When possible, an http code will be included to make troubleshooting the issue easier. (For example, "401".)
For more information about error message configurations, see the Customizing Jamf Setup with Managed App Configuration section.

Additional Information

For information about the Jamf Reset app, see the Configuring and Deploying the Jamf Reset App Knowledge Base article.

Like Comment
Order by:
SOLVED Posted: by jasonaswell

Jamf Setup doesn't appear to be available in VPP when searching via ABM. Jamf Reset is in there, and Jamf Setup is available via the App Store directly on a device - but it doesn't appear to be "purchasable" as a VPP app. Did the "Available with a volume discount for educational institutions" checkbox get skipped in App Store Connect?

Like
SOLVED Posted: by KMerendaTFMC

@jasonaswell I've got the same VPP issue. I deployed it just as an app store app with the config posted in this article. App installs OK and is branded like I wanted, but each time I hit submit it gives me a (409) error. I stripped the config down to just the required parameters, and triple-checked the user account permissions but can't get past the 409.

Like
SOLVED Posted: by canopimp

To do the app configuration you will need to use the VPP app and as of 30 minutes ago, it was available in the Education VPP store.

Like
SOLVED Posted: by jasonaswell

Still not available through Apple Business Manager, and Jamf Reset is no longer coming up in my searches even though I already claimed 100 licenses for our account. Could just be an App Store indexing thing across CDNs since it was just released. I'll try to be patient and check on it again tomorrow 😬

Like
SOLVED Posted: by KMerendaTFMC

+1 to Jamf Setup still not in Apple Business Manager.

Like
SOLVED Posted: by mahughe

I got both of them from ASM yesterday afternoon...for some reason it's case sensitive Jamf Reset or Jamf Setup. Atleast it was like that yesterday.

Like
SOLVED Posted: by jasonaswell

Echoing @mahughe's experience: I was finally able to get them both today via ABM by using the exact title-casing in search.

Like
SOLVED Posted: by KMerendaTFMC

Ditto. I see them in ABM now. I just searched for "Jamf"

Like
SOLVED Posted: by cdenesha

Reminder you can still purchase apps in the older VPP portal and they will be in ASM/ABM. This helps immensely if you have an iTunes link to the app - just prepend 'volume' like: https://volume.itunes.apple.com

Like
SOLVED Posted: by KMerendaTFMC

So, I got it deployed via ABM using basically a copy/paste of the app config above. App installs and branding looks OK, but I get a (409) error when I tap submit. Opened a case on this yesterday but was hoping it was just because I wasn't using the app from ABM. Oh well - lets see what support has to say.

Like
SOLVED Posted: by kyle.hammond

When running on Jamf Pro v10.8, the user account specified in the Jamf Setup app config also needs "Update" permissions for "Users".

A change was made in v10.8 to the API related to the new Inventory Preload settings, and the change also impacted the API endpoints that Jamf Setup uses. We will be updating the documentation soon.

Like
JAMFBadge
SOLVED Posted: by brendon.paucek

Thanks for the feedback. The Requirements section has been updated to include "Update Users" as an additional permission.

Like
SOLVED Posted: by KMerendaTFMC

Thanks @kyle.hammond - that fixed my issue.

Like
SOLVED Posted: by nramos03

I have setup and reset setup but when I go to switch between my two POC profiles, I error out in the commands with the following:

Anybody have any ideas? It loads the POC 1 perfectly fine.

Thanks

Like
SOLVED Posted: by tim.knox

@nramos03, that could be due to having two HomeScreen layouts scoped to a device. The way I've had the most success is to only have ONE HomeScreen layout assigned to ALL your devices. So, everyone has the same look under the hood. Then hide all the apps you don't want for each look.

So, look 1 has apps A and B
Look 2 has apps B and C
Look 3 has apps A and C

Same HomeScreen layout for all the devices, hide app C for Look 1, hide app A for Look 2, and hide app B for Look 3. Add in different wallpapers from your SmartGroups and you should see better results.

Like
SOLVED Posted: by bdelamarche

Hi All is there any other additionnal Key-Value Pair ? Like a key that permit to populate an extension attribut to many iPad or a class or a static group
Any documentation regarding the Key-Value Pair ?
Thanks a lot
Benoit

Like
JAMFBadge
SOLVED Posted: by brendon.paucek

This article has been updated to include recommended restrictions and a link to an article including additional configuration recommendations for Jamf Setup.

Like
SOLVED Posted: by bdelamarche

Is there additionnal Key-Value Pair ?
@brendon.paucek thanks the clarification in case there is other value to setup the student in a classe from a teacher iPad or to setup a child iPad from a Parent iOS
Many thanks

Like
JAMFBadge
SOLVED Posted: by brendon.paucek

@bdelamarche The functionality you are describing is currently not a supported workflow but an interesting idea. Consider submitting your question as a feature request.

Like
SOLVED Posted: by OxfordHealthJamf

I'd like to deploy Jamf Setup to only a portion of my iPad estate. The devices will be reset and setup on an ongoing basis. I initially tried creating a static device group which I then used as the scope for the Jamf Setup app. However when the device gets reset, it is removed from the satiric device group, and hence never gets the Jamf Setup app the second time around.

There must be a way to do this. What am I missing?!

Like
SOLVED Posted: by cdenesha

@OxfordHealthJamf Hello. This is the way static groups work for Computers and Mobile Devices - they are removed from the group once the device is erased. Instead you will want to create a Smart Group based off a field you already have, or based off a new Extension Attribute that you create. Possibly "Deploy Jamf Setup" = Yes

Like
SOLVED Posted: by OxfordHealthJamf

Thanks for the advice. Jamf advise that we set our re-enrolment settings to clear the Extension Attribute as a best practise. Your suggestion implies not to actually do this, otherwise the attribute will be erased and we'll be back in the same position. The problem with this is that whilst it fixes the scoping of the app to the intended group, it breaks the use of Jamf Setup, which also uses smart groups based on Extension Attributes.

Like
SOLVED Posted: by mhegge

I am finding something missing in the KB regarding setting up the criteria for the Smart Groups. I am finding "Operator is" not to work and that "Operator matches regex" more specifically puts devices into the smart group, otherwise I see many devices out of the scope in which I want start getting Config Profiles or at least attempt to.

Issue with the various configs getting deployed after the smart group changes. ERROR: "Remove the profile “Restriction: Default JAMF Setup Home Screen” before installing this profile."

I must be missing something...likely obvious

Like
SOLVED Posted: by AndyCorps

We're looking at implementing this but don't seem to be able to make any more than 4 options available to select from. [We have multiple iPad classroom scenario's at multiple venues.]
I've added several VPP instances of the Jamf Setup app scoped for each venue, with respective com.jamf.config.setup.extension-attribute.options array sections as a short term option for now, but can see this limitation causing problems if Jamf Setup is to be a solution to our quick\easy automated setup routines.

Like
SOLVED Posted: by danny.porter

@AndyCorps Thank you for reaching out. I've taken a screen shot of our Managed App Config I did in our Webinar a couple weeks ago. You have an unlimited amount of arrays you can put in the app, so it shouldn't limit you. You can even put blank arrays like we did hear. Does this help?

[link text
](link URL)

Like
SOLVED Posted: by AndyCorps

Thanks for the reply.
In testing when I tried a single Array, the Jamf Setup App isn't display anymore then 4 strings.
For Example:

  <key>com.jamf.config.setup.extension-attribute.name</key><String>Site</string>
  <key>com.jamf.config.setup.extension-attribute.options</key>
    <array>
      <string>AB</string>
      <string>CD</string>
      <string>EF</string>
      <string>GH</string>
      <string>IJ</string>
      <string>KL</string>
    </array>

Just gives:

and no IJ or KL options...

What I'd love to have is a multi screen Jamf setup. Have it launch full screen (utilise single app mode) for the end user to answer 2-3 simple questions. At the end of use they just hit Jamf Reset ready for the next person to pick it up...

Like
SOLVED Posted: by AndyCorps

.

Like
SOLVED Posted: by danny.porter

@AndyCorps Thank you for your screen shot and sharing. Though the window within Jamf Setup doesn't show IJ or KL options, if you scroll down, do you see those options? Right now there isn't the ability to make that window any larger, but if you'd like as an option, please share it as Feature Request above.

As it pertains to what you're looking for in Jamf Setup, I wonder if there is something else that would meet your needs. Are you wanting to use it as a survey device and then when the survey is done, the end user uses Jamf Reset to reset the device and reload the device back to the home screen with the survey in Single App Mode? Jamf Setup changes the Inventory within Jamf Pro, so it wouldn't necessarily be able to facilitate your needs of answering questions. Please let me know if I didn't quite understand your question.

Like
SOLVED Posted: by dnikles

I've got an interesting use case I thought I'd share. We have thousands of end users but some ios apps we only purchase a small number of licenses for, but want to make the app available to more people than we have licenses for so they can choose to install the app or not. We can't scope to all users in self service because just scoping an app uses a license. I configured jamf setup to list the apps available to be installed. Once they pick an app, the extension attribute triggers them to be in a smart group. But, if they want more than one app we can't just rely on that smart group, so on the smart group membership change it also sends out a webhook. We take the webhook and add the device to a static group, and scope the apps to that static group. So jamf setup provides a method for us to allow users to install paid for apps that we don't have enough licenses to cover scoping to everyone.

Like
SOLVED Posted: by AndyCorps

@danny.porter thanks for the reply (sorry for a slow response, took an Easter break)
I didn't see any indication that the displayed options could be scrolled (no visible scroll bar), so hadn't checked for this. Doh!...
Thanks. Now I see it. So I'll make a feature request to make the ability to scroll the list a little more obvious maybe.

I could still do with the option to have more than one question also, to update more than one EA (so another Feature request for this)

Thanks again.

Like
SOLVED Posted: by Mark.Major

@mhegge , it may be a bug... I can also confirm that the other devices were being scoped into the Smart Group when I used the "is" operator.

I changed it to "matches regex" and the devices are back out of the scope.

Is anyone able to shed some light?

Like
SOLVED Posted: by danny.porter


@Mark.Major Thanks for sharing. I use the "is" operator and haven't had that issue, but I wonder is it at the time of enrollment that this happens? From the Prestage, I have the devices that will be getting the Jamf Setup app assigned to a Department I've titled: Danny Setup. Then in the Smart Group, the first is to scope to the department AND the extension attribute I've created: Danny Setup that is blank. Then when I designate the option I want in Jamf Setup on the device it un-scopes it from the Initial Smart Group and puts it in another that solely based on the Extension attribute.

I don't know if that helps, but I hope it does. Please let me know if there is anything else I can do to help.

Like
SOLVED Posted: by gabe2385

Hey @kyle.hammond I was having the same issue, I ran into this article from JAMF Tips for Configuring the Jamf Setup App this helped me find that there should only be one home layout or it can cause confliction. Once I had the one layout you can then restrict what apps you need and it works fine.

Like
SOLVED Posted: by danny.porter

@gabe2385 Thank you for the call out. It works best when creating the Home Screen layout separate from every other configuration profile else. Here are the two tips that helped me when I was also configuring my Jamf Setup apps.
1. Scope all apps to the device, whether the Prestage, Department, and not the Smart Group for the Extension Attribute. Make sure the "blank" or "initial" setup configuration profile restriction has allow only Jamf Setup, Reset, and Settings. Then when the selection is chosen within Setup, make sure a new restriction is setup allowing the apps you want for that selection.
2. Create a Home Screen Layout that is separate from all other configuration profiles. This helps the device and the process go very smoothly when switching between extension attributes.

Like
SOLVED Posted: by evaldes

Hi all! Is there a way to password protect the jamf setup icon and the jamf reset icon? I have about 500 iPads that are being configured for several departments and I'm trying to prevent users to access other departments in order to skip out of what apps they are allowed to see...

TIA

Like
SOLVED Posted: by evaldes

NVM I figured it out... by excluding the group inside the jamf setup scope.

Like
SOLVED Posted: by AndyCorps

@evaldes I scope the setup to just machines that don't have the EA defined (all new devices can be setup easily enough).
Upon reset, (and thusly re-enrolment) I make sure EA's aren't cleared. So devices are pretty mush stuck in the EA based smart groups that were defined initially. Only way to move\re-purpose them is for a Jamf admin to clear the EA. :-)

Like
JAMFBadge
SOLVED Posted: by hillary.smith

This article was updated to clarify required privileges and the navigation path to enabling those privileges. Other changes included adding more specific placeholders for instances directing users to insert the URL, username, or password.

For example, <string>insert-username-here</string> changed to <string>jamfpro-API-username</string>.

-Hillary

Like