jump to top
Online Dokumentation

Startseite / Vorlagenentwicklung / Regeln / Anbindung externer Logik <SCHEDULE/>

<SCHEDULE/> Asynchrone Regelausführung

Inhaltsverzeichnis

• Anbindung externer Logik an dynamische Formulare

• Werte ermitteln, die außerhalb des aktuellen Kontextes liegen

• Attribute

• Attribut "service"

• Attribut "id"

• Attribut "delay"

• Beispiele

• Beispiel 1) Automatische Generierung von Keywords aus dem Wert eines Eingabefelds

• Beispiel 2) Prüft die Gültigkeit einer ISBN

Anbindung externer Logik an dynamische Formulare

Mithilfe des Tags <SCHEDULE/> kann externe Logik (über einen Service) in ein dynamisches Formular eingebunden werden. Das bedeutet, die eigentliche Validierungs-Logik wird in ein FirstSpirit-Modul ausgelagert („Asynchrone Regelausführung“).

Dazu muss das zugehörige Modul vor der Regelausführung auf dem FirstSpirit-Server installiert werden.

Der <SCHEDULE/>-Abschnitt einer Regeldefinition dient der Wertermittlung über einen externen Service und ersetzt in diesem Fall den <WITH/>-Abschnitt einer herkömmlichen Regeldefinition. Der <SCHEDULE/>-Abschnitt muss vor den Tags definiert werden, die eine Handlungsanweisung einleiten.

Dabei gilt für die Definition einer Wertermittlung:

  • Für jede Regel muss eine Wertermittlung definiert werden. Das kann auf herkömmlichem Weg über einen <WITH/>-Abschnitt erfolgen oder, wenn externe Logik verwendet werden soll, über einen <SCHEDULE/>-Abschnitt.
  • Optional kann ein <CONDITION/>-Tag innerhalb eines <SCHEDULE/>-Abschnitts definiert werden.
    Das <CONDITION/>-Tag entspricht der Definition einer Vorbedingung <IF/> bei der herkömmlichen Regeldefinition. Über die Bedingung wird ein Boolescher Wert ermittelt. Ist die Bedingung erfüllt (TRUE), wird der definierte Service angefordert, im Negativfall (FALSE) nicht. Ist keine Bedingung definiert, wird der Service immer angefordert.
    Die Vorbedingung bezieht sich immer auf eine bestimmte Eigenschaft des Formularelements oder des Formulars („Wurde das Formular in der Inhalte-Verwaltung geöffnet?“). Dazu ist die Angabe eines <PROPERTY/>-Tags innerhalb des <CONDITION/>-Abschnitts notwendig. Über die folgenden Ausdrücke können weitere Werte abgeleitet werden. So kann der Wert der Eingabekomponente beispielsweise gegen bestimmte reguläre Ausdrücke oder gegen einen Vergleichswert geprüft werden:
  • Wird die Wertermittlung vom SiteArchitect auf ein FirstSpirit-Modul übertragen, können innerhalb eines <SCHEDULE/>-Abschnitts Parameter und Werte an die externe Logik übergeben werden, beispielsweise der aktuelle Werte aus einer Eingabekomponente des Formulars. Innerhalb eines <PARAM/>-Tags ist dazu mindestens die Angabe eines <PROPERTY/>-Tags und ggf. weiterer Tags notwendig.
  • In einem <SCHEDULE/>-Tag können drei Attribute übergeben werden:
    • über das Pflicht-Attribut service wird der Name einer externen Klasse angegeben,
    • über das Pflicht-Attribut id wird ein freiwählbarer Identifier angegeben,
    • über das optionale Attribut delay kann eine Verzögerung für die Ausführung des übergebenen Services definiert werden, z. B.:<SCHEDULE service="Keywords" id="x" delay="500">

Für die Implementierung der externen Logik gilt:

  • Über jedes <SCHEDULE/>-Tag kann immer nur eine einzelne Komponente des Moduls vom Typ „Public“ referenziert werden.
  • Für die Implementierung eines Services muss das Interface ValueService implementiert werden: public class MyValueService implements ValueService {...}
  • Der Rückgabewert (also der Objekttyp) der ValueService.getValue()-Implementierung sollte zur gewünschten (Ziel-)Eingabekomponente passen.
  • Die Übergabeparameter (siehe <PARAM/>) sind immer vom Typ Object und müssen in der Implementierung entsprechend gecasted werden.
  • Innerhalb einer ValueService-Implementierung können Werte aus FirstSpirit-Eingabekomponenten verwendet werden. Unterstützt wird diese Funktionalität für die Eingabekomponenten:
  • Ab der FirstSpirit-Version Verfügbar ab FirstSpirit-Version 2024.8 können auch Werte komplexer Eingabekomponenten (z. B. FS_DATASET, FS_REFERENCE) innerhalb einer ValueService-Implementierung verwendet werden.

Wichtig Externe Services sind im Rahmen der Regelauswertung (im <SCHEDULE/>-Abschnitt) nur verfügbar, wenn ein Formular interaktiv von einem Redakteur bearbeitet wird.
Diese Regeln greifen nicht, wenn Operationen zum Lesen, Speichern oder Freigeben per API ausgeführt werden, z. B. in Executables oder Beanshell-Skripten.
Validierungen mit den Restriktionsstufen scope="RELEASE" bzw. scope="SAVE" in Verbindung mit <SCHEDULE/> eignen sich damit ausschließlich für redaktionelle Aufgaben (ähnlich wie die Eigenschaft EDITABLE) und nicht dazu, die Gültigkeit von Inhalten technisch sicherzustellen.

Werte ermitteln, die außerhalb des aktuellen Kontextes liegen

Neben Werten, die im aktuellen Kontext einer Regelausführung verfügbar sind, die also das aktuelle Formular bzw. FirstSpirit-Element betreffen, in dem die Regel ausgeführt wird, kann auch auf FirstSpirit-Elemente zugegriffen werden, die außerhalb des aktuellen Kontextes liegen.

Damit können Informationen aus anderen Formularen, z. B.:

  • Formulardaten aus einer anderen Seite,
  • aus Metadaten-Formularen oder
  • aus den Projekteinstellungen

geholt werden.

Diese Wertermittlung wird über das <SCHEDULE/>-Tag mithilfe der Dienste FormDataValueService oder MetaDataValueService ausgeführt:
Dokumentation und Beispiele siehe Auf Informationen aus anderen Formularen zugreifen.

Attribute

Attribut "service"

Über das Attribut „service“ kann eine einzelne Public-Komponente des Moduls referenziert werden.
Übergeben wird hier der Name der Public-Komponente, der unter <name> im Komponenten-Modul-Deskriptor definiert wird, hier <SCHEDULE service='Keywords'.../>:

...
<components>
 <public>
 <name>Keywords</name>
 <class>mypackage.Keywords</class>
 </public>
</components>
...

Attribut "id"

Über das Attribut „id“ kann ein Identifier vergeben werden. Wird die Public-Komponente innerhalb der Regeldefinition mehrfach referenziert, können über die Vergabe unterschiedlicher Identifier in den <SCHEDULE/>-Abschnitten „gleichartige“ Calls vermieden werden.

Wird also (abhängig von der Regeldefinition) z. B. der Service „Keywords“ gestartet und ist in der aktuellen Benutzer-Sitzung bereits ein Service mit der angegebenen Servicename-ID-Kombination aktiv, wird der bestehende Serviceaufruf abgebrochen.

<RULE>
 <SCHEDULE service="Keywords" id="k1" delay="500">
 ...
 </SCHEDULE>
 <DO>
 ...
 </DO>
</RULE>

<RULE>
 <SCHEDULE service="Keywords" id="k2" delay="500">
 ...
 </SCHEDULE>
 <DO>
 ...
 </DO>
</RULE>

Attribut "delay"

Über das optionale Attribut „delay“ kann eine Wartezeit in Millisekunden festgelegt werden. Ohne Angabe eines Wertes wird immer „0“ als Wert angenommen. Ist ein Wert größer „0“ angegeben, wird die Ausführung des eigentlichen Dienstaufrufs um die entsprechende Zeit verzögert.

Hintergrund: Innerhalb eines <SCHEDULE/>-Abschnitts wird externe Logik eingebunden, die beispielsweise die Werte einer FirstSpirit-Eingabekomponente ausliest, verarbeitet und eine zweite Eingabekomponente füllt. So kann beispielsweise nach der Eingabe von „Ort“ und „Straße“ in einem Formular automatisch das Feld „Postleitzahl“ gefüllt werden. Kommt der externe Call zurück, nachdem sich eines der betroffenen Felder wieder geändert hat (z. B. weil ein Tippfehler im Feld „Ort“ mittlerweile korrigiert wurde), muss das gelieferte Ergebnis wieder verworfen werden. Dieses Verhalten ist in vielen Fällen nicht erwünscht, da der externe Call potentiell zeit- und ressourcenintensiv ist. Ein Aufruf bei jedem Tastendruck des Redakteurs sollte durch die Angabe des Attributs „delay“ unterbunden werden.

Wichtig Bei komplexeren Abfragen oder einer sehr umfangreichen Regeldefinition kann es außerdem sinnvoll sein, eine Vorbedingung mittels eines <CONDITION/>-Tags zu definieren.

Beispiele

Beispiel 1) Automatische Generierung von Keywords aus dem Wert eines Eingabefelds

In einem Formular gibt es je ein Eingabefeld für die Eingabe von redaktionellen Inhalten („st_text“) und ein weiteres Feld zur Eingabe von Schlüsselwörtern („st_keywords“). Über ein dynamisches Formular soll nun sichergestellt werden, dass die Inhalte, die vom Redakteur in das erste Feld eingetragen werden, automatisch als Schlüsselworte in das zweite Eingabefeld übernommen werden. Die externe Logik dazu wird in ein Modul ausgelagert, das zunächst auf dem FirstSpirit-Server installiert werden muss: FirstSpirit ValueService (Example) (Version 0.1)

Innerhalb der Regeldefinition wird dann ein <SCHEDULE/>-Abschnitt mit den folgenden Attributen definiert:

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            ...
        </SCHEDULE>
    </RULE>
</RULES>

Über diese Syntax wird der Dienst „Keyword service“ unter der ID „x“ mit einer Verzögerung von 500 ms angefordert. Der Dienst soll jedoch nicht ständig angefordert werden, sondern nur, wenn der Redakteur Werte im Eingabefeld „st_text“ hinterlegt. Die Regeldefinition wird daher innerhalb des <SCHEDULE/>-Abschnitts um eine Bedingung (<CONDITION/>) ergänzt:

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            ...
        </SCHEDULE>
    </RULE>
</RULES>

Der Dienst „Keyword service“ wird jetzt nur noch angefordert, wenn die Komponente „st_text“ vom Redakteur im Formular fokussiert wird.

Im nächsten Schritt sollen die Inhalte aus der Komponente „st_text“ ausgelesen werden. In diesem Fall müssen die Werte an die externe Logik (also den Dienst) übermittelt werden. Dazu erfolgt innerhalb des <SCHEDULE/>-Abschnitts (und ggf. unterhalb der <CONDITION/>) eine Parameterübergabe mittels eines oder mehrerer <PARAM/>-Tags. Über das Attribut „name“ wird der Parametername definiert. Die Wertermittlung erfolgt dann wie gewohnt über ein <PROPERTY/>-Tag innerhalb des <PARAM/>-Abschnitts. In diesem Beispiel wird der aktuelle Inhalt der Eingabekomponente „st_text“ und die Redaktionssprache, in der das Formular aktuell bearbeitet wird, übergeben:

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            <PARAM name="text">
                <PROPERTY source="st_text" name="VALUE"/>
            </PARAM>
            <PARAM name="lang">
                <PROPERTY source="#global" name="LANG"/>
            </PARAM>
        </SCHEDULE>
    </RULE>
</RULES>

Die Parameter-Wert-Paare „text“ und „lang“ werden an den Service übermittelt und dort weiterverarbeitet (Einstiegspunkt für die Implementierung eines ValueServices siehe FirstSpirit-Access-API: ValueService), z. B.:

...
public Object getValue(final SpecialistsBroker broker, final Map<String, ?> parameters) {
	    final Locale locale;		
	    final Object lang = parameters.get("lang");
	    ...
}
...

Der <DO/>-Abschnitt der Regel wird nach der Ausführung des Dienstes mit dem dort ermittelten Rückgabewert ausgeführt. Im Beispiel sollen die ermittelten Rückgabewerte in die Komponente „st_keywords“ übernommen werden. 

<RULES>

    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            <PARAM name="text">
                <PROPERTY source="st_text" name="VALUE"/>
            </PARAM>
            <PARAM name="lang">
                <PROPERTY source="#global" name="LANG"/>
            </PARAM>
        </SCHEDULE>
        <DO>
            <PROPERTY source="st_keywords" name="VALUE"/>
        </DO>
    </RULE>

</RULES>

Beispiel 2) Prüft die Gültigkeit einer ISBN

In einem Formular gibt es ein Text-Eingabefeld für die Eingabe einer ISBN-Nummer („cs_isbn13“). Über ein dynamisches Formular soll nun sichergestellt werden, dass der Wert der Eingabekomponente beim Bearbeiten geprüft wird. Diese Prüfung wird über den externen Dienst „ISBN13VerificationService“ ausgeführt:

<RULE> 
    <SCHEDULE service="ISBN13VerificationService" id="isbn13" delay="0"> 
        <PARAM name="value"> 
            <PROPERTY source="cs_isbn13" name="VALUE"/> 
        </PARAM> 
    </SCHEDULE> 
    <DO> 
        <VALIDATION> 
            <PROPERTY source="cs_isbn13" name="VALID"/> 
            <MESSAGE lang="*" text="Es muss eine gültige ISBN-13-Nummer angegeben werden!"/> 
        </VALIDATION> 
    </DO> 
</RULE>

Die ValueService.getValue()-Implementierung prüft die Nummer und liefert einen Booleschen Wert zurück. 

public Boolean getValue(final SpecialistsBroker broker, final Map<String, ?> parameters) { 
    final Object value = parameters.get("value"); 
    if (value instanceof String) { 
        log("Performing ISBN-13 verification..."); 
        return isValidISBN13((String) value); 
    } 
    return false; 
}

Der zurückgelieferte Wert wird anschließend im <VALIDATION/>-Abschnitt der Regel ausgewertet.

Druckversion | Seitenanfang

© 2005 - 2024 Crownpeak Technology GmbH | Alle Rechte vorbehalten. | FirstSpirit 2024.13 | Datenschutz