WS1 + ServiceNow Part 2
Introduction
Over the last few weeks I have been spending a bunch of time understanding how Workspace One and Service Now can work together to make our customers lives easier. This is the second part in my VMware Workspace ONE and Service Now blog series, in part 1, we worked out how to use the Workspace ONE Intelligence tool to automatically feed device records into Service now, and map data elements to their correct fields in Service Now.
In part 2, we are going to work out how to feed data the other direction - from Service Now back into Workspace ONE UEM. The use case we are going to consider is devices going though a break / fix cycle and help desk or admins managing that in the Service Now console. While the device moves though the break / fix cycle, we will apply a tag in the UEM console to ensure the status of the device is reflected properly in both tools, and to ensure apps, policy configurations, compliance rules, etc.. are in an appropriate configuration on the device.
Requirements and prep work
For the work today, we will need a ServiceNow instance, and an Workspace ONE UEM instance.
Based on Part 1 of this series - we were able to sync device records and meta data from UEM to Service Now. There is 1 attribute that we didn't mention syncing in the last series, but we will be using in this series. That is Device ID. We will need that attribute to match the 2 systems together easily.
The next step is to launch the Workspace ONE API Explorer
This URL will depend on your specific Workspace ONE Implementation, in general for Hosted SaaS models, the API server follows the naming convention of your Admin Console Server. In an On premise deployment, the API service is installed by default on both the Admin console and Device Services endpoints. Whats important in the on premise model is that the Service Now instance can reach that API server.
To locate your API server address, in your UEM console navigate to Groups & Settings > All Settings > System > Advanced > Site URLs
Look for the REST API URL and copy that to a notepad for later use
Next lets generate a UEM API key for Service Now to use
In your UEM console navigate to Groups & Settings > All Settings > System > Advanced > API > REST API
Click Add to generate a new API key
Give the API key a name and description so you know what service it is being used for - in my case i called it ServiceNow
Copy the key to a notepad for later use
Next lets generate an a new service account that has API access for our ServiceNow integration to use
In your UEM console navigate to Accounts > Administrators > List View > Add > Add Admin
You can use a directory based account or a local UEM admin, in my example we will create a local admin account
Fill out the required fields and assign the account a role with the appropriate permissions
Next lets get our organization group code
In your UEM console navigate to Groups & Settings > Groups > Organization Groups > Details
In the Address bar of our web browser, at the very end of the URL string is a number, that is our group code.
Lets copy that to our notepad for later use as well.
And finally lets get a Device ID for us to test the tag application via API.
In your UEM console navigate to Devices > List View > and click on a device to view its detailed view
Just like the Organization group, we are going to look in the address bar to get the ID out of the URL.
the last few numbers in the URL are the device ID we are interested in - copy that for later use
At this point we have a Service Account created, an API key created and our Organization group code
UEM Tag Creation
The Workspace ONE UEM tool has a concept of device tagging - this allows admins to give extra metadata about the device and use that as part of a smart group assignment criteria.
Here is the link to the VMware documentation regarding device tags: VMware UEM Tags Overview
For our walkthrough today, we are going to create a Tag in the admin console, get the tag ID via the UEM API for use in the next step of the integration.
Begin by logging into your Workspace ONE UEM Console
Navigate to Groups & Settings > All Settings > Devices & Users > Advanced > Tags
Hit create Tag and give you Tag a name
In this case, I want to clearly relate the tag to a service now action, so I am calling my tag: SNOW - Repair
Hit Save
Workspace ONE UEM APIs
At this point we have nearly all of the building blocks to assemble our integration. In the next steps we will build out our API calls so we understand how the 2 systems are talking to each other.
In the next steps, we will get familiar with using the Workspace ONE API explorer. We will begin by listing out the tags that exist in our Workspace ONE UEM environment and get their details - we are interested in the tag ID.
The second step will be to get familiar with the API to assign devices to tags. That will help us form our API in Service now.
Lets begin with Getting the Tag details for our environment
In a browser navigate to your Workspace ONE API explorer by appending /help to the API url we retrieved earlier
Based on the Site URLs for me the API explorer is https://as1506.awmdm.com/api/help
Login using the service account credentials we created earlier
Select the MDM (Mobile Device Management) REST API V1 module
Select API Reference
Click Authorize
You should see your self already logged in
Under API key authorization look for the api-tenant-code header
Paste in your API key we generated and saved in the previous steps
Click Authorize
Scroll down to the Tags section
Click on Tags
Select the /tags/search key
Scroll down to the parameters section
Enter the Organization Group Code we located earlier into the orginizationgroupId field
Hit Try it out!
If your credentials, api key and organization group code are all correct, you should get a response containing the tags that have been created in your Workspace ONE UEM tool.
In my case I see a few, if i look at the details for the tag with the TagName of SNOW - Repair I can see its Value - that numerical ID is what we will use to reference this tag later on.
Copy that value for later use.
The next step is to understand how to use assign devices and tags via the API
For this scroll up in the API explorer and select the /tags/{tagid}/adddevices key
In the tagid field, enter the tag value we got from the previous step
Because this API option supports a bulk load of data, we have to do some special formatting
Here is an example of what to enter into the field - update the 12345 value with your Device ID we captured during our prep work
{
"bulkValues": {
"Value": [
"12345"
]
}
}
Hit Try it out!
Just like the other API you will see a response below. If all went according to plan you should see a pretty simple response indicating the number of devices that the tag was applied to - in my case, 1
In the API explorer you should see a section labeled Request URL - copy that for later use
If you look back in your Workspace ONE UEM Console, you will see the tag applied to your device, in both the Device List View as well as in the device details
Lets clear the tag from the device so we can see it happen via the ServiceNow API later on
Great! At this point we have veified we have everything we need to complete our integration with ServiceNow
ServiceNOW integration Overview
To complete the integration and send an API request from ServiceNow back to our UEM instance with the device tag information we want to apply, there are 2 things we need to create in service now. First we are going to create a new outbound REST message web service, this will allow us to send over the device information and the tag we want to apply. The second thing we will configure is a Business rule, that is watching the Computers status, and if it changes to fire off the REST message to update a device in the UEM console.
Servicenow Outbound REST API Message
In this section we will be going though the API configuration to update the records in the UEM console
Begin by logging into your ServiceNow Console
In the search window search for System Web Services
under the Outbound section, select REST Message
Select New
Give your REST Message a name and description so you know later on what this API message is doing. In my case I am managing the repair tag, so I am noting it as such
In this case the endpoint we are going to use is the URL for the add device tag we tested and noted in the UEM explorer previously.
Paste that into the Endpoint URL
Set the authentication type to basic
Select a authentication profile, if you don't have one for the Workspace ONE UEM API, lets create one.
Select the Magnifying glass next to the Basic authentication profile
Click new in the window that opens
Give the authentication profile a name
Enter the API service account and password for the UEM service - this is the one we created and used to login to the API service to do our testing previously
hit submit
The Authentication profile creation window will close
Right click on the title bar for the REST Message and click save
The page will refresh and at the bottom there will be a new section called HTTP Methods
By default service now will create a Default GET method
We will need a POST type method to send our tag update request, so lets hit New
Select POST from the HTTP Method
And give our new action a name
Set the same Endpoint URL for the UEM Add device tag API
Leave our Authentication type as inherit from parent
Select the HTTP Request tab
Define 3 headers and values to be:
Header Name: Content-Type , Value: application/json
Header Name: Accept , Value: application/json
Header Name: aw-tenant-code , Value: Set to your API key
Under the HTTP Query Parameters section in the content field add the same API message body from before - as a reminder it should be formatted like this:
{
"bulkValues": {
"Value": [
"12345"
]
}
}
Now because the values for the device ID that need to be updated will change with each device record, we want to make that a dynamic value.
So in the Content field, replace the device id we entered manually (in the above sample thats 12345) with a Lookup value - in this case i am going to use ${UEMDeviceID} .
In the Endpoint URL we will replace the hardcoded tag ID with a lookup value as well. In this case I am using ${UEMTagID}
Right click in the title bar and click Save
Now at the bottom select the link to Auto-Generate Variables
This will populate the Variable Substitution fields with the variables we set inline in the previous step
In the test values, lets go ahead and enter the Device ID and Tag ID values
Right click on the title bar and save
Under the related links section, hit test
A test run of the API command will be executed and the status displayed - if you have the Tag ID correct, device ID correct, and API Key, API Username / Password all correct, you will see a success status, like we did in the UEM api explorer. If not - double check the error message and your configurations for those items.
Refresh your UEM console to see that the tag was applied
Lets remove the tag so we can see it be applied in a later step
Click Back on the test run to return to the HTTP Method configuration
Under the related links section, click Preview Script Usage, and copy the whole script from the pop up dialog window. Save this in a note pad for later editing and use
ServiceNow Business Rule Creation
Now that we have our Outbound REST message configured, we need to configure the rules engine to trigger the message to be sent on an action in the ServiceNow console. In our case, there is device status that we will change, and that status change will be the trigger to update the device description as well as sent the API message which will add a device tag in the UEM console.
Begin by searching for Business rules in your ServiceNow console. You may see multiple Business rules, select the one under the System Definition header
Select New
give the new rule a descriptive name
Select the computer[cmdb_ci_computer] table
Select Update for when to run
Define our condition to look for the Status field Changes to Pending Repair
For my own notes and flow activation verification, I am going to set a description value
On the Actions Tab set the Description to Comment added via Business rule
Select the Advanced tick box
Click the Advanced tab that now displays
In the Script editor, add a few lines under the // Add your code here comment
For me, I find it hand to add a comment line to close out my code, so after the few empty lines, i am adding: // end of your code
In the space between those to comments, paste the Script code that we copied from the HTTP Method previously
Remember that we want to make the Device ID value a dynamic value, so that any device we update to Pending Repair in ServiceNow gets the tag applied.
So lets edit our script to pull the value from the record
In my case, from Part 1 of the series, I am syncing asset data from the UEM instance to ServiceNow. the key attribute that we are going to be referencing now is the Device ID.
I set up my asset sync to store the UEM Device ID value as the Correlation ID value in Service now. So if i reference the correlation ID in my script that will set the correct Device ID in the API call to UEM.
So lets edit the script while we have it open in the editor lets update it to reference the correlation ID instead of the hardcoded value for the device id. If you are storing the UEM device ID in an alternative field, just use that instead.
In my script that means setting this line:
r.setStringParameterNoEscape('UEMDeviceID', '12345');
to
r.setStringParameterNoEscape('UEMDeviceID', current.correlation_id);
(quick hint that tripped me up, notice the lack of quotes around the current.correlation_id).
Right click and Save in the title bar
Now lets give it a test!
Navigate to your computers list, and change the device status to Pending Repair
Right click and save or hit the update button in the title bar
You should see your description update to have the comment we added via the business rule when you look at the computer record
and in the UEM console you should see the tag applied to the device record
Great work! We have now configured ServiceNow to automatically update UEM anytime a device moves into the Pending Repair State! our integration is working and complete.
What next!?
At this point we have created a full round trip integration between Workspace ONE UEM, Workspace ONE Intelligence, and ServiceNow. From here, you would probably want to create a few more business rules and API sets to remove or update the tags or other data bits as the devices move though their lifecycle. In the Workspace ONE UEM console, now that we are using the tags to match device status, we can use the tags as part of our SmartGroups, so that while devices are out for repair or other condition, we are adjusting the policy and app configurations to match.
Now that have done it once, the rest is easy!