Update Documentation

- Describe Configuration Profiles
- Describe Logging
- Refactor: Put each Sentence in a new line.

2 files changed, 177 insertions, 43 deletions

diff --git a/docs/spec.md b/docs/spec.md
index ce336e4..042d959 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -3,6 +3,9 @@
 ## Introduction
 
 MOA ZS is a middleware that allow a sender application (app) to send delivery requests to delivery services.
+MOA ZS uses Apache CXF as a web service framework and the Spring Framework as inversion of control container.
+
+TODO: write a proper introduction with actors, sequence diagram & interfaces
 
 ## Changelog
 
@@ -18,59 +21,170 @@ For version 2.0.0, MOA ZS was rewritten from scratch. The following list summari
 - Drop support for message encryption and signature creation.
 - Target Platform Java 12.
 
-### Changes between app2mzs 1.5.3 and 2.0.0
+### Changes between app2mzs 1.5.3 and app2mzs 2.0.0
 
-This section describes, how the app2mzs wsdl contract was changed and explains, why these changes were applied. Due to the nature of the changes (feature additions and feature removals in [zusemsg] 2.0.0 and [zusetnvz] 2.0.0) and due to the fact that changes propagate into the app2mzs interface, some changes are not backwards compatible and require to be integrated into the app.
+This section describes, how the app2mzs wsdl contract was changed and explains, why these changes were applied.
+Due to the nature of the changes (feature additions and feature removals in [zusemsg] 2.0.0 and [zusetnvz] 2.0.0) and due to the fact that changes propagate into the app2mzs interface, some changes are not backwards compatible and require to be integrated into the app.
 
 #### Changes in `mzs:DeliveryRequest`
 
-- The `Server` element was removed from the `DeliveryRequest` type because this element replaced the response from the request that was sent to the ZKOPF. The ZKOPF request does not exist anymore, therefore the `Server` response is not relevant. This change is *not backwards-compatible*.
-- The `ProfileID` option in the `DeliveryRequest/Sender` element was replaced by `msg:SenderProfile` because sender profiles are now registered at the delivery service and referred to via `DeliveryRequest/Sender/SenderProfile`. This change is *not backwards-compatible*.
-- The `SignatureKeyID` element was removed from `DeliveryRequest` because this element refers to the signing key. Since signature creation was dropped, the element is not relevant. This change is *not backwards-compatible*.
-- The optional elements `msg:Logo` and `msg:AdditionalCriteria` were added to `DeliveryRequest/Sender` because they were also added as optional elements to [zusemsg]. This change is *backwards-compatible*.
-- The element `Person` in `DeliveryRequest/Sender` was replaced by the `p:CorporateBody` profile because that is the only sender that is allowed by [zusemsg]. This change is *not backwards-compatible*.
-- `DeliveryRequest/Sender/Address` was removed because the element was dropped in [zusemsg]. This change is *not backwards-compatible*.
-- An alternative choice to the `Person`-`Address` sequence in `DeliveryRequest/Receiver` was added. This choice allows to pass a `p:Identification` element instead of the `Person`-`Address` sequence. The choice was added because it is a new, optional feature in [zusemsg]. This change is *backwards-compatible*.
-- The optional element `tvnz:AustrianAddressesOnly` was added to `DeliveryRequest/Receiver` because this element was also added as an optional element to [zusetnvz]. This change is *backwards-compatible*.
-- The optional element `msg:AdditionalCriteria` and `msg:PreAdviceNote` were added to `DeliveryRequest/Receiver` because these element were also added as optional elements to [zusemsg]. This change is *backwards-compatible*.
-- The element `MetaData` in `DeliveryRequest` was replaced with the `msg:MetaData` element from [zusemsg]. The reason for replacing the `MetaData` element is that the `MetaData` from the app2mzs contract represents the same data that the delivery service expects. Furthermore, the amount of changes between both elements prohibits a straight forward conversion between them. This change is *not backwards-compatible*.
-- The optional `Config` element was added to the `DeliveryRequest` element. This element allows to override individual configuration parameters for the ongoing request. See [Chapter Configuration](#configuration) for more details. This change is *backwards-compatible*.
-- The element `XMLDocument` was replaced as this element was dropped from [zusemsg] in favor of the `msg:Payload` element. This change is *not backwards-compatible*.
-- The types `BinaryDocument` and `DocumentReference` in `DeliveryRequest/Payload` were merged to remove duplicated element and to ensure that all fields that allow a conversion from `mzs:Payload` to `msg:Attachment` are available. This change is not *backwards-compatible*.
-- The element `MD5Checksum` in `DeliveryRequest/Payload/DocumentReference` was replaced with `msg:Checksum`, which was introduced by [zusemsg]. This change is not *backwards-compatible*.
-- The element `msg:Size` was added to `DeliveryRequest/Payload` because it was also added as a mandatory element in [zusemsg].
-- The `sync` attribute was dropped in favor to the element `Config/ServiceTimeout`. This change is not *backwards-compatible*.
+- The `Server` element was removed from the `DeliveryRequest` type because this element replaced the response from the request that was sent to the ZKOPF.
+  The ZKOPF request does not exist anymore, therefore the `Server` response is not relevant.
+  This change is *not backwards-compatible*.
+- The `ProfileID` option in the `DeliveryRequest/Sender` element was replaced by `msg:SenderProfile` because sender profiles are now registered at the delivery service and referred to via `DeliveryRequest/Sender/SenderProfile`.
+  This change is *not backwards-compatible*.
+- The `SignatureKeyID` element was removed from `DeliveryRequest` because this element refers to the signing key.
+  Since signature creation was dropped, the element is not relevant.
+  This change is *not backwards-compatible*.
+- The optional elements `msg:Logo` and `msg:AdditionalCriteria` were added to `DeliveryRequest/Sender` because they were also added as optional elements to [zusemsg].
+  This change is *backwards-compatible*.
+- The element `Person` in `DeliveryRequest/Sender` was replaced by the `p:CorporateBody` profile because that is the only sender that is allowed by [zusemsg].
+  This change is *not backwards-compatible*.
+- `DeliveryRequest/Sender/Address` was removed because the element was dropped in [zusemsg].
+  This change is *not backwards-compatible*.
+- An alternative choice to the `Person`-`Address` sequence in `DeliveryRequest/Receiver` was added.
+  This choice allows to pass a `p:Identification` element instead of the `Person`-`Address` sequence.
+  The choice was added because it is a new, optional feature in [zusemsg].
+  This change is *backwards-compatible*.
+- The optional element `tvnz:AustrianAddressesOnly` was added to `DeliveryRequest/Receiver` because this element was also added as an optional element to [zusetnvz].
+  This change is *backwards-compatible*.
+- The optional element `msg:AdditionalCriteria` and `msg:PreAdviceNote` were added to `DeliveryRequest/Receiver` because these element were also added as optional elements to [zusemsg].
+  This change is *backwards-compatible*.
+- The element `MetaData` in `DeliveryRequest` was replaced with the `msg:MetaData` element from [zusemsg].
+  The reason for replacing the `MetaData` element is that the `MetaData` from the app2mzs contract represents the same data that the delivery service expects.
+  Furthermore, the amount of changes between both elements prohibits a straight forward conversion between them.
+  This change is *not backwards-compatible*.
+- The optional `Config` element was added to the `DeliveryRequest` element.
+  This element allows to override individual configuration parameters for the ongoing request.
+  See [Chapter Configuration](#configuration) for more details.
+  This change is *backwards-compatible*.
+- The element `XMLDocument` was replaced as this element was dropped from [zusemsg] in favor of the `msg:Payload` element.
+  This change is *not backwards-compatible*.
+- The types `BinaryDocument` and `DocumentReference` in `DeliveryRequest/Payload` were merged to remove duplicated element and to ensure that all fields that allow a conversion from `mzs:Payload` to `msg:Attachment` are available.
+  This change is *not backwards-compatible*.
+- The element `MD5Checksum` in `DeliveryRequest/Payload/DocumentReference` was replaced with `msg:Checksum`, which was introduced by [zusemsg].
+  This change is *not backwards-compatible*.
+- The element `msg:Size` was added to `DeliveryRequest/Payload` because it was also added as a mandatory element in [zusemsg]. This change is not *backwards-compatible*.
+- The `sync` attribute was dropped in favor to the element `Config/ServiceTimeout`.
+  This change is *not backwards-compatible*.
 
 ### Changes in `mzs:DeliveryResponse`
 
-- The option `DeliveryConfirmation` in `DeliveryResponse` was dropped because it was dropped in [zusemsg]. This change is *not backwards-compatible*.
-- Add `DeliverySystem`, `ZSDeliveryID` and `GZ` to `MessageType`, which is the base type of `DeliveryResponse/Success`, -`PartialSuccess`, and -`Error`. These mandatory elements were added to [zusemsg]. This change is *backwards-compatible*.
-- Add `SignedDeliveryRequestStatus` to` MessageType`. This optional element contains the original response that was send from the delivery service to MOA ZS. The response was not modified such that containing signatures can be verified by the app. This change is *backwards-compatible*.
-- Remove `MZSDeliveryID` because this ID does not exist anymore, as MOA ZS does not maintain requests in a database. This change is *not backwards-compatible*.
-- Add the optional `PreadviceNoteSend` element to `ErrorType` because it was added in
-  [zusemsg]. This change is *backwards-compatible*.
-- Remove `DocumentReference` from `ErrorType` because it was removed from [zusemsg]. This change is not *backwards-compatible*.
-- Add the elements `msg:DeliveryTimestamp` and `msg:RelayedViaERV` to `SuccessType` because they were added in [zusemsg]. This change is *backwards-compatible*.
+- The option `DeliveryConfirmation` in `DeliveryResponse` was dropped because it was dropped in [zusemsg].
+  This change is *not backwards-compatible*.
+- Add `DeliverySystem`, `ZSDeliveryID` and `GZ` to `MessageType`, which is the base type of `DeliveryResponse/Success`, -`PartialSuccess`, and -`Error`.
+  These mandatory elements were added to [zusemsg].
+  This change is *backwards-compatible*.
+- Add `SignedDeliveryRequestStatus` to` MessageType`.
+  This optional element contains the original response that was send from the delivery service to MOA ZS.
+  The response was not modified such that containing signatures can be verified by the app.
+  This change is *backwards-compatible*.
+- Remove `MZSDeliveryID` because this ID does not exist anymore, as MOA ZS does not maintain requests in a database.
+  This change is *not backwards-compatible*.
+- Add the optional `PreadviceNoteSend` element to `ErrorType` because it was added in [zusemsg].
+  This change is *backwards-compatible*.
+- Remove `DocumentReference` from `ErrorType` because it was removed from [zusemsg].
+  This change is *not backwards-compatible*.
+- Add the elements `msg:DeliveryTimestamp` and `msg:RelayedViaERV` to `SuccessType` because they were added in [zusemsg].
+  This change is *backwards-compatible*.
 
 ### Changes in `mzs:DeliveryNotification`
 
-- Remove `DeliveryConfirmation` and `DeliveryStatement` elements from `DeliveryNotification` as those element were dropped from [zusemsg]. This change is *not backwards-compatible*.
-- Add the elements `msg:SenderDetails`, `msg:ReceiverDetails`, `msg:User`, `AdditionalFormat` and `msg:NotificationsPerformed` to the `DeliveryNotification` because they were added to [zusemsg]. This change is *backwards-compatible*.
+- Remove `DeliveryConfirmation` and `DeliveryStatement` elements from `DeliveryNotification` as those element were dropped from [zusemsg].
+  This change is *not backwards-compatible*.
+- Add the elements `msg:SenderDetails`, `msg:ReceiverDetails`, `msg:User`, `AdditionalFormat` and `msg:NotificationsPerformed` to the `DeliveryNotification` because they were added to [zusemsg].
+  This change is *backwards-compatible*.
 
 ### Changes in `mzs_mypersondata`
 
-- The element `AbstractPersonType` was defined as `abstract`, since the equivalent type in [zusemsg] is abstract as well. This change is *not backwards-compatible*.
-- The elements `Name` and `DateOfBirth` in `PhysicalPersonType` were set from optional to mandatory because they are mandatory in [zusemsg]. This change is *not backwards-compatible*.
-- The optional element `Affix` was added to `PersonNameType` since this element was added to [zusemsg] as well. This change is *backwards-compatible*.
-- The `CorporateBodyType` was extended by the optional `Target` element that was added to [zusemsg]. This change is *backwards-compatible*.
-- The elements `FullName` and `Organization` in `CorporateBodyType` were set from optional to mandatory because they are mandatory in [zusemsg]. This change is *not backwards-compatible*.
-- The restriction from `CountryCode` was lifted. This change is *backwards-compatible*.
-- The optional attribute `type` was added to `PostalAddressType`. This change is *backwards-compatible*.
-- The optional attribute `MessengerService` was added to `TelephoneAddressType`. This change is *backwards-compatible*.
+- The element `AbstractPersonType` was defined as `abstract`, since the equivalent type in [zusemsg] is abstract as well.
+  This change is *not backwards-compatible*.
+- The elements `Name` and `DateOfBirth` in `PhysicalPersonType` were set from optional to mandatory because they are mandatory in [zusemsg].
+  This change is *not backwards-compatible*.
+- The optional element `Affix` was added to `PersonNameType` since this element was added to [zusemsg] as well.
+  This change is *backwards-compatible*.
+- The `CorporateBodyType` was extended by the optional `Target` element that was added to [zusemsg].
+  This change is *backwards-compatible*.
+- The elements `FullName` and `Organization` in `CorporateBodyType` were set from optional to mandatory because they are mandatory in [zusemsg].
+  This change is *not backwards-compatible*.
+- The restriction from `CountryCode` was lifted.
+  This change is *backwards-compatible*.
+- The optional attribute `type` was added to `PostalAddressType`.
+  This change is *backwards-compatible*.
+- The optional attribute `MessengerService` was added to `TelephoneAddressType`.
+  This change is *backwards-compatible*.
 
 ## Configuration
 
-TODO
+The folder `src/test/resources/config` serves as a template for configuring MOA ZS.
+Most aspects of MOA ZS can be configured via [application.yaml](../src/test/resources/config/application.yaml).
+If you want to switch to your own configuration format, you may consult [Spring Boot Documentation: Externalized Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).
+The following section explains individual configuration aspects.
+
+### Delivery Request Configuration Profiles
+
+A configuration profile contains all parameters that determine, how MOA ZS processes a delivery request.
+The following list specifies, how a parameter can be configured and in which priority MOA ZS lets you override parameters (highest priority first):
+
+1. You can set a parameter directly in a `mzs:DeliveryRequest` under the `Config` element.
+   See [app2mzs.xsd](../src/main/resources/mzs/app2mzs.xsd) for a list of parameters that you can configure.
+   Note that each parameter is optional and you can override individual parameters.
+   For parameters that are missing from the `Config` elements, MOA ZS falls back to the parameter from the referred profile.
+   The scope of a parameter in the `Config` element is limited to the current delivery request.
+
+2. You can refer to a specific profile in `mzs:DeliveryRequest/Config/ProfileID`, where the value of `ProfileID` refers to a profile that was configured in `application.yaml`.
+   MOA ZS looks up the profile by the chosen ID and uses all parameters from this profile.
+   To create a profile in `application.yaml`, copy an existing profile, set a new `ProfileID` and adapt the parameters.
+   The key of each child in `delivery-request-configuration-profiles` is the `ProfileID` of the underlying profile.
+   If a parameter is missing, MOA ZS falls back to the parameter in the `default` profile.
+
+3. If you so not specify a parameter in `Config`, if you do not select a `ProfileId`, or if the parameter in the selected profile is missing, MOA ZS falls back to the parameter in the `default` profile.
+
+If a mandatory parameter is not configured in any of the listed manners, MOA ZS rejects the delivery request.
+The following listing shows the structure of a profile.
+You find a description of the individual parameters in `application.yaml`.
+
+```
+  default:
+    service-timeout: 60
+    perform-query-person-request: false
+    tvnz-client:
+      url: http://localhost:8082/tnvz/
+      connection-timeout: 0
+      receive-timeout: 0
+      ssl:
+      custom-http-headers:
+        X-PVP-NAME-1: VALUE-X
+        X-PVP-NAME-2: VALUE-Y
+    msg-client:
+      url: http://localhost:8081/services/DeliveryRequest
+      connection-timeout: 0
+      receive-timeout: 0
+    msg-response-sinks:
+      save-response-to-file:
+        active: false
+        path: /msg-responses/
+      log-response: true
+      forward-response-to-service:
+        active: false
+        mzs-client:
+          url: http://service.which.implements.mzs2app.wsdl/services/
+          connection-timeout: 0
+          receive-timeout: 0
+          ssl:
+```
+
+### Server
+
+`server.port`: Choose, under which port MOA ZS exposes its services.
+
+### Logging
+
+MOA ZS uses Spring Boot's default logging backend, which is logback.
+In application.yaml you can choose, which loggers should log which levels.
+You can choose between the following five log levels (sorted by descending importance and ascending level of detail): `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`.
+You may specify if MOA ZS should log events to a file appender via `logging.file`.
+You can specify the logging format in `logback.xml`. See [Spring Boot Documentation: Logging](https://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html) for details.
 
 ## Namespace Declarations
 
@@ -84,4 +198,5 @@ TODO
 ## References
 
 [zusemsg] Tauber, Arne: Elektronische Zustellung Message Spezifikation 2.0.0 (2019-04-08)
+
 [zusetnvz] Tauber, Arne and Wolf, Dieter Auer: Elektronische Zustellung Teilnehmerverzeichnis 2.0.0 (2019-04-08)
diff --git a/readme.md b/readme.md
index 6eca69d..1e6a603 100644
--- a/readme.md
+++ b/readme.md
@@ -1,5 +1,8 @@
 # MOA ZS - README
 
+This file gives instructions on how to build, test, and deploy MOA ZS.
+See [the technical specification](docs/spec.md) for a more detailed description of MOA ZS and how it can be configured.
+
 ## Build Instructions
 
 Compilation and Runtime Requirements:
@@ -14,7 +17,8 @@ mvn test
 
 ### Run Integration Tests
 
-Integration tests start with the prefix `IT`. Run them with the following command:
+Integration tests start with the prefix `IT`.
+Run them with the following command:
 ```
 mvn test -P integration-tests
 ```
@@ -26,12 +30,14 @@ Command:
 mvn test -P all-tests
 ```
 
-Note that some integration tests (prefix `ITSSL`) rely on a TLS connection and Client Authentication. The following guide explains how to set up TLS and Client Authentication with Apache 2.
+Note that some integration tests (prefix `ITSSL`) rely on a TLS connection and Client Authentication.
+The following guide explains how to set up TLS and Client Authentication with Apache 2.
 
 #### Quick Guide: Set Up SSL (inc. Client Authentication) in Apache 2.
 
 This guide is only needed for running all tests.
-Some tests require SSL protection of the service endpoint with SSL Client Authentication. Here's a quick guide how to set up an Apache 2 service on localhost as a SSL terminating reverse proxy to the zusemsg endpoint that runs on <http://localhost:8081/>.
+Some tests require SSL protection of the service endpoint with SSL Client Authentication.
+Here's a quick guide how to set up an Apache 2 service on localhost as a SSL terminating reverse proxy to the zusemsg endpoint that runs on <http://localhost:8081/>.
 
 1.   Install Apache 2.
 1.   Ensure that mod-proxy is installed and enabled.
@@ -78,7 +84,10 @@ After packaging the application to a `war` file, the application can be deployed
 
 ### Configuration
 
-The folder `src/test/resources/config` serves as a template for configuring the application. This folder can be used as-is for deploying the application in a test or development environment. You may apply changes to this folder to fit the needs of a productive environment. See [specification.md](docs/spec.md) and [application.yaml](src/test/resources/config/application.yaml) for more details.
+The folder `src/test/resources/config` serves as a template for configuring MOA ZS.
+This folder can be used as-is for deploying MOA ZS in a test or development environment.
+You may apply changes to this folder to fit the needs of a productive environment.
+See [specification.md](docs/spec.md) and [application.yaml](src/test/resources/config/application.yaml) for more details.
 
 ### Deploy as Standalone Application
 
@@ -100,7 +109,8 @@ The folder `src/test/resources/config` serves as a template for configuring the
      cp src/test/resources/config standalone/ -r
      ```
 
-     If you rename this folder, the application might not find the configuration file `application.yaml`. Consult [Spring Doc: External Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files) for further details and alternative ways to configure the application.
+     If you rename this folder, the application might not find the configuration file `application.yaml`.
+     Consult [Spring Doc: External Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files) for further details and alternative ways to configure the application.
 
 1.   Start application.
 
@@ -108,6 +118,9 @@ The folder `src/test/resources/config` serves as a template for configuring the
      (cd standalone && java -jar moa-zs.war)
      ```
 
+1.   The app2mzs service is reachable under <http://localhost:$SERVER_PORT/services/mzs>.
+     The zuse2app service is reachable under <http://localhost:$SERVER_PORT/services/msg>.
+
 ### Deploy to Tomcat Container
 
 1.  Copy the application package `moa-zs.war` to Tomcat's `webapps` directory.
@@ -122,10 +135,16 @@ The folder `src/test/resources/config` serves as a template for configuring the
     cp test/main/resources/config/ $MZS_CONFIG
     ```
 
-1.  Ensure that the spring-boot application finds `$MZS_CONFIG/application.yaml`. Option a) Add the folder `$MZS_CONFIG` to the class path of the web application, e.g. by specifying the `common.loader` property (see [Tomcat's Class Loader How-To](https://tomcat.apache.org/tomcat-9.0-doc/class-loader-howto.html)). Option b) Set the system property `spring.config.location` to `$MZS_CONFIG/application.yaml`. In that case, make sure that all paths in `$MZS_CONFIG/application.yaml` are absolute paths.
+1.  Ensure that the spring-boot application finds `$MZS_CONFIG/application.yaml`.
+    Option a) Add the folder `$MZS_CONFIG` to the class path of the web application, e.g. by specifying the `common.loader` property (see [Tomcat's Class Loader How-To](https://tomcat.apache.org/tomcat-9.0-doc/class-loader-howto.html)).
+    Option b) Set the system property `spring.config.location` to `$MZS_CONFIG/application.yaml`.
+    In that case, make sure that all paths in `$MZS_CONFIG/application.yaml` are absolute paths.
 
 1.  Start tomcat.
 
+1.  The app2mzs service is reachable under <http://localhost:$TOMCAT_PORT/moa-zs/services/mzs>.
+    The zuse2app service is reachable under <http://localhost:$TOMCAT_PORT/moa-zs/services/msg>.
+
 # Footnotes
 
 [1] https://bugs.openjdk.java.net/browse/JDK-8214098