Add 4.31 WIP guide

docs/application/administration/settings/content/projects.rst

@@ -40,17 +40,9 @@ Project Creation
 Summary Report
 ==============
 
-We can turn **Summary Report** on or off. It is a feature that allows users to generate and see a summary report in their projects.
+We can turn **Summary Report** on or off. It is a feature that allows users to generate and see a **Summary Report** in their projects.
 
-
-Feedback
-========
-
-In case we want to allow users to provide feedback specific to questions directly from :ref:`questionnaires<project-questionnaire>`, we can enable **Feedback** and configure a GitHub repository which will be used as an issue tracker. We should have a bot/service account created with access to the GitHub repository and obtain `Personal Access Token <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line>`_. This account will be used to create the GitHub issues in the repository. Then, we need to simply fill **GitHub Repository Owner**, **GitHub Repository Name**, and the **Access Token**.
-
-.. NOTE::
-
-    The **Access Token** value is encrypted in the database.
+The **Summary Report** shows how many questions are answered and unanswered in each chapter. It can either count all questions in the Knowledge Model or only the questions required for the project’s current phase. Questions from later phases are ignored in the phase-based view. If a parent question is unanswered, its child questions are not counted separately. Chapter results are combined into the total **Summary Report**.
 
 
 Project Tagging

docs/application/administration/settings/system/authentication.rst

@@ -21,27 +21,4 @@ For internal authentication, we can set whether the **Registration** is enabled
 
 Another option is whether the **Two-Factor Authentication** (2FA) is enabled. If enabled, once users try to log in using credentials, they receive an email message with one-time code to confirm the login. Moreover, we can configure **Code Length** (how many character the code has) and **Expiration** period in seconds.
 
-
-.. _auth-services:
-
-External
-========
-
-Using these settings we can add **OpenID Services** to allow logging into the |project_name| instance via external identity provider. First, press :guilabel:`Add` and fill **ID** of the service. Then, we should prepare the client application on the side of OpenID service:
-
-*  Use **Callback URL** (and optionally **Logout URL**) to create the client
-*  Obtain **Client ID** and **Client Secret**
-*  Obtain OpenID endpoint **URL** (we may get one ending with ``/.well-known/openid-configuration``, if so we just use the part before this suffix)
-*  Configure the client to have the following claims: ``openid``, ``profile``, ``email``
-*  Configure the client to provide the following details in ID tokens: ``email``, ``given_name``, ``family_name``
-
-Back in the |project_name| settings, we can fill **Client ID**, **Client Secret**, and **URL** from our OpenID client together with optional **Parameters** (usually not needed). Finally, we can configure how the log-in button will look like by setting **Icon** (by using `Font Awesome <https://fontawesome.com/v6/search?o=r&m=free>`_), **Name**, **Background**, and text/icon **Color**.
-
-.. NOTE::
-
-    After setting a new OpenID service, we should directly test it and verify that the configuration works well. For that, we can simply open our |project_name| instance in a new anonymous window of the web browser.
-
-
-.. figure:: authentication/openid.png
-
-    Example configuration of OpenID service.
+We can also set up **Session Expiration** and **User Email Link Expiration** in hours. The first one defines how long the user session is valid before the user needs to log in again. The second one defines how long the email links (e.g., for password reset) are valid before they expire and cannot be used anymore.

docs/application/administration/settings/system/index.rst

@@ -15,6 +15,7 @@ System settings allow us to configure basics about the organization running the
 
     Organization<organization>
     Authentication<authentication>
+    OpenID<openid>
     Privacy & Support<privacy-and-support>
     Features<features>
     Plugins<plugins>

docs/application/administration/settings/system/openid.rst

@@ -0,0 +1,147 @@
+.. _openid-settings:
+
+OpenID
+******
+
+Using these settings we can add `OpenID <https://openid.net/>`__ configuration to allow logging into the FAIR Wizard via external identity provider.
+
+FAIR Wizard supports Microsoft Azure, ORCID, as well as any other OpenID providers. Following are detailed description of the setups for these options.
+
+.. NOTE::
+
+    After setting a new OpenID service, we should directly test it and verify that the configuration works well. For that, we can simply open our FAIR Wizard in a new anonymous window of the web browser.
+
+
+Microsoft Azure Setup
+=====================
+
+1. Go to https://portal.azure.com/.
+2. Go to ``App registrations``.
+3. Click on ``New registration``.
+4. Fill in a name.
+5. Select ``Single tenant only - ...``.
+6. Keep ``Redirect URI`` empty.
+7. Click on ``Register``.
+8. Copy and store ``Directory (tenant) ID`` and ``Application (client) ID``.
+9. Click on ``Manage`` in the left menu → ``Certificates & Secrets``.
+10. Click on ``New client secret``.
+11. Fill description, set ``Expires`` and note it somewhere, then click on ``Add``.
+12. Copy ``Value`` and store it somewhere. You will not able to view it again.
+
+13. Go to OpenID in FAIR Wizard: ``Admin Center`` → ``Settings`` → ``Organization OpenID`` → ``Create``.
+
+14. Fill in a ``Name`` of the service. This name will be used to identify the service in the list of login options, so it should be something descriptive.
+
+15. Open the ``Microsoft`` tab and fill in :
+	- ``Application (client) ID``
+	- ``Directory (tenant) ID``
+	- ``Client Secret`` → ``<stored secret value>``
+
+16. (optional) fill Icon (``fab fa-microsoft``, or some other from `Font Awesome <https://fontawesome.com/v6/search?o=r&m=free>`_), ``Background Color`` and ``Text Color``.
+
+17. Click on ``Save``.
+
+18. Go back to Microsoft Azure.
+19. Click on ``Manage`` in the left menu → ``Authentication (Preview)``.
+20. Click on ``Add Redirect URI``.
+21. Click on ``Web``.
+22. Copy ``Redirect URI`` and ``Front-channel logout URL`` from FAIR Wizard.
+23. **Do not** check any checkbox.
+24. Click on ``Configure``.
+25. Click on ``Manage`` in the left menu → ``API permissions``.
+26. Click on ``Add a permission``.
+27. Click on ``Microsoft Graph`` → ``Delegated permissions``.
+28. Under ``OpenId permissions`` check ``email``, ``openid`` and ``profile``. Under ``User`` keep checked ``User.Read``.
+29. Click on ``Add permissions``.
+
+30. Click on ``Manage`` in the left menu → ``Token configuration``.
+31. Click on ``Add optional claim``.
+32. Select ``ID`` and check ``email``, ``family_name`` and ``given_name``.
+33. Click on ``Add``.
+
+34. Test your OpenID configuration in FAIR Wizard (You might need to refresh the login page for the login button to appear).
+
+.. .. figure:: openid/openid.png
+..     :width: 700
+
+..     Example configuration of OpenID Microsoft Azure service.
+
+
+ORCID Setup
+===========
+
+ORCID requires a redirect URI before it allows us to save the application and obtain credentials. Because FAIR Wizard generates the callback URL only after the OpenID configuration is saved, we first create the FAIR Wizard configuration with temporary credentials and then return to ORCID.
+
+1. Go to OpenID in FAIR Wizard: ``Admin Center`` → ``Settings`` → ``Organization OpenID`` → ``Create``.
+2. Fill in a ``Name`` of the service, for example ``ORCID``.
+3. Open the ``Custom`` tab.
+4. Fill in temporary values:
+	- ``Client ID`` → ``placeholder``
+	- ``Client Secret`` → ``placeholder``
+	- ``URL`` → ``https://orcid.org``
+5. Leave ``Parameters`` empty.
+6. (optional) fill Icon (``fab fa-orcid``), ``Background Color`` (``#A6CE39``), and ``Text Color``.
+7. Click on ``Save``.
+8. Copy ``Callback URL`` from FAIR Wizard. It will look similar to ``https://example.fair-wizard.com/admin/open-id/<uuid>/callback``.
+
+9. Go to https://orcid.org/signin and sign in to ORCID.
+10. Open ``Developer Tools`` from the account menu.
+11. If this is the first application, register for ORCID Public API credentials.
+12. Fill in the application details:
+	- ``Name`` → name of the FAIR Wizard instance or organization.
+	- ``Application URL`` → public URL of the FAIR Wizard instance.
+	- ``Application Description`` → short description of the FAIR Wizard instance.
+	- ``Redirect URI`` → paste the ``Callback URL`` copied from FAIR Wizard.
+13. Save the application and generate credentials.
+14. Copy ``Client ID`` and ``Client Secret``.
+
+15. Go back to the ORCID OpenID configuration in FAIR Wizard.
+16. Replace temporary credentials:
+	- ``Client ID`` → ORCID ``Client ID``
+	- ``Client Secret`` → ORCID ``Client Secret``
+	- ``URL`` → keep ``https://orcid.org``
+17. Click on ``Save``.
+18. Test your OpenID configuration in FAIR Wizard (You might need to refresh the login page for the login button to appear).
+
+.. NOTE::
+
+    ORCID uses the term ``Redirect URI`` for the FAIR Wizard ``Callback URL``. The FAIR Wizard ``Logout URL`` does not need to be entered in ORCID Public API credentials.
+
+.. NOTE::
+
+    For ORCID sandbox testing, use https://sandbox.orcid.org/ for ORCID registration and use ``https://sandbox.orcid.org`` as the FAIR Wizard ``URL``.
+
+
+Custom Setup
+============
+
+1. Go to OpenID in FAIR Wizard: ``Admin Center`` → ``Settings`` → ``Organization OpenID`` → ``Create``.
+2. Fill in a ``Name`` of the service. This name will be used to identify the service in the list of login options, so it should be something descriptive.
+3. Open the ``Custom`` tab.
+4. Prepare the OpenID endpoint ``URL``. This is usually the issuer URL of the provider. If the provider gives us a URL ending with ``/.well-known/openid-configuration``, use only the part before this suffix.
+5. Prepare the client application on the side of the OpenID provider:
+	- If the provider allows creating the client without redirect URLs, create it and obtain ``Client ID`` and ``Client Secret``.
+	- If the provider requires redirect URLs before it creates credentials, use temporary values in FAIR Wizard first, for example ``placeholder`` for ``Client ID`` and ``Client Secret``. Fill in the real OpenID endpoint ``URL`` and click on ``Save``. Then copy the generated ``Callback URL`` from FAIR Wizard and use it in the provider.
+6. In the OpenID provider, configure redirect URLs:
+	- Use FAIR Wizard ``Callback URL`` as the provider redirect URI, callback URL, reply URL, or sign-in redirect URI.
+	- If the provider supports logout URLs, use FAIR Wizard ``Logout URL`` as the provider logout URL.
+7. Configure the client in the OpenID provider:
+	- Allow the ``authorization_code`` flow, if this is configurable.
+	- Configure the client to have the following scopes or claims: ``openid``, ``profile``, ``email``.
+	- Configure the client to provide the following details in ID tokens: ``email``, ``given_name``, ``family_name``.
+8. Go back to FAIR Wizard and fill in the real ``Client ID``, ``Client Secret``, and ``URL`` from the OpenID provider.
+9. Leave ``Parameters`` empty unless the provider documentation requires an additional parameter.
+10. (optional) fill Icon (some from `Font Awesome <https://fontawesome.com/v6/search?o=r&m=free>`_), ``Background Color`` and ``Text Color``.
+11. Click on ``Save``.
+12. Test your OpenID configuration in FAIR Wizard (You might need to refresh the login page for the login button to appear).
+
+
+Advanced Configuration
+======================
+
+In the ``Advanced`` dropdown of the OpenID configuration, we can set up additional options.
+
+- **Registration enabled** - if enabled, users will be able to register a new FAIR Wizard account using this OpenID service. If disabled, only existing FAIR Wizard OpenID accounts can log in.
+- **Scopes** - scopes requested from the OpenID provider.
+	- **Email** - some services (such as ORCID) do not provide an email address. By disabling this option, we can enable email completion upon the user's first login. This means that if the OpenID provider does not return an email address, the user will be prompted to enter it manually after the first login. FAIR Wizard requires an email address to send password reset instructions and other notifications, so it is required for the user account.
+	- **Profile** - if the provider does not return profile information, the user will be prompted to enter their first and last name manually after the first login.

docs/application/administration/settings/user-interface/dashboard-and-login-screen.rst

@@ -42,7 +42,7 @@ We can select the **Dashboard Style** whether the user should see a standard **w
 Login Info
 ==========
 
-It is possible to write a message that users will see before logging in the |project_name| instance, using HTML or Markdown. The Login info is placed in the center of the login screen. We can use it to explain users in what cases they can/should use our |project_name| instance, how they should log in (e.g. if we have more :ref:`authentication services<auth-services>` configured), or if there is any news regarding our |project_name| instance.
+It is possible to write a message that users will see before logging in the |project_name| instance, using HTML or Markdown. The Login info is placed in the center of the login screen. We can use it to explain users in what cases they can/should use our |project_name| instance, how they should log in (e.g. if we have more authentication services configured), or if there is any news regarding our |project_name| instance.
 
 .. WARNING::
 

docs/application/administration/users/index.rst

@@ -3,7 +3,7 @@
 Users
 *****
 
-Users list allows admins to see and manage all users in a |project_name| instance. The list can be filtered using role, searched based using name or email fragment, and sorted via various properties of users. The list shows the role of a user next to its name and also indicates in case the user is inactive. Next to the email, we can quickly see what authentication services the user uses to log-in (:guilabel:`internal` is the internal authentication with email-password credentials, other are based on configured :ref:`OpenID services<auth-services>`).
+Users list allows admins to see and manage all users in a |project_name| instance. The list can be filtered using role, searched based using name or email fragment, and sorted via various properties of users. The list shows the role of a user next to its name and also indicates in case the user is inactive. Next to the email, we can quickly see what authentication services the user uses to log-in.
 
 A :ref:`user detail<user-detail>` can be opened by clicking the name of a user or by selecting :guilabel:`Edit` in the right dropdown menu for the desired row. There, a user can be also deleted via the :guilabel:`Delete` action. Finally, administrator can :ref:`create a new user<user-create>` by clicking :guilabel:`Create`.
 

docs/application/knowledge-models/list/compare.rst

@@ -0,0 +1,13 @@
+.. _km-compare:
+
+Knowledge Model Compare
+***********************
+
+We can compare two versions of a knowledge model by clicking :guilabel:`Compare` from the right item menu (three dots) of a specific KM in the :doc:`./index` or from KM :doc:`./detail`. This will open a new page where we can select another KM to compare with. The comparison will show the differences between the two versions, including changes in the name, description, as well as changes in the structure of the KM (e.g. added or removed entities, attributes, etc.).
+
+The comparison can be starter in project migration and in KM list and detail.
+
+.. TODO::
+
+    Add screenshot
+

docs/application/knowledge-models/list/detail.rst

@@ -13,6 +13,7 @@ In the top pane, we can see the options based on our role:
 
 - :guilabel:`Preview` can be used to check the content of the KM via the :doc:`./preview` feature.
 - :guilabel:`Export` for exporting the latest version of the KM as a file.
+- :guilabel:`Compare` for comparing the current version of the KM with another version (see :doc:`./compare`).
 - :guilabel:`Create KM editor` is a shortcut for :doc:`../editors/create` for creating a new version.
 - :guilabel:`Fork KM` is again a shortcut for :doc:`../editors/create` for to create a fork (some more specific KM based on this one).
 - :guilabel:`Create project` is a shortcut to :doc:`../../projects/list/create` with this KM.

docs/application/knowledge-models/list/index.rst

@@ -7,8 +7,10 @@ As **data stewards** and **admins**, we can manage the knowledge models that are
 
 For each knowledge model (KM), we can see the latest version in the list. If we want to read more about a specific KM or see the older versions, we need to access the :doc:`./detail` by clicking the name of KM or clicking :guilabel:`Open` from the right item menu (three dots). There are also other options for each item:
 
+- :guilabel:`Open` for opening the KM detail (same as clicking the name of the KM).
 - :guilabel:`Preview` to see how :doc:`../../projects/index` generated using this KM would look like.
 - :guilabel:`Export` for exporting the latest version of the KM as a file.
+- :guilabel:`Compare` for comparing the current version of the KM with another version (see :doc:`./compare`).
 - :guilabel:`Create KM editor` is a shortcut for :doc:`../editors/create` for creating a new version.
 - :guilabel:`Fork KM` is again a shortcut for :doc:`../editors/create` for to create a fork (some more specific KM based on this one).
 - :guilabel:`Create project` is a shortcut to :doc:`../../projects/list/create` with this KM.
@@ -56,4 +58,5 @@ Finally, there is an option to :doc:`./import` by click the :guilabel:`Import` b
     Import<import>
     Detail<detail>
     Preview<preview>
+    Compare<compare>
 

docs/application/projects/list/detail/metrics.rst

@@ -8,7 +8,7 @@ In the :guilabel:`Metrics` tab in the project detail we can see a **Summary Repo
     Summary report of project metrics.
 
 
-The report shows how many answered questions out of how many are there for the current phase (if there are phases in the knowledge model) and overall.
+The **Summary Report** shows how many questions are answered and unanswered in each chapter. It can either count all questions in the Knowledge Model or only the questions required for the project’s current phase. Questions from later phases are ignored in the phase-based view. If a parent question is unanswered, its child questions are not counted separately. Chapter results are combined into the total **Summary Report**.
 
 If there are any metrics in the knowledge model, the report also shows the score for each metric. The score is calculated as a weighted average of all the answers affecting that metric and is always between 0 and 1. If there are at least 3 metrics present, a spider chart is also displayed.
 

docs/application/projects/list/detail/questionnaire.rst

@@ -69,7 +69,6 @@ Based on our role in the project and specific instance settings there are some a
 
 - :ref:`Add TODO<todos>`
 - :ref:`Add comment<add-comment>`
-- Provide feedback for the question
 
 We can get more information on how various collaboration tools work and can be used in :ref:`Sharing<sharing>`.
 

docs/conf.py

@@ -25,7 +25,7 @@
 project_name_full = 'Data Stewardship Wizard'
 
 # The full version, including alpha/beta/rc tags
-version = release = '4.30'
+version = release = '4.31'
 
 rst_prolog = f"""
 

docs/more/self-hosted-dsw/configuration/configuration.rst

@@ -54,7 +54,7 @@ This configuration section is used only by **Server** and covers basic configura
 
 If we need to change our ``secret``, we need also replace all values encrypted by the secret that is stored in the database as follows:
 
-1. Note somewhere values from Settings: Client ID and Client Secret of OpenID configurations, Registry token, and GitHub token for Feedback functionality, etc. Adjust the settings that the values are not there (recommended; e.g., remove OpenID configuration), and save it.
+1. Note somewhere values from Settings: Client ID and Client Secret of OpenID configurations, Registry token, etc. Adjust the settings that the values are not there (recommended; e.g., remove OpenID configuration), and save it.
 2. Change the ``secret`` in the configuration file and restart the |project_name| server (re-create the container if using Docker).
 3. Adjust the settings back to our previous values.
 4. If we also use some “user properties” (for the Document Submission feature), let our users know to change the values in their profiles.