diff --git a/docs/INJECT_process/specify/injects.md b/docs/INJECT_process/specify/injects.md index 8384e6a7add954966348a78a5a9c9c5d8144adda..2948080d6e18a1df8376a735f4b7d323c6cf2491 100644 --- a/docs/INJECT_process/specify/injects.md +++ b/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 diff --git a/docs/changelog.md b/docs/changelog.md index 62090ed08ea8d51ac2ae6a770573dd62ccb6eda0..38ffb9efc049884833f1dd8be06f447bf6457c1e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,6 +1,6 @@ # 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) diff --git a/docs/images/Logo_BW_inverz.png b/docs/images/Logo_BW_inverz.png index 75c93107915f6d474217f87703bdfe1112196f7b..e919ac06f27a7d14e29f9917497eda599f4b48e9 100644 Binary files a/docs/images/Logo_BW_inverz.png and b/docs/images/Logo_BW_inverz.png differ diff --git a/docs/images/editor-inject-preparation-error.png b/docs/images/editor-inject-preparation-error.png new file mode 100644 index 0000000000000000000000000000000000000000..f935f5eb3eefe7956b8389d33a79663cf0d4cca8 Binary files /dev/null and b/docs/images/editor-inject-preparation-error.png differ diff --git a/docs/index.md b/docs/index.md index 17661d111dbb382dcaedcca8c54e63b5ab488401..07e6723505d97aca6fd5d3a87b477812903d2453 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/known-issues.md b/docs/known-issues.md index 3214a7299bcf694f8be3aefb5cf6c2aab2052cc6..16f055d87e6c79f20869c366df2b50bf732a5d05 100644 --- a/docs/known-issues.md +++ b/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: + + + +### 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. diff --git a/docs/license.md b/docs/license.md index 6f6b92db7062a0e75a61c992f2b78e75698a0e5a..449dae1f79942d06adbf8a013108464ff58e398a 100644 --- a/docs/license.md +++ b/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 diff --git a/docs/tech/architecture/definitions/CHANGELOG.md b/docs/tech/architecture/definitions/CHANGELOG.md index f5150bbd36ba80e194fc696e9667d3afca1e839e..b0e91d01ae55b9354a71e154257095c251499f49 100644 --- a/docs/tech/architecture/definitions/CHANGELOG.md +++ b/docs/tech/architecture/definitions/CHANGELOG.md @@ -1,6 +1,6 @@ ## 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 diff --git a/docs/tech/installation/overview.md b/docs/tech/installation/overview.md index ec6f518e9b5f5f1b2f709532234b0d66701c6c02..12056e4d57931f44924a6c6ba47aa8af2ee2f2e7 100644 --- a/docs/tech/installation/overview.md +++ b/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. diff --git a/docs/tech/version-compatibility.md b/docs/tech/version-compatibility.md index 17009f5a266a6e24895032e6f8e95f873c4a4f6b..97f68676a5b3e794f18a581c5c4b451d1e500ca1 100644 --- a/docs/tech/version-compatibility.md +++ b/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