Getting Started with VMware Workspace ONE Intelligence API ... · GETTING STARTED WITH VMWARE WORKSPACE ONE INTELLIGENCE API: VMWARE WORKSPACE ONE OPERATIONAL TUTORIAL GUIDE | 5 You

GUIDE – MAY 2019

PRINTED 15 MAY 2019

GETTING STARTED WITHVMWARE WORKSPACE ONEINTELLIGENCE API: VMWAREWORKSPACE ONEOPERATIONAL TUTORIALVMware Workspace ONE

GETTING STARTED WITH VMWARE WORKSPACE ONE INTELLIGENCE API: VMWARE WORKSPACE ONEOPERATIONAL TUTORIAL

GUIDE | 2

Table of Contents

Overview

– Introduction

– Audience

Preparing Prerequisites

– Introduction

– Prerequisites

– Logging In to the Workspace ONE UEM Console

– Obtaining Workspace ONE UEM API Key

– Opting-in to Workspace ONE Intelligence

Getting Started with Intelligence API

– Introduction

– Prerequisites

– Obtaining Refresh Token from Workspace ONE UEM

– Obtaining Access Token from Workspace ONE Intelligence

Understanding Data Category Core Attributes

– Introduction

– Prerequisites

– Getting Available Data Columns for Device Categories

Querying and Extracting Data

– Introduction


GUIDE | 3

– Prerequisites

– Creating the Report

– Executing the Report

– Tracking the Report Status

– Downloading the Report

– Validating the Report in the Workspace ONE Intelligence Console

Summary and Additional Resources

– Conclusion

– Terminology Used in This Tutorial

– Additional Resources

– About the Author

– Feedback


GUIDE | 4

Getting Started with Workspace ONE Intelligence

OverviewIntroductionVMware 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 andcorrelates 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.

AudienceThis 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 VMwareWorkspace ONE® UEM and REST API is also helpful.

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

PrerequisitesBefore 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 credentialsOrganization Group (OG) created and set as Customer typeWorkspace ONE Intelligence Reports enabled in your Workspace ONE UEM environment

Contact your support representative to enable Workspace ONE Intelligence ReportsAdmin role with Custom Reports and Intelligence permissionsAdvanced REST Client installed on your machineNotepad ++ 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 Intelligencedata is hosted.

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

http://www.vmware.com/products/workspace-one.html

https://www.vmware.com/products/airwatch-enterprise-mobility-management.html

https://www.vmware.com/products/airwatch-enterprise-mobility-management.html

https://docs.vmware.com/en/VMware-Workspace-ONE-UEM/1902/MDM/GUID-AWT-ADMINROLES.html

https://install.advancedrestclient.com/install


GUIDE | 5

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.com—the region is na1.

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

1. Launch Chrome Browser

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

2. Navigate to the VMware Workspace ONE UEM ConsoleFor example, navigate to https://<WorkspaceONEUEMHostname> where WorkspaceONEUEMHostname is the host name of theWorkspace ONE UEM console.

3. Authenticate In to the Workspace ONE UEM Console


GUIDE | 6

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


GUIDE | 7

Enter your Password, for example, VMware1!1.Click Login.2.

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

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

1. Navigate to All Settings


GUIDE | 8

In the Workspace ONE UEM console, at the appropriate Organization Group level:

Click Groups & Settings.1.Click All Settings.2.

2. Regenerate the API Key


GUIDE | 9


GUIDE | 10

Click System.1.Click Advanced.2.Click API.3.Click REST API.4.Click Override to generate the new API Key used to integrate with Workspace ONE Intelligence.5.For the AirWatchAPI Service, select and copy the API Key. Then, paste the copied text into Notepad++.6.Click Save.7.

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


GUIDE | 11

1. Launch Workspace ONE Intelligence


GUIDE | 12

In the Workspace ONE UEM Console:

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

2. Opt in to Workspace ONE Intelligence

https://media.screensteps.com/image_assets/assets/002/323/997/original/d7d35ba7-5684-4ba3-a276-c39c4f903e48.png


GUIDE | 13

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

3. Complete the Terms of Service


GUIDE | 14

Provide the following details:1.NameEmail AddressTitleCompany NameCompany Address

Click Accept.2.

4. Initiate Free-Trial


GUIDE | 15

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

5. Enter User Account Details


GUIDE | 16

Provide the following details:1.First NameLast NameEmailTitleCompanyCityCountryZip/Postal CodePhone

Click Accept.2.


GUIDE | 17

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

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

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

Obtaining Refresh Token from Workspace ONE UEMAfter enabling the Workspace ONE UEM API, you are ready to begin exploring Intelligence API. In this activity, you learn how to getaccess to Intelligence data through APIs by requesting a refresh token from Workspace ONE UEM API and obtaining the accesstoken from Intelligence.

To make successful calls to Intelligence APIs, you need a valid refresh token. This token can be generated by calling your WorkspaceONE 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

Select Get from the Method drop-down menu.1.Enter https://{Workspace ONE UEM API Server}/api/system/customreports/refreshtoken for Request URL2.



GUIDE | 18

– replace {Workspace ONE UEM API Server} with your API Server FQDN.Enter the Workspace ONE UEM API Key that you obtained from previous step.3.Click Send.4.

2. Authenticate API Call

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


GUIDE | 19

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 IntelligenceTo make successful calls to Intelligence APIs, you need a valid refresh token to authenticate against Intelligence. This token can be

https://media.screensteps.com/image_assets/assets/002/399/394/original/cd2800df-227f-429b-9b29-1b54f2bac023.png


GUIDE | 20

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

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

Remove any other header that you have from previous calls.

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


GUIDE | 21

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

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

3. Get the Access Token

https://media.screensteps.com/image_assets/assets/002/399/390/original/31e4842e-a161-4dec-886d-d27429a602d1.png

https://media.screensteps.com/image_assets/assets/002/399/723/original/7cc9ec59-6d60-4e2d-98a2-4f40bd786874.png


GUIDE | 22

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 AttributesIntroductionUnderstanding 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 tosuccessfully query the data available in Workspace ONE Intelligence.


Getting Available Data Columns for Device CategoriesIn a traditional relational database, you can only create a query against a table if you know the name of the tables, where theinformation 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

Select Get from the Method drop-down menu.1.Enter https://api.{region}.data.vmwservices.com/api/v1/meta/integration/{integration}/entity/en2.tity/attributes for Request URL

Replace {region} with the region code where you Intelligence data is hosted.


https://media.screensteps.com/image_assets/assets/002/406/331/original/be2a0ca2-30e2-4469-889b-2a31b418f9b8.png


GUIDE | 23

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 alsouse application or windowspatch as an entity value.

Add a new header and enter authorization as Header name.3.Enter the access token key as a header value for the authorization – add the string Bearer in front of the access token.4.Add a new header and enter content-type as Header name.5.Enter application/json as the header value for content-type.6.Add a new header and enter Cache-Control as Header name.7.Enter no-cache as the header value for Cache-Control.8.Click Send.9.

2. Verify the Result


GUIDE | 24

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


GUIDE | 25

label - label used on the Intelligence UIdescription - detailed description of the fielddata_type - data type of the field

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

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

Define the report structure including columns and filtersRun the report and monitor the status until it is generatedDownload 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.

https://media.screensteps.com/image_assets/assets/002/399/825/original/f9641ca0-0e0a-49dc-ae43-688618b4da7a.png


GUIDE | 26


Creating the ReportIn this activity, you create a new report using Intelligence API, define the information you want as a result and specify the filters toobtain the expected result.

Perform these steps in the Advanced REST Client.

1. Define the API and Header Attributes

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

2. Set Report Attributes


https://media.screensteps.com/image_assets/assets/002/404/475/original/77a3c8d2-6de0-47f8-967e-c3363d882900.png


GUIDE | 27

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

Enter the following JSON string to the body of the request:1.

{"category_name":"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}

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


GUIDE | 28

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 ReportIn this activity, you use an API to run the report which creates a scheduled request in Intelligence. Using the API, you monitor therequest status until it completes and then you can download the content via API.



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

2. Configure the Request Body and Run the Report



GUIDE | 29

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

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

{ "report_id": "REPORT ID"}

A 201 Created response is returned from the POST command, confirming the request to generate the report and make the reportavailable 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 statusin a later activity.

Tracking the Report StatusYour report is now in a queue to be processed and available for download. In this activity, you track the status of the report generationuntil it completes.


GUIDE | 30



Select POST from the Method drop-down menu.1.Enter https://api.{region}.data.vmwservices.com/api/v1/reports/{id}/downloads/search for Request URL2.

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.

Make sure you have the content-type and authorization headers defined. Follow the steps from the previous API call.3.Click Body.4.

2. Configure the Request Body and Run API



GUIDE | 31

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

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

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

3. Monitor Report Status


GUIDE | 32

The result for the /download/search API call represents a list of requests for this report. Each request contains several attributesfor 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 isrequired to download the report.


GUIDE | 33

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

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


https://media.screensteps.com/image_assets/assets/002/404/744/original/8726317c-b61f-4b1e-8b94-db3d57fb05e6.png


GUIDE | 34

Select GET from the Method drop-down menu.1.Enter https://api.{region}.data.vmwservices.com/api/v1/reports/tracking/{id}/download for Request URL2.

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.

Make sure you have the authorization and content-type headers defined. Follow the steps from the previous API call.3.Click Send.4.A successful execution returns a 200 OK code and the list of enrolled Android devices from your Workspace ONE UEM5.environment, based on the report parameters defined earlier in this exercise.

Validating the Report in the Workspace ONE Intelligence ConsoleIn 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

https://air-watch.screenstepslive.com/admin/v2/internal_links/1078805?type=lesson


GUIDE | 35

From the Workspace ONE UEM Console:

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

2. Select the Report


GUIDE | 36

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


GUIDE | 37

3. Review the Report

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

4. Review the Activities List


GUIDE | 38

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

Summary and Additional ResourcesConclusionThis operational tutorial provided steps on how to start using Workspace ONE Intelligence APIs to query and extract data related todevices managed by Workspace ONE UEM.

Procedures included:

Configuring prerequisites in Workspace ONE UEMUsing APIs to create, execute, monitor report status, and download report contentValidating all the results generated through the API in Workspace ONE Intelligence

For more information, see the Workspace ONE Intelligence Documentation.

Terminology Used in This TutorialThe following terms are used in this tutorial:

https://media.screensteps.com/image_assets/assets/002/404/968/original/f8df09a8-3503-473d-a5ac-66649393fd0c.png

https://docs.vmware.com/en/VMware-Workspace-ONE/services/Intelligence/GUID-AWT-WS1INT-OVERVIEW.html


GUIDE | 39

application storeA user interface (UI) framework that provides access to a self-service catalog, publicexamples of which include the Apple App Store, the Google Play Store, and the MicrosoftStore.

auto-enrollmentAuto-enrollment simplifies the enrollment process by automatically enrolling registereddevices following the Out-of-Box-Experience.

catalogA user interface (UI) that displays a personalized set of virtual desktops and applications tousers and administrators. These resources are available to be launched upon selection.

cloudAsset of securely accessed, network-based services and applications. A cloud can also hostdata storage. Clouds can be private or public, as well as hybrid, which is both private andpublic.

device enrollmentThe process of installing the mobile device management agent on an authorized device.This allows access to VMware products with application stores, such as VMware IdentityManager.

identity provider (IdP)A mechanism used in a single-sign-on (SSO) framework to automatically give a user accessto a resource based on their authentication to a different resource.

mobile devicemanagement(MDM) agent

Software installed on an authorized device to monitor, manage, and secure end-user accessto enterprise resources.

one-touch loginA mechanism that provides single sign-on (SSO) from an authorized device to enterpriseresources.

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 machineA software-based computer, running an operating system or application environment, that islocated in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

Additional ResourcesFor more information about Workspace ONE, you can explore the following resources:

VMware Workspace ONE Action PathVMware Workspace ONE product pageVMware Workspace ONE DocumentationVMware Identity Manager product pageVMware Identity Manager DocumentationVMware Workspace ONE UEM, powered by VMware AirWatch product pageVMware AirWatch DocumentationVMware Workspace ONE free trialVMware Workspace ONE Enterprise Edition Reference ArchitectureVMware End-User-Computing BlogsWorkspace ONE UEM Hands-On Lab

About the AuthorThis tutorial was written by:

https://www.vmware.com/support/pubs/

https://techzone.vmware.com/workspace-one

http://www.vmware.com/products/workspace-one.html

https://docs.vmware.com/en/VMware-Workspace-ONE/index.html

http://www.vmware.com/products/identity-manager.html

https://www.vmware.com/support/pubs/identitymanager-pubs.html

https://www.vmware.com/products/enterprise-mobility-management.html

https://docs.vmware.com/en/VMware-AirWatch/index.html

http://www.air-watch.com/lp/free-trial/

http://www.vmware.com/content/dam/digitalmarketing/vmware/en/pdf/techpaper/vmware-workspace-one-reference-architecture-validated-integration-design.pdf

https://blogs.vmware.com/euc/?s=Workspace+ONE

https://my.vmware.com/web/vmware/evalcenter?p=airwatch-18-hol


GUIDE | 40

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

FeedbackThe 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 [email protected].

mailto:[email protected]

VMware, Inc. 3401 Hillview Avenue Palo Alto CA 94304 USA Tel 877-486-9273 Fax 650-427-5001 www.vmware.com

Copyright © 2019 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.

VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of

VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective

companies.

Documents

Getting Started with VMware Workspace ONE Intelligence API ... · GETTING STARTED WITH VMWARE WORKSPACE ONE INTELLIGENCE API: VMWARE WORKSPACE ONE OPERATIONAL TUTORIAL GUIDE | 5 You