Classrooms extension REST API reference

This document contains detailed information about the REST API resources and operations associated with Classrooms extension.

For information about other Skytap API resources, see Skytap API quick start.

Contents

Courses resource

https://cloud.skytap.com/v2/courses/{course-id}.json

Courses v2 resource model

The following fields are defined:

Field Name

Type

Access

Description

id

string

ro

Course identifier

name

string

rw

Name of the course. Max. 64 characters.

description

string

rw

Description of the course. Max. 1000 characters.

template_ids

array

rw

Array of template IDs (strings) used by the course.

At this time, courses must have exactly 1 template.

template_missing

Boolean

ro

Indicates whether the template used by the course has been deleted. (A class cannot be provisioned if the template is missing.)

max_labs

integer

rw

Maximum number of labs which can be created for a class created from this course.

Valid range: 1 to 20, inclusive. 20 by default.

vm_access

array

rw

An array of hashes representing the VM access settings for each VM in the template. If vm_access is not defined during course creation, all VMs are set to have run_and_use permissions.

Each hash has the following subset of attributes:

  • vm_ref | string | rw

    The VM ID or URI.

    (When writing to this field, enter the VM ID; in the response, the API will return the VM URI)

  • name | string | ro

    The VM name

  • access | string | rw

    The Access level for the VM. Must be one of:

    • do_not_publish (Labeled “Excluded” in the UI)
    • view_only
    • use
    • run_and_use (Labeled “Full Control” in the UI)

anonymous_smart_rdp

Boolean

rw

If true, the lab environment includes the option to download a SmartRDP file. This file will provide access to the environment while the sharing portal is active.

False by default.

sso_required

Boolean

rw

This field is only available for accounts with SSO enabled.

If true, the lab environment uses SSO to authenticate users. If true, password (below) must be empty.

support_url

string

wo

Used to customize the support link that appears with the lab environment. If this field is empty, the default help page will be used ( http://help.skytap.com/SmartClient_Help_Page.html).

String format must be one of the following:

  • http://example.com
  • https://example.com
  • mailto:support@example.com

custom_content_enabled

Boolean

rw

If true, the lab environment includes a second tab with the contents of the custom_content field. The tab must have a name, defined in the custom_title field below.

False by default.

custom_title

string

rw

Name of the custom content tab. Max. 32 characters.

This field is required if custom_content_enabled is true.

custom_content

string

rw

The content you want displayed in the custom content tab. The string can contain plain text or HTML. Limited to 32kb (approximately 32,000 characters).

For a list of supported HTML tags, see HTML Tags Allowed in Custom Content. For starter templates, see Custom Content for Published URLs - Starter Templates.

This field is required if custom_content_enabled is true.

custom_content_is_default

Boolean

rw

If true, the custom content tab is displayed first when the lab environment is accessed by a student (instead of displaying the VMs tab first).False by default.

class_count

integer

ro

The number of current training classes created from this course.

This includes classes in any state (scheduled, expired, etc.); it does not include courses that have been deleted.

created_at

timestamp

ro

The date and time the course was created.

last_deployed

timestamp

ro

The most recent time that a class was provisioned from this course.

can_edit

Boolean

ro

If true, the user has permission to edit the course.

owner_id

string

ro

The ID of the course owner.

owner_name

string

ro

The full name of the course owner.

owner_url

URI

ro

The URI of the course owner.

last_updated_by

object

ro

A representation of the most recent user to modify this course.

storage

integer

ro

Storage size of the course template (in GB).

templates

array

ro

An array of course template objects.

Operations on courses

Get course

Request

GET https://cloud.skytap.com/v2/courses/{course-id}.json

Response

Representation of the course.

Get list of courses

Request

GET https://cloud.skytap.com/v2/courses.json?count=10&offset=0

Required parameters

count – Indicates the number of results to return. Used with offset to create paginated results.

offset – Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return a list of 50 courses owned by a particular user and that have been created in the last 30 days, you could use the following request:

GET https://cloud.skytap.com/v2/courses?query=user_id:12345&created_at=now-30d+to+now&count=50&offset=0

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

name Filters results by keyword (Example: query=name:centOS).
user_id Filters results by resource owner (Example: query=user_id:12345). Limited to one user_id per request.

created_at

string

Filters by course creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp

last_deployed

string

Filters by course last deployed date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp

sort

string

Sorts the results either in ascending or descending order.

Options:

  • Sort by date created: created_at or created_at_desc
  • Sort by date last deployed: last_deployed or last_deployed_desc
  • Sort by name: name or name_desc
Response

Returns a list of courses.

Get list of classes created from a course

Request

GET https://cloud.skytap.com/v2/courses/{course-id}/classes.json

Response

Returns a list of classes.

Create course

Request

POST https://cloud.skytap.com/courses.json

{
    "name": "New course",
    "description": "API test",
    "max_labs": "15",
    "template_ids": [
        "12345"
    ],
    "vm_access": [
        {
            "vm_ref": "11111",
            "access": "run_and_use"
        },
        {
            "vm_ref": "22222",
            "access": "view_only"
        }
    ]

}
Required parameters
  • name
  • description
  • template_ids
  • max_labs
Response

Representation of the new course

Schedule a class from the course

Request

POST https://cloud.skytap.com/courses/{course-id}/classes.json

{
    "start_at": "New course"
}
Required parameter
  • start_at
Optional parameters

See the Classes resource model for a list of editable class fields.

Response

Representation of the new class.

Edit course

Request

PUT https://cloud.skytap.com/v2/courses/{course-id}.json

{
    "name": "Change course name"
}

If the template is changed and new VM access controls are not set, VM access will be reset to allow full access to the VMs.

Response

Representation of the updated course.

Delete course

Request

DELETE https://cloud.skytap.com/v2/courses/{course-id}.json

The course cannot be deleted if there are any classes associated with it. The class_count field must be 0.

Response

Deleted course

Export course report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/courses/exports.json

To request the report be emailed to you when it is complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/courses/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}
Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    GET https://cloud.skytap.com/v2/courses/exports/123456.json
    
    {
       "id": "123456",
       "ready": true,
       "url": "https://cloud.skytap.com/v2/courses/exports/123456",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

    Sample request:

    GET https://cloud.skytap.com/v2/courses/exports/123456.csv

Response

The report is downloaded.

Classes resource

https://cloud.skytap.com/v2/classes/{class-id}.json

Classes v2 resource model

The following fields are defined:

Field Name

Type

Access

Description

id

string

ro

Class identifier.

name

string

rw

Name of the class. Max. 64 characters.

If not defined, course name is used.

description

string

rw

Description of the class. Max. 1000 characters. If not defined, course description is used.

course_id

array

rw

ID of the training course this class is based on.

start_at

timestamp

rw

The date and time the class is scheduled to begin. Format: YYYY/MM/DD HH:MM:SS (Example: 2015/11/28 10:45:00).

The class provisioning and class run times are calculated relative to the class start time.

end_at

timestamp

rw

The date and time the class is scheduled to end. Format: YYYY/MM/DD HH:MM:SS (Example: 2015/11/28 10:45:00).

The class shut down and cleanup times (if present) are calculated relative to the class endtime.

time_zone

array

rw

Time zone for start_at, end_at, start_time, end_time, and expiration_date. If this is not defined, your personal time zone is used.

For a list of time zones, see Time zones and UTC offsets.

provision_hours

integer

rw

Instructs Classrooms extension to automatically create the lab environments X hours prior to the start_at time. Default is 24 hours; allowed range is 1 to 336 hours.

run_hours

integer

rw

Instructs Classrooms extension to automatically run the lab environments X hours prior to the start_at time. Default is 24 hours; allowed range is 1 to 336 hours. Must be less than or equal to provision_hours.

cleanup_hours

integer

rw

Instructs Classrooms extension to automatically delete the lab environments X hours after the end_at time. If not set (or if end_at is unset), the environments are not deleted automatically.

shutdown_hours

integer

rw

Instructs Classrooms extension to automatically shut down the lab environments X hours after the end_at time. If not set (or if end_at is unset), the environments are not shut down automatically. Must be less than or equal to cleanup_hours (if both are used).

delete_at_end

Boolean

ro

Indicates whether the lab environments will be deleted when the class is over (based on values in end_at and cleanup_hours). If either is unset, this value is false.

daily_startup_time

daily_shutdown_time

strings

rw

Optional settings for multi-day classes. Used to schedule daily, automatic runstate changes for student lab environments.

  • HH:MM format.
  • The first time you set daily run and shut down times, daily_startup_time and daily_shutdown_time must be entered as a pair. When editing existing multi-day run and shut down settings, daily_startup_time and daily_shutdown_time can be edited separately.
  • For more information, see the instructions for creating a class.

start_time

end_time

strings

rw

Used to restrict the time of day that students can access their lab environment.

  • When defining an access window, start_time and end_time must be entered as a pair. When editing an existing access window, start_time and end_time can be edited separately.
  • HH:MM format.
  • To delete an access window, enter null for start_time and end_time.

runtime_limit

integer

rw

The number of minutes that students can access the lab environment (while the lab environment is running). Once this limit is met, access is restricted; the VMs are not suspended by this action. Null if not in use.

expiration_date

timestamp

rw

Expiration date and time for student access to the lab environment. Format: YYYY/MM/DD HH:MM:SS (Example: 2015/11/28 10:45:00). Null if not in use.

password

string

wo

If a password is included in this field, it is required for student access to the lab environment. If you do not want to require a password for access, enter an empty string in this field.

access_code

string

ro

Access code for the shareable class management view URL.

The class management view URL is https://cloud.skytap.com/instructor/<class-id>

state

string

ro

The class status. One of the following:

  • scheduled
  • incomplete
  • provisioning
  • provisioned
  • started
  • running
  • shutdown
  • expired
  • pending_cleanup
  • pending_deletion

The following class states are deprecated. New classes will not enter these states:

  • provisioning_error
  • starting_error
  • shutdown_error
  • starting

created_at

timestamp

ro

The date and time the class was created.

can_edit

Boolean

ro

If true, the user has permission to edit the class.

owner_id

string

ro

The ID of the class owner.

owner_name

string

ro

The full name of the class owner.

owner_url

URI

ro

The URI of the class owner.

lab_count

integer

ro

The number of labs defined in the class settings.

labs_created_at

timestamp

ro

Date and time when the create class lab environments operation completed. If unsuccessful or if labs have not been created yet, this field is null.

labs_run_at

timestamp

ro

Date and time when the run class lab environments operation started. If unsuccessful or if labs have not been run yet, this field is null.

labs_deleted_at

timestamp

ro

Date and time when the delete class lab environments operation completed. If unsuccessful or if labs have not been deleted yet, this field is null.

labs_shutdown_at

timestamp

ro

Date and time when the shut down class lab environments operation started. If unsuccessful or if labs have not been shut down yet, this field is null.

error_message

string

ro

The most recent error message, if any, which resulted from a failed attempt to create, run, shut down, or delete the lab environments.

regions

array

ro

A list of region names corresponding to the templates used by the class.

Operations on classes

Get class

Request

GET https://cloud.skytap.com/v2/classes/{class-id}.json

Response

Representation of the class.

Get list of classes

Request

GET https://cloud.skytap.com/v2/classes.json

Required parameters

count – Indicates the number of results to return. Used with offset to create paginated results.

offset – Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return a list of 50 classes owned by a particular user and that have been created in the last 30 days, you could use the following request:

GET https://cloud.skytap.com/v2/classes?query=user_id:12345&created_at=now-30d+to+now&count=50&offset=0

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

Name

Description

name

Filters results by keyword (Example: query=name:centOS).

user_id

Filters results by resource owner (Example: query=user_id:12345). Limited to one user_id per request.

course_id

Filters results by course (Example: query=course_id:1111). Limited to one course_id per request.

state

Filter request by class status (Example: query=state:running).

Options:

  • scheduled
  • incomplete
  • provisioned
  • provisioning_error
  • starting
  • started
  • starting_error
  • running
  • shutdown
  • shutdown_error
  • expired
  • pending_cleanup
  • pending_deletion
  • error (Returns classes in any error state)

region

Filters results by region name (Example: query=region:US-Central).

created_at

string

Filters by class creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp

last_deployed

string

Filters by class last deployed date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp

sort

string

Sorts the results either in ascending or descending order. Options:

  • Sort by date created: created_at or created_at_desc
  • Sort by name: name or name_desc
  • Sort by owner: owner_name or owner_name_desc
Response

a list of classes.

Create class

  • Create a new class by scheduling the class from a course. For instructions, see Schedule a class.
  • Create one or more labs for the class. For instructions, see Add labs to a class.

The class remains in an Incomplete state until at least one lab is added to it.

Edit class

Request

PUT https://cloud.skytap.com/v2/classes/{class-id}.json

{
    "name": "Change class name"
}
Response

Representation of the updated class.

End an In Progress class

Request

PUT https://cloud.skytap.com/v2/classes/{class-id}.json

{
    "end_at": "2017/01/10 12:00:00"
}

Notes:

  • The class status must be running.
  • end_at must be in the format YYYY/MM/DD HH:MM:SS (Example: 2017/11/28 10:45:00). The time zone is inherited from the class start time.
Response

Representation of the updated class.

Delete class and all lab environments created for the class

Request

DELETE https://cloud.skytap.com/v2/classes/{class-id}

Response

Deleted class; the lab environments in the class are also deleted.

Export class report (.CSV)

Request
Step 1: Create the report

POST https://cloud.skytap.com/v2/classes/exports.json

To request the report be emailed to you when it is complete, append ?notify_by_email=1 to the URL.

Response
Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/classes/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}
Request
Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    GET https://cloud.skytap.com/v2/classes/exports/123456.json
    
    {
       "id": "123456",
       "ready": true,
       "url": "https://cloud.skytap.com/v2/classes/exports/123456",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL. Sample request

     GET https://cloud.skytap.com/v2/classes/exports/123456.csv
    
Response

The report is downloaded.

Class labs resource

https://cloud.skytap.com/v2/classes/<class-id>/labs

Class labs v2 resource model

The following fields are defined:

Field Name

Type

Access

Description

id

string

ro

ID of the lab.

class_id

string

ro

ID of the class this lab belongs to.

name

string

rw

Name that appears in the student lab environment access link.

template_name

string

ro

Name of the Skytap template used to create the lab environment.

template_id

integer

ro

ID of the Skytap template used to create the lab environment.

region

string

ro

Region where the Skytap template is located.

configuration_id

string

ro

ID of the Skytap environment.null before lab environments are provisioned.

desktops_url

string

ro

URL for accessing the student lab environment. null before lab environments are provisioned.

state

string

ro

The lab status. One of the following:

  • initialized
  • provisioning
  • provisioned
  • provisioning_error
  • starting
  • started
  • starting_error
  • shutting_down
  • shut_down
  • shutdown_error
  • deleting
  • deleted
  • deletion_error

Operations on class labs

Get list of labs in a class

Request

GET https://cloud.skytap.com/v2/classes/{class-id}/labs.json

Response

Representation of the class labs.

Get information about a lab

Request

GET https://cloud.skytap.com/v2/labs/{lab-id}.json

Response

Representation of the class labs.

Add labs to a class

Request

Request to add one lab

POST https://cloud.skytap.com/v2/classes/{class-id}/labs.json

{
    "name": "Lab name 1"
}

Request to add multiple labs

POST https://cloud.skytap.com/v2/classes/{class-id}/labs/create_multiple.json

[
    {
        "name": "Lab name 1"
    },
    {
        "name": "Lab name 2"
    }
]

These requests will cumulatively add labs to the class. Previous labs are not overwritten or removed.

Response

Representation of the added lab(s).

The operation will fail if the maximum labs count would be exceeded.

Edit class lab

Request

PUT https://cloud.skytap.com/v2/lab/{lab-id}.json

{
    "name": "New lab name"
}

Labs cannot be edited after the class is provisioned or while the lab state is provisioning.

Response

Representation of the updated class.

Remove lab from class

Request

DELETE https://cloud.skytap.com/v2/lab/{lab-id}.json

Labs cannot be removed when their state is provisioning, starting, or shutting_down.

Response

No response body.

Export class labs report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/classes/{class-id}/labs/exports.json

To request the report be emailed to you when it is complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/labs/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}
Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    GET https://cloud.skytap.com/v2/labs/exports/123456.json

    {
       "id": "123456",
       "ready": true,
       "url": "https://cloud.skytap.com/v2/labs/exports/123456",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

    Sample request

    GET https://cloud.skytap.com/v2/labs/exports/123456.csv

Response

The report is downloaded.

Class environments resource

https://cloud.skytap.com/v2/classes/{class-id}/configurations

Class environments v2 resource model

The class environments resource returns an array of environments created for the class. For more information about the fields returned for each environment, see v2 Environments resource.

Operations on class environments

Get list of environments in a class

Request

GET https://cloud.skytap.com/v2/classes/{class-id}/configurations.json

Response

Representation of the class environments.

Operations on existing resources

Operations on users

Give a Skytap Cloud standard user or user manager access to the Classrooms extension

Request

PUT https://cloud.skytap.com/users/<user-id>?classrooms_access=<true>

Notes

  • This is a v1 API request.
  • You must be a user manager or administrator to make this request.
  • This permission cannot be edited for restricted user or administrator accounts. For more information, see Additional user permissions.
Response

Updated user account.

Operations on auditing

Generate an auditing report on Classrooms extension activity

To generate a Skytap auditing report, see Auditing reports resource.

The Classrooms extension adds new auditing activities that appear in your auditing reports.

For more information, see Auditing actions related to the Classrooms extension.

  Activity Name
Add template to training course AddTemplateToTrainingCourseHistory
Clean up training class CleanUpTrainingClassHistory
Create training class CreateTrainingClassHistory
Create training course CreateTrainingCourseHistory
Create training lab CreateTrainingLabHistory
Delete training class DeleteTrainingClassHistory
Delete training course DeleteTrainingCourseHistory
Delete training lab DeleteTrainingLabHistory
Failed training class instructor login FailedTrainingClassInstructorLoginHistory
Grant user classroom access GrantUserClassroomAccessHistory
Provision training class ProvisionTrainingClassHistory
Remove template from training course RemoveTemplateFromTrainingCourseHistory
Revoke user classroom access RevokeUserClassroomAccessHistory
Run training class RunTrainingClassHistory
Shutdown training class ShutdownTrainingClassHistory
Update training class UpdateTrainingClassHistory
Update training course UpdateTrainingCourseHistory
Update training lab UpdateTrainingLabHistory

Change log

November 2017

  • Added state field in Class labs resource. This field displays the lab status.

    • Also updated description of Edit lab and Remove lab operations in the Class labs resource. Labs cannot be edited while a lab is in a Provisioning state; labs cannot be removed while they are in a Provisioning, Starting, or Shutting down state.
  • Updated description of state field in Classes resource. Several status options (Provisioning error, Starting error, Shutting down error, and Starting) are considered legacy and do not apply to classes created after this release.

September 2017

  • Added configuration_id field in Class labs resource. This field displays the Skytap environment ID associated with a lab.
  • Fixed the following documentation errors:

    • Changed maximum run_hours value to 336; previously, this was 48 (see Classes resource).
    • Added max_labs as a required field when creating a course (see Courses resource).

August 2017

  • Labs can now be added and removed after the class is provisioned (see Class labs resource).
  • Added daily_startup_time and daily_shutdown_time fields to the Classes resource. These are used to set daily run and shut down times for multi-day classes.
  • Added list of auditing activity names that are unique to the Classrooms extension.

June 2017

April 2017

February 2017

  • Increased maximum limit for provision_hours field in Classes resource from 48 hours to 336 hours.

January 2017

  • Published initial draft.