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)
There are four types of challenge scripts:
There are two track scripts:
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)
while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]doecho "Waiting for Instruqt to finish booting the VM"sleep 1done
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.
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# checkecho "Checking the solution of the challenge"if [ !$EVERYTHING_WENT_WELL ]; thenfail-message "Your challenge failed because of [REASON]"# which is equivalent toecho "FAIL: Your challenge failed because of [REASON]"exit 1fi
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
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:
check (expect failure, since the solve script has not been executed yet)
check (expect success, since the solve script was executed)
The cleanup script runs after a challenge is been completed, before the next challenge is setup.
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:
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.
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:
The Instruqt platform injects a set of parameters using environment variables into every script:
The ID of the track
(Optional) The ID of the challenge that the script is running on. This can be empty, in case of a track cleanup script.
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.
(Optional) The ID of the track invite. It is only present if the user accessed the track via an invite link.
(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.
(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.
(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.