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

The sender application sends a mzs:DeliveryRequest (specified in 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). 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).
The delivery service sends delivery notifications and status updates to MOA ZS via the 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).

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. If you want to switch to a different configuration format, you may consult Spring Boot Documentation: Externalized Configuration. 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:

You can set a parameter directly in a mzs:DeliveryRequest under the Config element. See 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.
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, paste, and indent the template from below or copy an existing profile from 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.
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

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.

<ProfileID-string>:

  service-timeout: <integer>

  perform-query-person-request: <boolean>

  tnvz-client:
    url: <string>
    connection-timeout: <integer>
    receive-timeout: <integer>
    ssl: ...
    custom-http-headers: ...

  msg-client:
    url: <string>
    connection-timeout: <integer>
    receive-timeout: <integer>
    ssl: ...
    custom-http-headers: ...

  msg-response-sinks:
    save-response-to-file:
      active: <boolean>
      path: <string>
    log-response: <boolean>
    forward-response-to-service:
      active: <boolean>
      app-client:
        url: <string>
        connection-timeout: <integer>
        receive-timeout: <integer>
        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: <boolean>
  lax-hostname-verification: <boolean>
  keystore:
    filename: <string>
    password: <string>
    filetype: <string>
  truststore:
    filename: <string>
    password: <string>
    filetype: <string>

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 the logging.file parameter. You can specify the logging format in logback.xml. See Spring Boot Documentation: Logging for further details.

MOA ZS Service Documentation

MOA ZS implements two services: the app2mzs.wsdl service, which accepts delivery requests from a sender, and the zuse2app_p2.wsdl service, which accepts notifications and request status updates from a delivery service. The file app2mzs.xsd documents the data structure and the parameters of the app2mzs.wsdl service. In order to get a complete overview, you might also review related schema files in the resources folder.

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)