Assign Staged Device to User using AirWatch API

Created: Modified: Knowledge Base

If you are using an AirWatch MDM with API integration, you may instruct GroundControl to assign staged devices to individual users. End-User passwords are not needed for this action, only usernames.


Say you have 1,000 iPhones to assign to 1,000 employees. You have several options to proceed:

  1. You may leave the devices untouched, and let End-Users activate devices with Apple’s Device Enrollment Program. This is “Zero-Touch” for IT but not for the end user, who must perform a device setup, albeit an abbreviated one.
  2. You may pre-stage devices with GroundControl, leaving them partially setup to an AirWatch staging user, then have the End-User complete setup using the AirWatch agent. This allows for a more consistent experience, but still not zero touch for the end user.
  3. You may use GroundControl and DEP to fully stage and assign devices to users, using this action. This is true “zero touch” for both IT and the End-User. Each End-User receives a fully personalized device with no setup work.

Option 3 is a unique feature of GroundControl, never before available to the public.


There are several prerequisites that must be met to assign devices to individuals in this way.

  • All devices must be enrolled in DEP.
  • You must have set up GroundControl with API access to your AirWatch server. This option is not currently available with any other MDM.
  • You must create a user within AirWatch set up for multi-user staging.
  • In AirWatch you must have a DEP profile that either:
    • Has authentication OFF but assigns devices to the staging user above, or
    • Has authentication ON, and you enroll as the staging user (with password) in a GroundControl workflow. 
  • You must have a way to assign each device to a user, using attributes. More information on that below. For the instructions, we assume you have created a custom attribute named “User”. If you are using Check In/Out, the attribute is called “Device User”.
Creating the Workflow

In GroundControl, create up a new workflow with the “Manage with DEP” option. If your AirWatch DEP profile requires authentication, click on “Activate using DEP” and enter the staging user username and password.

depstageAdd the action “Perform MDM Command” to the workflow. Check the option to “Assign Staged Devices to User.” Use the “Attribute” menu to enter the “[User]” variable you set up earlier.

awstageuserOptionally select the option to “Assign DEP profile”. This option will assign the correct DEP profile in AirWatch to the device. You may also wish to use this dialog to assign the device to an AirWatch organization group, or to any tags. When finished, save this dialog.

We recommend you use the “Set Wallpaper” action, and use the same “[User]” variable as text on the Lock Screen. This will make it easy to identify each device. (Note that any wallpaper pushed by AirWatch will override the wallpaper set by GroundControl, and you won’t see the username.)

screen-shot-2018-01-11-at-2-26-34-pmAdd any other helpful actions to the workflow. Some options are:

  • Erase: guarantee that all provisioned devices have the same starting point.
  • Add WiFi: WiFi is usually required for DEP enrollments.
  • Set Name: use the same “User” attribute to set a unique device name.
Error Messages

If a device is not assigned to a multi-user staging user, during authentication or perform MDM command it can not be assigned to another user. You will see the error: “Staged Device assignment failed: Device cannot be checked out. Device is not enrolled to a multi staging user.”

If you try to assign it to a user that does not exist, you will see the error: “Could not find the username <‘nobody’> in AirWatch.”

Options to Assign Users to Devices

There are many options on how to assign devices to users, including leveraging pre-deployment webhooks or GroundControl’s APIs. Here are two of the easiest.

Assignment Option 1: Assign each user at provisioning.

In Admin > Attributes, create a new Launchpad attribute called “User”. This attribute will appear on each Launchpad if the disclosure triangle is opened. Before each device is attached, the operator will enter the username of one End-User, and then attach one device.

screen-shot-2018-01-11-at-2-27-09-pmAs soon as the deployment begins, the operator may replace the username with the next user’s username, and then attach a second device. Multiple operators may work multiple Launchpads simultaneously without interference, and multiple devices may be in progress on one Launchpad as long as they were each started separately.

Assignment Option 2: Upload a spreadsheet with assignments.

In Admin > Attributes create a new device attribute named “User”. Then prepare a 2-column CSV file with column headings “Device Serial” and “User”. For each device serial, assign a username.

Upload this spreadsheet using the “Import” button on the Devices tab. This will create your devices as “pending” (not yet using a license) and ready for deployment. If you wish to change any association, you may click on the device in the Devices tab to change the username. Multiple devices may be provisioned simultaneously by as many operators and Launchpads as you want.