Definitions

This directory contains the example definitions which showcase various functionality.

Versioning

Definition use a modified semantic versioning:

Patch: adding fields and files to the definition, this allows for older versions of definitions to run on newer backends. Sensible defaults should be selected when adding fields to allow for backwards compatibility.
Minor: modifying existing fields, such as renaming, deleting or changing their meaning. Such changes would either break the definition validation or it would cause unintended/incorrect behaviour.
Major: no set of rules are defined, can be used for extreme changes to the definition format.

The current definition version the backend supports is the first version in the changelog.

Definition file structure

content/
files/
config.yml
channels.yml
injects.yml
email.yml
milestones.yml
tools.yml
roles.yml
questionnaires.yml
objectives.yml

The content/ and files/ directories are optional. They do not need to be present if your definition does not use the relevant features.

Furthermore, it is possible to use a directory instead of a single YAML file. The files inside the directory must follow the same structure as the original YAML file. For example, if you decide that injects.yml file is too large you can create a directory injects inside of which you create 4 different files which when combined will contain the original content of the injects.yml file. These files can be named in any way you like, however they must be in the YAML format.

The above currently holds true for all YAML files except config.yml. These approaches can be mixed: e.g. if you have many injects but not that many tools you can put the injects into a directory and still use a single tools.yml file.

Note: If the definition contains both a YAML file and a directory for the same structure, the YAML file will be prioritized and the directory ignored. E.g. if you have injects.yml and injects directory, the directory will be skipped.

Current file formats

Below are schema definitions for each file. Every field is required unless a default value is specified or it is stated otherwise.

Common definitions

This section contains definitions of common fields used by multiple definition files. Restrictions on some uses might apply, these restrictions will be listed on the exact location.

Content

Only one of content or content_path can be specified on a single content field. These fields can be formated as Markdown with these restrictions. Furthermore, it is currently not possible to embed images, audio and video. The Markdown syntax can be found here.

content: str, default="" - content displayed to users, mutually exclusive with content_path
content_path: str, default="" - name of a markdown file that contains the content, mutually exclusive with content
file_name: str, default="" - optional file attachment, has to be present in the files directory in the definition

Control

milestone_condition: str, default="" - condition which must be met before an object can be sent/processed. Supports simple logical expressions in Python format, where the allowed operators are and, or, not and (). These operators can be applied to names of milestones specified in the definition.
activate_milestone: str, default="" - a comma-separated list of milestones which will be activated after an object is sent/processed
deactivate_milestone: str, default="" - a comma-separated list of milestones which will be deactivated after an object is sent/processed
roles: str, default="" - usable only if roles are enabled, a space-separated list of roles, a team must have at least one of the roles to be eligible for this object

Overlay

duration: int - number of minutes the overlay should stay active

config.yml

This file contains various settings for an exercise. All advanced features are disabled by default:

exercise_duration: int - Duration of the exercise in minutes.
email_between_teams: bool, default=False - Allow emails between teams. Can only be enabled if emails are enabled.
custom_email_suffix: string, default="mail.com" - Changes the domain of email addresses of teams, e.g. if set to gmail.com team email addresses will have the form team_name@gmail.com.
show_exercise_time: bool, default=False - Show the remaining duration of the ongoing exercise to trainees on the frontend.
enable_roles: bool, default=False - Enables use of team roles. Requires roles.yml file to be included in the definition.
version: string - semver version string of the format this definition uses, see versioning for details.

objectives.yml

This file contains all learning objectives. Each learning objective has the following fields:

name: string, unique - name of the learning objective
tags: string, default="" - a comma-separated list of tags corresponding to this objective
activities: - list of learning activities
- name: string, unique - name of the learning activity
- tags: string, default="" - a comma-separated list of tags corresponding to this activity

channels.yml

This file contains the definitions of all channels used in the exercise.

name: string - the name that will be displayed to users
type: string - the type of messages that will be sent to this channel, see injects.yml for details.

Currently supported channel types:

info - the most basic type of message, IMPORTANT: A definition MUST include one and only one channel with the info type.
tool - tool usage by trainees will be sent to the channel with this type. Injects cannot be specified with this type and there can be at most one channel with this type in a definition
email - injects meant to represent email communication
form - questionnaires will be sent to this channel

At most one channel of a specific type can exist. In other words, there cannot be multiple channels with type email. If a definition does not contain a channel with the tool type, no tools can be specified. Same rule applies to emails and questionnaires. When a channel of some type is specified, at least one related object must be specified. E.g. if an email channel exists, at least one email address must be specified in emails.yml.

Note: Defining a channel for tools or emails is required to enable these features. Without such a channel, these functionalities will be turned off.

injects.yml

This file contains a list of injects. Each inject has the following fields:

name: string, unique - name of the inject
time: int, default=0 - time since the beginning of the exercise in minutes, the inject will not be processed until this time has been reached
delay: int, default=0 - time in minutes, whenever this inject is about to be sent, it is delayed by this number of minutes. The condition is checked throughout the duration and if it becomes false, the inject is cancelled and the process can start again.
organization: string, default="" - name of the organization this inject was sent from
type: string, default="info" - type of this inject, the alternatives field depends on this value
alternatives: options specified bellow

When selecting alternatives to send, they are ordered alphabetically based on their name. The first one that fulfills the condition is selected. In other words, when multiple alternatives can be sent, their priority is determined by their name attribute.

Alternatives: info

name: string - name of the alternative
content: content, default=empty - if empty, no ActionLog will be created when this alternative is sent. Can be used for hidden state management of the exercise.
control: control, default=empty
overlay: overlay, default=empty

Alternatives: email

name: string - name of the alternative
sender: string - an email address from which this alternative is sent, must be an address specified in email.yml.
subject: str - subject of the email
content: content, default=empty
control: control, default=empty
extra_copies: int, default=0 - number of extra copies to be sent, useful for specifying spam email.
overlay: overlay, default=empty

tools.yml

This file contains a list of tools. A tool can be thought of as a simple function, which based on its input and current state of the exercise returns some output. Each tool has the following fields:

name: string, unique - Name of the tool
tooltip_description: string, default="" - Description of a tool displayed to trainees.
hint: string, default="" - Argument hint
default_response: string - Response that the tool returns if no other response gets matched.
roles: string, default="" - Usable only if roles are enabled. Defines which roles will be able to use the tool. By default, all roles can access the tool. If tool is meant for multiple roles, it can be achieved by writing the role names separated by spaces:
```
- roles: role_name_1 role_name_2 role_name_3
```
responses: - A list of responses. A response is matched when its conditions are met. When trainees use a tool, the list of responses is examined from top to bottom and only the first matched response is sent back.
- param: string - A parameter that is matched exactly to the input of trainees. Can be written as Python regular expression if parameter regex is set to true.
- regex: bool, default=False - Determines whether parameter param is matched as a string or a regex.
- time: int, default=0 - Time since the beginning of the exercise in minutes after which this response can be matched. If the trainees use correct param but this time was not reached yet, it will not match.
- content: content, default=empty
- control: control, default=empty

milestones.yml

This file contains all milestones in an exercise. Any milestone_condition or (de)activate_milestone field in the whole definition can only contain milestones defined in here. Each milestone has the following fields:

name: string, unique - Name of the milestone. \ Rules for the naming of the milestones:
- A name must start with a letter or the underscore character
- A name cannot start with a number
- A name can only contain alphanumeric characters and underscores (A-z, 0-9, and _ )
- Variable names are case-sensitive (age, Age and AGE are three different variables)
- A name must be continuous string -> a name can not contain spaces
roles: string, default="" - Usable only if roles are enabled. Works only if the milestone is marked as visible. Defines, which roles will see the milestone. By default, all roles will see the milestone.
file_names: string, default="" - Defines the name of a file from the definition. Multiple file names can be specified as a space separated list. If at least one of these files is downloaded, this milestone activates.
final: bool, default=False - sets this milestone as a final milestone. If a team reaches this milestone, their exercise is considered to be finished. There must be at least one milestone, however there can be more than one.
activity: string, default="" - learning activity linked to this milestone
initial_state: bool, default=False - the initial state of the milestone, if this is set to True, final cannot be set to True

email.yml

This file contains all email addresses where each address has the following fields:

address: string, unique - Address of the simulated correspondent.
team_visible: bool, default=False - Adds this address into contact list of each team.
description: string - Description of the correspondent and related context for the instructor.
control: control, default=empty - milestone condition and roles cannot be specified
team_visible: bool, default=False - Specifies if this email address should be visible to the teams.
organization: string, default="" - Name of the organization this email address belongs to.
templates: not required - A list of template emails that the instructor can choose from when writing an email.
- context: string - Description of the context of this email answer for the instructor.
- content: content, default=empty
- control: control, default=empty - milestone condition and roles cannot be specified

roles.yml

Required if roles are enabled. This file contains all role names:

name: string, unique - Name of the role.

questionnaires.yml

This file contains all questionnaires. Each questionnaire has the following fields:

title: string - title of the questionnaire
time: int, default=0 - time since the beginning of the exercise in minutes, after which the questionnaire will be sent
control: control, default=empty
overlay: overlay, default=empty
questions:
- content: content, default=empty - should contain the text of the question
- max: int, required - the number of options for the question
- labels: str, default="" - the labels of options specified as a comma-separated string (,), empty string means the labels will be numbers in range [1-max], if specified, the number of labels must be equal to max
- correct: int, default=0 - position which represents the correct choice, for example, if we have 4 labels yes, no, maybe, absolutely, the correct field should have the number 3 if the correct choice is maybe, 0 means the question has no correct choice
- controls: int -> control, default=empty - a mapping of choice numbers to control objects in the format
```
  controls:
    1: { activate_milestone: ... }
    2: { deactivate_milestone: ... }
  ...
```
  When a user selects a choice which has a corresponding number, the milestones specified in the control object will be modified accordingly. Choices may be omitted. Valid numbers are in the range [1-max].