Die vom Parser in die Quellstruktur eingefügten Daten (Quellbaum) können einer semantischen Prüfung unterzogen werden, d. h. Sie können prüfen, ob bestimmte Felder vorkommen und einen bestimmten Wert haben. Ist die Prüfung nicht erfolgreich, bricht das Profil mit einem Fehler ab.

Konfiguration

Damit der Parser diese semantische Prüfung durchführt, müssen folgende Einstellungen vorgenommen werden.

Setzen Sie die Checkbox Semantische Prüfung ausführen in Phase 2/Dokumentenart. Alternativ kann man die System-Variable VAR_SYS_ENABLE_SEMANTIC_CHECK des Typs Boolean mit dem Wert true anlegen.
Entfernen Sie den Haken bei Checkbox Unbenutzte Quellfelder ignorieren in Phase 2/Erweitert.
Zudem muss eine passende Regel-Datei gefunden werden. Siehe folgenden Abschnitt.
Benutzen Sie den normalen Daten-Mapper.

Regel-Dateien

Die Regeln für die semantische Prüfung stehen in Regel-Dateien. Beim Start des Integration Servers werden alle Dateien mit dem Namen rule_*.xml im Verzeichnis ./etc/admin/datawizard/semantic/ eingelesen. Eine Regel wird im Profil verwendet, wenn die Attribute type und format passen (siehe Beispiele).

Es gibt mehrere Möglichkeiten die Regel-Dateien zur Laufzeit anzupassen und erneut einzulesen.

Die einfachste Möglichkeit steht im Bereich Regelwerke (Verwaltung) zur Verfügung.
Sie können die Regel-Dateien auch im Datei-Explorer ändern. Damit diese auch eingelesen werden, muss die Klasse com.ebd.hub.datawizard.parser.semantic.SemanticRuleManager im Bereich Ausführung von Klassen der Admin-Konsole ausgeführt werden.
Zudem können Sie das Einlesen auch per REST API auslösen, siehe Abschnitt Regel-Dateien für Semantische Prüfung (REST API).
In einem Load-Balancing-System kann die Funktion replicate file(a,b) verwendet werden.

Möchten Sie überprüfen, ob das Einlesen funktioniert hat, können Sie das in den Server-Logs (→ internal → message.log) tun.

Beispiele

Nehmen wir an, wir haben ein Profil mit der Dokumentenart CSV und einer einfachen Quellstruktur mit einem Knoten node und darunter einem Feld field. Prinzipiell gelten die Beispiele auch für alle anderen erlaubten Formate und kompliziertere Strukturen.

Die entsprechenden Einstellungen für die semantische Prüfung sind gesetzt.

Zudem haben wir an der entsprechenden Stelle die Regel-Datei rule_CSV.xml abgelegt und eingelesen.

Dokumentenart

Alle folgenden Beispiele können auch für alle anderen Dokumentenarten übernommen werden. Erlaubte Dokumentenarten: CSV, EXCEL, FIXRECORD, DB, EDIFACT, IDOC, X12, BWA, JSON, CARGOIMP, XML. Der XML-V4-Parser wird nicht unterstützt. Eine Regel wird verwendet, wenn das Profil die Dokumentenart hat, die in Attribut format angegeben ist. Hinweis: Das Format kann überschrieben werden mit der System-Variable VAR_SYS_SEMANTIC_FORMAT.

Regel-Typ

Gibt man in einer Regel den Wert common in Attribut type an, dann greift im Profil immer diese Regel (egal wie die Einstellung im Profil ist). Gibt man statt common einen beliebigen anderen Wert ein, dann muss man im Profil im Feld Quellstruktur (oberhalb der Quellstruktur) diesen Wert angeben, damit diese Regel greift. Hinweis: Der Typ kann überschrieben werden mit der System-Variable VAR_SYS_SEMANTIC_TYPE.

Pflicht-Feldwert

rule_CSV.xml

<rules type="common" format="csv">
    <rule segment="/node">
        <value mandatory="true" field="field">somevalue</value>
    </rule>
</rules>

In der semantischen Prüfung nach dem Parsen der Eingangsdatei des Profils, wird nun überprüft, ob das Feld field mindestens einmal (mandatory=true) den Wert somevalue hat. Wenn die Prüfung stattfindet, finden Sie im Log eine Zeile ...semantic check... (Trace-Meldung für Phase 2 müssen gesetzt sein).

Hinweise:

Bitte beachten Sie, dass die Knoten (Attribut segment) in XPath-Notation angegeben werden müssen.
Sie können ein weiteres Attribut regex=true verwenden, um den Pflichtwert als regulären Ausdruck anzugeben.
Wenn hier mandatory auf false gesetzt wird, hat das keinen Effekt. Es bedeutet nicht, dass der Wert zwar nicht vorkommen muss, aber wenn er vorkommt, den definierten Wert haben muss.
Beim Format EDIFACT und X12 wird das Feld field auch in der Komponente gesucht.

Einmaliger Feldwert

Ein Feldwert kann mehrfach auftreten. Wir können prüfen, ob ein Feldwert einmalig ist und einen Fehler produzieren, wenn mehrfach der selbe Feldwert auftritt. Dazu verwenden wir das Attribut unique.

rule_CSV.xml

<rules type="common" format="csv">
    <rule segment="/node">
        <value unique="true" field="field">somevalue</value>
    </rule>
</rules>

In unserem Beispiel klapp das problemlos, da alle erzeugten Knoten den selben Eltern-Knoten haben (den Root-Knoten):

Verwenden wir aber eine etwas komplexere Quellstruktur, dann ist das nicht mehr der Fall und es gibt mehrere verschiedene Eltern-Knoten:

In diesem Fall müssen wir unsere Regel-Datei leicht anpassen (abgesehen vom anderen Knoten-Pfad) mit dem Attribut cluster=true, damit alle Eltern-Knoten zusammengefasst werden.

rule_CSV_2.xml

<rules type="common" format="csv">
    <rule segment="/node/sub">
        <value unique="true" cluster="true" field="field">somevalue</value>
    </rule>
</rules>

Erlaubte Feldwerte

Es ist auch möglich eine Liste von erlaubten Feldwerten anzulegen. Verwenden Sie dazu, wie in der folgenden Datei, das Attribut ref und das Element definition.

rule_CSV.xml

<rules type="common" format="csv">
    <rule segment="/node">
        <value ref="myref" mandatory="true" unique="true" field="field">somevalue</value>
    </rule>
    <definition id="myref">
		<value>somevalue</value>
		<value>somevalue2</value>
	</definition>
</rules>

Hier muss also der Wert somevalue vorkommen, es darf aber nur einmal vorkommen und zudem sind nur die Feldwerte somevalue und somevalue2 erlaubt. Sie können mandatory auch auf false setzen und den Wert somevalue entfernen, dann wird nur auf die erlaubten Werte geprüft.

Zudem ist eine weiter Variante möglich. Hier kann für jeden erlaubten Wert festgelegt werden, ob er Pflicht ist und es kann eine Wildcard * verwendet werden, um alle Werte zu erlauben. Im folgenden Beispiel muss der Pflichtwert somevalue1 und somevalue2 auftreten, es dürfen aber alle Werte auftreten.

rule_CSV.xml

<rules type="common" format="csv">
    <rule segment="/node">
        <value ref="myref" regex="false" unique="false" mandatory="false" field="field"></value>
    </rule>
    <definition id="myref">
		<value mandatory="true">somevalue1</value>
		<value mandatory="true">somevalue2</value>
		<value>*</value>
	</definition>
</rules>

Alternativ zur Definition der erlaubten Werte direkt in der Regel-Datei, können die erlaubten Werte auch in einer weiteren Datei ./etc/admin/datawizard/semantic/common_values.xml ausgelagert werden. Das Attribut ref in der Regel-Datei bleibt dann gleich, aber das Element definition entfällt. Die Definition der erlaubten Werte in der Regel-Datei selbst hat immer Vorrang.

common_values.xml

<allowed_values>
	<definition id="myref">
		<value>somevalue</value>
		<value>somevalue2</value>
	</definition>
</allowed_values>

Normalisierung

Knoten- und Feldnamen müssen eindeutig sein. Um das zu gewährleisten, werden Suffixe in den Namen verwendet. Nehmen wir an, unsere Quellstruktur hätte statt dem Knoten node und dem Feld field einen Knoten node-1 und ein Feld field-1, dann könnten wir dennoch die selbe Regel-Datei verwenden, wenn wir ein zusätzliches Attribut normalized=true einfügen. Hier nochmal eine entsprechende Modifikation unseres ersten Beispiels.

<rules type="common" format="csv">
    <rule segment="/node" normalized="true>
        <value mandatory="true" field="field">somevalue</value>
    </rule>
</rules>