Guides

Introduction

Prior to Apple's Return to Service available with iOS/iPadOS 17 and tvOS 18, when a device was erased via Jamf Pro, the re-enrollment process required a user to manually select language, location and reconnect the device to Wi-Fi before proceeding through the Setup Assistant steps. With Return to Service, Jamf Pro can send an erase command that includes additional options to provide Wi-Fi settings so that a user does not need to manually reconnect to Wi-Fi along with auto selecting language and location.

This new workflow improves the user experience so that after a Jamf Pro wipe, the user is returned to the home screen without additional manual steps.

iOS/iPadOS end-user experience: One Tap → No Taps → Home Screen

tvOS end-user experience: Two Clicks → No Clicks → Home Screen

End-User Experience

Launch the app, touch the reset button with 5 seconds availability to cancel and then the device will return to service back to the home screen without any interactions.

iOS/iPadOS End-User Experience: One Tap → No Taps → Home Screen

tvOS End-User Experience: Two Clicks → No Clicks → Home Screen

IMPORTANT: New Implementation Option

Jamf Return to Service App offers two implementation options starting with version 3.1.3 called Legacy and Recommended. Recommended introduces a more secure method to access Jamf Pro from the native mobile app. Jamf recommends all new installations implement Recommended. Though not required, Jamf recommends existing Legacy implementations migrate to the Recommended implementation.

Requirements

iPad and iPhone

• iOS/iPadOS 17 or later
• Jamf Pro 10.50.0 or later (only for Legacy implementation)
• Jamf Pro 11.24.1 or later (only for Recommended implementation)

Apple TV

• tvOS 18 or later
• Jamf Pro 11.13.0 or later (only for Legacy implementation)
• Jamf Pro 11.24.1 or later (only for Recommended implementation)

All devices:

• Device scoped to PreStage Enrollment (Automated Device Enrollment)

Limitations

• Activation Lock needs to be disabled (only for Legacy implementation)
• Enrollment Customization is not supported for previous enrollment or next enrollment
• Require Credentials for Enrollment is not supported
• 802.1x and certificate based networks are not supported for enrollment
• Networks with captive portals (Guest Networks) are not recommended

Enable End-User Workflow (Recommended implementation)

Note: The following steps need to be completed in the exact order listed below.

Wi-Fi Configuration Profile

• Create or use existing configuration profile containing Wi-Fi payload(s) of your onboarding network

Note: 802.1x and certificate based networks are not supported for enrollment. Networks with captive portals (Guest Networks) are not recommended.

Enable PreStage

• Check Allow use of the Return to Service option during device reset
• Select Wi-Fi configuration profile
• Check Preserve managed apps (optional)

Note: Once a device enrolls through PreStage with Preserve managed apps enabled, the device OS cannot update remotely or by user-initiation until the device subsequently enrolls through PreStage without Preserve managed apps checked.

• Scope devices to PreStage

Note: Enrollment Customization is not supported for previous enrollment or next enrollment. Require Credentials for Enrollment is not supported.

Initial App Record Setup

1. Distribute Return to Service app to Jamf Pro using Volume Purchasing workflow
2. Add Jamf Return to Service to Jamf Pro app catalog if not created automatically
   • Managed Distribution: check Assign Content Purchased in Volume
   • Do not scope and leave managed app configuration blank at this time
   • Click Save
3. Take note of the app record ID in the URL displayed in the browser address bar: https://yourserver.jamfcloud.com/mobileDeviceApps.html?id=18&o=r

Linked App API Integration

1. Create API Role

   • In Settings > System > API Roles and Clients, select the API Roles tab
   • Click + New button
   • Set Display name to "Return to Service"
   • Select the following privilege and click Save:
     • Send Mobile Device Remote Wipe Command

2. Create API Client

   • In Settings > System > API Roles and Clients, select the API Clients tab
   • Click + New button
   • Set Display name to "Return to Service"
   • Select the API Role created in the previous step
   • Select "Enable API Client" button and click Save

3. Take note of the API Client record ID in the URL displayed in the browser address bar: https://yourserver.jamfcloud.com/view/settings/system-settings/apiroles-and-clients/api-clients/5

   Note: Do not generate a client secret.

4. Use Jamf Pro API to link Jamf Return to Service to the API Client created above

   Use a client credential with "Create API Integrations" privilege to request a bearer token. See Authentication and Authorization documentation for more details.

   A. Request bearer token. Modify yourserver.jamfcloud.com, your_client_id, and your_client_secret with the saved values of the client credential with "Create API Integrations" privilege.

   TOKEN=$(curl -s -X POST "https://yourserver.jamfcloud.com/api/oauth/token" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "client_id=your_client_id" \
     --data-urlencode "client_secret=your_client_secret" \
     | plutil -extract access_token raw -)
   

   B. Link app. Modify the JPS instance name and the 2 IDs saved from Initial App Record Setup (step 3) and Linked App API Integration (step 3) above.

   curl --request POST \
     --url https://yourserver.jamfcloud.com/api/v1/api-integrations-linked-app \
     --header "Authorization: Bearer $TOKEN" \
     --header "accept: application/json" \
     --header "content-type: application/json" \
     --data '
   {
     "apiIntegrationId": "0",
     "linkedAppId": "0",
     "linkedAppType": "MOBILE_DEVICE_APP",
     "claims": {
       "targets": ["MOBILE_DEVICE_ID"]
     }
   }
   '
   

Complete App Record Setup

1. Edit the Jamf Return to Service app record

2. Scope

3. Add the following to App Configuration:

   <dict>
     <key>JPS_URL</key>
     <string>$JPS_URL</string>
     <key>JSSID</key>
     <string>$JSSID</string>
     <key>OAUTH_AUTH_CODE</key>
     <string>$OAUTH_AUTH_CODE</string>
     <key>APP_CONFIG_REINSTALL_CODE</key>
     <string>$APP_CONFIG_REINSTALL_CODE</string>
   </dict>
   

4. (iOS/iPadOS optional) Deploy Web Clip to support custom icon and display name:

   • Label: custom display name on home screen
   • URL: return-to-service://
   • Icon: upload custom icon
   • Check full screen to suppress user-prompt to open app

tvOS only: Create another app record in Jamf Pro if either of the following apply:

• Existing Jamf Return to Service app record uses distribution method of "Make available in Self Service". tvOS requires "Install Automatically/Prompt Users to Install".
• Existing Jamf Return to Service app record was created before Jamf Return to Service 2.5.0. Prior to v2.5.0, tvOS was not supported and the app record only is enabled for iOS/iPadOS support.

During the Setup Assistant flow after wipe, do not click the remote and wait for the home screen to appear. May take up to 3 minutes to complete after restart.

If the remote is not paired with Apple TV after returning to the home screen, simultaneously press the menu and volume up (+) buttons while the remote is close to the Apple TV.

Now ready to experience zero touch return to service!

Enable End-User Workflow (Legacy implementation)

API Integration

1. Create API Role

   In Settings > System > API Roles and Clients:

   • Select API Roles tab
   • Click + New button
   • Set Display name to "Return to Service"
   • Select the following privileges:
     • Read iOS Configuration Profiles
     • Send Mobile Device Remote Wipe Command
     • View MDM command information in Jamf Pro API
     • Read Mobile Devices
   • Click Save

2. Create API Client

   In Settings > System > API Roles and Clients:

   • Select API Clients tab
   • Click + New button
   • Set Display name to "Return to Service"
   • Select the API Role created in the previous step
   • Select "Enable API Client" button
   • Click Save
   • Click Generate client secret button
   • Click create secret button
   • Copy/Save client ID and client secret to be used later
   • Click Close

Network Configuration Profile

1. Create or use existing configuration profile containing Wi-Fi payload of your on-boarding network
2. Take note of the config profile ID in the URL displayed in the browser address bar (only the ID is used, not the full URL): https://yourinstance.jamfcloud.com/iOSConfigurationProfiles.html?id=18&o=r In this example, the ID is 18.

Note: The default behavior of the app is to persist the Return to Service network config profile throughout setup assistance and enrollment. The instance of the network config profile used for Return to Service will be unmanaged. Any managed network config profile will take precedent over the unmanaged config profile. The unmanaged profile can be removed using the managed app config key rts_wifi_removal_seconds listed in Appendix A.

Managed App Configuration

1. Replace the following keys in the template below:

   <dict>
     <key>JPS_URL</key>
     <string>$JPS_URL</string>
     <key>JSSID</key>
     <string>$JSSID</string>
     <key>MANAGEMENTID</key>
     <string>$MANAGEMENTID</string>
     <key>client_id</key>
     <string>ENTER_YOUR_CLIENT_ID_HERE</string>
     <key>client_secret</key>
     <string>ENTER_YOUR_CLIENT_SECRET_HERE</string>
     <key>rts_wifi_config_profile_id</key>
     <string>ENTER_YOUR_WIFI_CONFIG_PROFILE_ID_HERE</string>
   </dict>
   

   App Config Key	Value
   client_id	Client ID saved from a previous step
   client_secret	Client Secret saved from a previous step
   rts_wifi_config_profile_id	ID of config profile with Wi-Fi payload noted above

2. Save the managed app config to be used later.

App Record Configuration

1. Distribute Return to Service app to Jamf Pro using Volume Purchasing workflow.
2. Add the app to Jamf Pro app catalog if it was not created automatically and complete the following, then save:
   • General
   • Scope
   • Managed Distribution — Check Assign Content Purchased in Volume
   • App Configuration — Copy the managed app config from above
3. (iOS/iPadOS optional) Deploy Web Clip to support custom icon and display name:
   • Label: custom display name on home screen
   • URL: return-to-service://
   • Icon: upload custom icon
   • Check full screen to suppress user-prompt to open app

tvOS only: Create another app record repeating step 2 above in Jamf Pro if either of the following apply:

• Existing Jamf Return to Service app record uses distribution method of "Make available in Self Service". tvOS requires "Install Automatically/Prompt Users to Install".
• Existing Jamf Return to Service app record was created before Jamf Return to Service 2.5.0. Prior to v2.5.0, tvOS was not supported and the app record only is enabled for iOS/iPadOS support.

During the Setup Assistant flow after wipe, do not click the remote and wait for the home screen to appear. May take up to 3 minutes to complete after restart.

If the remote is not paired with Apple TV after returning to the home screen, simultaneously press the menu and volume up (+) buttons while the remote is close to the Apple TV.

Now ready to experience zero touch return to service!

Appendix A-1: Managed App Configuration (Legacy implementation)

Key/Value Pairs

Note: All values are of type string

Full Template

<dict>
  <key>JPS_URL</key>
  <string>$JPS_URL</string>
  <key>JSSID</key>
  <string>$JSSID</string>
  <key>MANAGEMENTID</key>
  <string>$MANAGEMENTID</string>
  <key>client_id</key>
  <string>ENTER_YOUR_CLIENT_ID_HERE</string>
  <key>client_secret</key>
  <string>ENTER_YOUR_CLIENT_SECRET_HERE</string>
  <key>rts_wifi_config_profile_id</key>
  <string>ENTER_YOUR_WIFI_CONFIG_PROFILE_ID_HERE</string>
  <key>rts_header_label</key>
  <string>Return to Service</string>
  <key>rts_reset_label</key>
  <string>Tap Button to Reset</string>
  <key>rts_cancel_label</key>
  <string>Tap Button to Cancel</string>
  <key>rts_access_passcode</key>
  <string></string>
  <key>rts_countdown_time</key>
  <string>5</string>
  <key>rts_wifi_removal_seconds</key>
  <string>0</string>
  <key>rts_app_preservation</key>
  <string>no</string>
</dict>

Appendix A-2: Managed App Configuration (Recommended implementation)

Key/Value Pairs

Note: All values are of type string

Full Template

<dict>
  <key>JPS_URL</key>
  <string>$JPS_URL</string>
  <key>JSSID</key>
  <string>$JSSID</string>
  <key>OAUTH_AUTH_CODE</key>
  <string>$OAUTH_AUTH_CODE</string>
  <key>APP_CONFIG_REINSTALL_CODE</key>
  <string>$APP_CONFIG_REINSTALL_CODE</string>
  <key>rts_header_label</key>
  <string>Return to Service</string>
  <key>rts_reset_label</key>
  <string>Tap Button to Reset</string>
  <key>rts_cancel_label</key>
  <string>Tap Button to Cancel</string>
  <key>rts_access_passcode</key>
  <string></string>
  <key>rts_countdown_time</key>
  <string>5</string>
</dict>

Appendix B: Enable Jamf Pro Console Workflow (Target Device)

Requirements

• End-User workflow successfully configured and tested
• Jamf Return to Service app distributed to target devices

Jamf Pro Configuration Example

1. Modify Managed App Configuration

   Add the following to the Jamf Return to Service managed app configuration if not present:

   <key>rts_auto</key>
   <string>yes</string>
   

2. Re-enrollment Setting

   In Settings > Global > Re-enrollment:

   If not checked, click Edit, select "Clear extension attribute values on computers and mobile devices", then click Save.

3. Add Extension Attribute

   In Settings > Device Management > Extension Attributes:

   • Click + New button
   • Set Display Name to "Return to Service"
   • Set Input Type to Pop-Up Menu
   • Click + Add button. Add "Start" as choice
   • Click + Add button. Add "Cancel" as choice
   • Click Save
   • Click Save

4. Add Smart Device Group

   In Mobile Devices > Smart Device Groups:

   • Click + New button
   • Select Mobile Device Group tab
   • Set Display Name to "Return to Service"
   • Select Criteria tab
   • Click + Add button and click Show Advanced Criteria button
   • Choose "Return to Service"
   • Set Operator to "is" and set value to "Start"
   • Click + Add button
   • Choose "App Name"
   • Set Operator to "has" and set value to "Return to Service"
   • Click Save

5. Create Single App Mode Configuration Profile

   In Mobile Devices > Configuration Profiles:

   • Click + New button
   • Select General
   • Set Name to "Single App Mode (Return to Service)"
   • Select "Single App Mode" from payload list and click Configure button
   • Select "Jamf Return to Service" from "Lock to App" pop-up menu
   • Select Scope tab
   • Click + Add button
   • Select "Mobile Device Groups" tab
   • Click Add button next to "Return to Service" group name
   • Click Save

Send to Mobile Device

In the target mobile device record, perform the following 3 steps:

1. Click Edit button in Inventory tab: General
2. Click Start from "Return to Service" pop-up menu
3. Click Save button

The Jamf Return to Service app will automatically launch on the target device and execute Return to Service without any user interaction.

Appendix C: Enable Jamf Pro Console Workflow (Mass Action)

Requirements

• End-User workflow successfully configured and tested
• Jamf Return to Service app distributed to target devices
• During re-enrollment, the ability to clear or set device Building or Department attribute

Jamf Pro Configuration Example

Note: The following configuration example uses a cleared extension attribute as the attribute to trigger Return to Service.

1. Modify Managed App Configuration

   Add the following to the Jamf Return to Service managed app configuration if not present:

   <key>rts_auto</key>
   <string>yes</string>
   

2. Re-enrollment Setting

   In Settings > Global > Re-enrollment:

   If not checked, click Edit, select "Clear user and location information on mobile devices and computers", then click Save.

   Note: Other options to set building or department attributes during enrollment include setting in prestage enrollment or inventory preload.

3. Add Return to Service to Attribute

   In Settings > Network > Departments:

   • Click + New button. Set Display Name to "Return to Service". Click Save
   • Click back arrow
   • Click + New button. Set Display Name to "Cancel". Click Save

4. Add Smart Device Group

   In Mobile Devices > Smart Device Groups:

   • Click + New button
   • Select Mobile Device Group tab
   • Set Display Name to "Return to Service"
   • Select Criteria tab
   • Click + Add button
   • Choose "Department"
   • Set Operator to "is" and set value to "Start"
   • Click + Add button
   • Choose "App Name"
   • Set Operator to "has" and set value to "Return to Service"
   • Click Save

5. Create Single App Mode Configuration Profile

   In Mobile Devices > Configuration Profiles:

   • Click + New button
   • Select General
   • Set Name to "Single App Mode (Return to Service)"
   • Select "Single App Mode" from payload list and click Configure button
   • Select "Jamf Return to Service" from "Lock to App" pop-up menu
   • Select Scope tab
   • Click + Add button
   • Select "Mobile Device Groups" tab
   • Click Add button next to "Return to Service" group name
   • Click Save

Mass Action to Mobile Device Group

Select the target Smart device group:

1. Click View button and click Action button
2. Click Next button ("Edit the Building and Department" is default action)
3. Choose "Return to Service" from Department pop-up menu
4. Click Next button and click Done button

The Jamf Return to Service app will automatically launch on target devices and execute Return to Service without any user interaction.

Appendix D: Enable Auto Return to Service Healthcare Listener Workflow (Auto RtS) with inventory preload

Requirements

• End-User workflow successfully configured and tested
• Jamf Return to Service app distributed to target devices
• During re-enrollment, the ability to set device extension attribute using inventory preload
• Jamf Healthcare Listener setup and configured

Jamf Pro Configuration Example

1. Modify Managed App Configuration

   Add the following to the Jamf Return to Service managed app configuration if not present:

   <key>rts_auto</key>
   <string>yes</string>
   

2. Add Extension Attribute

   In Settings > Device Management > Extension Attributes:

   • Click + New button
   • Set Display Name to "Auto Return to Service"
   • Set Description to "Extension attribute for Jamf Healthcare Listener to automatically launch Return to Service app"
   • Set Data Type to String
   • Set Inventory Display to Extension Attributes
   • Set Input type to Pop-up Menu
   • Select + Add button. Type "Ready"
   • Click Save in the Pop-up Menu choice
   • Click Save at the bottom right hand corner

3. Add Smart Device Group

   In Mobile Devices > Smart Device Groups:

   • Click + New button
   • Select Mobile Device Group tab
   • Set Display Name to "Auto Return to Service"
   • Select Criteria tab
   • Click + Add button
   • Choose "Auto Return to Service" extension attribute you previously created
   • Set Operator to "is" and leave value blank
   • Click + Add button
   • Choose "App Name"
   • Set Operator to "has" and set value to "Return to Service"
   • Click Save

4. Create Single App Mode Configuration Profile

   In Mobile Devices > Configuration Profiles:

   • Click + New button
   • Select General
   • Set Name to "Single App Mode (Return to Service)"
   • Select "Single App Mode" from payload list and click Configure button
   • Select "Jamf Return to Service" from "Lock to App" pop-up menu
   • Select Scope tab
   • Click + Add button
   • Select "Mobile Device Groups" tab
   • Click Add button next to "Auto Return to Service" group name
   • Click Save

5. Create Healthcare Listener Rule

   In Settings > Server > Infrastructure Managers:

   Note: If Healthcare Listener is already setup in your environment to wipe device, you must replace the existing rules for discharge/transfer with the following.

   • Select your Healthcare Listener. Select Edit. Click + Add button
   • Create a Display Name of your choosing (Example: A03 - Auto Return to Service)
   • Set Remote Command: Clear Extension Attribute
   • Set Mobile Device Extension Attribute: Auto Return to Service
   • Select ADT message to automatically run rule (Example: Patient Discharge: A03 / Patient Transfer: A02)
   • Click Save

   Note: If passcodes are being enforced on patient devices (not common), create another rule to issue a clear passcode remote command on ADT event.

6. Add Inventory Preload for Patient Devices

   In Settings > Global > Inventory Preload:

   If you already have inventory preload setup, modify your template to add a column named EA Auto Return To Service (must match the extension attribute created previously).

   • Set status in "Auto Return to Service" to Ready
   • Select File Upload and upload inventory preload template

Manually Test Auto Return to Service Workflow

In the target mobile device record, perform the following 3 steps:

1. Click Edit button in Inventory tab: Extension Attributes
2. Select <Blank> from "Auto Return to Service" pop-up menu
3. Click Save button

The Jamf Return to Service app will automatically launch on the target device and execute Return to Service without any user interaction.

Appendix E: Enable Auto Return to Service Healthcare Listener Workflow (Auto RtS) without inventory preload

Requirements

• End-User workflow successfully configured and tested
• Jamf Return to Service app distributed to target devices
• Do NOT clear extension attributes during re-enrollment
• Jamf Healthcare Listener setup and configured

Jamf Pro Configuration Example

1. Modify Managed App Configuration

   Add the following to the Jamf Return to Service managed app configuration if not present:

   <key>JSSID</key>
   <string>$JSSID</string>
   <key>rts_auto</key>
   <string>yes</string>
   <key>rts_hcl</key>
   <string>yes</string>
   <key>rts_hcl_ea_name</key>
   <string>Auto Return to Service</string>
   <key>rts_hcl_ea_value</key>
   <string>Ready</string>
   

2. Modify API Role

   Add the following privilege to the Return to Service API Role:

   • Update Mobile Devices

3. Add Extension Attribute

   In Settings > Device Management > Extension Attributes:

   • Click + New button
   • Set Display Name to "Auto Return to Service"
   • Set Description to "Extension attribute for Jamf Healthcare Listener to automatically launch Return to Service app"
   • Set Data Type to String
   • Set Inventory Display to Extension Attributes
   • Set Input type to Pop-up Menu
   • Select + Add button. Type "Ready"
   • Click Save in the Pop-up Menu choice
   • Click Save at the bottom right hand corner

4. Add Smart Device Group

   In Mobile Devices > Smart Device Groups:

   • Click + New button
   • Select Mobile Device Group tab
   • Set Display Name to "Auto Return to Service"
   • Select Criteria tab
   • Click + Add button
   • Choose "Auto Return to Service" extension attribute you previously created
   • Set Operator to "is" and leave value blank
   • Click + Add button
   • Choose "App Name"
   • Set Operator to "has" and set value to "Return to Service"
   • Click Save

5. Create Single App Mode Configuration Profile

   In Mobile Devices > Configuration Profiles:

   • Click + New button
   • Select General
   • Set Name to "Single App Mode (Return to Service)"
   • Select "Single App Mode" from payload list and click Configure button
   • Select "Jamf Return to Service" from "Lock to App" pop-up menu
   • Select Scope tab
   • Click + Add button
   • Select "Mobile Device Groups" tab
   • Click Add button next to "Auto Return to Service" group name
   • Click Save

6. Create Healthcare Listener Rule

   In Settings > Server > Infrastructure Managers:

   Note: If Healthcare Listener is already setup in your environment to wipe device, you must replace the existing rules for discharge/transfer with the following.

   • Select your Healthcare Listener. Select Edit. Click + Add button
   • Create a Display Name of your choosing (Example: A03 - Auto Return to Service)
   • Set Remote Command: Clear Extension Attribute
   • Set Mobile Device Extension Attribute: Auto Return to Service
   • Select ADT message to automatically run rule (Example: Patient Discharge: A03 / Patient Transfer: A02)
   • Click Save

   Note: If passcodes are being enforced on patient devices (not common), create another rule to issue a clear passcode remote command on ADT event.

Manually Test Auto Return to Service Workflow

In the target mobile device record, perform the following 3 steps:

1. Click Edit button in Inventory tab: Extension Attributes
2. Select <Blank> from "Auto Return to Service" pop-up menu
3. Click Save button

The Jamf Return to Service app will automatically launch on the target device and execute Return to Service without any user interaction.

Appendix F: Enable App Preservation (Legacy implementation)

Requirements

• iOS/iPadOS 26.0 or later
• Jamf Pro 11.20 or later

Jamf Pro Configuration Example

1. Modify Managed App Configuration

   Add the following to the Jamf Return to Service managed app configuration if not present:

   <key>rts_app_preservation</key>
   <string>yes</string>
   <key>JSSID</key>
   <string>$JSSID</string>
   

2. Modify API Role

   Add the following privilege to the Return to Service API Role if not present:

   • Read Mobile Devices

3. Enable PreStage

   • Check Allow use of the Return to Service option during device reset
   • Select Wi-Fi configuration profile
   • Check Preserve managed apps
   • Scope devices to PreStage

   Note: The app will use the Wi-Fi configuration profile defined in the managed app config and NOT the profile defined in the PreStage. The profile defined in the PreStage must only contain one Wi-Fi payload and no other payloads.

4. Initial Return to Service

   • Initiate Return to Service from the app
   • Jamf Pro will escrow the bootstrap token and prepare device for app preservation

5. Return to Service after Initial

   • Initiate Return to Service from the app
   • In-scope managed apps will be installed from snapshot on device if present instead from the network

Legal

• Use Agreement: Application End User License Agreement
• Privacy Policy: Jamf Privacy Policy