Challenges
This page describes challenges, which provide the interaction with learners.

What is a challenge?

A challenge is an interactive step in a track and consists of instructional or background content in the form of notes and of hands-on interactive content. Each challenge focuses on an incremental step a learner needs to understand to achieve the learning goal of the track.
See the overview for where a challenge fits into the Instruqt environment.
Some challenge examples are:
  • Create a directory in a terminal
  • Edit a TypeScript file in VS Code
  • Deploy NGINX within Kubernetes
Building challenges
As a content developer, you can build challenges with the Web UI or the Instruqt CLI.

Challenge resources

A challenge can contain the following resources:
  • Tabs with software and service, which learners need to solve the challenge. Think of a tab as a view on the sandbox, so learners can interact with the sandbox. You can have the following tab types:
    • Service
    • Terminal
    • Editor
    • Website
    • External app
  • Notes that give instructions for the challenge or provide background information in the form of:
    • Text
    • Images
    • Video
  • Scripts that give learners the context or starting position they need and check the learner's solution including providing feedback. You can define automatically executed scripts for:
    • Setting up a challenge
    • Checking a challenge
    • Automatically solving a challenge
    • Cleaning up a challenge

Appearance

🌐 Web UI
πŸ’» Instruqt CLI
In the Web UI, a challenge appears within a track:
In Instruqt CLI, a challenge appears as a subdirectory (lines 2 to 7) within a track:
sandboxcontainer
β”œβ”€β”€ 01-creating-a-directory
β”‚ β”œβ”€β”€ assignment.md
β”‚ β”œβ”€β”€ check-container
β”‚ β”œβ”€β”€ cleanup-container
β”‚ β”œβ”€β”€ setup-container
β”‚ └── solve-container
β”œβ”€β”€ config.yml
└── track.yml
Every challenge has its own subdirectory. In this case, 01-creating-a-directory. In this directory, you will find, among other things, the assingment.md file. This file contains the challenge specification in a combination of YAML and Markdown.
Prefix numbering
Every challenge subdirectory gets a consecutive prefix number. 01, 02, and so on.

Challenge properties

You specify a challenge by setting the challenge properties. For example, the teaser property lets you specify a short description of the challenge. You can set the challenge properties through the Web UI or Instruqt CLI.
For Web UI, you will find the properties as fields on the Challenge details page. For Instruqt CLI, you will find the properties in the configuration file assignment.md as in this example:
YAML/Markdown
---
slug: creating-a-directory
id: 49x8munieydf
type: challenge
title: Creating a directory
teaser: Learn how to create directory
notes:
- type: text
contents: Please wait while we set up the first challenge
tabs:
- title: Shell
type: terminal
hostname: container
difficulty: basic
timelimit: 600
---
​
πŸ€– Let's start
==============
​
Create a directory with the name `instruqt` to complete this challenge.
​
Use the `mkdir` command to create the directory:
​
```
mkdir instruqt
```
​
To complete this track click the **Check** button.
The following tables show the challenge properties grouped by tab/section:
🌐 Web UI field list
πŸ’» Instruqt CLI property list

Description

Field
Description
Type
Required
Title
The title of the challenge.
string
Required
Type
The type of the challenge. Can either be Challenge or Quiz
string
Required
Slug
An URL-friendly identifier of a challenge. You can only use the same slug once in a single track.
string
Required
Assignment
Challenge: a description of the challenge. Quiz: the question.
markdown
Optional
Teaser
A short description of the challenge, which is shown in the challenge list.
string
Optional
Timelimit
Time limit in seconds. Challenge time limits are not enforced but the track time limit is. The track time limit is the sum of all challenge time limits in a track. If the track time limit is reached, the track is automatically stopped and marked as failed.
integer
Optional
​
You will get these extra fields when you select challenge type Quiz:
Field
Description
Type
Required
Answer
A possible quiz answer
string
At least one answer required
Correct answer
Multiple correct answers are possible.
boolean
At least one correct answer required
​

Notes

Notes provide the learner with context and background information.
​

Note: Text

Field
Description
Type
Required
Type
Text
string
Required
Contents new
This property sets the content of the note.
string
Required
​

Note: Image/video

Field
Description
Type
Required
Type
Image or Video
string
Required
URL
The url link of the image or url of the video.
string
Required
​

Tabs

Tabs provide services that are exposed to the learner in the browser.
​

Tab: Service

Field
Description
Type
Required
Title
This property sets the tab title. And each service has its own tab.
string
Required
Type
Service
string
Required
Host
This property sets the tab hostname.
string
Required
Path
The filesystem path on the host that should be used in the editor
string
Optional
Port
The port that is used to connect to the service running on the host. If the sandbox host is a container, the port must be exposed in config.yml If the service uses HTTPS, the port must end with 443 (for example 8443)
string
Required
Open in new window
Whether to open the tab in a new window. Useful for when the service doesn't allow being run in an iframe.
boolean
Optional
​

Tab: Terminal

Field
Description
Type
Required
Title
This property sets the tab title. And each service has its own tab.
string
Required
Type
Terminal
string
Required
Host
This property sets the tab hostname.
string
Required
​

Tab: Editor

Field
Description
Type
Required
Title
This property sets the tab title. And each service has its own tab.
string
Required
Type
Editor
string
Required
Host
This property sets the tab hostname.
string
Required
Path
The filesystem path on the host that should be used in the editor
string
Optional
​

Tab: Website

Field
Description
Type
Required
Title
This property sets the tab title. And each service has its own tab.
string
Required
Type
Website
string
Required
URL
The URL of the website opened in this browser. Must be a https:// address. Self-signed SSL certificates are OK. If you use ${_SANDBOX_ID} in a URL, it will be replaced with the sandbox ID.
string
Required
Open in new window
Whether to open the tab in a new window. Useful for when the service doesn't allow being run in an iframe.
boolean
Optional
​

Tab: External

Field
Description
Type
Required
Title
This property sets the tab title. And each service has its own tab.
string
Required
Type
External
string
Required
URL
The URL of the external resource. Must be a https:// address. Self-signed SSL certificates are OK.
string
Required

Description

Property
Description
Type
Required
title
The title of the challenge.
string
Required
type
The type of the challenge. challenge or quiz
string
Required
slug
An URL-friendly identifier of a challenge. You can only use the same slug once in a single track.
string
Required
Markdown section
Challenge: a description of the challenge. Quiz: the question.
markdown
Optional
teaser
A short description of the challenge, which is shown in the challenge list.
string
Optional
id
Server-generated (do not edit)
string
Required
timelimit
Time limit in seconds. Challenge time limits are not enforced but the track time limit is. The track time limit is the sum of all challenge time limits in a track. If the track time limit is reached, the track is automatically stopped and marked as failed.
integer
Optional
difficulty
This field will be deprecated in a future release and is not displayed to users.
string
Optional
​

Example assignment.md

YAML/Markdown
slug: creating-a-directory
id: 49x8munieydf
type: challenge
title: Creating a directory
teaser: Learn how to create directory
difficulty: basic
timelimit: 600
---
πŸ€– Let's start
==============
​
Create a directory with the name `instruqt` to complete this challenge.
​
Use the `mkdir` command to create the directory:
​
```
mkdir instruqt
```
​
To complete this track click the **Check** button.
​
You will also need the following properties when you select challenge type quiz:
​
Property
Description
Type
Required
answers: []
An array of strings that with the possible answers in the challenge
[]string
Required
solution: []
An array of integers with the indexes of the correct answers. Multiple correct answers are possible.
[]integer
Required
​

Notes

Notes provide the learner with context and background information.
Main property: notes:
Sub properties per note type:

Note: Text

Property
Description
Type
Required
type
text
string
Required
contents
This property sets the content of the note.
string
Required
​
Example assignment.md
YAML/Markdown
notes:
- type: text
contents: Please wait while we set up the first challenge
​

Note: Image/video

Property
Description
Type
Required
type
image or video
string
Required
url
The url link of the image or url of the video.
string
Required
​
Example assignment.md
YAML/Markdown
notes:
- type: video
url: https://www.youtube.com/watch?v=MLqEgjXFSaw
​

Tabs

Notes provide the learner with context and background information.
Main property: tabs:
Sub properties per tab type:

Tab: Service

Property
Description
Type
Required
title
This propert sets the tab title. And each service has its own tab.
string
Required
type
service
string
Required
hostname
This propert sets the tab hostname.
string
Required
path
The filesystem path on the host that should be used in the editor
string
Optional
port
The port that is used to connect to the service running on the host. If the sandbox host is a container, the port must be exposed in config.yml If the service uses HTTPS, the port must end with 443 (for example 8443)
string
Required
new_window
Whether to open the tab in a new window. Useful for when the service doesn't allow being run in an iframe.
boolean
Optional
​
Example assignment.md
YAML/Markdown
tabs:
- title: GCP Console
type: service
hostname: cloud-client
path: /
port: 80
​

Tab: Terminal

Property
Description
Type
Required
title
This propert sets the tab title. And each service has its own tab.
string
Required
type
terminal
string
Required
hostname
This propert sets the tab hostname.
string
Required
​
Example assignment.md
YAML/Markdown
tabs:
- title: Cloud CLI
type: terminal
hostname: cloud-client
​

Tab: Editor

Property
Description
Type
Required
title
This propert sets the tab title. And each service has its own tab.
string
Required
type
editor
string
Required
hostname
This propert sets the tab hostname.
string
Required
path
The filesystem path on the host that should be used in the editor
string
Optional
​
Example assignment.md
YAML/Markdown
tabs:
- title: Nano
type: editor
hostname: container
path: /
​

Tab: Website

Property
Description
Type
Required
title
This propert sets the tab title. And each service has its own tab.
string
Required
type
website
string
Required
url
The URL of the website opened in this browser. Must be a https:// address. Self-signed SSL certificates are OK. If you use ${_SANDBOX_ID} in a URL, it will be replaced with the sandbox ID.
string
Required
new_window
Whether to open the tab in a new window. Useful for when the service doesn't allow being run in an iframe.
boolean
Optional
​
Example assignment.md
YAML/Markdown
tabs:
- title: Instruqt
type: website
url: https://www.instruqt.com
new_window: true
​

Tab: External

Property
Description
Type
Required
title
This propert sets the tab title. And each service has its own tab.
string
Required
type
external
string
Required
url
The URL of the website opened in this browser. Must be a https:// address. Self-signed SSL certificates are OK. If you use ${_SANDBOX_ID} in a URL, it will be replaced with the sandbox ID.
string
Required
Example assignment.md
YAML/Markdown
tabs:
- title: Instruqt
type: external
url: https://www.instruqt.com