Getting Started with Workspace ONE Intelligence API: VMware Workspace ONE Operational Tutorial

VMware Workspace ONE UEM 9.7 and later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment. VMware Workspace ONE® Intelligence™ is designed to simplify user experience without compromising security. The intelligence service aggregates and correlates data from multiple sources to give complete visibility into the entire environment. 

In this tutorial, learn how to use the Workspace ONE Intelligence API to query and extract data related to your devices, applications, and OS updates.

Audience

This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Familiarity with networking, JSON format and API concepts is assumed. Knowledge of additional technologies such as VMware Workspace ONE® UEM and REST API is also helpful.

Preparing Prerequisites

Introduction

In this activity, you validate and configure the prerequisites to start using Workspace ONE Intelligence APIs. Access to Workspace ONE Intelligence through APIs requires an access token from Workspace ONE UEM, as a result, you must enable REST API and obtain an API Key from Workspace ONE UEM to use with Workspace ONE Intelligence.

Prerequisites

Before you can perform the procedures in this exercise, verify that the following components installed and configured:                

  • Workspace ONE UEM Console v9.7 and later with admin account credentials
  • Organization Group (OG) created and set as Customer type
  • Workspace ONE Intelligence Reports enabled in your Workspace ONE UEM environment
    • Contact your support representative to enable Workspace ONE Intelligence Reports
  • Admin role with Custom Reports and Intelligence permissions
  • Advanced REST Client installed on your machine
  • Notepad ++ with word wrap enabled (In Notepad++, select ViewWord wrap).

Identify the Intelligence Data Region

In this tutorial, you will call Intelligence APIs multiple times. These calls are made against the environment where your Intelligence data is hosted.

The activities request you to update the {region} parameter with the respective region where the Intelligence data is hosted.

You can easily identify the region based on the URL that you see when using the Workspace ONE Intelligence Console. For example, the URL in the screenshot is https://na1.data.vmwservices.comthe region is na1.

Logging In to the Workspace ONE UEM Console

To perform most of the steps in this exercise, you must first log in to the Workspace ONE UEM Console.

1. Launch Chrome Browser

Launch Chrome Browser

On your desktop, double-click the Google Chrome icon.

3. Authenticate In to the Workspace ONE UEM Console

  1. Enter your Username, for example, administrator.
  2. Click Next. After you click Next, the Password text box is displayed.
  1. Enter your Password, for example, VMware1!
  2. Click Login.

Note: If you see a Captcha, be aware that it is case sensitive.

Obtaining Workspace ONE UEM API Key

The Workspace ONE UEM REST API Key is used to obtain the refresh token, and this token is required to gain access to the Intelligence API. In this activity, you generate the API Key and copy it to Notepad++.

Opting-in to Workspace ONE Intelligence

After you have met the requirements, you are ready to enable Workspace ONE Intelligence. In this activity, you launch the Workspace ONE Intelligence Console, and sign up for a free trial.

1. Launch Workspace ONE Intelligence

In the Workspace ONE UEM Console:

  1. Click Monitor.
  2. Click Intelligence.
  3. Click Get Started to initiate the Opt-in process.

2. Opt in to Workspace ONE Intelligence

Next
  1. Scroll down to the Opt in to use Intelligence section.
  2. Select the Opt In checkbox.
  3. Click Next.

3. Complete the Terms of Service

Accept Terms of Service
  1. Provide the following details:
    • Name
    • Email Address
    • Title
    • Company Name
    • Company Address
  2. Click Accept.

4. Initiate Free-Trial

After the accepting the Terms of Service in the Workspace ONE UEM console, you redirect to the Workspace ONE Intelligence console. In the bottom-right corner of the page that appears, click Start 30 Day Trial.

5. Enter User Account Details

  1. Provide the following details:
    • First Name
    • Last Name
    • Email
    • Title
    • Company
    • City
    • Country
    • Zip/Postal Code
    • Phone
  2. Click Accept.

Getting Started with Intelligence API

Introduction

Workspace ONE Intelligence provides a powerful REST API interface to allow organizations to query and extract data related to their managed devices, applications, and OS updates part of the managed devices. The same APIs used by Workspace ONE Intelligence are now open to not only extract data but also build an automated workflow that can allow your organization to integrate with other business tools.

In this activity, you request a refresh token using Workspace ONE UEM API; the refresh token is required to request authorization access to Workspace ONE Intelligence.

Prerequisites

Before you can perform the procedures in this exercise, you must complete Preparing Prerequisites.

Obtaining Refresh Token from Workspace ONE UEM

After enabling the Workspace ONE UEM API, you are ready to begin exploring Intelligence API. In this activity, you learn how to get access to Intelligence data through APIs by requesting a refresh token from Workspace ONE UEM API and obtaining the access token from Intelligence.

To make successful calls to Intelligence APIs, you need a valid refresh token. This token can be generated by calling your Workspace ONE UEM environment REST API, and it is valid for 5 minutes.

Launch the Advanced REST Client and perform the next steps.

1. Set Up Call to Workspace ONE UEM API

  1. Select Get from the Method drop-down menu.
  2. Enter https://{Workspace ONE UEM API Server}/api/system/customreports/refreshtoken for Request URL – replace {Workspace ONE UEM API Server} with your API Server FQDN.
  3. Enter the Workspace ONE UEM API Key that you obtained from previous step.
  4. Click Send.

2. Authenticate API Call

  1. Enter the User Name. For example, jdoeadmin. This is an admin user in your Workspace ONE UEM environment.
  2. Enter the Password.
  3. Click Accept.

3. Get Refresh Token

After calling the API, a response will return containing the refreshToken.

Click the Copy icon to copy the refreshToken from the Response and paste into Notepad++.

Obtaining Access Token from Workspace ONE Intelligence

To make successful calls to Intelligence APIs, you need a valid refresh token to authenticate against Intelligence. This token can be generated by calling your Workspace ONE UEM environment REST API, and it is valid for 5 minutes.

1. Set Up API Header Call to Obtain Refresh Token

  1. Select Post from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/auth/console/token for Request URL – replace {region} with the region code where your Intelligence data is hosted.
  3. Enter content-type for Header name
  4. Enter application/json for Header value

Remove any other header that you have from previous calls.

2. Add Refresh Token as Part of the Body API call

  1. Click Body.
  2. Paste the refreshToken that you obtained from Workspace ONE UEM.
  3. Click Send.

The Refresh Token is only valid for 5 minutes. If you get an error message CODE-JWT EXPIRED, you must obtain a new refresh token, calling the UEM API from the previous step and pasting the new token to this API call.

3. Get the Access Token

The response returns the access token which is your authorization to access Intelligence via API.

Copy the value returned by the access_token from the response and paste into Notepad++.

Important: Do not include the double quotes.

Understanding Data Category Core Attributes

Introduction

Understanding the data categories and attributes is important when using Intelligence API to query data.

In this activity, you obtain a dictionary of attributes per data category using Intelligence API. This information is essential to successfully query the data available in Workspace ONE Intelligence.

Prerequisites

Before you can perform the procedures in this exercise, you must complete Preparing Prerequisites.

Getting Available Data Columns for Device Categories

In a traditional relational database, you can only create a query against a table if you know the name of the tables, where the information resides, and the column names to obtain the results based on filters that you provide.

Intelligence is no different. Intelligence provides APIs that will return available Data Categories and their respective attributes.

In this activity, you query all the attributes per Device Category to be used in future API calls to query data.

Perform these steps from the Advanced REST Client

1. Query Attributes from Device Category

  1. Select Get from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/api/v1/meta/integration/{integration}/entity/{entity}/attributes for Request URL
    • Replace {region} with the region code where you Intelligence data is hosted.
    • Replace {integration} with airwatch to obtain attributes for the respective entity.
    • Replace {entity} with device to obtain all the device attributes for AirWatch integration. You can also use application or windowspatch as an entity value.
  3. Add a new header and enter authorization as Header name.
  4. Enter the access token key as a header value for the authorization – add the string Bearer in front of the access token.
  5. Add a new header and enter content-type as Header name.
  6. Enter application/json as the header value for content-type.
  7. Add a new header and enter Cache-Control as Header name.
  8. Enter no-cache as the header value for Cache-Control.
  9. Click Send.

2. Verify the Result

The response is a JSON array containing all the available attributes and their characteristic for device category, which includes:

  • name - field name to use for query and filter data based on the specific field name
  • label - label used on the Intelligence UI
  • description - detailed description of the field
  • data_type - data type of the field

Click the Toggle structured table view icon to visualize the results in a table format.

Querying and Extracting Data

Introduction

Querying and extracting data in Workspace ONE Intelligence is based on Report APIs; this means to retrieve the final data, you must satisfy the following requirements:

  • Define the report structure including columns and filters
  • Run the report and monitor the status until it is generated
  • Download the report results

If you have used Reports through the Intelligence Console, you will note that the process is the same.

This exercise guides you through all of these steps.

Prerequisites

Before you can perform the procedures in this exercise, you must complete Preparing Prerequisites.

Creating the Report

In this activity, you create a new report using Intelligence API, define the information you want as a result and specify the filters to obtain the expected result.

Perform these steps in the Advanced REST Client.

1. Define the API and Header Attributes

  1. Select POST from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/api/v1/reports for Request URL – replace {region} with the region code where your Intelligence data is hosted.
  3. Add a new header and enter content-type as Header name.
  4. Enter application/json as the Header value for content-type.
  5. Add a new header and enter authorization as the Header name.
  6. Enter the access token key as a header value for the authorization – add the string Bearer before the access token.
  7. Click Body.

2. Set Report Attributes

The body of the request contains all the characteristics of the report, including the report name, descriptions, columns, filters, and data category.

  1. Enter the following JSON string to the body of the request:
{"entity":"device",
 "name":"Enrolled Android Devices",
 "description":"List all managed Android Devices",
 "column_names": ["device_friendly_name", "device_last_seen"],
 "integration": "airwatch",
 "filter":" device_platform IN ( 'Android' ) AND device_enrollment_status = 'Enrolled'",
 "ignore_case": true}

201 Created response is returned from the POST command, this confirms that the Enrolled Android Devices report has been created in Workspace ONE Intelligence.

2. Copy the Report id value and paste into Notepad++. The Report id value is required in the following steps.

3. Click Send.

Executing the Report

In this activity, you use an API to run the report which creates a scheduled request in Intelligence. Using the API, you monitor the request status until it completes and then you can download the content via API.

Perform these steps in the Advanced REST Client.

1. Define the API and Header Attributes

  1. Select POST from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/api/v1/reports/run for Request URL – Replace {region} with the region code where your Intelligence data is hosted.
  3. Make sure you have the content type and authorization headers defined. Follow the steps from the previous API call.
  4. Click Body.

2. Configure the Request Body and Run the Report

The body of the request only needs the Report ID that you want to run.

  1. Replace REPORT ID with the value of the report id previously generated. The value must be between double quotes:
{ "report_id": "REPORT ID"}

A 201 Created response is returned from the POST command, confirming the request to generate the report and make the report available to download.

2. Click Send.

3. Copy the id value and paste into Notepad++. This id value represents the Schedule Track ID and will be used to check the status in a later activity.

Tracking the Report Status

Your report is now in a queue to be processed and available for download. In this activity, you track the status of the report generation until it completes.

Perform these steps in the Advanced REST Client.

1. Define the API and Header Attributes

  1. Select POST from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/api/v1/reports/{id}/downloads/search for Request URL
    • Replace {region} with the region code where your Intelligence data is hosted.
    • Replace {id} with the REPORT ID that you obtained when the report was created.
  3. Make sure you have the content-type and authorization headers defined. Follow the steps from the previous API call.
  4. Click Body.

2. Configure the Request Body and Run API

The body of the request only needs the Report ID that you want to run.

  1. Enter {} in the request body.
  2. Click Send.
  3. Scroll down to view the result.

The 200 code response is returned when the API call is successfully executed.

3. Monitor Report Status

The result for the /download/search API call represents a list of requests for this report. Each request contains several attributes for the request, including the status, which starts with INITIATED and when finalized will show as COMPLETED.

Click Send to refresh the status of your report until it shows COMPLETED, then copy and paste the id  into Notepad++. The id is required to download the report.

The screenshot shows the output of a completed report. The status is COMPLETED and the location attribute is added to the response, showing the location of the generated report file.

Downloading the Report

After you have confirmed that the report has completed, you download the report results using the download API.

1. Define the API and Header Attributes

  1. Select GET from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/api/v1/reports/tracking/{id}/download for Request URL
    • Replace {region} with the region code where your Intelligence data is hosted.
    • Replace {id} with the SCHEDULED ID obtained from the /reports/run API call.
  3. Make sure you have the authorization and content-type headers defined. Follow the steps from the previous API call.
  4. Click Send.
  5. A successful execution returns a 200 OK code and the list of enrolled Android devices from your Workspace ONE UEM environment, based on the report parameters defined earlier in this exercise.

Validating the Report in the Workspace ONE Intelligence Console

In this activity, you return to the Workspace ONE Intelligence Console and search for the report you just created.

1. Return to the Workspace ONE Intelligence Console

From the Workspace ONE UEM Console:

  1. Click the menu icon.
  2. Select Workspace ONE Intelligence.

2. Select the Report

  1. Navigate to Reporting > Reports.
  2. Select the report. For example, Enrolled Android Devices.

3. Review the Report

  1. Check the Report Preview which contains a few records returned by the report.
  2. Check the number of generated reports available for download. This result is the number of times the /reports/run API was called.
  3. Click Activity.

4. Review the Activities List

The Activity tab lists all recent activities including report generation and downloaded reports.

Summary and Additional Resources

Conclusion

This operational tutorial provided steps on how to start using Workspace ONE Intelligence APIs to query and extract data related to devices managed by Workspace ONE UEM. 

Procedures included:

  • Configuring prerequisites in Workspace ONE UEM
  • Using APIs to create, execute, monitor report status, and download report content
  • Validating all the results generated through the API in Workspace ONE Intelligence

For more information, see the  Workspace ONE Intelligence Documentation.

Terminology Used in This Tutorial

The following terms are used in this tutorial:

application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as VMware Identity Manager.
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile device management
(MDM) agent
Software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
service provider (SP)
A host that offers resources, tools, and applications to users and devices.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

Additional Resources

About the Author

This tutorial was written by:

  • Andreano Lanusse, End-User-Computing Staff Architect, Technical Marketing, VMware.

Feedback

The purpose of this tutorial is to assist you. Your feedback is valuable. To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.