Inhalt

Mit dem XNachricht Plugin für formcycle haben Sie die Möglichkeit, automatisiert standardisierte Nachrichten aus erfassten Formulardaten zu bilden. Das Datenformat ist XÖV.

Installation

Die Installation kann als Mandantplugin oder Systemplugin erfolgen:

• Anmeldung am Mandanten oder System in formcycle.
• Navigieren Sie zum Menüpunkt Plugins und öffnen Sie den Plugin-Store.
• Suchen Sie nun nach XNachricht und installieren Sie das Plugin.
• Jetzt steht Ihnen eine neue Workflow-Aktion Nachricht erstellen zur Verfügung.

Verwendung

Die Workflow-Aktion erwartet die Auswahl eines Nachrichtentyps. 

Der initiale Release des Plugins unterstützt ausschließlich den Standard XPersonenstand in der Version 1.7.8. Folgend sind die initial unterstützten Nachrichtentypen aufgelistet:

portal2StA.Geburt.081010

• Mit dieser Nachricht können die Angaben zu einer Geburt im Rahmen einer elektronischen Voranzeige
  dem Standesamt übermittelt werden.

portal2StA.Ehe.082020

• Mit dieser Nachricht können die Angaben zur Anmeldung einer Eheschließung im Rahmen einer elektronischen Voranmeldung dem Standesamt übermittelt werden.

portal2StA.Sterbefall.084010

• Mit dieser Nachricht können die Angaben zu einem Sterbefall im Rahmen einer elektronischen Voranzeige dem Standesamt übermittelt werden.

Kindelemente der ausgewählten Nachricht

Sobald Sie den Nachrichtentyp ausgewählt haben, füllt sich dieser Bereich mit Eingabemöglichkeiten. Sie können diese Ansicht in einem Dialog öffnen. Der Nachrichtentyp stellt das erste und grundlegende Element einer Nachricht dar. Jedes weitere Element ist ein Kind dessen.

Die Tabelle hat 2 Spalten:

1. Name: der Name des Elements entspricht dem Namen in der Spezifikation bzw. dem Standard.
2. Wert: der Wert des Elements kann fest hinterlegt werden (siehe Zeile mit produkt) oder kann per Platzhalter bei der Ausführung des Workflows aus den Formulardaten ermittelt werden (siehe Zeile mit geburtstag).

Eine Zeile mit einem fett geschriebenen Namen und einem Stern/Asterisk ist ein Pflichtfeld.

Ein groß geschriebener Name deutet auf fixed Werte hin, diese werden gleich aus dem Standard übernommen.

Datentyp des Wertes

Der Wert eines Elements muss einem bestimmten Datentyp entsprechen. Welcher Datentyp erwartet wird ist anhand des Symbols rechts vom Namen erkennbar.

• Zeichenkette (String)

            Eine Zeichenkette entspricht einer regulären Texteingabe eines Eingabefeldes mit dem Datentyp Text.

• Zahl (BigInteger)

            Eine Zahl entspricht einer regulären Texteingabe eines Eingabefeldes mit dem Datentyp (positive) Ganzzahl.

• Boolscher Wert (Boolean)
  

            Eine Eingabe von true oder on führt zu der Übermittlung von true.

• Datum (XMLGregorianCalendar)

            Ein Datum muss einem unterstützen Pattern entsprechen um bei der Ausführung korrekt eingelesen zu werden. 

• Code

            Setzt sich aus dem ausgewähltem Code (String) sowie automatisch ermittelten Metadaten zur Codeliste zusammen.

Datum als Wert

Das XNachricht-Plugin unterstützt initial folgende Datum Pattern:

yyyy

• Ausschließlich Angabe des Jahres mit vier Stellen. 
• Relevant für die Angabe von teilbekanntesDatum - jahr.

MM.yyyy

• Angabe des Monats mit zwei Stellen gefolgt vom Jahr wie zuvor. 
• Relevant für die Angabe von teilbekanntesDatum - jahrMonat.

dd.MM.yyyy

• Reguläres Datum bestehend aus Tag, Monat und Jahr. 
• Das Pattern entspricht einem Eingabefeld mit dem Datentyp Datum (TT.MM.YYYY).

dd.MM.yyyy HH:mm:ss Z

• Datum mit Uhrzeit. Dies ist für die Angabe vom erstellungszeitpunkt notwendig. Dafür sollte der Systemplatzhalter für das Datum verwendet werden und das entsprechende Pattern hinterlegt werden: 
  • [%$DATE("dd.MM.yyyy HH:mm:ss Z")%] .

Code als Wert

Für die Angabe eines Codes ermittelt formcycle automatisch die notwendige Codeliste. Sie haben die Möglichkeit Text einzugeben und Ihnen werden Vorschläge gemacht (autocomplete). Sie können auch Platzhalter einfügen, bitte beachten Sie hierbei am entsprechenden Auswahlelement die korrekte Datenquelle auszuwählen.

Zum initialen Release des Plugins werden folgende Codelisten unterstützt:

Geschlechtsangaben in XInneres 

• urn:xoev-de:xinneres:codeliste:geschlecht
• Element mit dem Namen geschlecht

Kommunikationskanal / Erreichbarkeit

• urn:de:xoev:codeliste:erreichbarkeit
• Element mit dem Namen kanal

Präfixe im DVDV 

• urn:xoev-de:bund:bmi:bit:codeliste:dvdv.praefix
• Element mit dem Namen praefix

DVDV Behördenschlüssel der Bundesbehörden 

• urn:xoev-de:bund:bmi:bit:codeliste:dvdv.behoerdenschluessel
• Element mit dem Namen kennung

Nachrichtentypen in XInneres 

• urn:de:xinneres:codeliste:nachrichtentyp
• Element mit dem Namen nachrichtentyp

Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes

• urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staat
• Element mit dem Namen staat

Staatsangehörigkeit aus der Staats- und Gebietssystematik des Statistischen Bundesamtes

• urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staatsangehoerigkeit
• Element mit dem Namen staatsangehoerigkeit

Gemeinden, dargestellt durch den Amtlichen Gemeindeschlüssel (AGS) des Statistischen Bundesamtes

• urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:ags
• Elemente mit dem Namen ags

Die Version der Codeliste richtet sich nach der Version des verwendeten Standards. Dies ist somit initial ausschließlich XPersonenstand 1.7.8. Weitere Informationen dazu finden Sie auch im XRepository unter Inhalte > Codelisten.

Sonderfälle

In manchen Fällen erlaubt der Standard die Angabe von Werten welche nicht in der Codeliste enthalten ist:

Die Spalte mit dem Namen code erlaubt die Angabe von einem staat aus der Codeliste Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes. Ein eigener Wert kann in die Spalte mit dem Namen nichtGelisteterWert eingetragen werden. 

Im Formular-Designer entspricht dies einem Auswahlelement mit den Staaten sowie einem Eingabefeld:

Eine Checkbox erlaubt das umschalten von Auswahlelement zu Eingabefeld. Bitte beachten Sie, dass das Element beim sperren außerdem auch geleert werden sollte.

Wiederholungen von Elementen

Elemente einer Nachricht können mehrere Werte darstellen, sie können wiederholt werden. Dies ist erkennbar an den zwei Symbolen rechts des Namen:

In diesem Beispiel kann das Element kontaktdaten sowie dessen Kindelemente kanal, kennung und zusatz wiederholt werden. Im Formular-Designer könnte das wie folgend dargestellt werden:

In dem Beispiel bildet kontaktdaten einen wiederholten Container. In diesem sind das Auswahlelement kanal, mit der Datenquelle Kommunikationskanal / Erreichbarkeit, und das Eingabefeld kennung.

Sonderfälle

Diverse Nachrichten können ineinander verschachtelte wiederholte Elemente haben. Dies ist zum Beispiel der Fall bei portal2StA.Ehe.082020:

Dem Bild können Sie entnehmen, dass sowohl das Element angabenEheschließende als auch dessen Kindelemente staatsangehoerigkeit sowie kontaktdaten wiederholt sein können.

Der Formular-Designer erlaubt keine wiederholten Elemente innerhalb von wiederholten Containern. Die Funktionen des Plugins Geschachtelte Wiederholungen sind nicht mit diesem Plugin kompatibel.

Für die Abbildung dieser Szenarien sind die Buttons rechts des Namens eines wiederholten Elements zu verwenden. Dem Standard der Nachricht kann entnommen werden, dass das Element angabenEheschließende genau zweimal erwartet wird. Also wird eine Kopie dieses Elementes angelegt. 

Das Element staatsangehörigkeit kann nun ein reguläres wiederholtes Textfeld sein. Das Element kontaktdaten kann wie zuvor beschrieben eingepflegt werden.

Rückgabewerte der Workflow-Aktion

Die Aktion hat beim initialen Release keine Rückgabewerte. Ausschließlich die generierte Nachricht kann in weiteren Workflow-Aktionen verwendet werden.

Fehlercodes der Workflow-Aktion

TRANSFORM_DATE_EXCEPTION

• Fehlercode, wenn die Transformierung eines Datums fehlgeschlagen ist. Die aktuell unterstützen Datum Pattern sind im Abschnitt Datum als Wert erläutert. Das Datum, bei dem die Transformierung versucht wurde, wird ausgegeben.

DATA_DESERIALIZER_EXCEPTION

• Fehlercode, wenn die Deserialisierung der Kindelemente der Nachricht fehlgeschlagen ist.

MSG_OBJECT_EXCEPTION

• Fehlercode, wenn die Erstellung des Nachrichtenobjekts fehlgeschlagen ist.

FILE_EXCEPTION

• Fehlercode, wenn die Nachricht bzw. Datei nicht in das Dateisystem geschrieben werden kann.

MSG_VALIDATE_EXCEPTION

• Weicher Fehlercode, wenn die Nachricht nicht dem entsprechenden Schema entspricht. Dennoch wurde die Nachricht bzw. Datei erstellt und eine Weiterverarbeitung ist gesichert. Die fehlerhaften Stellen werden aufgelistet ausgegeben.

Generierung der Nachricht/Datei

Bei erfolgreicher Ausführung der Workflow-Aktion wird eine Nachricht bzw. Datei generiert. Dieser können Sie einen eigenen Namen geben und in folgenden Workflow-Aktionen verwenden.

Die generierte Nachricht ist im Format einer XML-Datei. Eine Dateiendung muss nicht explizit angegeben werden.