Using the Workspot Control API

  • 14 October 2022
  • 0 replies
  • 447 views

Userlevel 4
Badge
  • Workspot Community Administrator
  • 0 replies

Using the Workspot Control API

Last update: March 18, 2024 by Robert Plamondon

 

Content

 

 

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.

The API is available for Workspot installations in both the Microsoft Azure and Google GCP Clouds. The two behave identically, except that the "redeploy," "screenshotDesktop," "moveDesktop," and "cancelMoveDesktop" commands are not currently available for GCP.

The basics of making API calls are covered in preparing to use the API and Making Workspot API Calls. A PowerShell example is given in Example: Get a Workspot Usage Report.

 

Most commands are self-documenting through https://api.workspot.com, but a few require more explanation, which is provided here:

Accessing the Workspot Control API

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

The API homepage is shown below:

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, part 1.


API commands, part 2.

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:

 

Limitations

 

General

You cannot take the successful completion of a command for granted and must poll its status and be prepared to resubmit it if it fails in part or in full.

Concurrent Provisioning of Desktops

Only a limited number of desktop provisioning requests can be outstanding at any given time. This is across all Clouds and pools. If the current limit is exceeded, any rejected requests will have a status message like this:

{

    "status": "Failed",

    "startTime": "2024-02-06T10:50:37.621Z",

    "endTime": "2024-02-06T10:50:37.644Z",

    "details": null,

    "errorInfo": {

        "error": "maxConcurrentProvisioningError",

        "description": "You have reached the max concurrent provisionings allowed. Please wait for some time and try again."

    }

}

In addition to this limit, no desktops are provisioned in parallel. Provisioning is always one desktop at a time.

 

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 screenshot 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 screenshot expires after 15 minutes.

Remote Assistance API Call

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

 

Moving Desktops

The moveDesktop command lets you transfer a persistent desktop to a different pool while keeping it assigned to the same user. The desktop is transferred, the new desktop is powered up, and when this succeeds, the old desktop is deleted. However, a snapshot of the original is retained and can be restored by Workspot Support.

Note: This command is available only on Azure, and for persistent desktops only.

How it Works

Moving a desktop does the following:

  1. The source desktop is shut down.
  2. A snapshot is made of the source desktop.
  3. A copy of the desktop is made in the target pool.
  4. The new desktop is powered on.
  5. The Workspot Agent registers the desktop.
  6. The end-user's assignment is transferred to the new desktop. When the end-user launches the desktop, everything seems the same as before, including the desktop's DNS name.
  7. The source desktop is deleted.

Best Practices When Moving Desktops

Moving desktops can be disruptive to users and can run into throttling limits with Cloud providers. Use these best practices when moving desktops:

  1. Do not reboot or redeploy a desktop VM while migration is in progress. During migration, the desktop will be inaccessible and the end-user may try to reboot it. To minimize this problem, move desktops during off-hours, inform the users of the downtime, or both.
  2. Limit the number of simultaneous moveDesktop calls. The number of outstanding API calls to create or move desktops should be capped at ten for your entire enterprise.
  3. Add a delay of 60 seconds or more between moveDesktop calls.

Limitations

  • The moveDesktop and cancelMoveDesktop calls are available only for Azure persistent desktops.
  • Desktops that are suspended, are part of a regional disaster recovery event, or have a connected user cannot be moved.
  • Both the source and the target pools must be in the same Azure region.
  • The target desktop pool has to use a VM that's consistent with the source pool. For example, you cannot move a GPU workstation into a non-GPU pool. In general, the SKUs have to be the same.

Troubleshooting

  • Failures in the early stages of the move leave the source desktop in place, and it is still the copy assigned to the end-user. Very early failures (when powering down or backing up the source desktop) cause the source desktop to be powered back on, making it available to the user.
  • If the failure happens later in the process, the source desktop remains powered down. If the end-user's desktop assignment hasn't been transferred to to the target desktop, rebooting the source desktop is all that is required. Otherwise, use the cancelMoveDesktop API command to bring back the source desktop.
  • If for some reason the Workspot Agent takes more than a few hours to register the desktop with Workspot Control, auto-registration will fail and will have to be registered manually with the pool's Agent Token by running “C:\Program Files\Workspot Agent\reregister_poolvm.bat tokenvalue" on the desktop VM.

 

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:
    • The Client ID, which uniquely identifies your organization’s API access.
    • The Client Secret, which validates your identity.
  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: 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:

 

  • 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 are 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:

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

 

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').StatusUrlDo {
    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

     © 2024 Workspot


0 replies

Be the first to reply!

Reply