Using the Lab Client API to Customize Labs

Overview

The Lab Client API is a public, managed client-side API that allows you to customize and integrate labs into your own applications or portals. It provides two ways to interact with the lab client:

• Direct JavaScript access: Call methods directly from theme scripts using the global window.api object.

• postMessage integration: Send and receive messages between the lab client (when embedded in an Iframe) and your parent application.

Lab developers have historically customized the lab client using internal or private JavaScript APIs. The risk with this method is that changes to internal APIs can cause labs to break, leading to support issues and deployment risks.

To address this, we developed the Lab Client API. This API provides a stable, supported interface for customization, allowing customers to safely integrate with the lab client while giving our internal teams the flexibility to evolve the platform without impacting existing integrations.

Benefits

• Eliminates breakage caused by internal API changes

• Enables safe, supported customization for customers and internal teams

• Supports robust automated testing of public APIs

• Accelerates onboarding and ensures safer deployments

• Unlocks new capabilities for integrators and power users

Intended Audience

This API is designed for users who need to customize or extend the lab client through stable, supported integrations. It primarily supports these groups:

• Lab developers and admins integrating with external systems

• Customers requiring custom workflows

Typical roles include:

• Lab Developer

• Admin

• Integration Engineer

• Power User

Key Features

The Lab Client API is designed to give you flexibility whether you're working inside the lab client or embedding it into your own site.

Global API Object ( window.api )

The global API object is available on all top-level lab client pages, including LabClient, VirtualizationClient, and Instructions. It provides a stable, documented, and versioned interface with uniform method signatures and responses (regardless of the page context).

Each lab client page exposes a global window.api object in the JavaScript namespace.

JavaScript Access

Use a set of JavaScript methods and events inside theme scripts. Calling API methods directly through window.api lets you integrate custom logic and behaviors right inside your lab Themes for a simple, fast, flexible solution.

postMessage Interface

All API methods are available via standard browser postMessage calls. Parent applications embedding the lab client in an iframe can:

• Send commands (e.g., "go to instruction page 7")

• Receive notifications on events like VM state changes, instruction page changes, and activity completion

Communication is secure, asynchronous, and based on standard browser messaging.

How it Works

If you're embedding the lab client in an iframe (for example, inside your portal or LMS), you can use the postMessage API to send commands to the lab and listen for events, following this workflow:

1. Your parent application sends a message, with the method name and any required parameters, to the lab client.

2. The lab client executes the method and sends a response back when needed.

3. The lab client also broadcasts important events automatically to the parent.

Benefits

• Seamless integration with portals, LMS platforms, or other external applications.

• Asynchronous, decoupled communication between the host and the lab client that doesn't block or slow down your application.

• Flexible workflows that support both direct commands and even-driven integrations.

Backward Compatibility and Safety

To support our efforts in providing a secure, stable public API, we plan to deprecate older internal and private APIs. The Lab Client API is the supported path going forward, with ongoing versioning, testing, and documentation to ensure long-term stability.

Lab Client API Methods by Category

Common Use Cases

Use the Lab Client API to extend and customize lab experiences in various ways. Here are some common scenarios and the methods they use:

1. Manage lab variables programmatically

Create, update, and retrieve lab variables, as well as obtain lab tokens, without using the UI.

Example scenarios:

• Automate lab setup for new courses

• Bulk update lab variables for a training event

API methods/events used: getLabVariable, setLabVariable, getLabToken

2. Integrate labs in a parent application (via postMessage)

Embed the lab client in an iframe and control it directly from your application or portal using the postMessage interface.

Example scenarios:

• A customer portal embeds the lab client and tracks learner progress

• A parent app customizes instruction navigation

API methods used: All API methods and events are accessible via postMessage.

3. Monitor and react to environment connection status

Detect when a VM connects or disconnects, and update the user experience accordingly.

Example scenarios:

• Show a warning if a VM disconnects

• Log connection drops for analytics

API methods used: getEnvironmentConnectionStatus, onEnvironmentConnectionStatusChange

4. Automate text input in lab environments

Send commands, credentials, or code snippets directly into a VM for demos, testing, or guided labs.

Example scenarios:

• Auto-fill credentials

• Paste code samples for users

API methods used: sendTextToEnvironment

5. Track and control instructions navigation

Monitor and control the flow of lab instructions, making it easy to align with custom learning paths or LMS integrations.

Example scenarios:

• Advance instructions based on external triggers in a parent app

• Track which instruction page a user is currently on

API methods used: getInstructionsPageIndex, gotoInstructionsPage, onInstructionsPageChanged

6. Monitor and respond to activity completion

Detect when users complete lab activities and trigger external workflows, progress tracking, or gamification.

Example scenarios:

• Award badges when an activity is complete

• Sync user progress with an external LMS

API methods used: evaluateActivity, onActivityCompleted

7. Manage lab session timing

Monitor session time remaining and take action before a lab expires.

Example scenarios:

• Show a countdown timer to the learner

• Auto-save user work before time runs out

API methods used: getMinutesRemaining

8. Manage lab variables dynamically

Update and monitor lab variables in real time on adaptive labs or integrations.

Example scenarios:

• Update environment settings on the fly

• Sync lab variables with external systems

API methods used: getLabVariable, setLabVariable, onLabVariableChanged

Example Workflows

These examples show how you can combine multiple API methods to build common integrations. Each workflow includes the goal, flow, and a sequence diagram to illustrate the interaction between the parent application and the lab client.

1. Auto-fill credentials on VM connection

Automatically send login credentials to the VM when it connects.

Workflow:

1. The parent app listens for onEnvironmentConnectionStatusChange .

2. When the status is Connected, the parent app calls sendTextToEnvironment with credentials.

API methods used: onEnvironmentConnectionStatusChange , sendTextToEnvironment(text)

sequenceDiagram

    participant ParentApp

    participant LabClient

    LabClient->>ParentApp: postMessage (onEnvironmentConnectionStatusChange: "connected")

    ParentApp->>LabClient: postMessage (event_id: "sendTextToEnvironment", text: "username/password")

    LabClient-->>LabClient: Executes sendTextToEnvironment(text)

2. LMS-driven instructions navigation

Let an LMS system control which instruction page learners see.

Workflow:

1. The LMS sends gotoInstructionsPage(index) via postMessage.

2. The lab client navigates to the page.

3. The lab client broadcasts onInstructionsPageChanged .

API methods used: gotoInstructionsPage(index) , onInstructionsPageChanged

 sequenceDiagram
    participant LMS
    participant LabClient

    LMS->>LabClient: postMessage (event_id: "gotoInstructionsPage", index: 3)
    LabClient-->>LabClient: Executes gotoInstructionsPage(index)
    LabClient->>LMS: postMessage (event_id: "onInstructionsPageChanged", index: 3) 

3. Award badge on activity completion

Gamify the lab experience by awarding badges when activities are completed.

Workflow:

1. The lab client sends onActivityCompleted via postMessage.

2. The parent app receives it and triggers badge-awarding logic.

API methods used: evaluateActivity(alias) , onActivityCompleted

sequenceDiagram
    participant LabClient
    participant ParentApp
    LabClient->>ParentApp: postMessage (event_id: "onActivityCompleted", activity: "quiz1")
    ParentApp-->>ParentApp: Triggers badge award logic 

4. Show countdown timer in parent app

Show the remaining lab time directly in the parent app UI.

Workflow:

1. The parent app sends getMinutesRemaining via postMessage.

2. The lab client responds with the remaining time.

3. The parent app updates the timer display.

API methods used: getMinutesRemaining

 sequenceDiagram
    participant ParentApp
    participant LabClient

    ParentApp->>LabClient: postMessage (event_id: "getMinutesRemaining")
    LabClient-->>ParentApp: postMessage (event_id: "getMinutesRemaining", value: 12)
    ParentApp-->>ParentApp: Updates countdown timer