aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/spec.md189
1 files changed, 152 insertions, 37 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)