Ausdrücke in Prüfregel

Regeln werden in JavaScript erstellt. Der Regelcode wird zur Laufzeit von ASYS interpretiert, wobei zuvor Platzhalter für Datensatz- oder Nachrichtenfeldinhalte von der ASYS-Mittelschicht durch die jeweiligen Werte ersetzt werden. Innerhalb einer Regel können eine oder mehrere Abfragen bzw. ihre Ergebnisattribute verwendet werden, wobei ebenfalls eine Platzhalterersetzung durch die ASYS-Mittelschicht erfolgt. Der nach dieser Ersetzung ausgeführte Code muss immer true (WAHR) oder false (FALSCH) zurück liefern (bzw. das Ergebnis wird entsprechend als true oder false weiterverarbeitet).

Prinzipiell können alle Methoden und Funktionen, die JavaScript bietet, für Regeln verwendet werden. Damit allerdings nicht für jede Regel ein umfangreiches Skript geschrieben werden muss, gibt es einige Vereinfachungen sowie einige vordefinierte Funktionen, die in der Mittelschicht abgelegt sind und direkt verwendet werden können. Um diese Funktionalitäten nutzen zu können, werden dem Skriptinterpreter drei Objekte übergeben.

Der dc (Data Context) ist das Hauptobjekt für den Regelmechanismus. Er bietet alle Methoden/Funktionen, Attribute und Daten für den Zugriff auf die aktuellen Daten einer Maske oder einer Nachricht. Die vereinfachte Schreibweise für den Zugriff auf die Daten ({%Klasse.Attribut%}) wird vor der Ausführung intern in einen dc-Aufruf umgewandelt (bei Textfeldern z.B. in dc.getStringValue('Klasse.Attribut')). Relevant für den direkten Aufruf einer dc-Funktion innerhalb einer Regel ist in erster Linie die Methode dc.isNullValue('Klasse.Attribut'), über die festgestellt werden kann, ob ein Feld einen Inhalt besitzt.

Bei Masken (Aufgabenbereichen) enthält der dc die Daten der Datendarstellungsdefinition des gerade aktuell auf der Maske (Aufgabenbereichs) angezeigten Datensatzes (nicht aber die Daten von ggf. auf der Maske ebenfalls angezeigten abhängigen Datensätzen).

Bei Nachrichten enthält der dc alle Daten einer einzelnen Nachricht, die in einer 1:1-Beziehung vorliegen. Um welche Daten es sich hierbei handelt wird über den Kommunikationsbaum festgelegt.

Der sc (Session Context) stellt einige Funktionen zur Verfügung, über die insbesondere Angaben über den aktuellen Repository-Standort ermittelt werden können.

Das dco-Objekt ist nur für Nachrichten relevant. Es enthält den gesamten Dateninhalt einer einzelnen Nachricht mit allen 1:n:m-Beziehungen. Aufgrund der Komplexität dieses Objektes wird auf eine weitergehende Beschreibung verzichtet.

Eine Prüfregel ist so zu definieren, dass sie true zurückliefert, wenn die Bedingung erfüllt ist und false (also einen Fehler), wenn die Bedingung nicht erfüllt ist. Manchmal ist es jedoch einfacher, zu prüfen, ob eine Bedingung nicht erfüllt ist oder der Sprachgebrauch legt eine Umkehrung der Prüfung nahe. Aus diesem Grund kann eine Prüfregel auf inverse Logik gesetzt werden (s. Prüfregeln).

Beispiel: Die Frage 'Liegt das Eingangsdatum in der Zukunft?' hat als Antwort Ja, wenn das Datum in der Zukunft liegt. Das wäre in der BGS-Prüfung aber der Fehlerfall, der nur durch den Rückgabewert false sichtbar werden würde. Würde ein Regelcode vereinfacht formuliert also lauten 'Eingangsdatum > heute', muss das Feld inverse Logik angekreuzt werden, damit false (also ein Fehler) gemeldet wird, falls das Eingangsdatum tatsächlich in der Zukunft liegt.

Alle Attribute des aktuellen Datenkontextes können in den Prüfungen verwendet werden. Die Definitionsmaske des Administrators bietet diese Attribute zur Auswahl an. Folgende Konventionen sind dabei zu beachten:

{%BGS UNS.Abfallschluessel%}

Ein Attribut muss in geschweifte Klammern und Prozentzeichen eingefasst sein {%…%}. Zuerst wird der Klassenname und - durch einen Punkt verbunden - anschließend der Name des Attributes angegeben. Die Schreibweise des Tabellennamens und des Attributes muss exakt stimmen (also BGS UNS statt bgsuns oder Bgs Uns etc.). Äquivalent könnte auch die Schreibweise dc.getStringValue(„BGS UNS.Abfallschluessel“) verwendet werden. Hierbei ist der korrekte Datentyp zu beachten.

Am sinnvollsten wird ein Feld mit der Methode dc.isNullValue(„Klasse.Attribut“) daraufhin überprüft, ob ein Inhalt in diesem Feld vorhanden ist. Prinzipiell ist es jedoch auch möglich, die geschweifte Klammer/Prozent – Notation zu verwenden

{%Klasse.Attribut%}==null

Sofern für eine Regel nicht das Ankreuzfeld keine automatische Vorprüfung der Feldinhalte auf NULL gesetzt ist, wird vor der Ausführung der eigentlichen Regel jedes Feld, das in der Regel angegeben ist, auf einen NULL-Wert überprüft. Wenn einer der Feldinhalte NULL ist, liefert die Regel false zurück, ohne dass der Regelcode ausgeführt wurde! Verhindert werden soll mit diesem Mechanismus, dass Regeln unsinnige Werte zurückgeben.

{%*IKA STD BGS AVV gueltig.trefferzahl%} > 0

Wird eine Abfrage verwendet, muss nach dem ersten Prozentzeichen ein * folgen - also {%*…%}. Dann folgt der Name der Abfrage, ein Punkt und dann der Name des Rückgabewertes der Abfrage (einer der Einträge im Abschnitt RESULTS der Abfrage). Der Ausdruck {%*IKA STD BGS AVV gueltig.trefferzahl%} > 0 bewirkt, dass der Inhalt der Abfrage in einen SQL-Befehl an die Datenbank umgewandelt wird, der unter dem Spaltenaliasnamen trefferzahl einen numerischen Wert zurück liefert. Auch hier gilt, dass die Schreibweise exakt stimmen muss.

Die folgende Tabelle zeigt die allgemeine Syntax für den Aufbau einer Regel und einige häufig verwendete JavaScript-Funktionen.

( (Wenn 1) ? ( (Wenn 2) ? (Dann 2) : (Sonst 2) ) : (Sonst 1) )

Erläuterungen zu den Parametern in der vorstehenden Tabelle:

• Regel 1, Regel 2, Wenn, Dann, Sonst: In sich vollständige (Teil-)Regeln, die true oder false liefern.
• Wert: Ein fester Wert (z.B. 1 oder „EN“) oder das Ergebnis einer Regel.
• Feld: Meistens ein Attribut aus dem 'Data Context' oder einer Abfrage (z.B. {%BGS UNS.BGS UNS Nummer%} oder {%*IKA STD BGS vorhanden.trefferzahl%})

"eANV / XML".equals({%BGS UNS.Datenursprung Typ%})

{%BGS UNS.Datenursprung Typ%}.equals("eANV / XML") 

!dc.isNullValue("Rolle Befoerderer.Behoerdliche Nummer") && eq({%Rolle Befoerderer.Behoerdliche Nummer%},sc.blKennung())

Meist besteht der Regelcode nur aus einer Zeile (der ggf. im Fenster für den Regelcode automatisch umgebrochen wird). Es besteht aber auch die Möglichkeit, mehrzeiligen Code zu schreiben, um z.B. komplexere Fallunterscheidungen vorzusehen. Hierfür muss der Code als Codeblock gekennzeichnet werden:

[
mehrzeiliger
Codeblock
]

Der Codeblock wird durch ein Paar eckiger Klammern [ ] gekennzeichnet. Dieses Klammerpaar muss in der ersten und letzten Zeile des Regelcodes stehen. Nach der schließenden Klammer darf kein weiteres Zeichen folgen, auch kein Zeilenumbruch!

Innerhalb des Codeblocks können Variablen definiert und JavaScript-Sprachelemente verwendet werden.

Beispiel¹⁾²⁾:

[                                                                                <-Der Beginn des Codeblocks.
var nummer = {%Verantwortliche Erklaerung.Erzeugernummer%};                      <-Deklaration der Variablen 'nummer' und Zuweisung des Inhalts aus dem aktuellen Datensatz.
var ergeb = false;                                                               <-Deklaration der Variablen 'ergeb' und Initialisierung mit einem feststehenden Wert.

if (nummer == null)                                                              <-Prüfung, ob 'nummer' undefiniert ist.
  {
  ergeb = false;                                                                 <-Zuweisung eines feststehenden Wertes, wenn 'nummer' undefiniert ist.
  }
else                                                                             <-Codeteil der ausgeführt wird, wenn 'nummer' nicht undefiniert ist.
  {
   if (nummer.equals("A12345678") ||                                             <-Prüfung, ob die 'nummer' einen bestimmten Inhalt besitzt - liefert eine Fehlermeldung, wenn 'nummer' undefiniert ist.
       nummer.equals("A23456789") ||                                             <-weitere Prüfung gegen einen anderen Inhalt, die einzelnen Prüfungen sind per ODER verknüpft -> || = ODER; && = UND.
       ...
       nummer.equals("A98765432")
      )
      {
      ergeb = true;                                                              <- Zuweisung eines feststehenden Wertes, wenn eine der vorhergehenden Prüfungen ein positives Ergebnis erbracht hat.
      }
   }

return ergeb;                                                                    <- Rückgabe des Inhalts der Variablen 'ergeb' als Ergebnis des Regel-/Scriptcodes.
]                                                                                <- Ende des Codeblocks. Bitte beachten: Hier darf kein weiteres Zeichen oder ein Zeilenumbruch folgen.

Session-Context-Funktionen lassen sich mittels vorangestelltem sc. erreichen. Nach Eingabe von sc. erscheint automatisch eine Liste aller bereitstehender Funktionen jeweils mit einem Erläuterungstext. Die Liste kann auch mit Strg+Leer aufgerufen werden.

Für Data-Context-Funktionen gilt entsprechendes, nur das statt sc. ein vorangestelltes dc. einzugeben ist.

Eine Reihe von vordefinierten Funktionen können in Prüfregeln und Skripten eingesetzt werden. Eine Übersicht über diese Funktionen kann über die kontextsensitive Hilfe mittels Strg+Leer aufgerufen werden. Jeder Funktion ist ein kurzer Erläuterungstext - meist mit Beispielen - beigestellt.

Zurück zum Seitenanfang