Merge branch 'citadel-main-sync' into 'main'

Citadel-Main sync

See merge request inject/inject-docs!66

docs/INJECT_process/specify/injects.md

@@ -18,17 +18,18 @@
 
 
 ??? "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:
+      Channels are the locations within the platform where injects appear. Each channel has a name, which can be set to any string, and a type, which defines the form of the injects it contains. The basic channel types are:
 
-      - **Exercise    information** – general channel for communication about exercise
+      - **Exercise    information** – general channel type 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:
+      - **Questions** - a channel type where various interactive injects (e.g. questionnaires) are displayed. 
+
+      Media channels can be simulated by creating additional channels of type _Exercise information_. The implementation of a designated media channel type is being considered:
+      
       - **Website** - for simulating websites of different organizations 
       - **Intranet**
-      - **Social media** / - can be named as X, Facebook, LN, ... 
+      - **Social media** - May carry the name of a specific media outlet.
       - **Media** - injects in the form of articles, audio or video. May carry the name of a specific media outlet. 
 
 
@@ -50,8 +51,8 @@ Let's now take a detailed look at the different inject options. This is not a fi
 ??? "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. 
+    ### Channel type
+      Only a specific channel type for emails. It functions as a simple email client. 
     ### Overlay
       Emails are usually not used in conjunction with overlays.
     ### Typical use in an exercise 
@@ -76,7 +77,7 @@ Let's now take a detailed look at the different inject options. This is not a fi
 ??? "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
+    ### Channel type
       Exercise information. 
     ### Overlay
       The Exercise information inject can be displayed as an overlay, this is especially useful for important notifications or hints. 
@@ -97,8 +98,8 @@ Let's now take a detailed look at the different inject options. This is not a fi
 ??? "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)). 
+    ### Channel type
+      The document is most often used in the Exercise information channel type , but can also be presented in other, more specialized channel types 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
@@ -106,8 +107,8 @@ Let's now take a detailed look at the different inject options. This is not a fi
     ### 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.* 
+      - It depends on which channel type 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. 
     ### Examples
       - Incident response plan
       - Analysis of the media situation
@@ -122,8 +123,8 @@ Let's now take a detailed look at the different inject options. This is not a fi
 ??? "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. 
+    ### Channel type
+      They are displayed in a special channel type, which we refer to here as Questions.  
     ### Overlay
       The use is very appropriate. 
     ### Typical use in exercises
@@ -141,13 +142,12 @@ Let's now take a detailed look at the different inject options. This is not a fi
       - 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.
+    ### Channel type
+      These injects are displayed in a special channel type, which we refer to here as Questions. 
     ### Overlay
       The use is very appropriate. 
     ### Typical use in exercises
@@ -166,11 +166,11 @@ Let's now take a detailed look at the different inject options. This is not a fi
 
 
 ??? "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. 
+    ### Channel type
+      These injects are displayed in a special channel type, which we refer to here as Questions.
     ### Overlay
       The use is very appropriate.
     ### Typical use in exercises
@@ -190,10 +190,10 @@ Let's now take a detailed look at the different inject options. This is not a fi
 ??? "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.
+      Media injects are currently a combination of media outputs and specifically named channel types that is an abstraction of a real-world media (the platform does not attempt to mimic the look of social networks or websites). 
+      - There may be more than one such channel type 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 type
+      In general, we refer to this channel type as "media." It's likely that multiple media channel  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: 
@@ -214,11 +214,11 @@ Let's now take a detailed look at the different inject options. This is not a fi
       - 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.  
+    ### Channel type
+      The confirmation button will display in Exercise information channel type.  
 
     ### Overlay
       It is very useful for this inject option. 
@@ -247,8 +247,8 @@ Let's now take a detailed look at the different inject options. This is not a fi
       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. 
+    ### Channel type
+      Hints are displayed in the exercise information channel type. 
     ### Overlay
       It is very suitable to use it. 
     ### Typical use in an exercise

docs/changelog.md

 # Changelog
 
-The INJECT Exercise Platform (IXP) is released is different versions.
+The INJECT Exercise Platform (IXP) is released in different versions.
 Most significant changes between the releases are listed below.
 
 This list is not complete, as each new release also includes numerous fixes
@@ -10,8 +10,7 @@ and smaller improvements.
 
 ### Improved UI
 
-The platform was enhanced to provide a more appealing experience while ensuring
-that users have all the necessary information to use it efficiently:
+Improvements were made to the platform to create a better user experience and increase efficiency:
 
 - improved home page
     - added ability to view non-running exercises
@@ -29,9 +28,9 @@ that users have all the necessary information to use it efficiently:
 
 ### New options for exercise definition
 
-Additional optional features were added to the exercise definition format
+Additional optional features were added to the [exercise definition format](./tech/architecture/definitions/README.md)
 to enable you to create more complex and engaging exercises.
-The most important features are listed below:
+The most important changes are listed below:
 
 - ability to embed media (audio, video, and images) in injects
 - support for more file types in document viewer (video, audio, and SVGs)

docs/index.md

@@ -33,7 +33,7 @@ Welcome! Whether you're responsible for technical deployment or facilitating tab
 !!! News
     *February 16, 2025* 
     We've just released the third version of the INJECT Exercise Platform (v 3.0.0). The entire documentation has been updated to reflect this new version. 
-    If you are using an older version of the platform, please check our [Version Compatibility](tech/version-compatibility.md) page to ensure you are using the correct documentation version.
+    If you are using an older version of the platform, please check our [Version Compatibility](tech/version-compatibility.md) page.
  
 
 ## The Big Picture

docs/known-issues.md

@@ -22,6 +22,37 @@ The `data` directory is located in the base directory of the backend.
 These files can be deleted while the server is running,
 however only if there are no actual running exercises.
 
+## Editor: The created definition is invalid
+
+### Issue
+
+Leaving the _Content_ field blank during the _Injects preparation_ phase results in the creation of invalid definitions.
+
+### Cause
+
+In this case, the _content_path_ in _injects.yml_ is set to a non-existing file.
+
+### Solution
+
+During the _Injects preparation_ phase in Editor, make sure to fill in the _Content_ field for all your injects.
+
+## Editor: Failed to update inject (ConstraintError)
+
+### Issue
+
+When clicking on _Save_ or _Save & Exit_ during the _Injects preparation_ phase, the following error is shown:
+
+![Failed to update information inject: ConstraintError: Unable to add key to index 'injectInfoId': at least one key does not satisfy the uniqueness requirements. ConstraintError: Unable to add key to index 'injectInfoId': at least one key does not satisfy the uniqueness requirements.](./images/editor-inject-preparation-error.png)
+
+### Cause
+
+When saving the prepared inject for the first time, the creation process triggers twice due to an error in code.
+Therefore, the code is trying to create an inject with the same key (id), triggering the constraint error.
+
+### Solution
+
+Ignore the error.
+
 ## Conclusion
 
 If you require further assistance, don't hesitate to report issues to us. The [Report issue](report-issue.md) page includes instructions on how to report bugs.

docs/license.md

@@ -4,7 +4,7 @@ INJECT Exercise Platform is open-source software developed by Masaryk University
 
 ## License Terms
 
-Copyright 2024 Masaryk University
+Copyright 2025 Masaryk University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/tech/architecture/definitions/CHANGELOG.md

 ## 0.18.1
 
-Add note to questions. inject/backend#373
+Add note to questions.
 
 ### questionnaires.yml
 
@@ -9,8 +9,8 @@ Add note to questions. inject/backend#373
 
 ## 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
+Add option to tools to signify that they don't require an input.
+Change the type of `default_response` field.
 
 ### tools.yml
 
@@ -27,15 +27,15 @@ No format changes
 
 ## 0.17.1
 
-Allow embedding images and videos. inject/backend#359
+Allow embedding images and videos.
 
 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
+Add support for markdown in questionnaires.
+Add missing field from tools.
 
 ### questionnaires.yml
 
@@ -49,7 +49,7 @@ Add missing field from tools. inject/backend#297
 
 ## 0.16.0
 
-More definition enhancements. inject/backend#357
+More definition enhancements.
 
 ### config.yml
 
@@ -71,7 +71,7 @@ More definition enhancements. inject/backend#357
 
 ## 0.15.2
 
-Allow exercise designers to add more information to the definition. inject/backend#353
+Allow exercise designers to add more information to the definition.
 
 ### config.yml
 
@@ -103,7 +103,7 @@ Allow exercise designers to add more information to the definition. inject/backe
 
 ## 0.15.1
 
-Add confirmation button to info alternatives. inject/backend#351
+Add confirmation button to info alternatives.
 
 ### injects.yml
 
@@ -111,7 +111,7 @@ Add confirmation button to info alternatives. inject/backend#351
 
 ## 0.15.0
 
-Allow specifying open-ended questions in questionnaires. inject/backend#340
+Allow specifying open-ended questions in questionnaires.
 
 ### questionnaires.yml
 
@@ -121,7 +121,7 @@ Allow specifying open-ended questions in questionnaires. inject/backend#340
 
 ## 0.14.0
 
-Allow multiple info channels in a definition. #336
+Allow multiple info channels in a definition.
 
 ### injects.yml
 
@@ -133,14 +133,14 @@ Allow multiple info channels in a definition. #336
 ## 0.13.0
 
 Enabled a more fine-grained control over milestone modifications for 
-scale-based questions. #315
+scale-based questions.
 
 ### 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.
+  See definition documentation for more details.
 
 ## 0.12.1
 
@@ -153,7 +153,7 @@ Enable specification of `roles` in `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
+From now, the questions of questionnaires can be formatted via `content`.
 
 ### questionnaires.yml
 
@@ -164,7 +164,7 @@ From now, the questions of questionnaires can be formatted via `content`. #251
 
 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
+If the condition becomes false, the inject is cancelled and a new alternative can be selected.
 
 ### injects.yml
 
@@ -173,7 +173,7 @@ If the condition becomes false, the inject is cancelled and a new alternative ca
 ## 0.10.0
 
 Change the behavior of `info` alternatives.
-When an alternative contains no `content`, it will not create an action log. #264
+When an alternative contains no `content`, it will not create an action log.
 
 ### injects.yml
 
@@ -181,7 +181,7 @@ When an alternative contains no `content`, it will not create an action log. #26
 
 ## 0.9.1
 
-Add option to specify initial state for milestones. #263
+Add option to specify initial state for milestones.
 
 ### milestones.yml
 
@@ -190,7 +190,7 @@ Add option to specify initial state for milestones. #263
 
 ## 0.9.0
 
-Removed manual injects. #228
+Removed manual injects.
 All injects are now considered to be **automatic injects**.
 
 ### injects.yml
@@ -201,7 +201,7 @@ All injects are now considered to be **automatic injects**.
 ## 0.8.0
 
 Add a new required concept called `learning objectives`. 
-This concept _must_ be included in all exercise definition. #170
+This concept _must_ be included in all exercise definition.
 
 ### objectives.yml
 
@@ -213,7 +213,7 @@ This concept _must_ be included in all exercise definition. #170
 
 ## 0.7.0
 
-Add simple questionnaires. #165
+Add simple questionnaires.
 
 ### channels.yml
 
@@ -226,7 +226,7 @@ Add simple questionnaires. #165
 
 ## 0.6.1
 
-Add overlay to injects. #153
+Add overlay to injects.
 
 ### injects.yml
 
@@ -235,8 +235,8 @@ Add overlay to injects. #153
 
 ## 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.
+Added a new concept called `channels`. This concept is saved in a new `channels.yml` file.
+See definition documentation for details.
 
 ### config.yml
 
@@ -252,13 +252,13 @@ See [readme](README.md#channelsyml) for details.
 - remove field `hidden`
 - rename field `injects` to `alternatives`
 - add field `type` to inject
-- specify new types of alternatives, see [readme](README.md#alternatives-_info_)
+- specify new types of alternatives, see definition documentation for details
 
 ### 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
+- add new fields `content` and `control`, see definition documentation for details
 
 ### email.yml
 
@@ -267,12 +267,12 @@ See [readme](README.md#channelsyml) for details.
 - 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
+  see definition documentation for details
  
 
 ## 0.5.1
 
-Allow using directories of files instead of single YAML files inside the definition #128
+Allow using directories of files instead of single YAML files inside the definition.
 
 ## 0.5.0
 
@@ -296,7 +296,7 @@ Allow using directories of files instead of single YAML files inside the definit
 ## 0.4.0
 
 Introduce simplified syntax for `activate_milestone` and `deactivate_milestone`,
-which replaced the old field `reach_milestone`. #98
+which replaced the old field `reach_milestone`.
 
 Instead of the old syntax from `reach_milestone` reminding logical condition,
 the new fields `(de)activate_milestone` have a simple enumeration of milestones,
@@ -318,11 +318,11 @@ which could be separated by a comma, space, or comma followed by space.
 
 ### milestones.yml
 
-- add field `final` to milestones #74
+- add field `final` to milestones
 
 ## 0.2.0
 
-Introduce support for markdown content in `injects`, `tool responses` and `email templates`. #84
+Introduce support for markdown content in `injects`, `tool responses` and `email templates`.
 
 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.
@@ -346,11 +346,11 @@ If neither field is set, then the content is considered to be empty.
 
 ### email.yml
 
-- Add `organization` field to email addresses #83 
+- Add `organization` field to email addresses
 
 ### injects.yml
 
-- Add `organization` field to inject categories #83
+- Add `organization` field to inject categories
 
 ## 0.1.0
 

docs/tech/installation/overview.md

@@ -13,10 +13,10 @@ you can refer to the [architecture overview](../architecture/overview.md) in the
 
 Before you begin, ensure that you have the following:
 
-- A server with at least 2 core CPU and 6 GB RAM
+- A server with at least 2 core CPU and 8 GB RAM
 - A 64-bit x86 architecture
 - Root or sudo access to the server
-- At least 3 GB of disk space, although more might be necessary to hold files uploaded during exercises
+- At least 4 GB of disk space, although more might be necessary to hold files uploaded during exercises
 
 These requirements ensure that the backend server can handle data processing efficiently while serving the frontend interface smoothly.
 

docs/tech/version-compatibility.md

@@ -2,12 +2,15 @@
 
 ## In a nutshell:
 - The INJECT platform comes in different versions
-- Each platform version has a matching documentation version
-- Check the table below to find which documentation version you should use
+- Each platform version has a matching definition versions
+- Check the table below to find which definition version you should use
 
 ---
 
-| Platform Version | Documentation Version |
-|-----------------|----------------------|
-| Up to 0.12.1 | 2.0 |
-| 0.12.1 - (will be specified) | 3.0 |
+| Definition Version | Platform Version |
+|--------------------|------------------|
+| 0.12.1 | 2.0.0 |
+| 0.18.1 | 3.0.0 |
+
+
+[Definition upgrade Guide](architecture/definitions/upgrade.md){ .md-button }
\ No newline at end of file