Using Workspace ONE Intelligence to Automate a Return-to-Service Command on iOS Devices

Introduction

A few months ago, we wrote about the new Return-to-Service command that was introduced with iOS 17. This new functionality provided IT admins the ability to remotely wipe an iOS device and automatically have it activated and re-enrolled in MDM. In that previous blog post, we discussed how to send the new Return-to-Service command to a device as a Workspace ONE UEM Custom Command. You can read that initial blog post on Tech Zone.

In this new post, we’re going to build upon the information from the first and show you how to use Workspace ONE Intelligence to automate the process of issuing the Return-to-Service command to turn a one-off command into an easy helpdesk process, or better yet allow a third-party system, like ServiceNow or Epic, make the API call to wipe and return the device to service.

Our Example Use Case

As we mentioned in part one, the Return-to-Service API functionality can reduce IT admin time wasted on the cumbersome manual process of copying XML into the UEM console to initiate the Return-to-Service command any time a device needs to be wiped, activated, and re-enrolled for the next user. This isn’t an enterprise-ready process, it’s a lab experiment.

For this post, we are using an example from the healthcare industry, but this basic process will work for others as well. The current process works like this. Our patient-facing iPad with the Epic MyChart application installed provides the patient with health information, communication, billing details, and more. When a patient is transferred to a new room or discharged, the iPad needs to be wiped before the next patient can use it. There is a current integration in which Epic will call a Workspace ONE UEM API, which wipes the device. However, a nurse or other employee at the hospital must then touch the device to join it to Wi-Fi, select a language, and do other steps before it goes through automatic enrollment via DEP. As you can see, this is a time-consuming process for a category of employees who have *much* more important work to do (such as saving lives).

The general concept for automating this process requires leveraging tags in Workspace ONE UEM, which will trigger a workflow in Intelligence to issue the Return-to-Service command. This simple diagram shows the expected flow for this example.

NOTE: In this example, we are using an API call from Epic MyChart to assign the tag to the iOS device. However, this same process can be done with any third-party application or service capable of issuing the API command to Workspace ONE UEM.

Automating with Intelligence, Custom Connectors, and Workflows

To automate the process discussed above, we need to do the following:

• Create a Tag in Workspace ONE UEM called ReturnToService.
• Create a Custom Connector in Workspace ONE Intelligence to UEM and add a custom MDM command payload.
• Create a workflow in Intelligence called Return-to-Service Wipe.

First, create a Tag in Workspace ONE UEM called ReturnToService. This tag will be assigned to an iOS device by Epic when a patient is discharged or transferred to another room. Epic will use the REST API to issue the command to make the tag assignment.

Next, create a Custom Connector in Omnissa Intelligence that is configured with the REST API details for your Workspace ONE UEM console. You can use either Basic Authentication or OAuth for managing the credentials required by the REST API. If you are unfamiliar with how to configure a Custom Connector, see Using Custom Connectors in Intelligence Automations on Tech Zone.

After you’ve configured your Custom Connector, you need to add an Action by importing a JSON file into the connector. A sample of the required JSON file can be found on GitHub. You can import the sample file into an app like Postman to modify the details to match your current configuration. Some items that will need to be edited include your UEM instance URL and the base64-encoded profile string for your Wi-Fi profile. Keep in mind that the base64-encoded profile string is in multiple locations. Make sure you change it everywhere. For instructions for creating the base64-encoded profile string, look under the “Wi-Fi Profile” section of the first Return-to-Service post on Tech Zone.

Finally, create a workflow in Workspace ONE Intelligence that will call the Return-to-Service action you created earlier. The data source for the workflow will be Workspace ONE UEM -> Devices Data. Set the trigger to Automatic and create a filter that checks Device Tags for ReturnToService.

Next, add the first of two actions to the workflow. This first action will trigger the Custom Connector you created earlier and execute the action defined in the JSON file you imported. Make sure that you set the Query_Parameter for id to ${airwatch.device.device_udid}. This will ensure that the Return-to-Service command is sent to the correct device.

Then, add the second action to the workflow, which will remove the ReturnToService tag from the device. You must select the Organization Group in which the tag resides and select the tag name.

After the workflow is enabled, Workspace ONE Intelligence will trigger the workflow process when it identifies a device with the ReturnToService tag. The command will be sent to the device, initiating a device wipe, activation, and re-enrollment.

Tagging Devices with the Workspace ONE UEM API

You can assign the ReturnToService tag to an iOS device through the Workspace ONE UEM console, but this can quickly become cumbersome if you manage a large number of shared iOS devices. As we mentioned in our example use case, we want to utilize a third-party application (in this case, Epic) to automatically assign the tag. You can easily do this with almost any application that can make API calls to Workspace ONE UEM.

The API command to assign a tag in Workspace ONE UEM is:

POST https://[uem_api_url]/api/mdm/devices/[device_uuid]/tags/[tag_uuid]

In this command, there are three variables that you will need to set for your specific environment. They are highlighted in bold above.

• uem_api_url – This is the API URL for your Workspace ONE UEM instance. You can find this in the UEM console by navigating to Groups & Settings -> All Settings -> System -> Advanced -> API -> REST API.
• device_uuid – This is the device unique identifier (Device UUID) in Workspace ONE UEM. This value needs to be dynamically set for each device.
• tag_uuid – This is the unique identifier (Tag UUID) for the ReturnToService tag you created in Workspace ONE UEM. This value will remain static.

To get the device UUID, you can configure your third-party application to run the following API call to your Workspace ONE instance. In the Epic example use case, we pass the device UUID into the MyChart mobile app itself using managed app configuration, and the MyChart mobile app tells the backend the value. Thus, the process is automated.

GET https://[uem_api_url]/api/mdm/devices?searchBy=serialNumber&id=[serialnumber]

This returns a body of all the device information. Device UUID is the uuid which is usually the last item returned. As with the earlier API call, you will need to add your unique Workspace ONE UEM API URL, as well as the serial number of the device for which you are searching.

To get the tag UUID, assign the tag to a device in Workspace ONE UEM and execute the following API call, ensuring that you replace [device_uuid] with the Device UUID for the device.

GET https://[uem_api_url]/api/mdm/devices/[device_uuid]/tags

This will return a JSON with the assigned tags for the device and UUID for each tag. As mentioned, the tag UUID is a static value and only needs to be obtained once.

Now that you have the tag UUID, you can configure your third-party application (in our example, Epic) to issue the API call to get the specific device UUID, and then follow that with the call to assign the tag using the dynamic device UUID and the static tag UUID. From there, the workflow created earlier will be triggered and the Return-To-Service process will execute.

Putting It All Together

Now that we have all the pieces, let’s return to our example use case and our diagram.

Here is how all the pieces fit together.

1. A patient is discharged or transferred to another room. The Epic MyChart application triggers an API command that assigns the ReturnToService tag to the iPad that was assigned to that patient.
2. The Workspace ONE Intelligence workflow filters for devices that have the ReturnToService tag. When the iPad is tagged in the previous step, the workflow triggers two actions.
3. The first action uses the Custom Connector to send the Return-To-Service command to the device. The command includes a base64 encoded Wi-Fi payload to ensure that the device rejoins Wi-Fi after the wipe.
4. On the iPad, the Return-to-Service command wipes the device and adds the Wi-Fi payload., activates, and re-enrolls into Workspace ONE UEM.
5. The workflow removes the ReturnToService tag from the device in Workspace ONE UEM.
6. The device is ready for use by the next patient.

One Caveat

There is one thing that you need to keep in mind when performing a Return-to-Service wipe. If the device is Wi-Fi only, as many Frontline use cases are, the time zone will default to Pacific Standard Time (PST). Luckily, there is another Custom Command which allows you to set the time zone post enrollment. You simply need to add this as an additional action in your Custom Connector. You can download a sample JSON file for setting the time zone from here.

We recommend you schedule this additional action as a Freestyle Workflow to run on a specific cycle rather than an automatic trigger and filter on attributes, such as device time zone, device assignment group, and others to ensure that you are not triggering the workflow on devices unnecessarily.

Summary

The Return-to-Service command is yet another tool available to IT admins for managing their corporate-owned iOS devices. The command helps ensure that a device is wiped, enrolled, and ready for the next user without the need for IT to physically access the device. This can be extremely helpful for dedicated devices that are transferred between employees, or devices shared among shift workers.

Using Workspace ONE Intelligence workflows in conjunction with the Return-to-Service command is an excellent way to automate the process of preparing a shared iOS device after each use. Utilizing the Workspace ONE UEM API allows seamless integration with third-party applications like Epic and increases overall efficiency. Although we focused on a healthcare use case for this blog post, I’m sure you can see how useful this can be across other industries that utilize shared iOS devices with frontline use cases.

For more information on managing iOS devices with Workspace ONE UEM, check out the following resources on Tech Zone.