diff --git a/.gitignore b/.gitignore
index a66bd4658c76aae75f1398b0c59c950b154b41c1..ffc7fdef1bdf24827f5d750d2a5bca6ff3acb24f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,5 @@
# mkdocs documentation
site/
-docs/tech/architecture/definitions.md
-docs/tech/architecture/CHANGELOG.md
-docs/tech/api/openapi.yml
# python
.python-version
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 2568e39228ecee44fbfa6009372f5fee006032d1..6f4df9f5306d6ba8aade151e089cf866a1512d2a 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -5,7 +5,6 @@ variables:
stages:
- setup
- - commit
- build
- deploy
@@ -18,27 +17,7 @@ setup:
before_script:
- apt-get update
script:
- - ./utilities.sh # Running the script to setup directories and copy files
- artifacts:
- paths:
- - docs/tech
- - files-from-repos
-
-commit_zip:
- stage: commit
- when: manual
- allow_failure: true
- script:
- - git config --global user.email "ci@gitlab.com"
- - git config --global user.name "CI Bot"
- - git add files-from-repos/intro-definition.zip
- - git add files-from-repos/showcase-definition.zip
- - git commit -m "Add automatically deployment-files.zip"
- - git push https://oauth2:${GITLAB_TOKEN}@gitlab.fi.muni.cz/inject/inject-docs.git HEAD:"$CI_PIPELINE_ID" -o ci.skip
- dependencies:
- - setup
- only:
- - citadel
+ - echo "updating"
build:
stage: build
diff --git a/docs/INJECT_process/prepare/overview.md b/docs/INJECT_process/prepare/overview.md
index 3f1206ccf77a25cd4aa1e4d506a0c18bc8205078..f144f701b81fee3a14416b704a15692b3feb00c3 100644
--- a/docs/INJECT_process/prepare/overview.md
+++ b/docs/INJECT_process/prepare/overview.md
@@ -83,7 +83,6 @@ However, there is an alternative option available: you can prepare content direc
If the corespondent is expected to react a certain way to certain situations, use templates.
These give instructor pre-scripted email choices
-n.
??? "Editor"
The INJECT Exercise Platform now includes a new tool - the Editor - that makes exercise creation more accessible and guided. While it's still in development, it offers a user-friendly alternative to manual YAML editing.
diff --git a/docs/INJECT_process/specify/exercise_specification.md b/docs/INJECT_process/specify/exercise_specification.md
index 7d7d958f8bfe3d2fa683bc574004a6450e9d3e5c..5ff71c741875fda08e7b67c56951a210ac75c373 100644
--- a/docs/INJECT_process/specify/exercise_specification.md
+++ b/docs/INJECT_process/specify/exercise_specification.md
@@ -25,79 +25,89 @@ As we indicated at the beginning of the section describing [Learning objectives]
- The second type: **process-technical exercises** - based on an attempt to simulate the course of a process. The main input is e.g. a document describing the response to incidents, etc. injects here are primarily via emails, it is possible to use abstraction of specific tools or measures and at the end there is a reflexive part containing questionnaires or open questions. **Beware, if you don't have the actual organization and process as a basis**, you will be in a very difficult situation as a designer. In fact, if the organisation does not exist, you have to create it completely - a task that exceeds the contribution of TTX in its complexity.
??? "How to specify a strategic decision-making exercise"
- ### What do these exercises look like off the platform?
- Trainees usually receive a paper assignment where the individual injects are presented, structured into phases or blocks.
- The injects are most often in the form of text, but sometimes pictures are also added. Each inject is accompanied by questions. Depending on the type of target group, trainees work either in small teams or all together. Often a facilitator is involved.
-
- ### Modes of presentation in the platform:
- - It is recommended to divide trainees into smaller teams (3-5 members). It is best if everyone has a laptop with access to the platform, and they designate that only one of them will interact with it. Alternatively, they will divide their roles in some way.
-
- - If a screen or larger screen is available, the exercise can be presented to a larger group (the discussion will be influenced by the dominant members). It is useful to have a facilitator.
-
- - If the trainees cannot control the platform, one of the instructors can do so.
-
- - The exercise can theoretically be run for one trainee. However, without discussion it becomes more of an interactive training. Each team can go at its own speed
- ### How to use different types of injects
- - Inject type: email - not used in this type of exercise.
- - Inject type: execise information - suitable for instructions and outlining the general context at the beginning of the exercise.
- - Injects of the type: document - strategic briefs, reports, etc. Consider sending before the exercise.
- - Inject type: questionnaire / scale - recommended.
- - Decision point - recommended.
- - Inject type: free form - the main variant of inject for this type of exercise.
- - Media injects - suitable for adding context or as a direct part of the script.
- - Inject type: An off-platform activity - a spice up of the scenario, use is not necessary.
- - Hint - as needed.
- ### Use of tools
- - No tools are necessary for this type of exercise. If we want to use them, we recommend them for specific processes or actions that you want to highlight for the trainees.
- - Examples: The tool can substitute a supervisor's decisions such as issuing a press release, conducting a legal analysis, contacting the police, etc.
-
- ### Possible scenario structures:
- #### A) Coherent story - individual injects are interconnected. Everything relates to one storyline that unfolds gradually. Example:
- - The exercise starts with a document type inject - with a report from a national authority describing the current serious situation. This is followed by a combination of inject type:
- - Free form - activities: propose, argue, summarize ...
- – Scale/questionnaire - evaluate, select, determine
- – The exercise is complemented first by injects in the social media channel that express the public's perception of the situation
- – The following is also article in major medium.
- - The exercise proceeds to a serious decision - decision point type inject - we have an alternative conditional inject for each of the variants.
- - Adding several injects to reflect on the actions taken (free form or questionnaire).
- - Exercise is otherwise more or less linear, hints do not need to be prepared in advance.
- #### B) A sets of situations
- The trainees deals with different situations, which are not connected and are only briefly indicated, inspiration: https://x.com/badthingsdaily?lang=cs
- - The exercise starts with a general introduction in exercise information.
- - The first block follows with a description of the situation within the free form inject and a request for a description of the possible response.
- - Followed by 2-3 interactive injects.
- - The exercise continues in this way with a few more, tightened or slightly altered blocks.
- - At the end there is space for more general reflection.
- - The exercise can be improved by conditioning some of the responses in the free form injects.
+
+ ### What do these exercises look like off the platform?
+
+ The trainees usually receive a paper assignment where the individual injects are presented, structured into phases or blocks.
+ The injects are most often in the form of text, but sometimes pictures are also added. Each inject is accompanied by questions. Depending on the type of target group, trainees work either in small teams or all together. Often a facilitator is involved.
+
+ ### Modes of presentation in the platform:
+
+ - It is recommended to divide trainees into smaller teams (3-5 members). It is best if everyone has a laptop with access to the platform, and they designate that only one of them will interact with it. Alternatively, they will divide their roles in some way
+ - If a screen or larger screen is available, the exercise can be presented to a larger group (the discussion will be influenced by the dominant members). It is useful to have a facilitator
+ - If the trainees cannot control the platform, one of the instructors can do so
+ - The exercise can theoretically be run for one trainee. However, without discussion it becomes more of an interactive training. Each team can go at its own speed
+
+ ### How to use different types of injects
+
+ - Inject type: email - not used in this type of exercise
+ - Inject type: execise information - suitable for instructions and outlining the general context at the beginning of the exercise
+ - Injects of the type: document - strategic briefs, reports, etc. Consider sending before the exercise
+ - Inject type: questionnaire / scale - recommended
+ - Decision point - recommended
+ - Inject type: free form - the main variant of inject for this type of exercise
+ - Media injects - suitable for adding context or as a direct part of the script
+ - Inject type: An off-platform activity - a spice up of the scenario, use is not necessary
+ - Hint - as needed
+
+ ### Use of tools
+
+ No tools are necessary for this type of exercise. If we want to use them, we recommend them for specific processes or actions that you want to highlight for the trainees.
+
+ Examples: The tool can substitute a supervisor's decisions such as issuing a press release, conducting a legal analysis, contacting the police, etc.
+
+ ### Possible scenario structures:
+
+ #### A) Coherent story - individual injects are interconnected
+
+ Everything relates to one storyline that unfolds gradually. Example:
+ - The exercise starts with a document type inject - with a report from a national authority describing the current serious situation. This is followed by a combination of inject type:
+ - Free form - activities: propose, argue, summarize...
+ - Scale/questionnaire - evaluate, select, determine
+ - The exercise is complemented first by injects in the social media channel that express the public's perception of the situation
+ - The following is also article in major medium
+ - The exercise proceeds to a serious decision - decision point type inject - we have an alternative conditional inject for each of the variants
+ - Adding several injects to reflect on the actions taken (free form or questionnaire)
+ - Exercise is otherwise more or less linear, hints do not need to be prepared in advance
+
+ #### B) A sets of situations
+
+ The trainees deals with different situations, which are not connected and are only briefly indicated
+ - The exercise starts with a general introduction in exercise information
+ - The first block follows with a description of the situation within the free form inject and a request for a description of the possible response
+ - Followed by 2-3 interactive injects
+ - The exercise continues in this way with a few more, tightened or slightly altered blocks
+ - At the end there is space for more general reflection
+ - The exercise can be improved by conditioning some of the responses in the free form injects
??? "How to specify a process-technical exercise"
- ### What do these exercises look like on the platform?
- Trainees usually receive a paper assignment where individual injects are presented, structured into phases or blocks. The injects are most often in the form of text, but sometimes pictures are also added. Each inject is accompanied by questions. Trainees work in teams. It is assumed that the exercise relates to a process with which the trainees are familiar.
- ### Modes of presentation in the platform:
- - It is recommended to divide trainees into smaller teams (3-5 members). It is best if each person has a laptop with access to the platform, and designates that only one of them will interact with it.
- - The exercise can be completed even if only one of the trainees has a computer.
-
- ### How to use different types of injects
-
- - Inject type: Email - the main type of inject for this type of exercise.
- - Inject type: Execise information - intro inject, identity, tasks, context etc.
- - Inject type: Document - politics, structures, manuals, guides
- - Inject type: questionnaire / scale - reflection, propability
- - Decision point - usually not used (decisions are made in an email communication)
- - Inject type: free form - gathering opinions or more speicific reflections.
- - Medial injects - context, impact of the actions
- - Inject type: Hint - response to wrong action, action that wass missed or stuck in the exercise.
-
- ### Use of tools
- - For this type of exercise, the tools are absolutely essential. They usually try to mimic real tools that would be available to the trainee in a real situation and that could be used to resolve the incident. Most often these will be tools that are not too complex, such as IP blocking, network traffic dump, logging service logging, or creating a backup.
- ### Possible scenario structure:
- - Exercises most often start with an introductory inject in exercise information, which includes a description of the organisation concerned, the tasks of the exercisers and, if necessary, important contact details or documents to work with.
- - The following 2 options are available, either the trainees will learn about the problem or incident, for example through a notification they receive by email, or they can be tasked to be proactive and use, for example, a system scanning tool to detect a problem in the system (a very technical exercise).
- - The tools that the trainee is tasked with using to resolve the incident or support the process play a significant role here. However, the whole scenario does not revolve only around the tools, but combines extensively with elements from the strategic decision-making exercises, where trainees are also guided through questionnaires, either in the form of scales or free form.
- - Many processes are also heavily based on communication with actors in the organization, which implies the possibility of abundantly involving communication via email with fictional characters (careful reduces automation and keeps the instructor more busy).
- - The exercise is very much based on the actions of the trainee and only if they perform the anticipated actions can they move towards the goal of resolving the incident.
- - Very often, hints are implemented to prevent the team from getting completely
- - In the end, send reflective questionnaires
+ ### What do these exercises look like on the platform?
+ Trainees usually receive a paper assignment where individual injects are presented, structured into phases or blocks. The injects are most often in the form of text, but sometimes pictures are also added. Each inject is accompanied by questions. Trainees work in teams. It is assumed that the exercise relates to a process with which the trainees are familiar.
+ ### Modes of presentation in the platform:
+ - It is recommended to divide trainees into smaller teams (3-5 members). It is best if each person has a laptop with access to the platform, and designates that only one of them will interact with it.
+ - The exercise can be completed even if only one of the trainees has a computer.
+
+ ### How to use different types of injects
+
+ - Inject type: Email - the main type of inject for this type of exercise.
+ - Inject type: Execise information - intro inject, identity, tasks, context etc.
+ - Inject type: Document - politics, structures, manuals, guides
+ - Inject type: questionnaire / scale - reflection, propability
+ - Decision point - usually not used (decisions are made in an email communication)
+ - Inject type: free form - gathering opinions or more speicific reflections.
+ - Medial injects - context, impact of the actions
+ - Inject type: Hint - response to wrong action, action that wass missed or stuck in the exercise.
+
+ ### Use of tools
+ - For this type of exercise, the tools are absolutely essential. They usually try to mimic real tools that would be available to the trainee in a real situation and that could be used to resolve the incident. Most often these will be tools that are not too complex, such as IP blocking, network traffic dump, logging service logging, or creating a backup.
+ ### Possible scenario structure:
+ - Exercises most often start with an introductory inject in exercise information, which includes a description of the organisation concerned, the tasks of the exercisers and, if necessary, important contact details or documents to work with.
+ - The following 2 options are available, either the trainees will learn about the problem or incident, for example through a notification they receive by email, or they can be tasked to be proactive and use, for example, a system scanning tool to detect a problem in the system (a very technical exercise).
+ - The tools that the trainee is tasked with using to resolve the incident or support the process play a significant role here. However, the whole scenario does not revolve only around the tools, but combines extensively with elements from the strategic decision-making exercises, where trainees are also guided through questionnaires, either in the form of scales or free form.
+ - Many processes are also heavily based on communication with actors in the organization, which implies the possibility of abundantly involving communication via email with fictional characters (careful reduces automation and keeps the instructor more busy).
+ - The exercise is very much based on the actions of the trainee and only if they perform the anticipated actions can they move towards the goal of resolving the incident.
+ - Very often, hints are implemented to prevent the team from getting completely
+ - In the end, send reflective questionnaires
<div class="navigation" markdown>
[← Tools](../specify/tools.md){ .md-button }
diff --git a/docs/INJECT_process/specify/injects.md b/docs/INJECT_process/specify/injects.md
index 8508b78c466005764fe85a0fbecc203c36e45a42..8384e6a7add954966348a78a5a9c9c5d8144adda 100644
--- a/docs/INJECT_process/specify/injects.md
+++ b/docs/INJECT_process/specify/injects.md
@@ -18,29 +18,29 @@
??? "Channels"
- The location within the platform where the inject appears - each inject has just one channel within the exercise. At the same time, you can deliver the same inject information via diffrent channels. The basic channels are:
+ The location within the platform where the inject appears - each inject has just one channel within the exercise. At the same time, you can deliver the same inject information via diffrent channels. The basic channels are:
- - **Exercise information** – general channel for communication about exercise
- - **Emails** – classical email communication
- - **Tools** - tools outputs
- – **Questions** - a channel where various interactive injects (e.g. questionnaires) are displayed. The channel name can be changed.
- <BR>
- The implementation of media channels is being considered:
- - **Website** - for simulating websites of different organizations
- - **Intranet**
- - **Social media** / - can be named as X, Facebook, LN, ...
- - **Media** - injects in the form of articles, audio or video. May carry the name of a specific media outlet.
+ - **Exercise information** – general channel for communication about exercise
+ - **Emails** – classical email communication
+ - **Tools** - tools outputs
+ – **Questions** - a channel where various interactive injects (e.g. questionnaires) are displayed. The channel name can be changed.
+ <BR>
+ The implementation of media channels is being considered:
+ - **Website** - for simulating websites of different organizations
+ - **Intranet**
+ - **Social media** / - can be named as X, Facebook, LN, ...
+ - **Media** - injects in the form of articles, audio or video. May carry the name of a specific media outlet.
??? "Overlay"
- This is an interface effect that directly affects the dynamics of the exercise. While normally, for example, the questionnaire will be displayed in the preset channel, **if this inject is also set as an overlay, it will be displayed first above everything else**.
- <br>
-
- - Example, the overaly questionnaire will cause everything else to go dark and it will appear in the middle of the screen. This makes the inject disrupt the trainees' existing activity and draws their attention. Some strategy exercises may consist entirely of injects presented through an overlay.
+ This is an interface effect that directly affects the dynamics of the exercise. While normally, for example, the questionnaire will be displayed in the preset channel, **if this inject is also set as an overlay, it will be displayed first above everything else**.
+ <br>
+
+ - Example, the overaly questionnaire will cause everything else to go dark and it will appear in the middle of the screen. This makes the inject disrupt the trainees' existing activity and draws their attention. Some strategy exercises may consist entirely of injects presented through an overlay.
??? "A caption: "Not implemented""
- The injects with this caption have not yet been implemented in the platform. They are likely to be added in the future, though they may be modified based on team discussions.
+ The injects with this caption have not yet been implemented in the platform. They are likely to be added in the future, though they may be modified based on team discussions.
@@ -48,223 +48,223 @@
Let's now take a detailed look at the different inject options. This is not a final list; you can create any inject options you want from the basic elements in the platform. However, we describe these options because they have proven valuable in most exercises. Think of inject options as proven building blocks that you can use to construct your exercises. We describe their typical use in an exercise and the related learning activities. [Learning activities](../specify/learning_activities.md).
??? "1. Inject option: Email"
- ### Inject description
- This is a classic email conversation. It can also contain email attachments. The sender address is also an important part of this option of inject and is fully configurable. Emails in the form of an inject can be sent either automatically or as an instructor activity.
- ### Channel
- Only a specific channel for emails. The channel functions as a simple email client.
- ### Overlay
- Emails are usually not used in conjunction with overlays.
- ### Typical use in an exercise
- Emails can be used in any type of exercise. They are essential in process-technical exercises.
- Strategic decision-making exercises can be fully conducted via email, but require a scenario designed to work with specific individuals (concrete names and positions) within the organization.
- ### Possible mistakes
- - An important prerequisite for the use of emails is that the exercise trainees know their "game identity". In other words, they need to be clear why they are receiving the email. If you, as an instructor, do not communicate this well, there may be misunderstandings that result in not being able to use the pre-prepared template responses.
- - You must identify all email addresses prior to the exercise. Omissions cannot simply be resolved during the exercise, any address must be entered into the platform in advance. Therefore, think carefully about their structure and meaning. For example, ensure that all emails within the organisation have the same spelling. Also consider creating email addresses to give to trainees even if you don't intend to use them - it completes the scenario better and adds more decision-making for trainees.
- - Another possible error is a misunderstanding of the context for which this tool is suited. Could you imagine dealing with a truly escalated crisis situation through emails? Or would it be more likely that the team would be more likely to meet physically or at least make a phone call?
- - Consider whether it is necessary to specifically instruct trainees at the beginning of the exercise that the emails are legitimate and that they do not need to look for phishing attempts. In one of our first exercises, we had trainees simply not open the initial email because they thought it was phishing - in short, they expected it in a cybersecurity exercise.
- ### Related manifestations in the platform
- - Establishing email communication - trainees sent an email. LA is filled just by sending an email. Only 1x can be used for each email address.
- - Email reply from the instructor - see above.
- ### Examples
- - Internal communication in the organisation.
- - Inter-organisational communication.
- - Communication with oustsorced co-workers.
- - Communication with journalists.
- - Etc.
+ ### Inject description
+ This is a classic email conversation. It can also contain email attachments. The sender address is also an important part of this option of inject and is fully configurable. Emails in the form of an inject can be sent either automatically or as an instructor activity.
+ ### Channel
+ Only a specific channel for emails. The channel functions as a simple email client.
+ ### Overlay
+ Emails are usually not used in conjunction with overlays.
+ ### Typical use in an exercise
+ Emails can be used in any type of exercise. They are essential in process-technical exercises.
+ Strategic decision-making exercises can be fully conducted via email, but require a scenario designed to work with specific individuals (concrete names and positions) within the organization.
+ ### Possible mistakes
+ - An important prerequisite for the use of emails is that the exercise trainees know their "game identity". In other words, they need to be clear why they are receiving the email. If you, as an instructor, do not communicate this well, there may be misunderstandings that result in not being able to use the pre-prepared template responses.
+ - You must identify all email addresses prior to the exercise. Omissions cannot simply be resolved during the exercise, any address must be entered into the platform in advance. Therefore, think carefully about their structure and meaning. For example, ensure that all emails within the organisation have the same spelling. Also consider creating email addresses to give to trainees even if you don't intend to use them - it completes the scenario better and adds more decision-making for trainees.
+ - Another possible error is a misunderstanding of the context for which this tool is suited. Could you imagine dealing with a truly escalated crisis situation through emails? Or would it be more likely that the team would be more likely to meet physically or at least make a phone call?
+ - Consider whether it is necessary to specifically instruct trainees at the beginning of the exercise that the emails are legitimate and that they do not need to look for phishing attempts. In one of our first exercises, we had trainees simply not open the initial email because they thought it was phishing - in short, they expected it in a cybersecurity exercise.
+ ### Related manifestations in the platform
+ - Establishing email communication - trainees sent an email. LA is filled just by sending an email. Only 1x can be used for each email address.
+ - Email reply from the instructor - see above.
+ ### Examples
+ - Internal communication in the organisation.
+ - Inter-organisational communication.
+ - Communication with oustsorced co-workers.
+ - Communication with journalists.
+ - Etc.
??? "2. Inject option: Execise information "
- ### Inject description
- It is used to communicate basic information about the exercise - e.g., introductory inject, contextual information, exercise time shift information, closing information.
- ### Channel
- Exercise information.
- ### Overlay
- The Exercise information inject can be displayed as an overlay, this is especially useful for important notifications or hints.
- ### Typical use in exercise
- This inject option is defacto a form of instruction, so it can be used in any exercise.
- ### Possible mistakes
- - Mixing "ingame" information and information outside the exercise. Our recommendation is that all information should be communicated in a manner as appropriate to the scenario as possible. In other words, we recommend omitting information that shifts the context out of the scenario (e.g., noting that there is a catering ready, etc.).
- ### Related manifestations in the platform
- - Depending on the information presented, any LA may follow up. However, the Click on the Confirmation Button has a specific use - e.g. in situations where we want trainees to consciously end the phase of reading more extensive input information and move on.
- ### Examples
- - Information about the exercise identity of the trainees.
- - Basic rules of the exercise.
- - Information that the next injects take place at a different time than the previous one.
- - Context information that cannot be naturally communicated within other injects.
- - Summary of the exercise.
+ ### Inject description
+ It is used to communicate basic information about the exercise - e.g., introductory inject, contextual information, exercise time shift information, closing information.
+ ### Channel
+ Exercise information.
+ ### Overlay
+ The Exercise information inject can be displayed as an overlay, this is especially useful for important notifications or hints.
+ ### Typical use in exercise
+ This inject option is defacto a form of instruction, so it can be used in any exercise.
+ ### Possible mistakes
+ - Mixing "ingame" information and information outside the exercise. Our recommendation is that all information should be communicated in a manner as appropriate to the scenario as possible. In other words, we recommend omitting information that shifts the context out of the scenario (e.g., noting that there is a catering ready, etc.).
+ ### Related manifestations in the platform
+ - Depending on the information presented, any LA may follow up. However, the Click on the Confirmation Button has a specific use - e.g. in situations where we want trainees to consciously end the phase of reading more extensive input information and move on.
+ ### Examples
+ - Information about the exercise identity of the trainees.
+ - Basic rules of the exercise.
+ - Information that the next injects take place at a different time than the previous one.
+ - Context information that cannot be naturally communicated within other injects.
+ - Summary of the exercise.
??? "3. Inject option: Document"
- ### Inject description
- This inject means sending a pdf document to the trainees to read, analyze or make a decision based on it.
- ### Channel
- The document is most often used in the Exercise information channel , but can also be presented in other, more specialized channels such as an intranet or website. Last but not least, it can also be sent by an email or using tools (more in the specific section -> [Tools](../specify/tools.md)) .
- ### Overlay
- It can be used.
- ### Typical use in the exercise
- Sending reports, analyses, briefings, internal regulations, etc. At the same time, the document can serve as a certain assignment, a framework, which is then followed by other injects - for example, questionnaires or decision point.
- ### Possible mistakes
- - Sending a long document. If you need trainees to read a large amount of text, do everything you can to get them to do so before the exercise - e.g. sending handouts in advance.
- ### Related manifestations in the platform
- - It depends on which channel you are presenting the document in and what the content is. For example, the document can be initiated by LA, which will be linked to an email response from the instructor, etc.
- - It can be very useful to link to a click on the confirmation button. Imagine a document display with a button below it that says "Done", "Analysis complete", "Understood", "Read", etc. *Please note that this option is not yet implemented.*
- ### Examples
- - Incident response plan
- - Analysis of the media situation
- - Threat analysis
- - Expert group report
- - Warning from the national authority
- - Opinion of the Authority
- - Etc.
+ ### Inject description
+ This inject means sending a pdf document to the trainees to read, analyze or make a decision based on it.
+ ### Channel
+ The document is most often used in the Exercise information channel , but can also be presented in other, more specialized channels such as an intranet or website. Last but not least, it can also be sent by an email or using tools (more in the specific section -> [Tools](../specify/tools.md)).
+ ### Overlay
+ It can be used.
+ ### Typical use in the exercise
+ Sending reports, analyses, briefings, internal regulations, etc. At the same time, the document can serve as a certain assignment, a framework, which is then followed by other injects - for example, questionnaires or decision point.
+ ### Possible mistakes
+ - Sending a long document. If you need trainees to read a large amount of text, do everything you can to get them to do so before the exercise - e.g. sending handouts in advance.
+ ### Related manifestations in the platform
+ - It depends on which channel you are presenting the document in and what the content is. For example, the document can be initiated by LA, which will be linked to an email response from the instructor, etc.
+ - It can be very useful to link to a click on the confirmation button. Imagine a document display with a button below it that says "Done", "Analysis complete", "Understood", "Read", etc. *Please note that this option is not yet implemented.*
+ ### Examples
+ - Incident response plan
+ - Analysis of the media situation
+ - Threat analysis
+ - Expert group report
+ - Warning from the national authority
+ - Opinion of the Authority
+ - Etc.
??? "4. Inject option: Questionnaire/scale"
- ### Inject description
- Standard questionnaire - single choice or multiple choice. It can also act as a scale.
- ### Channel
- They are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
- ### Overlay
- The use is very appropriate.
- ### Typical use in exercises
- This inject option is very suitable for strategic decision-making exercises for presenting scenario-related questions. For process-technical exercises it can also be used, for example towards the end of the exercise, to reflect on the steps taken.
- ### Possible mistakes
- - Avoid making the whole exercise just a questionnaire. Such exercises do exist, but it is not engaging for the trainees and it does not fully exploit the potential of the platform.
- - Avoid making the exercise look like a knowledge test. Questionnaires can often be about expressing opinions (e.g. scales) rather than factual accuracy.
- ### Related manifestations in the platform
- - Submiting of questionaire is manifestation itself.
- ### Examples:
- - Assessment of the gravity of the situation
- – Reflection of actions
- - Probability assessment
- - Answer a factual question about the scenario (legal, organisational and technological aspects, competences, ...).
- - Etc.
+ ### Inject description
+ Standard questionnaire - single choice or multiple choice. It can also act as a scale.
+ ### Channel
+ They are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
+ ### Overlay
+ The use is very appropriate.
+ ### Typical use in exercises
+ This inject option is very suitable for strategic decision-making exercises for presenting scenario-related questions. For process-technical exercises it can also be used, for example towards the end of the exercise, to reflect on the steps taken.
+ ### Possible mistakes
+ - Avoid making the whole exercise just a questionnaire. Such exercises do exist, but it is not engaging for the trainees and it does not fully exploit the potential of the platform.
+ - Avoid making the exercise look like a knowledge test. Questionnaires can often be about expressing opinions (e.g. scales) rather than factual accuracy.
+ ### Related manifestations in the platform
+ - Submiting of questionaire is manifestation itself.
+ ### Examples:
+ - Assessment of the gravity of the situation
+ – Reflection of actions
+ - Probability assessment
+ - Answer a factual question about the scenario (legal, organisational and technological aspects, competences, ...).
+ - Etc.
??? "5. Inject option: Decision point"
- ## Not yet implemented
-
- ### Inject description
- This is a similar inject to the questionnaire. However, the difference is that some options can be linked to another, automatic response in the platform. The number of options for a decision is 2-5.
- - Simple example: decide the situation to communicate YES/NO to the public. If you choose "NO", the platform will respond by receiving an email a few minutes later from a curious journalist who has heard about the situation.
- ### Channel
- These injects are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
- ### Overlay
- The use is very appropriate.
- ### Typical use in exercises
- This inject option is very suitable for strategic decision-making exercises for situations where it is necessary to choose one of the options. It is particularly useful when you want to emphasize the importance of a decision. Using this inject option will draw more attention to the decision and is likely to lead to discussion.
- ### Possible mistakes
- Avoid creating too many alternative paths - such an exercise will be much more difficult to prepare and most of the content will not be seen by trainees anyway. Simplification is desirable.
- ### Related manifestations in the platform
- - Submiting of decision point is manifestation itself.
- ### Examples:
- - Ransomware ransom
- - Contacting the authority/stakeholder
- - Escalation
- - Declaration of a state of emergency.
- - Etc.
+ ## Not yet implemented
+
+ ### Inject description
+ This is a similar inject to the questionnaire. However, the difference is that some options can be linked to another, automatic response in the platform. The number of options for a decision is 2-5.
+ - Simple example: decide the situation to communicate YES/NO to the public. If you choose "NO", the platform will respond by receiving an email a few minutes later from a curious journalist who has heard about the situation.
+ ### Channel
+ These injects are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
+ ### Overlay
+ The use is very appropriate.
+ ### Typical use in exercises
+ This inject option is very suitable for strategic decision-making exercises for situations where it is necessary to choose one of the options. It is particularly useful when you want to emphasize the importance of a decision. Using this inject option will draw more attention to the decision and is likely to lead to discussion.
+ ### Possible mistakes
+ Avoid creating too many alternative paths - such an exercise will be much more difficult to prepare and most of the content will not be seen by trainees anyway. Simplification is desirable.
+ ### Related manifestations in the platform
+ - Submiting of decision point is manifestation itself.
+ ### Examples:
+ - Ransomware ransom
+ - Contacting the authority/stakeholder
+ - Escalation
+ - Declaration of a state of emergency.
+ - Etc.
??? "6. Inject option: Free form"
## Not yet implemented
### Inject description
- Inject with open response, can contain input in the form of image, video or text. Trainees respond in the form of free text.
- ### Channel
- These injects are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
- ### Overlay
- The use is very appropriate.
- ### Typical use in exercises
- This inject is very suitable for strategic decision-making exercises.
- ### Possible mistakes
- - Too long or complex assignments.
- - Not using the possibility of conditioned responses to the free forms. It can enhance the exercise trainees.
- ### Related manifestations in the platform
- - Firstly, there is the actual submiting of the free form inject, which is sufficient if we don't need to evaluate the content during the exercise.
- - Secondly, it is the instructor's response - i.e., the instructor reads the content and evaluates the fulfillment of a predefined condition - accordingly, he chooses a response that can trigger further automated steps.
- ### Examples:
- - A short description of an incident in the text and a request for trainees to briefly describe the first steps they will take in their organisation in response.
- - Similarly, they can present arguments, summarise their position, assess the situation, etc. The assignment can take the form of text, image or video.
+ Inject with open response, can contain input in the form of image, video or text. Trainees respond in the form of free text.
+ ### Channel
+ These injects are displayed in a special channel, which we refer to here as Questions. The channel can of course be called something else.
+ ### Overlay
+ The use is very appropriate.
+ ### Typical use in exercises
+ This inject is very suitable for strategic decision-making exercises.
+ ### Possible mistakes
+ - Too long or complex assignments.
+ - Not using the possibility of conditioned responses to the free forms. It can enhance the exercise trainees.
+ ### Related manifestations in the platform
+ - Firstly, there is the actual submiting of the free form inject, which is sufficient if we don't need to evaluate the content during the exercise.
+ - Secondly, it is the instructor's response - i.e., the instructor reads the content and evaluates the fulfillment of a predefined condition - accordingly, he chooses a response that can trigger further automated steps.
+ ### Examples:
+ - A short description of an incident in the text and a request for trainees to briefly describe the first steps they will take in their organisation in response.
+ - Similarly, they can present arguments, summarise their position, assess the situation, etc. The assignment can take the form of text, image or video.
??? "7. Inject option: Media"
- ## Not yet implemented
- ### Description of the inject
- Media injects are currently a combination of media outputs and specifically named channels that is an abstraction of a real-world channel (the platform does not attempt to mimic the look of social networks or websites).
- - There may be more than one such channel in each exercise. Let's take a few examples: websites of different organizations, social networks, mass media or intranets. Injects can be in the form of plain text, or graphic materials (e.g. a Facebook post screenshots) or a prepared video can be inserted into the platform.
- ### Channel
- In general, we refer to this channel as "media." It's likely that multiple media channels with different names can be used during the exercise. For example, you could have one media channel called "FB" to display screenshots of FB posts, and another channel for the national cybersecurity authority's website to display warnings.
- ### Overlay
- It may be appropriate in some cases - e.g. breaking news, warnings, etc. It always depends on the exercise scenario.
- ### Typical use in exercise:
- - Website or intranet: e.g. www.narodniautorita.cz and posts here can be titled as blog, warning, etc. In the same logic, the feeds can be, for example, the website of a practitioners' organisation or other relevant body. Pre-prepared graphics (i.e. screenshots from the web, etc.) can also be used.
- - Mass media: works similarly to the previous one. It is very useful to use pre-prepared graphic materials or videos. The media can report on a current crisis that affects the practitioners directly or just changes the context of the exercise.
- - Social media –specific posts can influence the perception of the situation in the exercise from the point of view of ordinary people or our target groups. Again, this can relate directly to the situation in the scenario (response to a service outage) or a more general trend that will influence future decision making.
-
- ### Possible mistakes
- - The platform does not currently style specific media channels - it is therefore advisable to use pre-prepared graphics or videos within them.
- - Inconsistency with the "media behaviour" of the target group: choose channels that are actually relevant for the exercise. Do not try to use media channels just because you have the opportunity.
- ### Related manifestations in the platform
- - It very much depends on the context of the scenario. The related manifestations in the platform can be very explicit. For example, we expect trainees to immediately contact their PR department in response to the report they have seen, or we may ask them some form of question - an interactive inject - depending on the events presented in the media. Finally, we can imagine that media injects only help to complete the context of the exercise and are not closely linked to any specific activity.
-
- ### Examples:
- - Negative reactions on Facebook in response to our service outage.
- - TV report on the terrorist attack in our city.
- - A hateful blog post on a organization's website that appeared here because of stolen login credentials.
- - Warning from the IT department on the organisation's intranet.
+ ## Not yet implemented
+ ### Description of the inject
+ Media injects are currently a combination of media outputs and specifically named channels that is an abstraction of a real-world channel (the platform does not attempt to mimic the look of social networks or websites).
+ - There may be more than one such channel in each exercise. Let's take a few examples: websites of different organizations, social networks, mass media or intranets. Injects can be in the form of plain text, or graphic materials (e.g. a Facebook post screenshots) or a prepared video can be inserted into the platform.
+ ### Channel
+ In general, we refer to this channel as "media." It's likely that multiple media channels with different names can be used during the exercise. For example, you could have one media channel called "FB" to display screenshots of FB posts, and another channel for the national cybersecurity authority's website to display warnings.
+ ### Overlay
+ It may be appropriate in some cases - e.g. breaking news, warnings, etc. It always depends on the exercise scenario.
+ ### Typical use in exercise:
+ - Website or intranet: e.g. www.narodniautorita.cz and posts here can be titled as blog, warning, etc. In the same logic, the feeds can be, for example, the website of a practitioners' organisation or other relevant body. Pre-prepared graphics (i.e. screenshots from the web, etc.) can also be used.
+ - Mass media: works similarly to the previous one. It is very useful to use pre-prepared graphic materials or videos. The media can report on a current crisis that affects the practitioners directly or just changes the context of the exercise.
+ - Social media –specific posts can influence the perception of the situation in the exercise from the point of view of ordinary people or our target groups. Again, this can relate directly to the situation in the scenario (response to a service outage) or a more general trend that will influence future decision making.
+
+ ### Possible mistakes
+ - The platform does not currently style specific media channels - it is therefore advisable to use pre-prepared graphics or videos within them.
+ - Inconsistency with the "media behaviour" of the target group: choose channels that are actually relevant for the exercise. Do not try to use media channels just because you have the opportunity.
+ ### Related manifestations in the platform
+ - It very much depends on the context of the scenario. The related manifestations in the platform can be very explicit. For example, we expect trainees to immediately contact their PR department in response to the report they have seen, or we may ask them some form of question - an interactive inject - depending on the events presented in the media. Finally, we can imagine that media injects only help to complete the context of the exercise and are not closely linked to any specific activity.
+
+ ### Examples:
+ - Negative reactions on Facebook in response to our service outage.
+ - TV report on the terrorist attack in our city.
+ - A hateful blog post on a organization's website that appeared here because of stolen login credentials.
+ - Warning from the IT department on the organisation's intranet.
??? "8. Inject option: Off-platform activity"
- ## Not yet implemented
- ### Inject description
- Sometimes it can really make sense to include an off-platform inject. This increases our possibilities for creating interesting scenarios. Technically, this is an instruction in the platform that is combined with a confirmation button. Example: Instruction 'Discuss now three action steps that you could implement in your organization later this month. Once you have that, click on the button." And below that instruction would be a confirmation button "Done".
- ### Channel
- The confirmation button will display in Exercise information channel.
-
- ### Overlay
- It is very useful for this inject option.
-
-### Typical use in exercise:
- - Invitation to trainees to discuss something.
- - Invite a representative of the team to attend a physical interview with the journalist.
- - Call for a representative to go to the classified room and see documents that other members do not have access to.
-### Possible mistakes
- - By having the activity take place outside the platform, think about its evaluation. It may be followed up by other LAs - e.g. writing a summary in an email to a supervisor, etc.
- Or you can also decide to evaluate it outside the platform - e.g. a journalist will conduct an evaluation of the interview, according to the criteria given.
-### Related manifestations in the platform
- - Click on the confirmation button. However, it should be added that off-platform activities can also be stimulated by other injects - for example, an email instruction arrives for an off-platform task, after which a response is required. Thus, it mainly depends on the creativity of the designer.
-### Examples:
- - Crisis interview.
- - Press conference.
- - Convening a crisis meeting that takes place in person and where, for example, trainees must present the situation to management.
- - Discussion on a predefined topic.
- - Telephone interview.
- - Obtaining information from a classified document.
+ ## Not yet implemented
+ ### Inject description
+ Sometimes it can really make sense to include an off-platform inject. This increases our possibilities for creating interesting scenarios. Technically, this is an instruction in the platform that is combined with a confirmation button. Example: Instruction 'Discuss now three action steps that you could implement in your organization later this month. Once you have that, click on the button." And below that instruction would be a confirmation button "Done".
+ ### Channel
+ The confirmation button will display in Exercise information channel.
+
+ ### Overlay
+ It is very useful for this inject option.
+
+ ### Typical use in exercise:
+ - Invitation to trainees to discuss something.
+ - Invite a representative of the team to attend a physical interview with the journalist.
+ - Call for a representative to go to the classified room and see documents that other members do not have access to.
+ ### Possible mistakes
+ - By having the activity take place outside the platform, think about its evaluation. It may be followed up by other LAs - e.g. writing a summary in an email to a supervisor, etc.
+ Or you can also decide to evaluate it outside the platform - e.g. a journalist will conduct an evaluation of the interview, according to the criteria given.
+ ### Related manifestations in the platform
+ - Click on the confirmation button. However, it should be added that off-platform activities can also be stimulated by other injects - for example, an email instruction arrives for an off-platform task, after which a response is required. Thus, it mainly depends on the creativity of the designer.
+ ### Examples:
+ - Crisis interview.
+ - Press conference.
+ - Convening a crisis meeting that takes place in person and where, for example, trainees must present the situation to management.
+ - Discussion on a predefined topic.
+ - Telephone interview.
+ - Obtaining information from a classified document.
??? "9. Inject option: Hint"
- ### Inject description
- It's a form of conditioned inject that activates if trainees miss an action, take the wrong action, or become stuck.
- Example - trainees did not report the incident to management, but should have. The hint can be automated or sent by the instructor on an ad hoc basis.
- - **Automated hints:** are set in advance, in response to something happening or not happening by a certain time. These hints are set based on exercise designer intuition about what might be causing the problem or data gathered from earlier runs of the exercise.
- - **Ad hoc hints:** are created and sent by the instructor in response to unexpected developments during the exercise.
- ### Channel
- Hints are displayed in the exercise information channel.
- ### Overlay
- It is very suitable to use it.
- ### Typical use in an exercise
- - We want to alert trainees to a misstep, an omission of an action, or help them move on.
- - You can use a hint to notify about incoming emails—especially useful in strategic decision-making exercises or in scenarios where trainees do not work with emails regularly.
- - If you were creating some form of tutorial, you could also use them for positive feedback.
- ### Possible mistakes
- - Overuse of hints - they should be used very sensitively and only when absolutely necessary - i.e. when it is not possible to nudge the trainees with another form of inject - for example with an email from an exercise entity (this form of ingame hint is usually much better).
- - Overuse of ad-hoc hints - if possible, rely instead on pre-prepared hints that come for selected situations.
- - We do not recommend using hints to give positive feedback during exercise because uncertainty is an important part of the exercise.
- ### Related manifestations in the platform:
- - The purpose of the hint is to alert trainees that they should engage in a learning activity.
- ### Examples:
- - Trainees forget to contact their CISO, the whole scenario freezes because of this. Hint suggests to do it.
- - The trainees convened the crisis staff too early - hint suggests to proceed with further communication after the requirements given in the respective process have been fulfilled.
- - In the tutorial we've designed for our students, we aim to confirm the correct use of the tool. Specifically, when the student clicks on the required action using the tool, an overlay hint appears, confirming that they have successfully completed the step.
+ ### Inject description
+ It's a form of conditioned inject that activates if trainees miss an action, take the wrong action, or become stuck.
+ Example - trainees did not report the incident to management, but should have. The hint can be automated or sent by the instructor on an ad hoc basis.
+ - **Automated hints:** are set in advance, in response to something happening or not happening by a certain time. These hints are set based on exercise designer intuition about what might be causing the problem or data gathered from earlier runs of the exercise.
+ - **Ad hoc hints:** are created and sent by the instructor in response to unexpected developments during the exercise.
+ ### Channel
+ Hints are displayed in the exercise information channel.
+ ### Overlay
+ It is very suitable to use it.
+ ### Typical use in an exercise
+ - We want to alert trainees to a misstep, an omission of an action, or help them move on.
+ - You can use a hint to notify about incoming emails—especially useful in strategic decision-making exercises or in scenarios where trainees do not work with emails regularly.
+ - If you were creating some form of tutorial, you could also use them for positive feedback.
+ ### Possible mistakes
+ - Overuse of hints - they should be used very sensitively and only when absolutely necessary - i.e. when it is not possible to nudge the trainees with another form of inject - for example with an email from an exercise entity (this form of ingame hint is usually much better).
+ - Overuse of ad-hoc hints - if possible, rely instead on pre-prepared hints that come for selected situations.
+ - We do not recommend using hints to give positive feedback during exercise because uncertainty is an important part of the exercise.
+ ### Related manifestations in the platform:
+ - The purpose of the hint is to alert trainees that they should engage in a learning activity.
+ ### Examples:
+ - Trainees forget to contact their CISO, the whole scenario freezes because of this. Hint suggests to do it.
+ - The trainees convened the crisis staff too early - hint suggests to proceed with further communication after the requirements given in the respective process have been fulfilled.
+ - In the tutorial we've designed for our students, we aim to confirm the correct use of the tool. Specifically, when the student clicks on the required action using the tool, an overlay hint appears, confirming that they have successfully completed the step.
## Conditional injects
diff --git a/docs/tech/api/openapi.yml b/docs/tech/api/openapi.yml
new file mode 100644
index 0000000000000000000000000000000000000000..6495f76d6423061851e098f3ed0f35ce57ba139e
--- /dev/null
+++ b/docs/tech/api/openapi.yml
@@ -0,0 +1,332 @@
+openapi: 3.0.0
+info:
+ title: Inject API
+ version: 0.4.0
+servers:
+ - url: http://api.example.com/inject/api/v1
+ description: Example API URL
+paths:
+ /version:
+ get:
+ tags:
+ - Version
+ summary: Retrieve the backend and definition versions
+ responses:
+ '200':
+ description: Success
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ version:
+ type: string
+ description: Backend version
+ definition_version:
+ type: string
+ description: Definition version supported by the backend
+ required:
+ - version
+ - definition_version
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /user/create-users:
+ post:
+ tags:
+ - user
+ summary: Upload a list of users in CSV format
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ format: binary
+ required:
+ - file
+ responses:
+ '201':
+ $ref: "#/components/responses/Success"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /export_import:
+ get:
+ tags:
+ - export_import
+ summary: Export database
+ description: ""
+ responses:
+ '200':
+ description: Exported file
+ content:
+ application/zip:
+ schema:
+ type: string
+ format: binary
+ '500':
+ $ref: "#/components/responses/Error"
+ post:
+ tags:
+ - export_import
+ summary: Import database
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ format: binary
+ required:
+ - file
+ responses:
+ '200':
+ $ref: "#/components/responses/Success"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /exercise_definition/upload-definition:
+ post:
+ tags:
+ - upload_definition
+ description: Upload a definition
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ description: Name of the definition
+ file:
+ type: string
+ format: binary
+ description: Definition file
+ required:
+ - name
+ - file
+ responses:
+ '200':
+ $ref: "#/components/responses/Success"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /exercise_definition/validate:
+ post:
+ tags:
+ - validate-definition
+ description: Validate the uploaded definition
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ format: binary
+ description: Definition file
+ required:
+ - file
+ responses:
+ '200':
+ $ref: "#/components/responses/Success"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /running_exercise/get_exercise_logs/{exercise_id}:
+ get:
+ tags:
+ - get_exercise_logs
+ description: Retrieve logs for the specific exercise
+ parameters:
+ - name: anonymize
+ in: query
+ description: Set to true for user anonymization otherwise leave empty
+ schema:
+ type: boolean
+ allowEmptyValue: true
+ - name: exercise_id
+ in: path
+ description: Id of the exercise
+ required: true
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Exported file
+ content:
+ application/zip:
+ schema:
+ type: string
+ format: binary
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /running_exercise/upload/{team_id}/:
+ post:
+ tags:
+ - team_upload_file
+ description: Upload a file as the specified team
+ parameters:
+ - name: team_id
+ in: path
+ description: Team id
+ required: true
+ schema:
+ type: integer
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ format: binary
+ description: File to upload
+ required:
+ - file
+ responses:
+ '200':
+ $ref: "#/components/responses/Success"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /running_exercise/{team_id}/{file_id}/:
+ get:
+ tags:
+ - team_download_file
+ parameters:
+ - name: team_id
+ in: path
+ required: true
+ schema:
+ type: integer
+ - name: file_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: File
+ content:
+ application/*:
+ schema:
+ type: string
+ format: binary
+ text/*:
+ schema:
+ type: string
+ format: binary
+ image/*:
+ schema:
+ type: string
+ format: binary
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /auth/login/:
+ post:
+ tags:
+ - auth
+ description: Login a user based on the credentials
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ username:
+ type: string
+ password:
+ type: string
+ required:
+ - username
+ - password
+ responses:
+ '200':
+ description: Login successful
+ $ref: "#/components/responses/AuthResponse"
+ '403':
+ $ref: "#/components/responses/Error"
+
+ /auth/logout/:
+ post:
+ tags:
+ - auth
+ description: Logout a user
+ responses:
+ '200':
+ $ref: "#/components/responses/AuthResponse"
+ '500':
+ $ref: "#/components/responses/Error"
+
+ /auth/session:
+ get:
+ tags:
+ - auth
+ description: Check whether the session is still valid
+ responses:
+ '200':
+ $ref: "#/components/responses/AuthResponse"
+ '500':
+ $ref: "#/components/responses/Error"
+
+components:
+ schemas:
+ JsonResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ - error
+ detail:
+ type: string
+ description: Message with extra details
+ required:
+ - status
+ - detail
+ AuthResponse:
+ type: object
+ properties:
+ sessionid:
+ type: string
+ nullable: true
+ description: session id
+ required:
+ - sessionid
+ responses:
+ Success:
+ description: Operation successful
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/JsonResponse"
+ Error:
+ description: "Error"
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/JsonResponse"
+ AuthResponse:
+ description: "Response to auth endpoints"
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/AuthResponse"
diff --git a/docs/tech/architecture/definitions/CHANGELOG.md b/docs/tech/architecture/definitions/CHANGELOG.md
new file mode 100644
index 0000000000000000000000000000000000000000..f5150bbd36ba80e194fc696e9667d3afca1e839e
--- /dev/null
+++ b/docs/tech/architecture/definitions/CHANGELOG.md
@@ -0,0 +1,357 @@
+## 0.18.1
+
+Add note to questions. inject/backend#373
+
+### questionnaires.yml
+
+- add optional field `note` to question
+
+
+## 0.18.0
+
+Add option to tools to signify that they don't require an input. inject/backend#194
+Change the type of `default_response` field. inject/backend#368
+
+### tools.yml
+
+- add optional field `requires_input` to tool
+- change the type of `default_response` to content
+
+
+## 0.17.2
+
+Fixed embedding in email templates
+
+No format changes
+
+
+## 0.17.1
+
+Allow embedding images and videos. inject/backend#359
+
+All `content` type fields now allow for embedding images/audio/video by using special syntax.
+See readme for more information.
+
+## 0.17.0
+
+Add support for markdown in questionnaires. inject/backend#361
+Add missing field from tools. inject/backend#297
+
+### questionnaires.yml
+
+- remove field `description` from questionnaire
+- add field `content` to questionnaire
+
+### tools.yml
+
+- add field `category` to tool
+
+
+## 0.16.0
+
+More definition enhancements. inject/backend#357
+
+### config.yml
+
+- add field `target_audience`
+- add field `prerequisites`
+
+### objectives.yml
+
+- add field `order` to objectives
+- add field `milestones` to activities
+
+### milestones.yml
+
+- remove field `activity`
+
+### email.yml
+
+- add field `subject` to email templates
+
+## 0.15.2
+
+Allow exercise designers to add more information to the definition. inject/backend#353
+
+### config.yml
+
+- add field `description`
+
+### objectives.yml
+
+- add field `description` to both objectives and activities
+
+### channels.yml
+
+- add field `display_name`
+- add field `description`
+
+### milestones.yml
+
+- add field `display_name`
+- add field `description`
+- add field `tags`
+
+### roles.yml
+
+- add field `display_name`
+- add field `description`
+
+### questionnaires.yml
+
+- add field `description` to questionnaire
+
+## 0.15.1
+
+Add confirmation button to info alternatives. inject/backend#351
+
+### injects.yml
+
+- add field `confirmation` to info alternatives
+
+## 0.15.0
+
+Allow specifying open-ended questions in questionnaires. inject/backend#340
+
+### questionnaires.yml
+
+- add field `type` to questions
+- add field `related_milestones` to `free-form` type questions
+- add field `multiline` to `free-form` type questions
+
+## 0.14.0
+
+Allow multiple info channels in a definition. #336
+
+### injects.yml
+
+- add field `target` that specifies info channel for the info injects
+
+### channels.yml
+- allow occurrence of multiple `info` channels
+
+## 0.13.0
+
+Enabled a more fine-grained control over milestone modifications for
+scale-based questions. #315
+
+### questionnaires.yml
+
+- remove field `control` in question objects
+- added field `controls` in question objects,
+ which is a mapping of `choice number` to `control`.
+ See [readme](README.md#questionnairesyml) for more details.
+
+## 0.12.1
+
+Enable specification of `roles` in `email` type injects.
+
+### injects.yml
+
+- allow specifying `roles` in control blocks inside `email` type injects
+
+## 0.12.0
+
+Replace `text` field by `content` in `Questionnaire` questions.
+From now, the questions of questionnaires can be formatted via `content`. #251
+
+### questionnaires.yml
+
+- remove field `text` of questions
+- add field `content` to questions
+
+## 0.11.0
+
+Change the behavior of `delay` on injects.
+Whenever an alternative is delayed, the condition is now checked throughout the duration.
+If the condition becomes false, the inject is cancelled and a new alternative can be selected. #266
+
+### injects.yml
+
+- change behavior of `delay` field
+
+## 0.10.0
+
+Change the behavior of `info` alternatives.
+When an alternative contains no `content`, it will not create an action log. #264
+
+### injects.yml
+
+- change behavior of `content` field in `info` injects
+
+## 0.9.1
+
+Add option to specify initial state for milestones. #263
+
+### milestones.yml
+
+- add optional field `initial_state`
+
+
+## 0.9.0
+
+Removed manual injects. #228
+All injects are now considered to be **automatic injects**.
+
+### injects.yml
+
+- remove field `auto`
+
+
+## 0.8.0
+
+Add a new required concept called `learning objectives`.
+This concept _must_ be included in all exercise definition. #170
+
+### objectives.yml
+
+- added new file
+
+### milestones.yml
+
+- add field `activity`
+
+## 0.7.0
+
+Add simple questionnaires. #165
+
+### channels.yml
+
+- add new channel type `form`
+
+### questionnaires.yml
+
+- added new file
+
+
+## 0.6.1
+
+Add overlay to injects. #153
+
+### injects.yml
+
+- add field `overlay` to `info` and `email` injects
+
+
+## 0.6.0
+
+Added a new concept called `channels` #151. This concept is saved in a new `channels.yml` file.
+See [readme](README.md#channelsyml) for details.
+
+### config.yml
+
+- remove `enable_email` field
+- remove `team_visible_milestones` field, team visible milestones can now be specified without this flag
+
+### channels.yml
+
+- added this new required file
+
+### injects.yml
+
+- remove field `hidden`
+- rename field `injects` to `alternatives`
+- add field `type` to inject
+- specify new types of alternatives, see [readme](README.md#alternatives-_info_)
+
+### tools.yml
+
+- remove old `content`, `content_path`, `file_name` fields
+- remove old `milestone_condition`, `activate_milestone`, `deactivate_milestone`, `roles` fields
+- add new fields `content` and `control`, see [readme](README.md#common-definitions) for details
+
+### email.yml
+
+- remove `activate_milestone`, `deactivate_milestone` fields from email address
+- add `control` field to email address
+- remove old `content`, `content_path`, `file_name` templates from email templates
+- remove `activate_milestone`, `deactivate_milestone` fields from templates
+- add new fields `content` and `control` to email templates,
+ see [readme](README.md#common-definitions) for details
+
+
+## 0.5.1
+
+Allow using directories of files instead of single YAML files inside the definition #128
+
+## 0.5.0
+
+### injects.yml
+
+- add inject field `subject`
+
+## 0.4.1
+
+### config.yml
+
+- remove `team_file_upload` field, the feature is now always enabled
+- remove `custom_team_names` field, team names have been removed from the definition, it is now
+ a parameter when creating an exercise
+- remove `team_count` field, it is now a parameter when creating an exercise
+
+### teams.yml
+
+- temporarily removed from the definition
+
+## 0.4.0
+
+Introduce simplified syntax for `activate_milestone` and `deactivate_milestone`,
+which replaced the old field `reach_milestone`. #98
+
+Instead of the old syntax from `reach_milestone` reminding logical condition,
+the new fields `(de)activate_milestone` have a simple enumeration of milestones,
+which could be separated by a comma, space, or comma followed by space.
+
+### injects.yml
+
+- inject field `reach_milestone` is replaced by fields `activate_milestone` and `deactivate_milestone`
+
+### tools.yml
+
+- response field `reach_milestone` is replaced by fields `activate_milestone` and `deactivate_milestone`
+
+### email.yml
+
+- email and template field `reach_milestone` is replaced by fields `activate_milestone` and `deactivate_milestone`
+
+## 0.3.0
+
+### milestones.yml
+
+- add field `final` to milestones #74
+
+## 0.2.0
+
+Introduce support for markdown content in `injects`, `tool responses` and `email templates`. #84
+
+Add new optional folder `content` to the definition file structure.
+This folder should contain markdown files which will be pointed to by `content_path` fields.
+Only one of the `content`, `content_path` fields can be set at the same time.
+If neither field is set, then the content is considered to be empty.
+
+### tools.yml
+
+- rename response field `answer` to `content`
+- add field `content_path` to responses
+
+### inject.yml
+
+- add field `content_path` to injects
+
+### email.yml
+
+- add field `content_path` to emails
+
+## 0.1.1
+
+### email.yml
+
+- Add `organization` field to email addresses #83
+
+### injects.yml
+
+- Add `organization` field to inject categories #83
+
+## 0.1.0
+
+Initial version, no changes.
diff --git a/docs/tech/architecture/definitions/README.md b/docs/tech/architecture/definitions/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..1ba29e15997a0ace73a5b4d48754ba6f0180cf95
--- /dev/null
+++ b/docs/tech/architecture/definitions/README.md
@@ -0,0 +1,379 @@
+# Definitions
+
+This directory contains the example definitions which showcase various functionality.
+
+## Versioning
+
+Definition use a modified [semantic versioning](https://semver.org/):
+
+- **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 behavior.
+- **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 topmost version in the changelog.
+For example, backend version [`2.0.0`](https://gitlab.fi.muni.cz/inject/backend/-/tags/v2.0.0)
+supports definitions with version [`0.12.1`](https://gitlab.fi.muni.cz/inject/backend/-/blob/v2.0.0/definitions/CHANGELOG.md?ref_type=tags).
+
+## 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.
+
+### Quick list
+
+- [common definitions](#common-definitions)
+- [config.yml](#configyml)
+- [channels.yml](#channelsyml)
+- [injects.yml](#injectsyml)
+- [tools.yml](#toolsyml)
+- [milestones.yml](#milestonesyml)
+- [email.yml](#emailyml)
+- [roles.yml](#rolesyml)
+- [questionnaires.yml](#questionnairesyml)
+- [objectives.yml](#objectivesyml)
+
+### 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 formatted as **Markdown** with [these](https://python-markdown.github.io/#differences) restrictions.
+The Markdown syntax can be found [here](https://daringfireball.net/projects/markdown/syntax).
+
+**Warning**: The frontend application sanitizes the HTML generated by Markdown using
+the default options of [sanitize-html](https://www.npmjs.com/package/sanitize-html).
+Some content may therefore not be shown as intended. Mainly, `<script>`, `<style>`, `<iframe>`,
+`<img>`, `<video>`, and `<form>` tags, along with attributes like `id`,
+`class`, and event handlers (e.g., `onclick`, `onload`) are not allowed. Furthermore, the only URL schemes
+allowed (in `href`, `src`, and `cite`) are `http`, `https`, `ftp`, `mailto`, and `tel`.
+
+If you want to embed media (images, videos, or audio recordings), use files from the definition.
+To embed a file, simply surround the path to the file in `{{}}`.
+For example:
+
+```yaml
+content:
+ content: "This is an embedded image {{files/image.png}}"
+```
+
+**Warning**: If the embedding is done directly in YAML (like the example above),
+you have to surround the content in `"`, just like the example.
+
+The same syntax can also be used in markdown files,
+without the requirement of surrounding the text in `"`.
+It is recommended to do embeddings in markdown files instead of specifying it directly in YAML.
+
+All most commonly used [image](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#supported_image_formats), [audio, and video](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#index_of_media_container_formats_file_types) file formats are supported.
+
+- **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 milestone _names_ (not display names),
+ which will be activated after an object is sent/processed
+- **deactivate_milestone**: _str, default=""_ - a comma-separated list of milestone _names_ (not display names),
+ 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.
+- **description**: _string, default=""_ - description of the definition
+- **target_audience**: _string, default=""_ - target audience of the definition
+- **prerequisites**: _list of strings, default=empty_ - list of prerequisites for the definition
+- **version**: _string_ - semver version string of the format this definition uses, see [versioning](#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
+- **description**: _string, default=""_ - description of the objective
+- **order**: _int, default=0_ - order of the objective,
+ defines the order in which objectives will be displayed for instructors,
+- **activities**: - list of learning activities
+ - **name**: _string_ - name of the learning activity
+ - **description**: _string, default=""_ - description of the activity
+ - **tags**: _string, default=""_ - a comma-separated list of tags corresponding to this activity
+ - **milestones**: _list of strings, default=empty_ - list of milestones related to this activity,
+ a milestone can only be linked to _one_ activity
+
+### channels.yml
+
+This file contains the definitions of _all_ channels used in the exercise.
+
+- **name**: _string, unique_ - the name that will be displayed to users
+- **display_name**: _string, default=name_ - display name of the channel
+- **description**: _string, default=""_ - description of the channel
+- **type**: _string_ - the type of messages that will be sent to this channel, see [injects.yml](#injectsyml) for details.
+
+Currently supported channel types:
+
+- `info` - the most basic type of message,
+ A definition _can_ include one or more channels 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 (except the `info` channels).
+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
+- **target**: _string, default=""_ - a mandatory field (only for `info` injects) that specifies to which info channel should be the inject sent
+
+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](#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](#control), default=empty_ - milestone conditions are checked when the alternative is being selected,
+ milestone modifications happen _after_ the alternative has been selected
+- **overlay**: _[overlay](#overlay), default=empty_
+- **confirmation**: _default=empty_ - adds a confirmation button to this alternative
+ - **text**: _string_ - the button text
+ - **control**: _[control](#control)_ - milestone modifications happen _after_ a team presses the button,
+ milestone condition and roles cannot be specified
+
+#### 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](#content), default=empty_
+- **control**: _[control](#control), default=empty_ - milestone conditions are checked when the alternative is being selected,
+ milestone modifications happen _after_ the alternative has been selected
+- **extra_copies**: _int, default=0_ - number of extra copies to be sent, useful for specifying spam email.
+- **overlay**: _[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
+- **category**: _string, default=""_ - category of the tool, used to group multiple tools together visually
+- **tooltip_description**: _string, default=""_ - Description of a tool displayed to trainees.
+- **hint**: _string, default=""_ - Argument hint
+- **default_response**: _[content](#content), default=Empty_ - 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:
+ ```yml
+ - roles: role_name_1 role_name_2 role_name_3
+ ```
+- **requires_input**: _bool, default=True_ - if set to False, this tool will not require an input
+ and will be showcased as a simple button, will cause the `param` fields in responses to be ignored when selecting a response
+- **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](https://docs.python.org/3/library/re.html) 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](#content), default=empty_
+ - **control**: _[control](#control), default=empty_ - milestone condition is checked when a response is being selected,
+ milestone modifications are triggered _after_ this response has been selected
+
+### 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
+- **display_name**: _string, default=name_ - display name of the milestone
+- **description**: _string, default=""_ - description of the milestone
+- **tags**: _list of strings, default=empty_ - optional list of tags related to the milestone
+- **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.
+- **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.
+- **description**: _string_ - Description of the correspondent and related context for the instructor.
+- **control**: _[control](#control), default=empty_ - milestone condition and roles cannot be specified,
+ milestone modifications are triggered _after_ a team sends an email to this address
+- **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.
+ - **subject**: _string_ - subject of the email thread when sending this template
+ - **content**: _[content](#content), default=empty_
+ - **control**: _[control](#control), default=empty_ - milestone condition and roles cannot be specified,
+ milestone modifications are triggered once the template is sent
+
+### roles.yml
+
+Required if roles are enabled.
+This file contains all role names:
+
+- **name**: _string, unique_ - Name of the role.
+- **display_name**: _string, default=name_ - display name of the role
+- **description**: _string, default=""_ - description of the role
+
+### questionnaires.yml
+
+This file contains all questionnaires.
+Each questionnaire has the following fields:
+
+- **title**: _string_ - title of the questionnaire
+- **content**: _content, default=empty_ - description 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](#control), default=empty_ - the milestone condition is checked
+ when the questionnaire should be sent (similar to injects),
+ the milestone modifications are triggered once _after_ the questionnaire has been answered fully (all questions answered)
+- **overlay**: _[overlay](#overlay), default=empty_
+- **questions**: details specified bellow
+ - **content**: _[content](#content), default=empty_ - should contain the text of the question
+ - **type**: _string, default="radio"_ - type of the question, determines what fields can be specified,
+ currently supported values are `radio` and `free-form`
+ - **note**: _string, default=""_ - add a stylized note _after_ the question
+
+#### Question: radio
+
+- **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](#control), default=empty_ - a mapping of choice numbers to
+ control objects in the format
+ ```yaml
+ 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].
+
+#### Question: free-form
+
+- **related_milestones**: _list of strings, default=empty_ - list of related milestone names,
+ these milestones will be shown to the instructor for evaluation,
+ example:
+ ```yaml
+ related_milestones:
+ - milestone_1
+ - milestone_2
+ # or
+ related_milestones: [ milestone_1, milestone_2 ]
+ ```
+- **multiline**: _bool, default=False_ - changes whether the input text field should be multiline or single line
diff --git a/docs/tech/log-format.md b/docs/tech/log-format.md
index 051066d703f176c9b50f9ac287725da00c060e6d..d8ead5429c485df76a410773d339c5f485e94f88 100644
--- a/docs/tech/log-format.md
+++ b/docs/tech/log-format.md
@@ -35,27 +35,6 @@ Many of the fields described here are also described
in the definition format which can be found
[here](https://gitlab.fi.muni.cz/inject/backend/-/blob/main/definitions/README.md?ref_type=heads).
-### Quick list:
-
-**Exercise files**:
-- [exercise.jsonl](#exercisejsonl)
-- [teams.jsonl](#teamsjsonl)
-- [instructors.jsonl](#instructorsjsonl)
-- [exercise_injects.jsonl](#exercise_injectsjsonl)
-- [exercise_milestones.jsonl](#exercise_milestonesjsonl)
-- [exercise_tools.jsonl](#exercise_toolsjsonl)
-- [exercise_questionnaires.jsonl](#exercise_questionnairesjsonl)
-- [exercise_learning_objectives.jsonl](#exercise_learning_objectivesjsonl)
-- [email_participants.jsonl](#email_participantsjsonl)
-- [file_infos.jsonl](#file_infosjsonl)
-
-**Individual team files**:
-- [inject_states.jsonl](#inject_statesjsonl)
-- [questionnaire_states.jsonl](#questionnaire_statesjsonl)
-- [action_logs.jsonl](#action_logsjsonl)
-- [milestones.jsonl](#milestonesjsonl)
-- [emails.jsonl](#emailsjsonl)
-
### Timestamps
All fields with the `timestamp` type are timestamps in `ISO 8601` format.
diff --git a/files-from-repos/intro-definition.zip b/files-from-repos/intro-definition.zip
index 2a07576b5608ee52b89633fe497d323c3ce51ad9..67f16d65b00b67b516cee33e3236f8a1e1ca2c75 100644
Binary files a/files-from-repos/intro-definition.zip and b/files-from-repos/intro-definition.zip differ
diff --git a/files-from-repos/showcase-definition.zip b/files-from-repos/showcase-definition.zip
index 0807f0d34c97d85cb177302f2e07897473208f84..efe5238ee6af05eef613de690a95068b8f37bd23 100644
Binary files a/files-from-repos/showcase-definition.zip and b/files-from-repos/showcase-definition.zip differ
diff --git a/introductory-definition b/introductory-definition
index 2e76a590840b633aa6ffa4b84311667c8b75009c..22f416c4db54e0e3ee18e274231ab0f820f5fd5b 160000
--- a/introductory-definition
+++ b/introductory-definition
@@ -1 +1 @@
-Subproject commit 2e76a590840b633aa6ffa4b84311667c8b75009c
+Subproject commit 22f416c4db54e0e3ee18e274231ab0f820f5fd5b
diff --git a/overrides/partials/header.html b/overrides/partials/header.html
index a1ebee7dc7253559d8d3fe3cf0672dbd856aa865..be1d5f61d6f360a21cd49a51ef83084c2c7d391e 100644
--- a/overrides/partials/header.html
+++ b/overrides/partials/header.html
@@ -48,7 +48,7 @@
<option value="/bastion/">Version 2.0</option>
</select>
</div>
- -->
+
{% if config.theme.palette %}
{% if not config.theme.palette is mapping %}
{% include "partials/palette.html" %}
diff --git a/showcase-definition b/showcase-definition
index d8d877da2081db9cf6f63785d833484cde49a4d5..c97edaec330722fd4e257c3671282ebaddeaee05 160000
--- a/showcase-definition
+++ b/showcase-definition
@@ -1 +1 @@
-Subproject commit d8d877da2081db9cf6f63785d833484cde49a4d5
+Subproject commit c97edaec330722fd4e257c3671282ebaddeaee05
diff --git a/utilities.sh b/utilities.sh
deleted file mode 100755
index 06ed98752fee5c81b434e9f1cf81382145317174..0000000000000000000000000000000000000000
--- a/utilities.sh
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env bash
-
-# Initialize and update git submodules
-git submodule init
-git submodule update --remote
-
-# Check the status of the git submodules
-git submodule status
-
-# Create necessary directories
-mkdir -p docs/tech
-mkdir -p files-from-repos
-
-# Copy files to the respective directories
-cp ./backend/definitions/README.md ./docs/tech/architecture/definitions/README.md
-cp ./backend/definitions/CHANGELOG.md ./docs/tech/architecture/definitions/CHANGELOG.md
-cp ./backend/openapi.yml ./docs/tech/api/openapi.yml
-
-cp ./showcase-definition/assets/definition.zip ./files-from-repos/showcase-definition.zip
-cp ./introductory-definition/assets/definition.zip ./files-from-repos/intro-definition.zip