Skip to main content

Return to Service feature for iOS/iPadOS

What

Even though devices can be erased remotely, getting them back into service is a manual process, as it requires someone to physically touch them and take them through Setup Assistant. Return to Service for iOS and iPadOS can automate these setup steps when the device can connect to the configured network and complete enrollment.  This feature was added in FileWave version 15.1.0 for iOS 17.0 and iPadOS 17.0. As for FileWave version 15.5.0 this was also added for tvOS.

When/Why

Return To Service is the following process. The MDM server sends an EraseDevice command to the device. The command includes information for the device to reset, securely erase all data, connect to Wi-Fi, and enroll into MDM. Successful enrollment and setup return the device to the Home Screen; sending the command alone does not confirm that it is ready to use.

How

Return to Service erases the device's data. Before confirming a wipe, verify the selected device, any required backup, the Wi-Fi profile, and the enrollment configuration. An enrollment retry does not undo the erase or guarantee that the device returns to service.

If your ADE enrollment uses a custom identity-provider sign-in flow, confirm the Return to Service procedure with FileWave Support before erasing the device. Do not assume enrollment retry resolves an authentication requirement.

In FileWave Central, open the Remote Wipe dialog for the intended iOS or iPadOS device to configure Return to Service. Checkbox Return To Service allows to specify whether feature should be enabled or disabled. It can be checked only if Remove Activation Lock checkbox is checked as well. The feature can be used only if there is at least one configured Wi-Fi profile (fileset containing Network payload with Network Interface “Wi-Fi“). Available Wi-Fi profiles are displayed on combobox.

image.png

FileWave 17.0: enrollment retry and locale

The following additions apply to iPhone and iPad devices running iOS 27 or iPadOS 27 and later. They do not extend these options to tvOS or earlier iOS/iPadOS versions.

  1. Review enrollment retry in the Return to Service dialog. When enabled, the device retries enrollment if its initial attempt fails, with increasing delays between attempts. This can help with a temporary network or management-service failure; it is not a recovery-time guarantee.
  2. Prepare the locale in the ADE profile, not in the wipe command. For an ADE-enrolled iPhone or iPad, configure the desired language and region in the applicable ADE profile before the reset. The language value uses an ISO 639-1 two-letter code, and region uses an ISO 3166-1 two-letter code. If no new locale is specified, the previously selected choice is used. See ADE Profiles for the enrollment-profile workflow.

The earlier dialog illustration above shows the original Return to Service controls; it does not show the FileWave 17.0 retry addition.

What happens on the device?

After the device receives the erase command with Return to Service enabled, it erases its data and uses the selected Wi-Fi profile to connect and attempt MDM enrollment. Enrollment can fail, for example because of network or management-service errors, leaving the device erased but unenrolled. Verify that enrollment completes, the device is managed again, and it reaches the expected setup state before returning it to the user. For ADE Return to Service, also check that it remains associated with its existing FileWave client entry rather than appearing as a new client. This record-continuity check does not mean MDM enrollment is skipped. If enrollment does not complete, investigate the network and enrollment configuration rather than treating an accepted wipe command as success.

Troubleshooting

We have found that on the WiFi profile, setting Security to 'With Authorization' - even with the right password, will break Return to Service. What you will see is that the iPad will not be able to join the WiFi automatically when it boots up though you can manually join the WiFi. 

image.png

Digging Deeper

When Remote Wipe dialog is opened the list of configured Wi-Fi profiles is loaded in format:

[(<file_id>, <fileset_id>, <fileset_name>, <payload_display_name>, <payload_identifier>),(...)]

fileset_id and fileset_name are displayed on the UI, payload_display_name and payload_identifier are used for tool tip. file_id is used as internal data for combobox.

When Wipe Device button is pressed, on the backend side is generated MDM command EraseDevice with dictionary field ReturnToService and fields Enabled and WiFiProfileData according to values specified on the UI, then command is added to command queue.

When command is grabbed from command queue and is being composed for sending to the device MDMProfileData is added to ReturnToService dictionary. This data matches the final payload that is provided by MDM server when /ios/profile URL is used for OTA enrollment. MDMProfileData is not added for DEP devices.

API Command

Sending the command to wipe via an API command requires the following data format.

'{
    "ids": [<integer>, <integer>],
    "command": "EraseDevice",
    "options": {
        "DisallowProximitySetup": false,
        "PIN": "",
        "PreserveDataPlan": false,
        "ReturnToService": {
            "Enabled": true,
            "WiFiProfileID": <integer>
        }
    }
}'
  • 'ids' is a comma separated list of the Device IDs to be targeted
  • 'WiFiProfileID' is the File ID (this is not the Fileset ID)

To obtain the WiFiProfileID, will require an additional query first.  A full list of all Wi-Fi Profiles can be returned with the following API:

Set server_dns and auth securely in your shell before using these examples. Use a server certificate trusted by the calling system, and resolve certificate errors rather than disabling TLS verification. Confirm the API contract and required permissions for your server version before sending a device command.

curl -X GET "https://${server_dns}/filewave/api/apple/profiles/wifi" -H  "Content-Type: application/json" -H "authorization: ${auth}" | awk '{ gsub("\\]\\,\\[","\n"); gsub("\\]\\]",""); gsub("\\[\\[","");  print }'

Where:

  • ${server_dns} is the server name as seen in FileWave Central -> Preferences -> Mobile
  • ${auth} is a shell variable containing your application token from FileWave Central -> Manage Administrators (each user has one or more tokens). Both examples pass this value in the authorization header. Keep the token private; do not share it in scripts, logs, or support examples

The returned list might look something like:

750959,669526,"Profile - HOME WIFI","HOME WIFI","ml1063.lan.4bf6fba8-9cfc-48b5-ad74-a251a65c8759.Configuration.4bf6fba8-9cfc-48b5-ad74-a251a65c8759"
780638,736322,"Profile - WLTC wifi","WLTC wifi","ml1063.local.7a00d6eb-9b4b-4e7e-b68b-7ee7e6414051.Configuration.7a00d6eb-9b4b-4e7e-b68b-7ee7e6414051"
504184,411265,"Profile - Wi-Fi BT 2.4GHz","Wi-Fi BT 2.4GHz","FW1063.local.e285dc3b-9c4b-4a7a-84a9-a3cd5169f92d.Configuration.e285dc3b-9c4b-4a7a-84a9-a3cd5169f92d"
504185,24571,"Profile - Wi-Fi BT 5GHZ","Wi-Fi BT 5GHZ","ML1063.local.02d6d9c3-5a7d-490c-afa8-f160ba9b4e40.Configuration.02d6d9c3-5a7d-490c-afa8-f160ba9b4e40"

The first number is the File ID, whilst the second is the Fileset ID.

Example

Illustrative values for 3 devices to be wiped using 'Return to Service' are shown below. The Device IDs and Wi-Fi File ID are examples, not targets to copy into your environment. Verify and replace every ID before any authorized use:

Server FQDN from Preferences filewave.example.invalid (non-live example; use your server name in ${server_dns})
Authorisation Token

${auth} (your private application-token variable; no token is supplied here)

"Profile - WLTC wifi" [File ID of Fileset: 'Profile - WLTC wifi']

780638

iPad001 [FileWave Device ID]

3425

iPad002 [FileWave Device ID]

4342

iPad003 [FileWave Device ID]

3312

The API data block might look like:

'{
    "ids": [3425, 4342, 3312],
    "command": "EraseDevice",
    "options": {
        "DisallowProximitySetup": false,
        "PIN": "",
        "PreserveDataPlan": false,
        "ReturnToService": {
            "Enabled": true,
            "WiFiProfileID": 780638
        }
    }
}'

and the command:

The following POST requests an erase and permanently removes device data. Before sending it, verify the intended devices, required backups, Wi-Fi File ID, and enrollment configuration; replace all illustrative IDs. An accepted command is not proof of completed enrollment or a usable device.

curl -X POST "https://${server_dns}/api/devices/v1/devices/mdm-command" -H  "Content-Type: application/json" -H "authorization: ${auth}" -d  '{
    "ids": [3425, 4342, 3312],
    "command": "EraseDevice",
    "options": {
        "DisallowProximitySetup": false,
        "PIN": "",
        "PreserveDataPlan": false,
        "ReturnToService": {
            "Enabled": true,
            "WiFiProfileID": 780638
        }
    }
}'