# MOA ZS - Specification ## Introduction MOA ZS is a web application middleware that allows a sender application (app) to send delivery requests to delivery services. The goal of MOA ZS is to manage all aspects of the electronic delivery process from a senders perspective, such as: - Accepting delivery requests from a sender - Looking up participants in the participant registry ("Teilnehmerverzeichnis") - Forwarding requests to delivery services - Handling responses and notifications (e.g. signature verification, archiving) The following figure shows, with which electronic delivery participants MOA ZS communciates and which interfaces it uses: ![Architecture](https://git.egiz.gv.at/moa-zs/plain/docs/figures/architecture.png "Architecture") - The sender application sends a `mzs:DeliveryRequest` (specified in [app2mzs.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/mzs/app2mzs.wsdl)) to MOA ZS. - MOA ZS sends a `tnvz:QueryPersonRequest` to the participant registry to find out if the receiver is registered (specified in [zuse2tnvz_p2.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/zusetnvz/zuse2tnvz_p2.wsdl)). This request is optional and depends on parameters from the `mzs:DeliveryRequest` and from the MOA ZS configuration. If the receiver is registered, the participant registry returns an identifier for this receiver. - MOA ZS converts the `mzs:DeliveryRequest` to a `msg:DeliveryRequest` and forwards `msg:DeliveryRequest` to the delivery service (specified in [app2zuse_p2.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/zusemsg/app2zuse_p2.wsdl)). - The delivery service sends delivery notifications and status updates to MOA ZS via the [zuse2app_p2.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/zusemsg/zuse2app_p2.wsdl) service. - MOA ZS then handles notifications and status updates by verifying their signatures, archiving them, and by (optional) forwarding the notifications to the sender application (specified in [mzs2app.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/mzs/mzs2app.wsdl)). MOA ZS uses Apache CXF as a web service framework and the Spring Framework as inversion of control container. The application is written in Java and requires JDK 12 as runtime environment. ## Changelog This section summarizes changes between MOA ZS Releases that were made in the MOA ZS codebase and in the app2mzs interfaces. For a non-normative summary of changes that were made in the ZUSE specifications (and therefore affect MOA ZS directly and a sender application indirectly), the reader is referred to [ZUSE Specification Changelog](zusespec-changelog.md). ### Changes MOA ZS 2.0.0 RC3 - Remove Workaround that fixes JAXB Class Not Found Exception when running application in Tomcat. - Bump zusetnvz contracts from version 2.2.006 to 2.2.008. ### Changes MOA ZS 2.0.0 RC2 - Minor Fixes in Documentation and Readme. - Change MOA ZS Group ID from `at.gv.zustellung` to `at.gv.egiz`. - Bug Fix: Booleans in [application.yaml](../src/test/resources/config/application.yaml) are parsed correctly. - Bug Fix: [zusemsg] and [zusetnvz] clients use SOAP 1.2 to comply with the specification. - Bug Fix: Change `type` property key to `filetype` in [application.yaml](../src/test/resources/config/application.yaml) such that MOA ZS receives the property value. - Bug Fix: Validation error was assigned to TNVZ Client, but appeared in MSG Client. - Upgrade [zusemsg] schema files from 2.0.0 to 2.0.007 and apply changes to codebase. - Upgrade [zusetnvz] from 2.0.0 to 2.0.006 and apply changes to codebase. - Add licenses, license headers and NOTICE. - Add @author tags. #### app2mzs interface changes - Switch namespace of `AustrianAdressesOnly` from [tnvz] to [msg]. - Add new optional element `ClearingProfilID` to `mzs:DeliveryRequestType/Sender`; Reason: Element was added to [zusemsg] 2.2.007. - Add new choice in `mzs:DeliveryNotification` to forward new answer of type `msg:ERVConfirmedDelivery` to the app. - Move element `msg:RelayedViaERV` from `SuccessType` into `MessageType` (so that it's available to all types that derive from `MessageType`). - Change `mzs:MessageType/ZSDeliveryID` from mandatory to optional element. Reason: In certain cases the `ZSDeliveryID` does not exist. Example: Perform QueryPersonRequest, Request fails, no ZSDeliveryID because request was never sent to delivery service. - Change type of `mzs:Error/Code` from `xs:integer` to `xs:string`. Reason: `msg:Code` is also of type `xs:string`. ### Changes Between MOA ZS 1.5.3 and MOA ZS 2.0.0 RC1 For version 2.0.0, MOA ZS was rewritten from scratch. The following list summarizes the changes: - Add compatibility with [zusemsg]. - Add compatibility with [zusetnvz]. - Replace the database as persistent storage with an in-memory cache. - Update the app2mzs WSDL contract and its data types to fit the needs of [zusemsg] and [zusetnvz]. - Integrate signature verification with MOA SP-SS. - Drop support for message encryption and signature creation. - Target Platform Java 12. ### 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. The changes in the app2mzs WSDL contract accommodate feature additions and feature removals in [zusemsg] 2.0.0 and [zusetnvz] 2.0.0. Not all changes are backward compatible and require adjustments in app2mzs-1.5.3-compatible clients. #### Changes in `mzs:DeliveryRequest` - The `Server` element was removed from the `DeliveryRequest` type. In MOA ZS 1.5.3, this element replaced the ZKOPF response. ZKOPF request and response do not exist anymore, which renders the `Server` response irrelevant. This change is *not backward 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 backward compatible*. - The `SignatureKeyID` element was removed from `DeliveryRequest` because this element refers to the signing key. Since signature creation was dropped from MOA ZS, the element is not relevant. This change is *not backward 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 *backward 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 backward compatible*. - `DeliveryRequest/Sender/Address` was removed because the element was dropped in [zusemsg]. This change is *not backward 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 to enable the optional feature in [zusemsg]. This change is *backward compatible*. - The optional element `tnvz:AustrianAddressesOnly` was added to `DeliveryRequest/Receiver` because this element was also added as an optional element to [zusetnvz]. This change is *backward 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 *backward 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 MetaData from app2mzs 1.5.3 and [zusemsg] 2.0.0 prohibits a straight forward conversion between both elements. This change is *not backward compatible*. - The optional `Config` element was added to the `DeliveryRequest` element. This element allows overriding individual configuration parameters for the ongoing request. This change is *backward compatible*: You do not need to specify any parameters in the `Config`-element since you can also configure delivery requests in [application.yaml](../src/test/resources/config/application.yaml). See [Chapter Configuration](#configuration) for more details. - The element `XMLDocument` was replaced as this element was dropped from [zusemsg] in favor of the `msg:Payload` element. This change is *not backward compatible*. - The types `BinaryDocument` and `DocumentReference` in `DeliveryRequest/Payload` were merged to remove duplicated element. Merging these elements ensures that both payload types contain all of `msg:Attachment`s mandatory fields. This change is *not backward compatible*. - The element `MD5Checksum` in `DeliveryRequest/Payload/DocumentReference` was replaced with `msg:Checksum`, which was introduced by [zusemsg]. This change is *not backward 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 *backward compatible*. - The `sync` attribute was dropped in favor of the element `Config/ServiceTimeout`. This change is *not backward 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, unaltered response that was sent from the delivery service to MOA ZS. The app can use this response to verify the contained signature. This change is *backward compatible*. - Remove `MZSDeliveryID` because this ID does not exist anymore. This change is *not backward compatible*. - Add the optional `PreadviceNoteSent` element to `ErrorType` because it was added in [zusemsg]. This change is *backward compatible*. - Remove `DocumentReference` from `ErrorType` because it was removed from [zusemsg]. This change is *not backward compatible*. - Add the elements `msg:DeliveryTimestamp` and `msg:RelayedViaERV` to `SuccessType` because they were added in [zusemsg]. This change is *backward compatible*. ### Changes in `mzs:DeliveryNotification` - Remove `DeliveryConfirmation` and `DeliveryStatement` elements from `DeliveryNotification` as those element were dropped from [zusemsg]. This change is *not backward 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 *backward 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 backward compatible*. - The elements `Name` and `DateOfBirth` in `PhysicalPersonType` were set from optional to mandatory because they are mandatory in [zusemsg]. This change is *not backward compatible*. - The optional element `Affix` was added to `PersonNameType` since this element was added to [zusemsg] as well. This change is *backward compatible*. - The `CorporateBodyType` was extended by the optional `Target` element that was added to [zusemsg]. This change is *backward compatible*. - The elements `FullName` and `Organization` in `CorporateBodyType` were set from optional to mandatory because they are compulsory in [zusemsg]. This change is *not backward compatible*. - The restriction from `CountryCode` was lifted. This change is *backward compatible*. - The optional attribute `type` was added to `PostalAddressType`. This change is *backward compatible*. - The optional attribute `MessengerService` was added to `TelephoneAddressType`. This change is *backward compatible*. ## Configuration 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 a different 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 to configure a parameter 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](https://git.egiz.gv.at/moa-zs/tree/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, while omitting other parameters. For parameters that are missing from the `Config` element, MOA ZS falls back to the parameter from the *referred profile*. The scope of a parameter in the `Config` element is always 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](../src/test/resources/config/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](../src/test/resources/config/application.yaml), copy, paste, and indent the template from below or copy an existing profile from [application.yaml](../src/test/resources/config/application.yaml), set a new `ProfileID` and adapt 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 do not specify a parameter in `Config`, if you do not select a `ProfileId`, or if a parameter in the selected profile is missing, MOA ZS falls back to the parameter in the `default` profile. It is recommended to specify all mandatory parameters in this default profile. Otherwise, a parameter may be unconfigured, in which case MOA ZS rejects the delivery request. ### Structure of a Delivery Request Configuration Profile in [application.yaml](../src/test/resources/config/application.yaml) The following listing shows the structure of a delivery request configuration profile and serves as a template. You find a description and examples of the individual parameters in [application.yaml](../src/test/resources/config/application.yaml). : service-timeout: perform-query-person-request: tnvz-client: url: connection-timeout: receive-timeout: ssl: ... custom-http-headers: ... msg-client: url: connection-timeout: receive-timeout: ssl: ... custom-http-headers: ... msg-response-sinks: save-response-to-file: active: path: log-response: forward-response-to-service: active: app-client: url: connection-timeout: receive-timeout: ssl: ... custom-http-headers: ... This listing shows, how a connection of a client can be protected with SSL and how client authentication can be activated: ssl: trust-all: lax-hostname-verification: key-store: filename: password: filetype: trust-store: filename: password: filetype: ### 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](../src/test/resources/config/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 the `logging.file` parameter. 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 further details. ## Namespace Declarations MOA ZS and its documentation map the following acronyms to the following namespaces: - `msg` maps to `http://reference.e-government.gv.at/namespace/zustellung/msg/phase2/20181206#`. - `mzs` maps to `http://reference.e-government.gv.at/namespace/zustellung/mzs/app2mzs#`. - Depending on the context, `p` maps to two semantically equivalent namespaces: In the `msg` context, `p` maps to `http://reference.e-government.gv.at/namespace/persondata/phase2/20181206#`, whereas in the `mzs` context, `p` maps to `http://reference.e-government.gv.at/namespace/zustellung/mzs/persondata#`. - `tnvz` maps to `http://reference.e-government.gv.at/namespace/zustellung/tnvz/phase2/20181206#`. ## References [zusemsg] Tauber, Arne: Elektronische Zustellung Message Spezifikation 2.0.0 (https://www.ref.gv.at/AG-II-Spezifkationsunterlagen.3539.0.html, 2019-04-08). [zusetnvz] Tauber, Arne and Wolf, Dieter Auer: Elektronische Zustellung Teilnehmerverzeichnis 2.0.0 (https://www.ref.gv.at/AG-II-Spezifkationsunterlagen.3539.0.html, 2019-04-08)