Getting Started with Omnissa Intelligence APIs

Overview

Omnissa provides this operational tutorial to help you with your Workspace ONE® environment. Omnissa 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 Omnissa Intelligence Report 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  Workspace ONE® UEM and REST API is required.

Preparing Prerequisites

In this activity, you validate and configure the prerequisites to start using the Omnissa Intelligence API v2.

Prerequisites

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

• Workspace ONE UEM Console 2402+ with admin account credentials.
• Customer type Organization Group (OG) created, and REST API enabled on this OG.
• Omnissa Intelligence Reports enabled in your Workspace ONE UEM environment.
• Contact your support representative to enable Omnissa Intelligence Reports
• Admin role with Custom Reports and Intelligence permissions.
•  Postman app installed on your machine. This tutorial uses the postman app to perform all the Intelligence REST API calls.

  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 Omnissa Intelligence Console. For example, the URL in the screenshot is https://na1.data.vmwservices.com—the region is na1.

Opting in to Omnissa Intelligence

After you have met the requirements, you are ready to enable Omnissa Intelligence. In this activity, you launch the Workspace ONE 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. In the Workspace ONE UEM console, launch Omnissa Intelligence.
   1. Click Monitor.
   2. Click Intelligence.
   3. Click Get Started to initiate the Opt-in process.
2. Opt in to Omnissa Intelligence.
   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.
   1. Provide the details and click Accept.
4. Initiate free trial.
   1. After the accepting the Terms of Service in the Workspace ONE UEM console, you redirect to the Omnissa Intelligence console. In the bottom-right corner of the page that appears, click Start 30 Day Trial.
5. Enter User Account Details and click Accept.

Create Service Account Credentials for API Access

To access Omnissa 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 Omnissa Intelligence APIs.

1. Create a service account.
   1. Under Accounts menu 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.
   3. 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. Save the JSON file as those parameters are required to obtain the access token.

Getting Started with Intelligence API

Omnissa 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 Omnissa 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 Omnissa Intelligence.

Obtaining Access Token from Omnissa 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.

  Calling 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. Enter the client_Id value as the User Name.
4. Enter the client_secret value as the Password.
5. Click Send.

A successful API call returns 200 OK.

  Get the Access Token

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

Copy the value returned by the access_token from the response and add it as environment variable on your Postman. The access_token will be required in every API call moving forward.

Important: Do not include the double quotes.

Understanding Data Category Core Attributes

Learning about the data categories and attributes available in Omnissa 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.

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.

Omnissa 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.

  Query Attributes from Device Category

From the Postman app perform the following steps:

1. Select GET from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/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 the Authorization and Content-Type key values.
   • Set the Authorization key – add the string Bearer in front of the access token.
   • Set Content-Type to application/json.
4. Click Send.

  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

Querying and Extracting Data

Querying and extracting data in Omnissa 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 Omnissa Intelligence Console, you will note that the process is the same.

This exercise guides you through all of these steps.

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 Postman app.

  Define the Header and API Attributes

From the Postman app perform the following steps:

1. Select POST from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/reports for Request URL – replace {region} with the region code where your Intelligence data is hosted.
3. Add the Authorization and Content-Type key values.
   • Set the Authorization key – add the string Bearer in front of the access token.
   • Set Content-Type to application/json.
4. Switch to the body tab.

  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:

{
    "name": "Enrolled Android Devices",
    "integration": "airwatch",
    "entity": "device",
    "column_names": [
        "airwatch.device.device_friendly_name",
        "airwatch.device.device_last_seen"
    ],
    "filter": "airwatch.device.device_platform IN ( 'Android' ) AND airwatch.device.device_enrollment_status IN ( 'Enrolled' ) ",
    "report_type": "SNAPSHOT",
    "report_format": "CSV"
}

2. Click Send.

 A 201 Created response is returned from the POST command, this confirms that the Enrolled Android Devices report has been created in Omnissa Intelligence. Copy the Report id value. The Report ID value is required in the following steps.

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.

  Configure API Parameters to Run the Report

From the Postman app perform the following steps:

1. Select POST from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/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.

  Obtain the ID for the Report Request

A 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, it 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.

  Configure Parameters for the Preview API

From the Postman app perform the following steps:

1. Select POST from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/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. 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": "airwatch.device.device_last_seen",
            "order": "DESC"
        }
    ]
}

  Review the Result

A 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.

  Define the API and Header Attributes

From the Postman app perform the following steps:

1. Select POST from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/reports/{id}/downloads/search for Request URL
   • Replace {region} with the region code where your Intelligence data is hosted.
   • Replace {report_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. Configure the request body, 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.

{
    "offset": 0,
    "page_size": 100
}

5. Click Send.

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

  Monitor Report Status

The result for the /downloads/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 the id and name it as SCHEDULED ID. The id is required to download the report later.

Downloading the Report

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

From the Postman app perform the following steps:

1. Select GET from the Method drop-down menu.
2. Enter https://api.{region}.data.vmwservices.com/v2/reports/tracking/{schedule_id}/download/ffor Request URL
   • Replace {region} with the region code where your Intelligence data is hosted.
   • Replace {scheduled_id} with the TRACKING ID that you obtained in the previous step.
3. Make sure you have the content-type and authorization headers defined. Follow the steps from the previous API call.
4. Click Send.

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 this activity, you return to the Omnissa Intelligence Console and search for the report you just created through the APIs.

1. Navigate to Workspaces > Reports.
2. Click on the Enrolled Android Devices report.

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

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

Summary and Additional Resources

 This operational tutorial provided steps on how to start using Omnissa 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 Omnissa Intelligence.

For more information about Omnissa Intelligence, see the following resources:

•  Omnissa Intelligence API Documentation
•  Omnissa Intelligence User Guide

Additional Resources

For more information about Workspace ONE, explore the Omnissa Workspace ONE UEM product page. This activity path includes curated assets in the form of articles, videos, and labs from beginning to advanced, to help you level up your Workspace ONE knowledge.

You can also check out the  Omnissa Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using Omnissa Workspace ONE, Omnissa Horizon, and a variety of integrations.

Changelog

The following updates were made to this guide:

Date	Description of Changes
2025/01/15	Update the article to use Intelligence API v2
2024/09/19	Update links and references.
2022/02/24	This guide has been reviewed and content is up to date.
2020/05/01	Updated Download API steps to use curl command line.

About the Author and Contributors

This tutorial was written by:

•  Andreano Lanusse, Staff Architect, Technical Marketing, Omnissa.

Feedback

Your feedback is valuable.

To comment on this paper, either use the feedback button or contact us at tech_content_feedback@omnissa.com.