Lifecycle scripts

Content developers create lifecycle scripts that run on the sandbox hosts to setup and tear down the sandbox environment, give your learners feedback on their solution, or to automatically solve a challenge.

  • All lifecycle scripts are optional

  • You can use any scripting language to write the scripts (bash is the most common choice)

All lifecycle scripts in Instruqt and when they run

There are four types of challenge scripts:

  • Setup

  • Check

  • Solve

  • Cleanup

There are two track scripts:

  • Track setup

  • Track cleanup

Challenge Setup

The setup script runs before the challenge starts. Use it to:

  • Create files that are necessary for the challenge

  • Download and install specific binaries which are not included in the container or virtual machine

  • Set the appropriate state of your services (e.g. start a specific service)

How to wait for a complete bootstrap

while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
do
echo "Waiting for Instruqt to finish booting the VM"
sleep 1
done

Challenge Check

The check script runs after a learner pressed the "Check" button. The check script is used to validate if the learner solved the challenge.

The platform determines if the script was successful or not by looking at the exit code that is returned from the script:

  • If the exit code is 0, the platform mark the check as successful.

  • If the exit code is not 0, it will mark it as unsuccessful.

Providing feedback to the learner

If the check is unsuccessful, you can provide feedback to the learner. To do so, you can write a feedback message to stdout, prefixed with FAIL: . The platform uses the prefix to detect these feedback messages. This message (after stripping the prefix) is shown to the learner. We also provide a fail-message helper script for this.

Example of a check script:

#!/bin/bash
# check
echo "Checking the solution of the challenge"
if [ !$EVERYTHING_WENT_WELL ]; then
fail-message "Your challenge failed because of [REASON]"
# which is equivalent to
echo "FAIL: Your challenge failed because of [REASON]"
exit 1
fi

Challenge Solve script

The solve script solves the current challenge to allow the learner to skip a challenge.

The solve script is applied in the following scenarios:

  • When a user skips a challenge

  • By the instruqt track test CLI command

When running the instruqt track test CLI command, the CLI starts the track on the Instruqt platform and executes the following life cycle scripts:

  1. setup

  2. check (expect failure, since the solve script has not been executed yet)

  3. solve

  4. check (expect success, since the solve script was executed)

  5. cleanup

Challenge Cleanup Script

The cleanup script runs after a challenge is been completed, before the next challenge is setup.

Track Setup Script

A track setup script runs during the track setup phase.

To use track setup scripts using the CLI, create a folder with the name track_scripts and place the setup scripts in the folder with the following name format: setup-<hostname>.

Compared to challenge level setup scripts

Challenge level setup scripts are not executed when creating a pooled instance. As result students have to wait for this script before their environment is ready. With track level setup scripts this additional waiting time can be avoided because this script executes when setting up a pooled instance.

When the track level setup script executes to create a pooled instance environment variables that require reference to a user (e.g user ID) will not be populated.

Track Cleanup Script

The track cleanup script runs just before a sandbox environment is cleaned up. This allows you to call external systems to trigger a clean up, or to register that a user has finished with their track. The track cleanup script executes on a sandbox host.

To use track cleanup scripts using the CLI, create a folder with the name track_scripts and place the cleanup scripts in the folder with the following name format: cleanup-<hostname>

You can also use lifecycle scripts to publish events to external systems. For example, you can publish an event when a user starts a track. Use the script parameters to correlate these events with data in your own systems.

Script parameters

The Instruqt platform injects a set of parameters using environment variables into every script:

On a sandbox VM, start any script with #!/bin/bash -l as the first line to load the environment variables.

Environment Variable

Description

INSTRUQT_TRACK_ID

The ID 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 not the same as 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. This value can be empty, in case a script is run as part of a pooled instance.

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.

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.

INSTRUQT_PRIVACY_POLICY_CONSENT

Whether the user accepted the organization's privacy policy.