Launch a lab
    • 10 Jun 2024
    • 5 Minutes to read

    Launch a lab


    Article summary

    Get
    /launch

    The Launch command will launch a specified lab for a specified user.

    Security
    API Key
    Header parameter nameapi_key

    All methods require an API key, which must be obtained from Skillable. This key is used by Skillable to validate your account. The key can be passed as an HTTP request header with the header name "api_key".

    Query parameters
    labid
    integer (int32) Required

    The ID of the lab profile.

    userid
    stringRequired

    The ID you use to identify the user in your external system.

    firstname
    string

    An optional parameter used to set the user’s first name. If this value is not provided for a new user a random anonymized value in the format 'anon-#######' will be created.

    lastname
    string

    An optional parameter used to set the user’s last name. If this value is not provided for a new user a random anonymized value in the format 'anon-########' will be created.

    email
    string

    An optional parametre used to set the user’s email address.

    classId
    string

    An optional parameter used to associate the lab with a class (see GetOrCreateClass). This is the unique identifier of the class as it is represented in your organization.

    canBeMarkedComplete
    integer (int32)

    An optional parameter used to specify if the lab can be marked as complete by the student. 1 = true, 2 = false. If not specified, defaults to 1 (true).

    Valid values[ 1, 2 ]
    Default"1"
    tag
    string

    An optional parameter that can be used for tagging the lab instance with your own custom data.

    ipAddress
    string

    When specified, Skillable will attempt to launch the lab in the closest available delivery region. You should provide the IP address of the user that is taking the lab, not the IP address of your system. IPv4 and IPv6 address are supported.

    regionId
    integer (int32)

    When specified, Skillable will attempt to launch the lab in the specified delivery region if a suitable host in that region is available and all required storage is available in that region. Delivery regions can be found using the DeliveryRegions command or Catalog command. Using the ipAddress parameter will result in a more reliable geo-location of the lab for the end user.

    roleId
    integer (int32)

    Allows you specify the role(s) to assign to the user. You may pass multiple instances of this parameter to specify multiple roles. Roles are used for specialized integration purposes and are not needed in typical integration scenarios. Role IDs will be provided by Skillable when appropriate.

    variable-name
    string

    Allows you to set the values of named variables used within the lab instance. The key must start with the fixed text variable-.

    maxSavedLabs
    integer (int32)

    The max number of labs an individual user may save is capped by the number configured on your API consumer.

    maxActiveLabs
    integer (int32)

    The max number of concurrent lab instances is capped by the number configured on your API consumer.

    lang
    string

    Allows you to override the language of the Instruction Set as well as the lab client UI language. This affects lab client UI elements like menus, tabs, and dialogs. Using this in connection with instructionsId will allow you to select launching labs with a specific Instruction Set in the specified language if they have been defined within the lab profile.

    NOTE: If this parameter is omitted, or if the specified language is not specified on one of the Instruction sets in a lab profile, then the default language as defined in the Lab Profile âž” Manage Instructions Sets option.

    en = English
    es = Spanish
    fr = French
    de = German
    pt = Portuguese
    ja = Japanese
    zh-hans = Simplified Chinese
    zh-hant = Traditional Chinese
    ko = Korean

    Valid values[ "en", "es", "fr", "de", "pt", "ja", "zh-hans", "zh-hant", "ko" ]
    instructionsId
    string

    When specified, Skillable will attempt to launch the lab and present the selected instructions. If not specified, or the instruction Id could not be found, the default instructions, as defined on the Lab Profile, will be used instead. This is a string that cannot contain spaces.

    NOTE: To be able to see how to use this parameter, add the column "API Example" in the Manage Instruction Sets feature while editing the instructions.

    Responses
    200

    OK Response.

    Example of a successful lab instance launch
    {
      "Result": 1,
      "Url": "https://labondemand.com/console/setup/1b4909d6-0dbe-43db-9ab9-74ee4f913c4e",
      "LabInstanceId": 3896477,
      "Expires": 1337977153,
      "Status": 1,
      "Error": null
    }
    object
    Result
    integer (int32)

    Result of the launch command. Possible values are:
    0 = Error
    1 = Success
    2 = User has too many active labs
    3 = Insufficient host resources
    5 = API integration has too many active labs
    6 = User has a saved instance of this lab
    7 = API integration doesn't have enough available RAM
    10 = User doesn't have enough available RAM
    20 = User's organization has too many active labs
    30 = User's organization doesn't have enough available RAM
    40 = Lab profile has too many active instances
    50 = Lab organization doesn't have enough available RAM
    60 = Lab organization has too many active instances
    70 = Lab series has too many active instances
    80 = Lab series doesn't have enough available RAM
    90 = Too many labs within the specified class are currently active for another lab to be launched.
    100 = User has launched the maximum number of instances of this lab profile.
    110 = This lab is not currently available for launch via API. It is awaiting security review.
    120 = Lab instance is not in the correct state to perform the requested action.
    130 = This lab is not currently available for launch via API. It is awaiting security review.
    140 = The request is invalid or contains invalid parameters.
    150 = The participant lab instance cannot be launched because the shared class environment is not currently available.
    160 = The lab cannot be launched because the user is required to provide additional information.

    Url
    string

    A URL where the lab can be viewed by the user.

    LabInstanceId
    integer (int64)

    The Id assigned to the new lab instance.

    Expires
    integer (int64)

    When the lab will expire (in Unix epoch time).

    Status
    integer

    Indicates the status of the API request.
    0 = Error
    1 = Success

    Error
    string | null

    In the event of an error, this will contain a detailed error message.


    Was this article helpful?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.