Scripting overview

Introduction to scripting and how Instruqt leverages it.

What is a script?

A script is a set of commands that execute without compiling. Bash is a popular scripting language for Linux and Mac. The famous Hello World example, which prints simple text, looks like this in bash:

#!/bin/bash
echo "Hello World"

This page is only intended as an overview to scripting in Instruqt. To learn how to implement scripts, refer to the following pages:

• Track scripts

• Challenge scripts

Lifecycle scripts

From setup to teardown, all tracks follow the same lifecycle, which is split between a "track" and "challenge" component.

The track lifecycle consists of the following stages:

• Setup

• Cleanup

The challenge lifecycle consists of:

• Setup

• Check

• Solve

• Cleanup

Lifecycle script types

Setup

Setup scripts run at the beginning of a track or challenge, before user interaction begins. These scripts are commonly used for environment setup, variable initialization, software installation, and other setup tasks.

Check

Check scripts run when the user clicks the "Check" button to move to the next challenge. If the exit status is zero (success), then the user receives a message and the challenge ends. If the exit status is non-zero (failure), then the user is provided feedback and the challenge does not end.

It is recommended to use the set -euxo pipefailcommand in Linux bash scripts, as the fail-messagecan be customized to provide specific feedback to the learner.

The "Check" button will be labeled "Next" if no check script is defined.

Solve

Solve scripts enable users to skip to arbitrary challenges within a track by completing the steps in the solve scripts of each preceding challenge. This allows the track environment to "fast-forward" to the required state for the desired challenge.

For example, a three-challenge track may have a challenge each for installation, configuration, and upgrading a software product. In order to configure the software, it must first be installed, so a solve script for the first challenge would perform those tasks required to enable the next challenge (configuration) to take place.

Cleanup

Cleanup scripts run at the end of a track or challenge, after a user completes the section in question. This can be used to reinitialize variables or environments to known-good states to mitigate user experimentation, to cleanup extraneous files that may have been created, or other housekeeping tasks between challenges.

Track cleanup scripts run after the user has finished or idled out of a track, just before Instruqt destroys the sandbox environment, so typically, no cleanup is necessary here. It may be useful, however, to use this script to trigger external webhooks or APIs to perform actions on an external platforms. One example might be triggering an external SaaS system to remove a temporary account used during the track.

The following is a visual representation of the lifecycle stages a track and its challenges go through:

The track and challenge lifecycle stages

Content developers create lifecycle scripts that run on the sandbox hosts to:

• Set up and clean up the sandbox environment and the challenges.

• Check and give your learners feedback on their challenge solution.

• Automatically solve a challenge when a learner skips a challenge.

Script attributes

• All lifecycle scripts are optional.

• Any scripting language can be used to write the scripts—for example, bash or Python, where bash is the most common choice for Instruqt.
• Instruqt determines if a script was successful by checking the returned script exit code:

  • If the exit code is 0, Instruqt marks the script as successful.

  • If the exit code is not 0, Instruqt marks the script as unsuccessful.

• Scripts run in alphanumeric order, based on hostnames. (e.g the setup script of host-a will execute before the setup script of host-b.)

Script Size Limits & Best Practices

• The maximum size of a lifecycle script is 5 MB.

• Avoid embedding binary files inside lifecycle scripts to keep them lightweight and maintainable.

Script timeouts

Every lifecycle script has a maximum duration it can take to complete. After that the script times out and will exit with an error. Scripts are not retried when it times out.

The timeouts for scripts are:

Script	Timeout
Track Setup	55 min
Track Cleanup	55 min
Challenge Setup	55 min
Challenge Check	1 min
Challenge Solve	55 min
Challenge Cleanup	55 min

Script parameters

The Instruqt platform injects a set of environment variables, which are available as parameters in every script:

Environment Variable	Description
INSTRUQT_TRACK_ID	The ID of the track
INSTRUQT_TRACK_SLUG	The slug of the track
INSTRUQT_CHALLENGE_ID	(Optional) The ID of the challenge that the script is running on. This can be empty, in case of a track cleanup script.
INSTRUQT_PARTICIPANT_ID	The ID of the participant. This value is guaranteed to be unique for every play of a track, i.e. when a user starts the same track twice, the IDs will differ. Participant is the sandbox identifier, not a user.
INSTRUQT_TRACK_INVITE_ID	(Optional) The ID of the track invite. It is only present if the user accessed the track via an invite link.
INSTRUQT_USER_ID	(Optional) The ID of the user. This value uniquely identifies a user. Empty in a Hot Start track setup script.
INSTRUQT_USER_NAME	(Optional) The full name of the user (as they entered it when creating their account). This value is only be present if the user has given consent to share their details. For example, if a learner started a track through a track invite. Empty in a Hot Start track setup script.
INSTRUQT_USER_EMAIL	(Optional) The email address of the user. This value is only be present if the user has given consent to share their details. For example, if a learner started a track through a track invite. Empty in a Hot Start track setup script.
INSTRUQT_PRIVACY_POLICY_CONSENT	Whether the user accepted the organization's privacy policy.

Example

The following challenge setup script writes the learner's name and the challenge id to the logging:

Bash

#!/bin/bash
echo $INSTRUQT_USER_NAME started challenge $INSTRUQT_CHALLENGE_ID

If you play a track that contains this script and view the track log, you will see a log entry with the learner's name and the challenge id.