fixed review comments

schwzr · schwzr · commit 9c093dec054f · 2025-11-25T23:33:45.000+01:00
diff --git a/docs/src/operations/v2.0.0/bpe/logging.md b/docs/src/operations/v2.0.0/bpe/logging.md
@@ -62,11 +62,11 @@ Every logger exposes a *.style property and a corresponding environment variable
 Plain, unformatted text output (default for console output, used before DSF 2).
 
 Use when:
-- You want minimal overhead and simple logging.
-- Logs are read directly on the system.
+- You want minimal overhead and simple logging
+- Logs are read directly on the system
 
 Avoid when:
-- A log aggregation system is used.
+- A log aggregation system is used
 
 #### TEXT_MDC
 
@@ -77,26 +77,26 @@ Plain text with MDC (Mapped Diagnostic Context) fields, such as:
 - user
 - requestId
 
-Recommended for:
-- Production file logs
-- Debugging distributed workflows with correlation IDs
+Use when:
+- You want to log production environments without aggregation systems
+- You want to debug distributed workflows with correlation IDs
 
-Not ideal for:
-- A log aggregation system is used.
+Avoid when:
+- A log aggregation system is used
 
 #### TEXT_COLOR and TEXT_COLOR_MDC
 
 ANSI-colored text output for terminals.
 
-Recommended for:
-- Local development
-- Docker logs viewed directly with docker logs
-- Developers who want fast visual distinction between INFO/WARN/ERROR
+Use when:
+- You want to develop locally
+- You want to view docker logs directly with `docker logs` command
+- You want a fast visual distinction between INFO/WARN/ERROR
 
-Avoid for:
-- Log ingestion systems
-- Consoles without ANSI escape code support
+Avoid when:
+- A log aggregation system is used
+- Consoles without ANSI escape code support are used
 
 
 ### JSON-Based Logging Styles
-We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with your log aggreation system of your choice.
+We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with the log aggreation system of your choice.
diff --git a/docs/src/operations/v2.0.0/fhir/access-control.md b/docs/src/operations/v2.0.0/fhir/access-control.md
@@ -81,7 +81,7 @@ DSF roles specified via the `dsf-role` property define general access to the RES
 In order to allow users to start processes, the property `practitioner-role` can be used to assign codes from FHIR [CodeSystem](http://hl7.org/fhir/R4/codesystem.html) resources. Codes are specified in the form `system-url|code`.
 If the uses has a code specified here that match with a `requester` extension within the process plugin's [ActivityDefinition](http://hl7.org/fhir/R4/activitydefinition.html) resource, the user can start the process if he also has the `dsf-role` `CREATE`.
 
-Process plugins can defined and use there own code-systems. However, the DSF specifies a standard set of practitioner roles within the CodeSystem `http://dsf.dev/fhir/CodeSystem/practitioner-role`:
+Process plugins can define and use their own code-systems. However, the DSF specifies a standard set of practitioner roles within the CodeSystem `http://dsf.dev/fhir/CodeSystem/practitioner-role`:
 
 `UAC_USER`, `COS_USER`, `CRR_USER`, `DIC_USER`, `DMS_USER`, `DTS_USER`, `HRP_USER`, `TTP_USER`, `AMS_USER`, `ASP_USER`, `SPR_USER`, `TSP_USER`, `PPH_USER`, `BIO_USER`, and `DSF_ADMIN`.
 
@@ -109,17 +109,19 @@ The first example defines a group of DSF administrators. Two client certificates
 ```
 
 
-The second example defines a group of DSF administrators by specifying an `admin` role that gets matched against OAuth 2.0 access tokens:
+The second example defines an administrator group consisting of all users with the OAuth role admin plus two additional administrators identified by their client-certificate thumbprints. These administrators may perform the basic DSF tasks: starting and continuing of new process instances (by creating tasks and answering QuestionnaireResponses) and reading all resources on the DSF FHIR server.
 
 ```yaml
       DEV_DSF_FHIR_SERVER_ROLECONFIG: |
-        - token-role-admins:
+        - example_minimal_admin:
+            thumbprint:
+              - 0123...cdef
+              - abcd...6789
             token-role: admin
             dsf-role:
-              - CREATE
+              - CREATE: [Task]
               - READ
-              - UPDATE
-              - DELETE
+              - UPDATE: [QuestionnaireResponse]
               - SEARCH
               - HISTORY
             practitioner-role:
diff --git a/docs/src/operations/v2.0.0/fhir/logging.md b/docs/src/operations/v2.0.0/fhir/logging.md
@@ -50,11 +50,11 @@ Every logger exposes a *.style property and a corresponding environment variable
 Plain, unformatted text output (default for console output, used before DSF 2).
 
 Use when:
-- You want minimal overhead and simple logging.
-- Logs are read directly on the system.
+- You want minimal overhead and simple logging
+- Logs are read directly on the system
 
 Avoid when:
-- A log aggregation system is used.
+- A log aggregation system is used
 
 #### TEXT_MDC
 
@@ -65,26 +65,26 @@ Plain text with MDC (Mapped Diagnostic Context) fields, such as:
 - user
 - requestId
 
-Recommended for:
-- Production file logs
-- Debugging distributed workflows with correlation IDs
+Use when:
+- You want to log production environments without aggregation systems
+- You want to debug distributed workflows with correlation IDs
 
-Not ideal for:
-- A log aggregation system is used.
+Avoid when:
+- A log aggregation system is used
 
 #### TEXT_COLOR and TEXT_COLOR_MDC
 
 ANSI-colored text output for terminals.
 
-Recommended for:
-- Local development
-- Docker logs viewed directly with docker logs
-- Developers who want fast visual distinction between INFO/WARN/ERROR
+Use when:
+- You want to develop locally
+- You want to view docker logs directly with `docker logs` command
+- You want a fast visual distinction between INFO/WARN/ERROR
 
-Avoid for:
-- Log ingestion systems
-- Consoles without ANSI escape code support
+Avoid when:
+- A log aggregation system is used
+- Consoles without ANSI escape code support are used
 
 
 ### JSON-Based Logging Styles
-We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with your log aggreation system of your choice.
+We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with the log aggreation system of your choice.
diff --git a/docs/src/operations/v2.0.0/upgrade-from-1.md b/docs/src/operations/v2.0.0/upgrade-from-1.md
@@ -22,16 +22,18 @@ For DSF 2, we refined the [system requirements](install.md#prerequisites). If yo
 
 ::: info Non-standard configuration changes
 
-The most non-standard configuration changes working in DSF 1 will continue to work in DSF 2. If you have set custom timeout options please change them to the ISO 8601 standard. `120000` (Milliseconds) must be changed to `PT2M`.
+Most non-standard configuration changes working in DSF 1 will continue to work in DSF 2. If you have set custom timeout options please change them to the ISO 8601 standard. `120000` (Milliseconds) must be changed to `PT2M`.
 
 - You can now use more advanced [logging options](./fhir/logging.md).
 - If you use your own certificate authority, the [configuration](root-certificates.md) will be easier.
-- If can now use more fine granular access control settings in your own [access control / role config settings](./fhir/access-control.md).
+- More granular control in [access control / role config settings](./fhir/access-control.md).
 :::
 
 We recommend upgrading the PostgreSQL DBMS from version 15 to version 18. At present, it is possible to use PostgreSQL version 15, but we exclusively support PostgreSQL version 18 and test the DSF solely with version 18.
 The DBMS upgrade is described below in the update instructions.
 
+DSF 2 was designed to run DSF 1 (APIv1) process plugins, but due to stricter validation rules in DSF 2 we strongly recommend using the latest compatible plugin versions. Updates within the same major and minor version (e.g., from 1.2.3.4 to 1.2.9.9) are generally safe. An overview of the recommended MII/NUM versions can be found [here](./install-plugins.md).
+
 ## Modify DSF FHIR Server Setup
 1. Preparation / Backup
     * We recommend to create a backup of the `/opt/fhir` directory before proceeding with the upgrade.  
