Getting Started with Workspace ONE Intelligence APIs: 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, OS updates and device sensors.

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 the Workspace ONE Intelligence APIs.

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
  • Customer type Organization Group (OG) created and REST API enabled on this OG
  • 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 View > Word 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.

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 if this is your first time using Intelligence.

In case you already have an Intelligence environment enabled and data already flowing in, skip to the next activity.

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.

Creating Service Account Credentials for API Access

To access Workspace ONE Intelligence APIs, you must create a service account.

A service account provides you with a clientId (username) and clientSecret (password) that can be used to obtain a JSON Web Token to call Workspace ONE Intelligence APIs.

1. Create Service Account

  1. Click Service Accounts.
  2. Click Add.

2. Name the Service Account

  1. Enter a name for the Service Account. For example, uem_uat_access.
  2. Click Generate Client Secret.

Note: The credentials will be created and a JSON file containing the client secret will be downloaded. Store your client secret securely because you cannot recover it if lost.

3. Understand the Service Account Parameters

  1. Token Endpoint – This is the endpoint URI used to request an Access Token. It is associated with the region where the Intelligence tenant is hosted.
  2. Client Id – The clientId acts as the username.
  3. Client Secret –  The clientSecret is a password and must be protected. After creating the service account, you cannot retrieve the clientSecret again. You can generate a new clientSecret, but this replaces (invalidates) the original clientSecret.
  4. The information shown in the screenshot is included in the generated JSON file and downloaded locally. Save the JSON file as those parameters are required to obtain the access token.

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 devices, applications, OS updates and device sensors 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 use Intelligence API to request an authorization access token, obtain access to data using Report APIs in Workspace ONE Intelligence.

Prerequisites

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

Obtaining Access Token from Workspace ONE Intelligence

Before you can call Intelligence APIs, you first must call an authentication API using the configured service account for the environment. A successful authentication generates an access token (JWT) that can be used to call the Intelligence APIs.

1. Call Authorization API to Obtain Access Token

  1. Select Post from the Method drop-down menu.
  2. Enter the Token End Point URL from your service account for Request URL. For example, https://auth.{region}.data.vmwservices.com/oauth/token?grant_type=client_credentials. Replace {region} with the region code where your Intelligence data is hosted.
  3. Click Send.

2. Authenticate Using Service Account Credentials

  1. Enter the clientId value as the User Name.
  2. Enter the clientSecret value as the Password.
  3. Click Accept.

A successful API call returns 200 OK.

3. Get the Access Token

The response returns an access_token, which is your authorization to access Intelligence APIs.

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

Learning about the data categories and attributes available in Workspace ONE Intelligence is the first and most important step when starting with Intelligence APIs. Data categories and attributes represent the API metadata and are part of the process to create a report definition, define filter condition, find out which data to query, and so on.

In this activity, you leverage the Report Metadata API to obtain the dictionary of attributes per data category.

Prerequisites

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

Obtaining Report API Metadata

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

Workspace ONE Intelligence is no different; Report API metadata is available to allow you to query each Data Category (entity) and their respective attributes.

Data is organized in a three-level hierarchy: Integration / Entity or Event Type / Attribute.

  • Integration – Usually the name of the vendor or product that is sourcing the data.
  • Entity or Event Type
    • An Entity is an object for which the system tracks attributes over time. For example, devices and users would be entities.
    • An Event Type is an event that occurs at a point in time. For example, an app launch or a notification from a security vendor would both be events.
  • Attribute – An attribute is a key-value pair associated with an entity or an event type. For example, a Device Friendly Name could be an attribute of a device.

For reporting, the following integration/entity combinations are available:

  • airwatch is the integration name for Workspace ONE UEM integration
  • application is the entity related to Apps
  • device is the entity for Devices
  • windowspatch is the entity for OS Updates
  • devicesensors is the entity for Devices Sensors

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/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 Workspace ONE UEM 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. Click Send.

2. Verify the Result

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

  • name – the field name to use for querying and filtering data based on the specific field name
  • label – the label used on the Intelligence UI
  • description – a detailed description of the field
  • data_type – the 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 in the Workspace ONE 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/v1/reports for Request URL – replace {region} with the region code where your Intelligence data is hosted.
  3. Add a new header and enter authorization as the Header name.
  4. Enter the access token key as a header value for the authorization – add the string Bearer before 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. 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'"
}

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

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

Running 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. Configure API Parameters to Run the Report

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

2. Obtain the ID for the Report Request

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

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.

Generating a Report Preview

In this activity, you use the Preview API to validate the report results based on the report definition and make changes if necessary.

For small searches of targeted data, the report preview API can be used to extract data. This API returns no more than 1000 results.

Perform these steps in the Advanced REST Client.

1. Configure Parameters for the Preview API

  1. Select POST from the Method drop-down menu.
  2. Enter https://api.{region}.data.vmwservices.com/v1/reports/{report_id}/preview for Request URL
    1. Replace {region} with the region code where your Intelligence data is hosted.
    2. Replace {report_id} with the value of the report id previously generated by the Create Report API
  3. Make sure you have the content type and authorization headers defined. Follow the steps from the previous API call.
  4. Click Send.

2. Define the Preview Conditions

  1. Add the following condition to the body; limit the results to 3 records and order by the device last seen.
{
    "offset": 0,
    "page_size": 3,
    "sort_ons": [
        {
            "field": "device_last_seen",
            "order": "DESC"
        }
    ]
}

2. Click Send.

3. Review the Result

200 OK response is returned from the POST command, and the response shows the 3 ordered records based on the report definition.

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/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

In the request body, you can set the page size to limit the number of records per page. If the page size is not specified, Intelligence API defaults to 100 records.

  1. Enter {"offset": 0, "page_size": 100} 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++ and name as SCHEDULED ID. 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/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 previous steps and copied on your Notead.
  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 and Intelligence
  • 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 about Workspace ONE Intelligence, see the following resources:

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 Workspace ONE Access (formerly 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

For more information about Workspace ONE, explore the VMware Workspace ONE Activity Path. The activity path provides step-by-step guidance to help you level-up in your Workspace ONE knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon. 

 

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.