Getting Started with Workspace ONE Intelligence APIs: Workspace ONE Operational Tutorial

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

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

For example, navigate to https://<WorkspaceONEUEMHostname> where WorkspaceONEUEMHostname is the host name of 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.

In the Workspace ONE UEM Console:

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

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

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

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.

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

1. Click Service Accounts.
2. Click Add.

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.

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.

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.

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.

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.

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.

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.

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.

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'"
}

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

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.

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 and paste into Notepad++. This id value represents the Schedule Track ID and will be used to check the status in a later activity.

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.

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.

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

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.

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.

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.

Open a command line and execute the following command, replace the variables region, download_id and access_token with the respective values:

• 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 Notepad.
• Replace {access_token} with the access token key used on all the previous steps as part of the Authentication header.
• Replace {output}  with the file name including .csv extension for the report output.

curl -X GET https://api.{region}.data.vmwservices.com/v1/reports/tracking/{id}/download   -H "Authorization: Bearer {access_token}" -L -o {output}

The report content is downloaded to the file informed on the -o parameter.

You can add --Verbose to your curl command, which displays the redirect happening to obtain the report similar to the next image.

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.

The result should be similar to the image above, where the first row is the header and is followed by the device records.

From the Workspace ONE UEM Console:

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

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

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.

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