Using the Workspot Control API

Robert Plamondon -

Workspot provides a REST API for Workspot Control. This API uses standard REST concepts and provides a simple command interface for performing administrative tasks.

This guide shows you how to use the API. The examples use Microsoft PowerShell, which should be readable enough that non-PowerShell users can treat them as pseudo-code when creating equivalent routines.

Accessing the Workspot Control API

The Workspot Control API is reached via https://api.workspot.com

The API homepage is shown below:

api-home.PNG

The API is largely self-documenting. Clicking the api-controller link at the bottom of the page shows a complete list of functions and their syntax:

api-commands.png

Clicking an individual command gives a summary, syntax, error codes and their meaning, and the opportunity to use the command interactively, as shown for the Delete command below:

api-command-details.png

Preparing to Use the API

Before you can use the API, you must do the following:

  1. Contact Workspot and request API access, which is not enabled by default.
  2. Once API access is enabled, a “Setup > API tab” will appear in Workspot Control. This tab contains two parameters you need to access the API:
    1. The Client ID, which uniquely identifies your organization’s API access.
    2. The Client Secret, which validates your identity.

api-control.png

  1. You can generate new API security credentials at any time, at which point any existing ones become invalid.
  2. To access the API, you need to copy both the Client ID and the Client Secret. The Client Secret is normally hidden except for a few digits. Press the Reveal button to make the Client Secret visible.
  3.  You now have the information you need to make API calls.

Making Workspot API Calls

A Workspot REST API call is consists of a properly formatted HTTP POST, GET, or DELETE command with a base URL of https://api.workspot.com/.

To use the API, you need to authenticate yourself. This process uses an OAuth 2.0 token. The OAuth token is generated through a call to https://api.workspot.com/oauth/token. Its parameters include the string “Client_ID:Client_Secret” that you got from Workspot Control, and a few other parameters, such as the email and password of a Control administrator. See the sample code for details.

This token remains valid until it expires, at which point you use the same procedure to generate a new one.

Once you have the OAuth token, you can use the other functions of the API.

 

Example 1: Get a Workspot Usage Report

The example below creates an OAuth token and then calls the API to retrieve a usage report for the indicated date range.

In all the examples in this document, the parameters are declared at the top, but are left blank for security reasons. For this code example, there are two sets of parameters: OAuth token parameters and usage report parameters.

The OAuth parameters are:

  • Client ID
  • Client Secret
  • Control User (email address of a Control admin account)
  • Control Password

The user report parameters are:

  • Start Date for the report in YYYY-MM-DD format, no more than 30 days in the past
  • End date for the report, as above

Optional CSV path for the output file. The report is always fetched in JSON format (the only supported option). If the CSV option is specified, the output is converted into CSV format and saved to the specified file. Otherwise, it is displayed without conversion on the PowerShell console, as shown below:

  • api_user_report.png
  • Most of these values should be self-explanatory except for the following:
    • costCenter is the value in the AD user record field, if any, selected to represent which accounting group the user belongs to. If the cost center feature is not enabled, this will always be blank. See Using the Cost Center Feature in Workspot Control.
    • timeSpent is the number of hours the user spent actively signed in to desktops and apps.
    • Sessions is the number of times the user initiated a new desktop or application session.

Usage Report Request Flow

This example uses Windows PowerShell. The code does the following:

api_usage_2.png

  • Report generation is asynchronous, so the request returns before the report is ready, providing a status/download URL for the request. This URL is tested every five seconds with an HTTP GET until the report is ready. When the report is ready, it is provided in the body of the HTTP response.

4.2. Usage Request Code

###############################################################################
# Sample script to run a Workspot Usage report (for up to a thirty day window #
###############################################################################
###########################

# Variable initialization #

$ApiClientId = "" #Workspot Control API Client ID
$ApiClientSecret = "" #Workspot Control API Client Secret
$WsControlUser = "" #Workspot Control Administrator user email address
$WsControlPass = "" #Workspot Control Administrator user password
$StartDate = "" #First date of range for report, format YYYY-MM-DD
$EndDate = "" #Last date of range for report, format YYYY-MM-DD
$CsvPath = "" #Optional path to output directly to CSV

############################

$ApiClientPair = "$($ApiClientId):$($ApiClientSecret)"
$EncodedApiCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($ApiClientPair))
$HeaderAuthValue = "Basic $EncodedApiCreds"
$Headers = @{Authorization = $HeaderAuthValue}
$PostParameters = @{username=$WsControlUser;password=$WsControlPass;grant_type='password'}
$ApiReturn = Invoke-RestMethod -Uri "https://api.workspot.com/oauth/token" -Method
    Post -Body $PostParameters -Headers $Headers
$ApiToken = $ApiReturn.Access_Token
$Headers = @{Authorization =("Bearer "+ $ApiToken)}

$RestUri =
$ReportParams = @{
    end = $EndDate
    format = "JSON"
    start = $StartDate
}
$ReportParamsJson = $ReportParams | ConvertTo-Json
$ReportStatusUrl = (Invoke-RestMethod -Uri "https://api.workspot.com/v1.0/reports/generateusagereport" -Method Post -Headers
    $Headers -Body $ReportParamsJson -ContentType 'application/json').StatusUrl
Do {
    Start-Sleep -Seconds 5
    $StatusReturn = Invoke-RestMethod -Method GET -ContentType "application/json" -Uri
        $ReportStatusUrl -Headers $Headers
} Until($StatusReturn.Status -ne "InProgress")

If($CsvPath) { #Output to path specified for CSV file
    (Invoke-RestMethod $StatusReturn.details.downloadUrl).UsersUsage | Export-CSV
        $CsvPath -NoTypeInformation
}

$ReportArray = (Invoke-RestMethod $StatusReturn.details.downloadUrl).UsersUsage
#Write report to object in JSON format

$ReportArray #Display report to PowerShell Console

 

Have more questions? Submit a request

Comments

Powered by Zendesk