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

Details About Selected Commands

Taking a Desktop Screen Shot

The API allows you to take screen captures of desktops. The snapshot is of the login screen only; it returns nothing if there’s an active desktop session.

When the screen shot is complete, the Status URL contains a link to the screen capture. This is typically used to debug boot issues, such as the desktop being unavailable because a Windows Update is being applied. The screen shot expires after 15 minutes.

api-screenshot.png

Remote Assistance API Call

api-remote-assistance-5.png

Remote assistance sessions can now be initiated from the Control API (in addition to from the Control UI). The parameters for the API call are:

  • Email address: The address Control associates with the end-user needing assistance.
  • desktopID: The desktop ID string of the end-user, as given by the API.
  • Password: A temporary password used only for this Remote Assistance session, set by the administrator.
  • poolID: The ID of the desktop pool containing the end-user’s desktop.

As with any Remote Assistance session, the end-user’s system will generate a .msrincident file. This will be transferred to Workspot Control by the Workspot Agent on the desktop, then uploaded to the Cloud. A link to this file is contained in the Status URL response.

The Expert role for the Remote Assistance session can be accepted by any user with access to the .msrincident file, the password, and who has a desktop with access to the same network as the end-user. In other words, once the expert has the .msrincident file and the and the password, a standard Remote Assistance session is the next step.

The .msrincident file expires one hour after creation, so the Remote Assistance session must be started before then.

The response format is given below. api-remote-assistance-4.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

 

Related Document

Have more questions? Submit a request

Comments

Powered by Zendesk