Assign Staged Device to User using the AirWatch API

Created: Modified: Knowledge Base

When using the VMware Workspace ONE (AirWatch) MDM with API integration, you may instruct GroundControl to assign staged devices to individual users. 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 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.
  • Set up GroundControl with API access to your AirWatch server.
  • Create a user within AirWatch configured 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, Imprivata assumes you have created a custom attribute named User. If you are using Check In/Out, the attribute is called Device User.
Create the Workflow
    1. In GroundControl, create a new Workflow with the “Manage with DEP” option. If your AirWatch DEP profile requires authentication, click Activate using DEP and enter the staging user username and password.depstage
    2. Add the action “Perform MDM Command” to the Workflow. Select the Assign Staged Devices to User. This option is not available for Android devices in GroundControl 6.0.
    3. Select the [User] variable you set up earlier from the Attributes drop-down list.awstageuser
    4. Optionally select the option to Assign DEP profile. This option assigns 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.
    5. Click Save.

NOTE: Any wallpaper pushed by AirWatch overrides 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: Wi-Fi 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
  1. In Admin > Attributes, create a new Launchpad attribute called “User”. This attribute will appear on each Launchpad when the expanding arrow is clicked.
  2. Before each device is attached, the operator will enter the username of one end user, and then attach one device.
  3. As 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.

    1. In Admin > Attributes, create a new device attribute named “User”.
    2. Prepare a 2-column CSV file with column headings “Device Serial” and “User”. For each device serial, assign a username.
    3. Upload this spreadsheet using the Import button on the Devices tab. This creates your devices as “pending” (not yet using a license) and ready for deployment.
    4. To change any association, 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.