Introduction
In this post I will explain step by step an NPM package that wraps Workspace ONE Intelligence APIs to simplify their usage. I will show you how to integrate it with your Node.js in-house applications by providing easy-to-understand examples and simplifying certain concepts.
Audience
This post is most appropriate for the following audiences:
- Anyone new to VMware Workspace ONE.
- Anyone new to VMware Workspace ONE Intelligence.
- Anyone with basic Node.js programming expertise.
What is Workspace ONE Intelligence?
VMware Workspace ONE Intelligence is a cloud service built for the VMware Workspace ONE UEM platform that provides deep insights, analytics and automation for the entire digital workspace. You can query and extract data related to your devices, applications, OS updates, device sensors...
Workspace ONE Intelligence APIs Wrapper
This wrapper is created using Node.js Javascript, to make Workspace ONE Intelligence APIs easy to use and easy to integrate in Node.js applications.
What You Will Build
A Node.js script that will create an intelligence report and download it as CSV file.
Prerequisites
Before you can perform and apply the steps in this article, you will need to verify that the following components are installed and configured:
- Workspace ONE UEM Console v9.7 and later with admin credentials.
- Workspace ONE Intelligence already configured (we will soon add an article that shows how to).
- Node.js latest version.
- Integrated development environment (IDE).
Access to Workspace ONE Intelligence
Launch a navigator and navigate to your Workspace ONE UEM console (e.g. cn801.awmdm.com).
After authentication go to the right Organization Group and launch Intelligence from there.
Service Account
This NPM wrapper exploits Workspace ONE Intelligence APIs, to access them you must create a service account.
A service account provides you with a clientId and clientSecret that can be used to obtain a JSON Web Token to call Workspace ONE Intelligence APIs.
Create Service Account
After accessing Intelligence, follow the next steps to create a service account for your application:
- Click Settings in the top bar
- Click Service Accounts
- Click ADD
After clicking ADD, choose a name for your service account and click on GENERATE CLIENT SECRET
Note: After clicking on GENERATE CLIENT SECRET a JSON file containing client_id and client_secret will be downloaded, store it in a secure location because client_secret cannot be recovered.
Understanding Service Account Parameters
- Token Endpoint: this URL used to request an Access Token.
- Client Id: is a public identifier for apps, it acts like a username.
- Client Secret: is a secret known only to the application and the authorization server, it acts like a password.
Setting Up Node.js Project
Create a project directory named wsone-intelligence anywhere in your system and make it your current directory:
mkdir wsone-intelligence
cd wsone-intelligence
Execute the following command within the wsone-intelligence directory to initialize your Node.js project with default settings:
npm init
Then, create the entry point of the application, a file named index.js:
touch index.js
Installing Workspace ONE API Wrapper Package
Execute the following command within the wsone-intelligence directory to install the npm package:
npm install --save workspace-one-intelligence-api
Open the project using your favourite IDE
The project content should look like the following:
Steps Generate and Download Report
- Initialize workspace-one-intelligence-api package.
- Get report columns.
- Create report.
- Search report downloads.
- Download report.
Initialize workspace-one-intelligence-api Package
The following piece of code is how you initialize the package with the variables we got from Workspace ONE Intelligence Service Account:
Get Report Columns
We will get users report columns as example. In the following code, we create columns and process them to have an accepted format to create a report method:
After executing the code above, you will get the following results:
Create Report
We will use the columns we got from the previous chapter to create a user's report:
After creating the report, you will get the report ID that looks like the following format:
b06f1152-e423-47c1-8578-f9dbacb96ec0
Search Report Downloads
Each report has multiple downloads each one is generated when you run the report, so when you create a report for the first time a download is generated automatically, so we need to get it's ID to download it.
Report data takes time to generate, so after launching the create report method, you need to use search report downloads to check if the report is ready.
Downloads results are an array so you always check the first index [Ø].
Download Report
When executing the download method, the results will return as CSV data format.
After getting the data, you need to add them to a CSV file.
First we call the file system module like the following:
const fs = require('fs');
After adding the results to a CSV file, the data will look like the following:
Conclusion
Using this package will make is easy to integrate Workspace ONE Intelligence APIs to your Node.js application, because instead of going through the APIs documentation and trying to figure out how the actions flow works, this package does it for you, easy to understand, easy to integrate.
There will be new wrappers for other languages like Python, PHP, ...and so on.
