diff --git a/docs/client_config.rst b/docs/client_config.rst index fbe6a98f..6351fa4d 100644 --- a/docs/client_config.rst +++ b/docs/client_config.rst @@ -6,24 +6,24 @@ Client Configuration Overview -------- -A Client Configuration is needed to configure a SEB client to securely connect to the SEB Server and present a list of available exams -for selection. At least one Client Configuration is needed for an institution that then can exported and be deployed with a SEB within a managed device setup or can be made available within a download link -on a internal or trusted server. Since the Client Configuration is security relevant because it contains sensitive data to connect to SEB Server, +A client configuration is needed to configure a SEB client to securely connect to the SEB Server and present a list of available exams +for selection. At least one client configuration is needed for an institution that then can exported and be deployed with a SEB within a managed device setup or can be made available within a download link +on a internal or trusted server. Since the client configuration is security relevant because it contains sensitive data to connect to SEB Server, there are different security level one can choose to apply within a internal safe e-assessment strategy. -The lowest level of security is to just have one not encrypted Client Configuration for the whole institution and for all e-assessments. +The lowest level of security is to just have one not encrypted client configuration for the whole institution and for all e-assessments. In this case the sensitive data is more exposed to be compromised and misused by others because of the missing encryption and also it takes -more effort to deal with such an issue while there is only one Client Configuration used by all e-assessments of the institution. +more effort to deal with such an issue while there is only one client configuration used by all e-assessments of the institution. -The currently highest level of security is to have encrypted and different Client Configuration for different e-assessment or semester-wise. -In this case the Client Configuration is encrypted with a password that can be defines by a institutional- or exam-administrator while -creating the Client Configuration. Once the SEB loads such a Client Configuration it will fist prompt the user about the password that must be +The currently highest level of security is to have encrypted and different client configuration for different e-assessment or semester-wise. +In this case the client configuration is encrypted with a password that can be defines by a institutional- or exam-administrator while +creating the client configuration. Once the SEB loads such a client configuration it will fist prompt the user about the password that must be given to proceed and connect to the SEB Server. -Usually a Client Configuration is created or maintained by an institutional administrator or by an exam administrator. Exam supporter role has -no access to client configurations and a SEB administrator is able to see Client Configurations of other institutions but not to create or modify them. +Usually a client configuration is created or maintained by an institutional administrator or by an exam administrator. Exam supporter role has +no access to client configurations and a SEB administrator is able to see client configurations of other institutions but not to create or modify them. -To see the list of all available Client Configuration for an institution and the specific user-role, go to the sub-section "Client Configuration" +To see the list of all available client configuration for an institution and the specific user-role, go to the sub-section "Client Configuration" of the "Configuration" section on the menu on the left hand side. .. image:: images/client_config/list.png @@ -42,14 +42,14 @@ or remove selection to hide all fallback related attributes. :align: center :target: https://raw.githubusercontent.com/SafeExamBrowser/seb-server/master/docs/images/client_config/new.png -Short description of all attributes of a Client Configuration: +Short description of all attributes of a client configuration: -- **Name**: The name of the Client Configuration used to maintain client configurations within the SEB Server application. +- **Name**: The name of the client configuration used to maintain client configurations within the SEB Server application. - **Configuration Purpose**: Defines the configuration purpose as described in `SEB Configuration `_ section "Use SEB settings file for". - **Starting an Exam**; Will cause SEB to use this Client Configuration settings on startup but won't change local SEB settings. - **Configuring a Client**; Will cause SEB to use this Client Configuration settings and also save it as local SEB settings. -- **Configuration Password**: Used to encrypt the Client Configuration with a password. A SEB client will prompt this password while loading a password protected Client Configuration. -- **With Fallback**: Select this to see and define a fallback strategy for SEB clients using this Client Configuration in case of SEB Server service unavailability. + **Starting an Exam**; Will cause SEB to use this client configuration settings on startup but won't change local SEB settings. + **Configuring a Client**; Will cause SEB to use this client configuration settings and also save it as local SEB settings. +- **Configuration Password**: Used to encrypt the client configuration with a password. A SEB client will prompt this password while loading a password protected client configuration. +- **With Fallback**: Select this to see and define a fallback strategy for SEB clients using this client configuration in case of SEB Server service unavailability. - **Fallback URL**: Defines a start URL that is loaded by the SEB client in a fallback case. - **Connection Attempts**: Defines the number of attempts a SEB client will try to unsuccessfully connect to the SEB Server service until it switches to the fallback case. - **Interval**: Time interval (in milliseconds) a SEB client will wait after a unsuccessful connection attempt before starting a next connection attempt. @@ -57,7 +57,7 @@ Short description of all attributes of a Client Configuration: - **Fallback Password**: If set, a SEB client will prompt for this password before switching into the fallback case. - **Quit Password**: If set, a SEB client will prompt for this password when a user wants to exit SEB before in fallback case or before the SEB client has loaded an exam. -A Client Configuration may also contain and define a fallback strategy that takes place when SEB Server service is not available while +A client configuration may also contain and define a fallback strategy that takes place when SEB Server service is not available while a SEB client tries to connect to the SEB Server. .. note:: @@ -69,19 +69,19 @@ The fallback strategy contains some connection attributes that define until when well as attributes that defines how a SEB client has to proceed in the fallback case. How a SEB client reacts to a fallback case differs on the configuration settings in the following ways: -- Client Configuration with "Configuring a Client" setting and no fallback strategy: +- client configuration with "Configuring a Client" setting and no fallback strategy: Show warning message with options "retry" and "quit". -- Client Configuration with "Configuring a Client" setting and fallback strategy: +- Client configuration with "Configuring a Client" setting and fallback strategy: Show warning with options "retry", "fallback" (load Fallback URL) and "quit". -- Client Configuration with "Starting an Exam" setting and no fallback (without local client configuration): +- Client configuration with "Starting an Exam" setting and no fallback (without local client configuration): Show warning message with options "retry" and "quit". -- Client Configuration with "Starting an Exam" setting and no fallback (with local client configuration): +- Client configuration with "Starting an Exam" setting and no fallback (with local client configuration): Show warning message with options "retry", "load local settings" and "quit". -- Client Configuration with "Starting an Exam" setting and fallback strategy: +- Client configuration with "Starting an Exam" setting and fallback strategy: Show warning with options "retry", "fallback" (load Fallback URL) and "quit". @@ -90,15 +90,15 @@ Use Cases **Create Client Configuration** -As an Institutional Administrator one should create a new secure Client Configuration for the upcoming semester. The setup shall operate with +As an Institutional Administrator one should create a new secure client configuration for the upcoming semester. The setup shall operate with secure configurations because the configuration file may be exposed to the public Internet. And the setup shall also have a proper fallback strategy where SEB clients uses the a given start URL in fallback case. - Sign in as an Institutional Administrator and select the "Client Configuration" sub-menu of the "SEB Configuration" main-menu on the left. -- Use the "Add Client Configuration" on the right action pane to create a new Client Configuration. -- Give the new Client Configuration a name that not already exists and select "Start an Exam" for "Configuration Purpose". +- Use the "Add Client Configuration" on the right action pane to create a new client configuration. +- Give the new client configuration a name that not already exists and select "Start an Exam" for "Configuration Purpose". This will ensure that a SEB client that uses this configuration will not override the local configuration that then can be used on fallback. -- Give a password to ensure security and to encrypt the Client Configuration on export. A SEB client will prompt for the password while loading this configuration. +- Give a password to ensure security and to encrypt the client configuration on export. A SEB client will prompt for the password while loading this configuration. - Check "With Fallback" to show all the fallback related attributes. - Define a fallback URL that will be used by a SEB client as start URL in the fallback case. - Define also fallback case, how many connection attempts on what interval a SEB client shall try before going into fallback mode. @@ -107,31 +107,31 @@ strategy where SEB clients uses the a given start URL in fallback case. - When a SEB client goes to fallback mode it will prompt the user as described in the case list above. To prevent further fallback options with a password prompt, give a "Fallback Password" and / or a "Quit Password" that a SEB client will prompt on either the fallback- or the quit-option. -- After all details are correctly been entered, use the "Save Client Configuration" action on the right action pane to save the new Client Configuration. -- Now the new Client Configuration is created but not active for now and therefore cannot be exported yet. +- After all details are correctly been entered, use the "Save Client Configuration" action on the right action pane to save the new client configuration. +- Now the new client configuration is created but not active for now and therefore cannot be exported yet. **Activate and export Client Configuration** -A Client Configuration for the upcoming semester has been created so far but was not active until now because of security reasons. -Now we want to activate this Client Configuration and export it to make it accessible by a download link on a public server. +A client configuration for the upcoming semester has been created so far but was not active until now because of security reasons. +Now we want to activate this client configuration and export it to make it accessible by a download link on a public server. - Sign in as an Institutional Administrator and select the "Client Configuration" sub-menu of the "SEB Configuration" main-menu on the left. -- Use the list filter and / or the list navigation to find the needed Client Configuration. +- Use the list filter and / or the list navigation to find the needed client configuration. - Double-click on the list entry or use the "View Client Configuration" action on the right for a selected list row, to show the details of a specific Client configuration. -- Then either on the list or in the view mode of the form, use the "Activate Client Configuration" action on the right action pane to activate the Client Configuration -- Now there is a "Export Client Configuration" action in the detail view of the Client Configuration. Use the "Export Client Configuration" action +- Then either on the list or in the view mode of the form, use the "Activate Client Configuration" action on the right action pane to activate the client configuration +- Now there is a "Export Client Configuration" action in the detail view of the client configuration. Use the "Export Client Configuration" action to start a download dialog. Choose "Save As" and download the file with the name "SEBClientSettings.seb". - This file can now be published as download-link within a public server where SEB user can click and start the download and startup of the SEB client automatically. **Deactivate a Client Configuration** -The semester has ended and for security reasons we don't want that SEB clients with a Client Configuration for the ended semester -are able to connect to SEB Server anymore. For this we just have to deactivate the Client Configuration for that semester. A SEB client -that connects with this Client Configuration will then receive an HTTP 401 Unauthorized response. +The semester has ended and for security reasons we don't want that SEB clients with a client configuration for the ended semester +are able to connect to SEB Server anymore. For this we just have to deactivate the client configuration for that semester. A SEB client +that connects with this client configuration will then receive an HTTP 401 Unauthorized response. - Sign in as an Institutional Administrator and select the "Client Configuration" sub-menu of the "SEB Configuration" main-menu on the left. -- Use the list filter and / or the list navigation to find the needed Client Configuration and select the row of this Client Configuration. -- Now use the "Deactivate Client Configuration" action from the right action pane to deactivate the Client Configuration. -- The Client Configuration is now deactivates und SEB client using this Client Configuration are not able to connect to SEB Server anymore. +- Use the list filter and / or the list navigation to find the needed client configuration and select the row of this client configuration. +- Now use the "Deactivate Client Configuration" action from the right action pane to deactivate the client configuration. +- The client configuration is now deactivated and SEB client using this client configuration are not able to connect to SEB Server anymore. diff --git a/docs/configurations.rst b/docs/configurations.rst index dff10cdf..3aa295fb 100644 --- a/docs/configurations.rst +++ b/docs/configurations.rst @@ -2,19 +2,19 @@ SEB Configurations ================== There are two different kind of SEB specific configurations that must be defined and be put in place to support e-assessments with -SEB and SEB Server. The Client Configuration is used to configure SEB with all needed information to securely connect to SEB Server -and an Exam Configuration is used to configure SEB to access a running exam with SEB. The Client Configuration is only needed at least +SEB and SEB Server. The is used to configure SEB with all needed information to securely connect to SEB Server +and an Exam Configuration is used to configure SEB to access a running exam with SEB. The is only needed at least once for an institution and must be deployed as start-configuration on a managed SEB setup or can be placed as a download link within an internal trusted server, that automatically loads within the SEB application and configures the SEB to connect to the SEB Server. -An Exam Configuration, as the name implies, is done for an exam and contains most of the known configuration attributes +An exam configuration, as the name implies, is done for an exam and contains most of the known configuration attributes from the latest `SEB Configuration Tool `_ -Currently an Exam Configuration can only be applied to one Exam but can easily be copied to use with another exam. For detailed -information about Exam Configuration see :ref:`exam-configuration-label` +Currently an exam configuration can only be applied to one Exam but can easily be copied to use with another exam. For detailed +information about exam configuration see :ref:`exam-configuration-label` -Within Configuration Templates, it is possible to create templates for Exam Configuration. Within the current version of SEB Server +Within Configuration Templates, it is possible to create templates for exam configuration. Within the current version of SEB Server there is the possibility to define different default value(s) for each exam configuration attribute and also to define if the attribute -is been shown in the Exam Configuration or not. This allows an Exam Administrator to create a exam configuration template for exams +is been shown in the exam configuration or not. This allows an Exam Administrator to create a exam configuration template for exams with context defines default values and also to be able to only see change the attributes that are relevant for an exam configuration. This feature is currently in an experimental state and may be changed and / or expanded within future releases of SEB Server. See :ref:`config-template-label` diff --git a/docs/exam_config.rst b/docs/exam_config.rst index a37f0d70..1fd8441b 100644 --- a/docs/exam_config.rst +++ b/docs/exam_config.rst @@ -6,6 +6,93 @@ Exam Configuration Overview -------- +An exam configuration defines all the SEB settings for an exam and can be applied to an exam. A SEB client that is connecting to SEB Server +and an exam defined by the SEB Server is downloading this exam configuration from SEB Server and reconfigure itself before accessing the +exam on the learning management system (LMS) and present it to the user. + +An exam administrator is able to create, modify and maintain exam configurations while the SEB Server administrator and the institutional administrator +role have only read access either for all exam configurations or for the exam configurations of the institution. +A exam supporter role is able to see and modify only the exam configurations to which the user-account is assigned as supporter. + +To view the list of available exam configuration go the the sub-menu "Exam Configuration" within the menu "SEB Configurations" on the left +hand side. The list shows the name, the description and the status of the exam configurations in a column. With SEB Server administrator role +also an institution column is shown because a SEB Server administrator is able to see all exam configurations of all institutions. +As usual, to filter the list use the filter inputs above and click on the lens symbol on the right to apply the filter and to clear the +filter use the clear symbol right to the lens symbol. See :ref:`gui-label` for more information about the list navigation. + +.. image:: images/exam_config/list.png + :align: center + :target: https://raw.githubusercontent.com/SafeExamBrowser/seb-server/master/docsexam_config/list.png + +To view details of a specific exam configuration either double-click on a list entry or select a list entry and use the "View Exam Configuration" +action from the right action pane. In the detail view all general settings are shown and also a list of exams that uses this exam configuration. +In the current version of SEB Server, an exam configuration can only be assigned to one exam. + +.. note:: + For the actual SEB Server version it is not possible to assign the same exam configuration to more then one exam. This because it shall be + possible to change configuration settings for running exams when no active SEB clients are connected within the specified exam. This is + manageable for one exam but is going to become confusing if more exams are involved. + But there is the possibility to copy an existing exam configuration to use the same for another exam. + +The status of an exam configuration defines its visibility and assignment possibilities. If an exam configuration is still in the creation process +and shall not be to an exam yet, it should stay in the "Under Construction" status. +This is the default status while creating a new exam configuration. Once a exam configuration is done and ready for assignment, one can change this +status to "Ready To Use". Exam configurations wihtin this status are available for selection and assignment on exams. When a exam configuration +is assigned to an exam the status changes automatically to "In Use" and the SEB settings of the exam configuration will appear only in read mode for default. + +.. image:: images/exam_config/view.png + :align: center + :target: https://raw.githubusercontent.com/SafeExamBrowser/seb-server/master/docsexam_config/view.png + +An exam configuration has a general settings part (like other domain objects has within SEB Server) that defines the name, description and status +of the exam configuration that are used to maintain the exam configurations SEB Server internally. And a exam configuration has, separated from +the general settings, the SEB settings that contains most of the SEB setting attributes as they are provided by the SEB. + +.. note:: + For more information and detailed description of the SEB setting attributes, see `SEB Configuration `_. + Currently not all settings are available and some has different uses. For details about differences see :ref:`setting-dif-label` + +The SEB settings differ from the general form-settings also in how they are managed and stored on server-side. Unlike the form-settings, +the SEB settings are arranged like they are in the SEB Configuration Tool for Windows and they are stored while modifying. This means, +a entered value for an attribute is immediately sent to and stored by the SEB Server. There is no additional save action needed and +no entered data will be lost. Instead the "Save / Publish Settings" can be used to store the current setting in a new revision in the history +while also publish them to exams that uses this exam configuration. + +.. image:: images/exam_config/settings.png + :align: center + :target: https://raw.githubusercontent.com/SafeExamBrowser/seb-server/master/docsexam_config/settings.png + +.. note:: + Changes in SEB settings must be published to be available on exams they use this exam configuration. Before publishing they are not + available for exams and SEB clients that connect to the SEB Server will still receive the last published version of the SEB settings. + +.. note:: + Currently there is an "Undo" function to revert the changed made to the last published state. But there is no possibility yet to + maintain the publishing history of a Exam Configuration but may be available in a future release of the SEB Server. + Use Cases --------- + +**Create new Exam Configuration** + +**Edit SEB Settings and prepare for Use** + +**Export an Exam Configuration** + +**Import an Exam Configuration** + +**Copy an Exam Configuration** + +**Save an Exam Configuration as Template** + +**Generate and Export the Config-Key of an Exam Configuration** + +**Edit SEB Settings of an Exam Configuration in Use** + + +.. _setting-dif-label: + +SEB Setting Differences +----------------------- + diff --git a/docs/images/exam_config/config_key.png b/docs/images/exam_config/config_key.png new file mode 100644 index 00000000..30fdb7a8 Binary files /dev/null and b/docs/images/exam_config/config_key.png differ diff --git a/docs/images/exam_config/edit.png b/docs/images/exam_config/edit.png new file mode 100644 index 00000000..3d3b458b Binary files /dev/null and b/docs/images/exam_config/edit.png differ diff --git a/docs/images/exam_config/list.png b/docs/images/exam_config/list.png new file mode 100644 index 00000000..24273b08 Binary files /dev/null and b/docs/images/exam_config/list.png differ diff --git a/docs/images/exam_config/settings.png b/docs/images/exam_config/settings.png new file mode 100644 index 00000000..2c4316fe Binary files /dev/null and b/docs/images/exam_config/settings.png differ diff --git a/docs/images/exam_config/view.png b/docs/images/exam_config/view.png new file mode 100644 index 00000000..dcce3fbb Binary files /dev/null and b/docs/images/exam_config/view.png differ diff --git a/docs/lmssetup.rst b/docs/lmssetup.rst index ca470238..ff1366a1 100644 --- a/docs/lmssetup.rst +++ b/docs/lmssetup.rst @@ -1,4 +1,4 @@ -Leraning Management System (LMS) Binding -======================================== +Leraning Management System Setup +================================ TODO \ No newline at end of file