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

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 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	30 min
Track Cleanup	30 min
Challenge Setup	30 min
Challenge Check	1 min
Challenge Solve	30 min
Challenge Cleanup	30 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.