# MOA ZS - Specification This document gives an overview on what MOA ZS does, on how it can be configured and on which input- and output data MOA ZS processes. ## 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. ## 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. ## MOA ZS Service Documentation MOA ZS implements two services: the [app2mzs.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/mzs/app2mzs.wsdl) service, which accepts delivery requests from a sender, and the [zuse2app_p2.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/zusemsg/zuse2app_p2.wsdl) service, which accepts notifications and request status updates from a delivery service. The file [app2mzs.xsd](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/mzs/app2mzs.xsd) documents the data structure and the parameters of the [app2mzs.wsdl](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/mzs/app2mzs.wsdl) service. In order to get a complete overview, you might also review related schema files in the [resources folder](https://git.egiz.gv.at/moa-zs/tree/src/main/resources/). ### Namespaces 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)