Retaining Enrolment User Information On AirWatch via the API

Standard

post_airwatch

AirWatch only keeps a record of the devices currently enrolled user, if the device is re-enrolled by/for someone else the details are overwritten.

Worse is that if your devices are not supervised, it’s trivial to unenroll a device. This then leaves a device record on AirWatch but with no user information.

To counter this, I’ve written the below API script that will add the enrolment users information to the devices notes. A new note is created with each scripts run, meaning that if a device is enrolled by another user, we’ll have a record & these notes are not deleted when a device is unenrolled.

This is detailed below.

End Result

Before we crack on with the scripts details, lets see where these notes are created & what they look like.

A devices notes can be found by searching for the device within the console, once found click “More” then “Notes”

Screenshot 2015-12-16 00.35.07

The script will add a new note with every run, & these will show like the below:

Screenshot 2015-12-16 00.35.22

Pressing the Pencil/Edit icon will take you into the note, where you can see it’s contents:

Screenshot 2015-12-16 00.35.35

Enrolment User Details

AirWatch’s REST API documentation has a few different calls to retrieve “Enrolment User Details”.

This advises that the following can be returned:

{
 "UserName": "String",
 "FirstName": "String",
 "LastName": "String",
 "Status": "Boolean",
 "Email": "String",
 "SecurityType": "String",
 "ContactNumber": "String",
 "MobileNumber":"String",
 "EmailUserName": "String",
 "Group": "String",
 "LocationGroupId": Numeric,
 "Role": "String",
 "MessageType": "String",
 "EnrolledDevicesCount": "String",
 "MessageTemplateId": Numeric,
 "Id": Numeric,
 "ExternalId":"String",
 }

For us, these are pulled in when people enroll a device from their AD account via the mappings we’ve set within: System > Enterprise Integration > Directory Services > Users > Advanced & the mappings found there.

These mappings can be shown below, most seem to one to one map with the above API response with Phone Number being Contact Number:

Sadly, not all the shown attributes are returned.

However, not mentioned within the API documentation is that one more attribute is returned:

"CustomAttribute1": "String"

These, “Custom Attributes” can be added within System > Enterprise Integration > Directory Services > Users > Advanced by toggling on “Enable Custom Attributes” & then mapping them.

Screenshot 2015-12-15 22.52.02

Above I have mapped the enrolment users manager attribute, as if someone leaves the business & the device is then unenrolled the “Enrollment Users” information might be useless as may no longer exists on AD or be usable to track a device down.

One thing to note with this is that this returns the distinguished name for the manager, & does not return the managers email address as per the attribute above.

Variables

The script is based off of the template shown in the previous post, & actually uses the same variables contained within that template.

Logging

The only change is the logging level. The script iterates makes a POST to each device under the Organisation Group supplied, this can get be extremely verbose & flood the scripts log file.

Therefore the script is set to a logging level of WARNING, with the logging methods adjusted to this level.

This will look like the below in the scripts log file:

2015-12-14 20:47:56,383 WARNING -------- Getting A List of Devices --------
2015-12-14 20:48:06,332 WARNING -------- Adding Notes to 921 Devices --------
2015-12-14 21:07:51,527 WARNONG -------- Added Notes to 921 Devices --------

Script Breakdown

As the script is based off of the template shown in the previous post, as such I’m going to skip over the already documented function sendMail.

Except to note that this script will not email on success, as it’s intended to be run daily it makes little sense to email with every run.

You will receive an email from it if something goes wrong though.

awTest = requests.get

This returns all devices under the Organisation Group passed to the locationGroupID variable.

If this GET request fails, the script exits & emails the contents of the log.

for device in deviceDetails

Next we iterate through each device within the deviceDetails list.

deviceID = str(device[‘Id’][‘Value’])

We grab the devices ID & convert to a string.

userID = str(device[‘UserId’][‘Id’][‘Value’])

Within this try block we try & get the UserID for the devices enrolment user, is this fails we exit the try block & move to the next iteration of the enclosing for loop.

This is required as non-enrolled devices will not have a UserID for us to grab.

awTest = requests.get

With this second GET we try to get the enrolment users UserName, Email, ContactNumber, Mobile Number & CustomAttribute1.

employeeNote

We next create a string with the enrollment user details we’ve grabbed.

payload = {“DeviceId”: deviceID, “Note”: employeeNote}

This is the payload for the POST command.

awTest = requests.post

This is the command to post the information we’ve grabbed for the enrolment user to the devices notes.

This is commented out in the below so you can run the script & make any changes to the script before running it live.

logging.warning(payload)

This will write the details we’re to post to the scripts log. Comment this out when running live.

The Script

The script can be found below.

As mentioned above this has a line commented out & another added to allow for testing without committing anything to your AirWatch instance.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.