Ask AirWatch

All, this is an exciting post. It has been a while since I've posted anything and I have yet to post any interesting End User Computing pieces.  Hoping to pick that up the last few months of the year. No more delays, proud to announce:

Ask AirWatch .. a skill for Amazon Alexa


This is a pretty lengthy post but I will put the good stuff up top and the meat and potatoes at the bottom.  The short story is as an avid Alexa user at home with most of my home automated (wanna be Tony Stark) I wondered if anyone uses this with Enterprise.  Shortly after I saw a few posts by Cody De Arkland (thehumblelab.com) and William Lam (virtuallyghetto.com) I decided to do something about it.  I quickly partnered with a friend and colleague, Lucas Herrera, who I have created other API based scripts and apps with.  Here is what we came up with, I hope you enjoy our video:


First Lucas and I have to show some respect for the Live TV and Youtube Bloggers out there. Sounding good on camera is tough... and a skill we will obviously need to work at.

Wait, how did that just work?

Well its actually pretty simple, hats off to Amazon for a great framework for Alexa skills.  We created an Alexa Skill called Ask AirWatch. Inside of the skill, you define what you want your users to say and what input to save. Then link it to AWS Lambda for some Node.js serverless compute power to run the actual skill. That is right, no servers needed. Inside of Lambda there is around 750 lines of code in various functions. Mostly though we send a REST API call to the AirWatch API server specified in your Lambda environment, process the result, and write the string for Alexa to speak back. 

We have all of the code and Amazon side instructions on Github:


Meat and Potatoes

As of this writing, 8/22/2017, the Ask AirWatch Skill supports about 70 unique phrases. Many do the same thing but are different permutations. I have included an index of all commands at the very bottom of the post. Highlights are:
  • The number of 'xyz' devices in the environment
    • Where 'xyz must be: total, employee owned, employee, corporate dedicated, corporate shared, byo, byod, compromised, no passcode, enrolled, valid, unenrolled, registered, undefined, not encrypted, android, iOS, apple, apple iOS, windows pc, mac os, mac, apple tv, windows mobile, windows phone 8, windows phone rt, windows phone, blackberry 10, chromebook
  • A device summary 
  • Details of internal app 'xyz' including how many, their version, and assigned to and installed on counts.
  • Details of public app 'xyz' including how many, their version, and assigned to and installed on counts.
  • Details of Purchased app 'xyz' including how many, their version, if they are eligible for managed deployment, and assigned to and installed on counts.
  • The version of AirWatch running
  • The health of AirWatch API, Device Services, and Secure Email Gateway
  • How many devices have checked in the past X days
We will say we have observed many times where Alexa has a tough time with app names. Especially when the appliance has a uncommon name. Sometimes even with common names you find that the Alexa does not work.  We may be stretching some of its capabilities. We have debugged some of them and find that Alexa skill sends Lambda the wrong word, or tries to run the wrong function, or Lambda sends the response but Alexa doesn't say it. So some commands in some environments is a 'your mileage may vary' type of situation.

One of the biggest disappointments with writing this skill has been we cannot publish this on the official Alexa Skill App Store. This is because Lucas and I needed a way to ensure Joe's Ask AirWatch skill was pointed to Joe's AirWatch environment.  Amazon does provide a way of sorts to link a user to a destination resource. They call this 'account linking' and it leverages OAuth2.  Well unfortunately, AirWatch does not support Oauth2 for authorization.  AirWatch uses traditional REST API with headers which include Authorization in the form of basic username/password or certificate. Additionally since AirWatch is mulit-tenant we must include the customer Organization Group API Key.  This along with Authorization determines the scope of the API command.  So back to why we could not release this as one simple skill. There was no way, short of writing middleware which stored folks Admin Username, Password and API Key to release a single skill to everyone.  That is the reason you must spend about 30 minutes to setup an Amazon Developer and AWS account.  

We also can envision another 100 phrases and actions this skill could enable. From asking how many devices Joe Rainone has to when the last time the device id 123455 has checked in last.  We are passionate about the community and this project and will try iterate as much as the community requests. 

One of the coolest finds of this project has been discovering you can call Alexa from your phone!  On iOS and Android you can download the 'Amazon Shopping' app. From there there is a little microphone button that you can press and 'Ask AirWatch is the SEG server healthy'


Parting thoughts before mindless documentation.  This has been extremely fun and challenging. Lucas and I are big proponents of the AirWatch API. There is a handy 1,000 page document on resources.airwatch.com which goes over in unbelievable detail all of the API calls, example calls and expected results. In our spare time we have coded an app which automated updating an Internal App on Supervised Single App Mode iPads, fed in AirWatch device data into ServiceNow CMDB, and scripted creating complex Organization Group Structures in AirWatch.  Your imagination to solve problems is the only limiting factor (and sometimes documentation).  Some may ask why not a Workspace ONE Alexa App. Good question, we are just waiting on some APIs to be made public....

As mentioned above the code and Amazon side instructions are linked here on Github.  I have added some sections to the blog to help fill gaps. 

Requirements

  • AirWatch environment
    • AirWatch API URL
    • AirWatch API Key
    • AirWatch Admin Username and Password
    • AirWatch Device Services URL (optional)
    • AirWatch Secure Email Gateway URL (optional)
  • Amazon Developer Account (free)
  • Amazon Web Services, AWS
    • Lambda service
      • Mostly free and details here
      • I haven't paid at all for compute while developing and testing this skill. Something like 1 million requests per month are free based on ram and compute time. 
      • I do have a 1 penny bill racked up from data transfer. I assume that is for making API calls. Amazon does say 'data in and out' which an API call is.
  • Amazon Echo or Amazon Shopping App
    • Echo
      • Static, always on, always listening device 
      • $50+
      • I have two Echo Dots which I use for yelling at my house to turn off the lights. They are great, and small, and however don't play music well (I have a Sonos for that).
    • Amazon Shopping App
      • The Amazon Shopping App, associated with your developer account, which is associated with your greater Amazon account. The app recently started including Alexa support. I imagine they thought it was handy to say 'order more dog food' rather than search.  We can leverage that to be our 'Jarvis'.
  • A small to medium size amount of patience. 
    • Not kidding.

Gather the AirWatch Requirements

We recommend first setting this up in your UAT environment. However it is pretty harmless, just a bunch of GET commands currently. We have not designed any action commands yet. 

AirWatch API URL
  1. Log into the Admin Console at the Customer OG
  2. Navigate to Groups & Settings -> All Settings
  3. After Settings pop up, Navigate to System -> Advanced -> Site URLs
  4. Look for the REST API URL and copy just the https://sub.domain.com
    1. Do not copy the /API piece
AirWatch API Key
  1. Log into the Admin Console at the Customer OG
  2. Navigate to Groups & Settings -> All Settings
  3. After Settings pop up, Navigate to System -> Advanced -> API -> REST API
  4. Look for the API Key which corresponds with an Admin Service.
AirWatch Admin Username and Password
  1. Create or use an existing AirWatch Admin Username that has at least read only rights to all OGs. 
AirWatch Device Services URL (optional)
       Used just for Health Check Purposes
  1. Log into the Admin Console at the Customer OG
  2. Navigate to Groups & Settings -> All Settings
  3. After Settings pop up, Navigate to System -> Advanced -> Site URLs
  4. Look for the Device Services URL and copy just the https://sub.domain.com
    1. Do not copy anything after the .com (or .net, .org)

AirWatch Secure Email Gateway URL (optional)
       Used just for Health Check Purposes
  1. Log into the Admin Console at the Customer OG
  2. Navigate to Groups & Settings -> All Settings
  3. After Settings pop up, Navigate to Email -> Configuration
  4. Look for the Secure Email Gateway URL and copy just the https://sub.domain.com
    1. Do not copy anything after the .com (or .net, .org)

Appendix 'Supported Phrases'


PhraseInputOutput
Ask AirWatch what is my device summary
n/a
A high level overview of device counts in your environment.
Ask AirWatch what's my device summary
Ask AirWatch device summary
Ask AirWatch environment summary
Ask AirWatch what is my environment summary
Ask AirWatch what's my environment summary
Ask AirWatch tell me about my environment
Ask AirWatch How many {DeploymentDetail} devices I have
total | employee owned | employee | corporate dedicated | corporate shared | byo | byod | compromised | no passcode | enrolled | valid | unenrolled | registered | undefined | not encrypted | android | iOS | apple | apple iOS | windows pc | mac os | mac | apple tv | windows mobile | windows phone 8 | windows phone rt | windows phone | blackberry 10 | chromebook
Detailed count of the {input} type of devices
Ask AirWatch Tell me the number of {DeploymentDetail} devices I have
Ask AirWatch Tell me how many {DeploymentDetail} devices I have
Ask AirWatch Give me the number of {DeploymentDetail} devices I have
Ask AirWatch Give me how many {DeploymentDetail} devices I have
Ask AirWatch count how many {DeploymentDetail} devices I have
Ask AirWatch What is the number of {DeploymentDetail} devices in the environment
Ask AirWatch What's the number of {DeploymentDetail} devices in the environment
Ask AirWatch what is the total number of {DeploymentDetail} devices
Ask AirWatch what's the total number of {DeploymentDetail} devices
Ask AirWatch What is the status of the internal application {InternalAppDetail}
Internal App Name
Number of apps with that name, their version, and how many devices they are assigned to and current installed on.
Ask AirWatch What is the status of the internal app {InternalAppDetail}
Ask AirWatch What's the status of the internal application {InternalAppDetail}
Ask AirWatch What's the status of the internal app {InternalAppDetail}
Ask AirWatch How is the deployment of the internal application {InternalAppDetail}
Ask AirWatch How is the deployment of the internal app {InternalAppDetail}
Ask AirWatch Tell me about the internal application {InternalAppDetail}
Ask AirWatch Tell me about the internal app {InternalAppDetail}
Ask AirWatch What is the status of the public application {PublicAppDetail}
Public App Name
Number of apps with that name, their version, and how many devices they are assigned to and current installed on.
Ask AirWatch What is the status of the public app {PublicAppDetail}
Ask AirWatch What's the status of the public application {PublicAppDetail}
Ask AirWatch What's the status of the public app {PublicAppDetail}
Ask AirWatch How is the deployment of the public application {PublicAppDetail}
Ask AirWatch How is the deployment of the public app {PublicAppDetail}
Ask AirWatch Tell me about the public application {PublicAppDetail}
Ask AirWatch Tell me about the public app {PublicAppDetail}
Ask AirWatch What is the status of the purchased application {VPPAppDetail}
Purchased(VPP) App Name
Number of apps with that name, their version, and how many devices they are assigned to and current installed on.
Ask AirWatch What is the status of the purchased app {VPPAppDetail}
Ask AirWatch What's the status of the purchased application {VPPAppDetail}
Ask AirWatch What's the status of the purchased app {VPPAppDetail}
Ask AirWatch How is the deployment of the purchased application {VPPAppDetail}
Ask AirWatch How is the deployment of the purchased app {VPPAppDetail}
Ask AirWatch Tell me about the purchased application {VPPAppDetail}
Ask AirWatch Tell me about the purchased app {VPPAppDetail}
Ask AirWatch what version am I
n/a
The current running version of AirWatch
Ask AirWatch what version are you running
Ask AirWatch what version am I running
Ask AirWatch what version is AirWatch
Ask AirWatch what version are you
Ask AirWatch how many devices have checked in the past {Days} day
Any number greater than 0
Number of devices checked in the past {input} days
Ask AirWatch how many devices have checked in the past {Days} days
Ask AirWatch how many devices have checked in the last {Days} day
Ask AirWatch how many devices have checked in the last {Days} days
Ask AirWatch how many devices have been seen in the past {Days} day
Ask AirWatch how many devices have been seen in the past {Days} days
Ask AirWatch how many devices have been seen in the last {Days} day
Ask AirWatch how many devices have been seen in the last {Days} days
Ask AirWatch is the Device Services server up
n/a
Health of DS endpoint with http code
Ask AirWatch is the DS server up
Ask AirWatch is the DS healthy
Ask AirWatch is the Device Services server healthy
Ask AirWatch is the Device Services healthy
Ask AirWatch is the Device Services up
Ask AirWatch is the API up
n/a
Health of API endpoint with http code
Ask AirWatch is the API server up
Ask AirWatch is the API healthy
Ask AirWatch is the API server healthy
Ask AirWatch is the Secure Email Gateway server up
n/a
Health of SEG endpoint with http code
Ask AirWatch is the SEG server up
Ask AirWatch is the SEG healthy
Ask AirWatch is the Secure Email Gateway server healthy
Ask AirWatch is the Secure Email Gateway healthy
Ask AirWatch is the Secure Email Gateway up

Comments

Post a Comment