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!