Filterausdrücke

Filterausdrücke werden in unserer Software verwendet um Filter für Daten zu konfigurieren. Es handelt sich dabei um eine auf XML basierende Filtersprache welche in diesem Kapitel beschrieben wird. Die Felder und Datentypen welche für den jeweiligen Anwendungszweck verfügbar sind findest du dabei in der Dokumentation der jeweiligen Konfiguration.

Später in diesem Kapitel werden auch noch Objektzuordnungen beschrieben, einer speziellen Form von Filterausdrücken. In diesen Dokumenten werden Filter mit Objektnamen und Objektgruppen verknüpft, damit lassen sich einzelne Objekte und Objektgruppen logischer benennen.

Einführung

Diese kurze Einführung gibt dir einen Überblick wie Filterausdrücke üblicherweise in einer Konfiguration verwendet werden.

Ein Filterausdruck als Konfigurationswert

In dem ersten Beispiel geht es um eine Software welche die Sessions von angemeldeten Benutzern anzeigt. Die Software verwendet unser Konfigurationssystem. Du möchtest in dieser Software einen Filter setzen, damit nur Sessions mit der ID null oder die des Benutzers example angezeigt werden.

Einfache Filter kannst du dabei direkt in die Konfiguration schreiben. Das folgenden Beispiel zeigt den gewünschten Filterausdruck direkt in die Konfiguration eingebettet:

<Module name="Example">
    ...
    <Value name="SessionFilter"><![CDATA[
        <Or>
            <NumberValue name="sessionId">
                <Equals>0</Equals>
            </NumberValue>
            <Value name="userName">
                <StartsWith>example</StartsWith>
            </Value>
        </Or>
    ]]></Value>
    ...
</Module>

Wichtig ist dabei, dass du den Filterausdruck in die Klammern <![CDATA[ und ]]> einschliesst. Diese Klammern machen es einfach den ganzen Filterausdruck als Text einzufügen. Vergisst du die Klammern, werden die XML Elemente als Teil der Konfiguration interpretiert.

Der Filterausdruck in einer separated Datei

Komplexere Filter schreibst du am besten in eine separate XML-Datei. In der Konfiguration fügst du dann einen absoluten Pfad zu der Datei ein.

Grundsätzlich ist der Inhalt der Datei identisch zu dem Filterausdruck den du direkt in die Konfiguration einfügst. Es kommen einfach die üblichen XML Elemente mit dem Schema und ein Filter Dokument-Element hinzu.

Das folgende Beispiel zeigt den Filter aus dem vorigen Beispiel als separate Datei:

<?xml version="1.0" encoding="utf-8" ?>
<Filter
    version="1"
    xmlns="http://educateit.ch/software/FilterLanguage/1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Or>
        <NumberValue name="sessionId">
            <Equals>0</Equals>
        </NumberValue>
        <Value name="userName">
            <StartsWith>example</StartsWith>
        </Value>
    </Or>
</Filter>

Die Datei fängt mit dem xml Block mit der Version und der Dateikodierung an. Danach folgt das Dokument-Element Filter mit einer Version und dem korrekten Schema. In diesem Dokument-Element ist dann der eigentliche Filterausdruck eingebettet.

Innerhalb des Dokument-Elements Filter darf nur genau ein einzelnes Element definiert werden, genau wie das bei einem eingebetteten Ausdruck der Fall ist. Du solltest also beispielweise ein And oder Or Element einfügen, wenn du mehrere Tests verwenden möchtest.

In der Konfiguration fügst du einen Absoluten Pfad zu dieser Datei ein:

<Module name="Example">
    ...
    <Value name="SessionFilter">E:/SessionApplication/example-filter.xml</Value>
    ...
</Module>

Selbstverständlich kannst du dabei mit dem Platzhaltern der Konfiguration arbeiten. Falls du den Filter direkt im Verzeichnis der Anwendung platzierst, konfigurierst du dies wie in dem folgenden Beispiel gezeigt:

<Module name="Example">
    ...
    <Value name="SessionFilter">●applicationDirectory●/example-filter.xml</Value>
    ...
</Module>

Grundlagen

Jeder Filter prüft einen oder mehrere Werte mit einem Test. Die geprüften Werte können dabei unterschiedliche Typen haben. Für diese unterschiedlichen Typen benötigst du die passenden Operatoren.

Aktuell werden die folgenden drei Typen unterstützt:

• Textwerte

• Zahlenwerte

• Datum- und Zeitwerte

Mehrere Tests kannst du ein einer booleschen Operation kombinieren. Es stehen dir dabei die folgenden booleschen Operationen zur Verfügung:

• OR

• NOR

• AND

• NAND

• NOT

Wenn alle Tests in einem Filter erfolgreich sind, schreiben wir in dieser Anleitung, dass der Filter auf die Daten passt. Was dies bedeutet, hängt von der Anwendung und der Konfiguration ab.

Es kann sein, das passende Daten entfernt werden oder das nur die passenden Daten behalten werden. Die genauen Details dazu findest du in der jeweiligen Beschreibung des Konfigurationswerts.

Testen eines einzelnen Werts

Das folgende minimale Beispiel zeigt wie ein einzelner Wert getestet wird:

<Value name="userName">
    <Matches>administrator</Matches>
</Value>

In der ersten Zeile wählen wir mit dem Value Element, welcher Wert getestet wird. In diesem Fall ist das der Wert userName. In unserem Beispiel handelt es sich bei diesem Wert um einen Textwert. Alles was durch das Value Element eingeschlossen wird bezieht sich auf den angegebenen Wert.

In der zweiten Zeile testen wir mit dem Matches Operator, ob der Text in dem Wert userName exakt dem Text administrator entspricht.

Der ganze Ausdruck und hiermit der Filter, passt also nur wenn der getestete Datensatz im Wert userName exakt den Text administrator enthält.

Kombinieren mehrerer Tests für einem Wert

In dem folgenden Beispiel kombinieren wir mehrere Tests innerhalb des Value Elements:

<Value name="userName">
    <Or>
        <Matches>administrator</Matches>
        <Matches>guest</Matches>
    </Or>
</Value>

In der zweiten Zeile verwenden wir die boolesche Operation Or. Damit testen wir, ob der Wert userName exakt dem Text administrator oder guest entspricht.

Das folgende Beispiel kombiniert zwei Tests mit der booleschen Operation And:

<Value name="userName">
    <And>
        <StartsWith>aa</StartsWith>
        <EndsWith>zz</EndsWith>
    </And>
</Value>

Hier testen wir, ob der Wert userName sowohl mit dem Text aa beginnt und mit dem Text zz endet. Es würde beispielsweise der Text aa200zz auf den Filter passen, aber nicht aa200yy oder bb200zz.

Das nächste Beispiel zeigt wie du einen Test mit dem Not Operator negieren kannst:

<Value name="userName">
    <Not>
        <Matches>administrator</Matches>
    </Not>
</Value>

Dieser Filter passt auf alle Datenelemente welche im Wert userName nicht exakt den Text administrator haben.

Du kannst dabei alle Operatoren frei kombinieren und damit beliebig komplexe tests erstellen. Das folgende Beispiel zeigt einen umfangreicheren Test eines Werts:

<Value name="userName">
    <And>
        <StartsWith>aa</StartsWith>
        <Or>
            <EndsWith>zz</EndsWith>
            <EndsWith>yy</EndsWith>
            <EndsWith>xx</EndsWith>
        </Or>
        <Not>
            <Matches>aabbccxx</Matches>
        </Not>
    </And>
</Value>

Der Filter in dem Beispiel oben testet ob der Wert userName mit dem Wert aa beginnt, und entweder mit zz, yy oder xx endet, und nicht exakt aabbccxx ist.

Kombinieren mehrerer Tests für verschiedene Werte

Du kannst auch die Tests für mehrere Werte mit den gleichen booleschen Operationen kombinieren. Das folgenden Beispiel kombiniert die tests zweier Werte mit dem And Operator:

<And>
    <Value name="userName">
        <Matches>administrator</Matches>
    </Value>
    <NumberValue name="sessionId">
        <Equals>0</Equals>
    </NumberValue>
</And>

Der Filter startet in der ersten Zeile mit dem booleschen Operator And. Dieser enthält den Test für den Textwert userName und dem Zahlenwert sessionId.

Dieser Filter passt auf Datensätze deren Wert userName exakt dem Text administrator entspricht und deren Wert sessionId der Zahl Null. In diesem Beispiel siehst du auch, wie du für verschiedene Werttypen andere Operatoren verwenden musst.

Den Möglichkeiten solcher Filterausdrücke sind keine Grenzen gesetzt. Das folgenden Beispiel zeigt einen komplexen Filter der verschiedenste Tests kombiniert:

<Or>
    <And>
        <Value name="userName">
            <And>
                <StartsWith>aa</StartsWith>
                <Or>
                    <EndsWith>zz</EndsWith>
                    <EndsWith>yy</EndsWith>
                    <EndsWith>xx</EndsWith>
                </Or>
                <Not>
                    <Matches>aabbccxx</Matches>
                </Not>
            </And>
        </Value>
        <NumberValue name="sessionId">
            <Or>
                <Equals>0</Equals>
                <And>
                    <GreaterThan>50</GreaterThan>
                    <LessOrEqualThan>80</LessOrEqualThan>
                </And>
            </Or>
        </NumberValue>
    </And>
    <And>
        <DateTimeValue name="start" precision="Day">
            <Before>now-5days</Before>
        </DateTimeValue>
    </And>
</Or>

Solch grosse Filterausdrücke, wie in dem letzten Beispiel gezeigt, solltest du besser in eine separate Datei schreiben und nicht direkt in die Konfiguration einfügen.

Filter Elemente

Die folgende Tabelle listet alle möglichen Elemente welche in einem Filterausdruck vorkommen können.

↓ Alles anzeigen ↓

Name	C	T	Beschreibung
Filter	1		Das Dokument Element welches den kompletten Filterausdruck in einem XML Dokument einschliesst.
Value	1		Testet einen Textwert.
NumberValue	1		Testet einen Zahlenwert.
DateTimeValue	1		Testet ein Datum/Zeit-Wert.
And	+		Schliesst mehrere Tests ein für eine logische AND Verknüpfung.
Nand	+		Schliesst mehrere Tests ein für eine logische NAND Verknüpfung.
Or	+		Schliesst mehrere Tests ein für eine logische OR Verknüpfung.
Nor	+		Schliesst mehrere Tests ein für eine logische NOR Verknüpfung.
Not	1		Negiert das Resultat eines Tests.
Matches		T	Testet ob ein Text exakt dem angegeben entspricht.
Contains		T	Testet ob der Text den angegebenen enthält.
StartsWith		T	Testet ob ein Text mit dem angegeben beginnt.
EndsWith		T	Testet ob ein Text mit dem angegeben ended.
MatchesRegularExpression		T	Testet ob ein Text auf den angegeben Regulären Ausdruck passt.
Equals		Z	Testet ob eine Zahl exakt der angegeben entspricht.
LessThan		Z	Testet ob eine Zahl kleiner als die angegebene ist.
LessOrEqualThan		Z	Testet ob eine Zahl kleiner oder gleich die angegebene ist.
GreaterThan		Z	Testet ob eine Zahl grösser als die angegebene ist.
GreaterOrEqualThan		Z	Testet ob eine Zahl grösser oder gleich die angegebene ist.
Exactly		D	Testet ob ein Datum/Zeit-Wert exakt dem angegeben entspricht.
Before		D	Testet ob ein Datum/Zeit-Wert vor dem angegeben liegt.
BeforeOrExactly		D	Testet ob ein Datum/Zeit-Wert vor dem angegeben liegt oder exakt diesem entspricht.
After		D	Testet ob ein Datum/Zeit-Wert nach dem angegeben liegt.
AfterOrExactly		D	Testet ob ein Datum/Zeit-Wert nach dem angegeben liegt oder exakt diesem entspricht.

Die Spalte „C“ zeigt dir, wie viele Kind-Elemente in dem Element enthalten sein können:

• Leer: Wenn die Spalte leer ist, sind keine Kind-Elemente für dies Element möglich.

• 1: Genau ein Kind-Element muss in dem Element eingeschlossen werden.

• +: Mindestens ein Kind-Element muss durch das Element eingeschlossen werden.

Für alle Testelemente steht ein Buchstabe in der Spalte „T“. Der Buchstabe gibt den Typ des Wertes an für den dieses Testelement funktioniert:

• T: Dieses Element funktioniert mit Texten.

• Z: Dieses Element funktioniert mit Zahlenwerten.

• D: Dieses Element funktioniert mit Datum/Zeit-Werten.

Die Beziehungen zwischen allen Filterelementen.

Dokument Element

Das Dokument Element Filter wird nur benötigt wenn der Filter in einer separaten XML Datei erstellt wird.

Filter

Das Filter Element benötigt ein einzelnes Attribut version. Dieses Attribut muss immer den Wert 1 haben. Das Element muss genau ein Kind-Element haben, welches entweder ein Wert-Element oder ein Logik-Element ist.

Das folgende Beispiel zeigt wie du das Filter Element verwendest:

<?xml version="1.0" encoding="utf-8" ?>
<Filter
    version="1"
    xmlns="http://educateit.ch/software/FilterLanguage/1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <Or>
        <NumberValue name="sessionId">
            <Equals>1</Equals>
        </NumberValue>
        <Value name="userName">
            <StartsWith>example</StartsWith>
        </Value>
    </Or>
</Filter>

Logik Elemente

Mit den Logik Elementen kombinierst du mehrere Wert- oder Test-Elemente mit einem Booleschen Operator. In jeder Elementbeschreibung findest du Tabellen welche die Resultate der Booleschen Logik visualisieren. Dabei visualisiert das Symbol ● das der Test erfolgreich war (eine logische 1 oder wahr) und das Symbol ○ steht für einen erfolglosen Test (eine logische 0 oder falsch).

Or

Der boolesche OR container verbindet zwei oder mehr Elemente. Falls eines der Kind-Elemente erfolgreich ist, ist der ganze Ausdruck erfolgreich.

Element 1	Element 2	Result
○	○	○
●	○	●
○	●	●
●	●	●

Das gleiche Prinzip funktioniert mit einer beliebigen Anzahl von Elementen.

1	2	3	4	Result
○	○	○	○	○
●	○	○	○	●
○	●	●	○	●
●	●	●	●	●

Das folgende Beispiel zeigt dir wie du das Or Element verwendest:

<Value name="userName">
    <Or>
        <Matches>administrator</Matches>
        <Matches>guest</Matches>
    </Or>
</Value>

And

Der boolesche AND container verbindet zwei oder mehr Elemente. Nur wenn alle der Kind-Elemente erfolgreich sind, ist der ganze Ausdruck erfolgreich.

Element 1	Element 2	Result
○	○	○
●	○	○
○	●	○
●	●	●

Das gleiche Prinzip funktioniert mit einer beliebigen Anzahl von Elementen.

1	2	3	4	Result
○	○	○	○	○
●	○	○	○	○
○	●	●	○	○
●	●	●	●	●

Das folgende Beispiel zeigt dir wie du das And Element verwendest:

<Value name="userName">
    <And>
        <StartsWith>aa</StartsWith>
        <EndsWith>zz</EndsWith>
    </And>
</Value>

Not

Der boolesche NOT container negiert das Resultat eines Elements.

Element	Result
○	●
●	○

Das folgende Beispiel zeigt dir wie du das Not Element verwendest:

<Value name="userName">
    <Not>
        <Matches>administrator</Matches>
    </Not>
</Value>

Nor

Der boolesche NOR container verbindet zwei oder mehr Elemente. Der container verhält sich genau wie ein OR element, aber das Resultat wird negiert.

Element 1	Element 2	Result
○	○	●
●	○	○
○	●	○
●	●	○

Das gleiche Prinzip funktioniert mit einer beliebigen Anzahl von Elementen.

1	2	3	4	Result
○	○	○	○	●
●	○	○	○	○
○	●	●	○	○
●	●	●	●	○

Das folgende Beispiel zeigt dir wie du das Nor Element verwendest:

<Value name="userName">
    <Nor>
        <Matches>administrator</Matches>
        <Matches>guest</Matches>
    </Nor>
</Value>

Nand

Der boolesche NAND container verbindet zwei oder mehr Elemente. Er verhält sich wie ein AND container, nur wird das Resultat negiert.

Element 1	Element 2	Result
○	○	●
●	○	●
○	●	●
●	●	○

Das gleiche Prinzip funktioniert mit einer beliebigen Anzahl von Elementen.

1	2	3	4	Result
○	○	○	○	●
●	○	○	○	●
○	●	●	○	●
●	●	●	●	○

Das folgende Beispiel zeigt dir wie du das Nand Element verwendest:

<Value name="userName">
    <Nand>
        <StartsWith>aa</StartsWith>
        <EndsWith>zz</EndsWith>
    </Nand>
</Value>

Wert Elemente

Mit dem Wert-Element wählst du den Wert eines Objekts aus, welcher du auf unterschiedliche Kriterien testes. Jedes der drei Wert-Elemente benötigt mindestens das name Attribut, mit dem du den Bezeichner des Werts angibst.

Alle Wert-Elemente benötigen genau ein Kind-Element. Entweder ein Logik-Element, wie beispielsweise And oder einen passendes Test Element wie Matches.

Du findest eine Tabelle mit allen verfügbaren Werten und deren Typen welche du für einen Filter verwenden kannst in der Dokumentation.

Value

Mit dem Value Element selektierst du einen Textwert von einem Objekt. Alle Werte, auch Zahlen und Datum-/Zeitwerte, kannst du als Textwerte verwenden. Letztere werden dabei automatisch in Text umgewandelt.

Die folgenden Beispiele zeigen dir wie du das Value verwendest:

<Value name="userName">
    <Matches>Administrator</Matches>
</Value>

<Value name="userName">
    <Or>
        <Matches>Administrator</Matches>
        <Matches>Example01</Matches>
        <Matches>Example02</Matches>
    </Or>
</Value>

NumberValue

Mit dem NumberValue Element selektierst du einen Zahlenwert von einem Objekt. Dies kann eine Ganzzahl (Integer) sein, aber auch Zahlen mit Nachkommastellen.

Die folgenden Beispiele zeigen dir wie du das NumberValue verwendest:

<NumberValue name="level">
    <Equals>10</Equals>
</NumberValue>

<NumberValue name="level">
    <And>
        <GreaterThan>40</GreaterThan>
        <LessThan>80</LessThan>
    </And>
</NumberValue>

Wenn du dieses Element auf Text anwendest, wird versucht den Text in eine Zahl umzuwandeln. Falls diese Umwandlung scheitert ist das Resultat, als würde keiner der Tests passen.

Das folgende Beispiel wendet das NumberValue Element auf einen Textwert an:

<NumberValue name="textValue">
    <Equals>0</Equals>
</NumberValue>

In der nächsten Tabelle siehst du die Resultate:

textValue	Resultat
0	●
192	○
0.0	●
abc	○

DateTimeValue

Mit dem DateTimeValue Element selektierst du einen Datum/Zeit-Wert vin einem Objekt. Dies kann ein Datum sein, oder auch ein Datum mit einer Zeit.

Neben dem name Attribut kannst du mit dem precision Attribut steuern, wie genau die Datums/Zeit-Werte überprüft werden. Das Attribut akzeptiert die folgenden Bezeichner:

precision	Beschreibung
Full	Die maximale Genauigkeit wird verwendet. Das schliesst auch Sekundenbruchteile ein.
Second	Für die Tests werden alle Werte auf Sekunden reduziert. Dabei wird nicht gerundet: Sekundenbruchteile werden einfach entfernt.
Day	Die Zeit aller Werte wird entfernt und nur das Datum verglichen.

Text-Test Elemente

Die Text-Test Elemente definieren wie der Text eines Wertes aussehen soll. Alle Text-Test Elemente unterstützen dabei das Attribut caseSensitivity. Dieses kannst du auf CaseSensitive setzen, damit bei dem Test auch die Gross-/Kleinschreibung unterschieden wird. Lässt du das Attribut weg, wird es auf CaseInsensitive gesetzt. Dabei wird die Gross-/Kleinschreibung nicht unterschieden.

Whitespace vor und nach dem Text in einem Test wird entfernt. Damit lassen sich die Tests einfacher formatieren. Falls du tatsächlich auf Leerzeichen oder Tabulatoren testen möchtest, verwendest du dazu am besten einen Regulären Ausdruck.

Beispieltabellen

Nach der Beschreibung jedes Elements folgt eine Tabelle mit einigen Beispielen. In der Spalte „Test“ steht der Wert welchen du testest. Die Spalte „CS“ zeigt, ob du das caseSensitivity Attribut auf CaseSensitive gesetzt hast. Dabei wird die Gross-/Kleinschreibung bei □ beachtet und bei ■ nicht.

In der Spalte „Wert“ steht der Wert des Objekts der getestet wird, und in der letzten Spalte „R“ wird das Resultat angezeigt, ob der Test auf das Kriterium passt ● oder nicht ○.

Matches

Das Element Matches testet ob der Wert exakt dem angegebenen Wert entspricht. Falls also der Wert „example“ ist, und du auf „example“ testest, dann ist dein Test erfolgreich.

<Value name="userName">
    <Matches>Administrator</Matches>
</Value>

In der folgenden Tabelle siehst du einige Beispiele:

Test	CS	Wert	R
example	□	example	●
example	■	ExAmplE	●
exampl	□	example	○
exampl	■	ExAmplE	○
example1	□	example	○

Contains

Das Element Contains testet ob ein Text in dem getesteten Wert enthalten ist. Falls beispielsweise der Wert im Objekt „example“ ist, und du den Text „amp“ testest, dann ist dieser Test erfolgreich da amp in example enthalten ist.

<Value name="userName">
    <Contains>-user</Contains>
</Value>

In der folgenden Tabelle siehst du einige Beispiele:

Test	CS	Wert	R
amp	□	example	●
amp	■	ExAmplE	●
ex	□	example	●
example	□	example	●
example1	□	example	○

StartsWith

Das Element StartsWith testet ob ein Wert mit einem bestimmten Text beginnt. Beispielsweise wenn der Wert des Objekts „example“ ist, und du den Text „ex“ testest, dann ist dieser Test erfolgreich, da „example“ mit „ex“ startet.

<Value name="userName">
    <StartsWith>ext-</StartsWith>
</Value>

In der folgenden Tabelle siehst du einige Beispiele:

Test	CS	Wert	R
ex	□	example	●
ex	■	ExAmplE	●
ex	□	ExAmplE	○
amp	□	example	○
example1	□	example	○

EndsWith

Das Element EndsWith testet ob ein Wert mit einem bestimmten Text ended. Beispielsweise wenn der Wert des Objekts „example“ ist, und du den Text „ple“ testest, dann ist dieser Test erfolgreich, da „example“ mit „ple“ ended.

<Value name="userName">
    <EndsWith>-disabled</EndsWith>
</Value>

In der folgenden Tabelle siehst du einige Beispiele:

Test	CS	Wert	R
ple	□	example	●
ple	■	ExAmplE	●
ple	□	ExAmplE	○
amp	□	example	○
aexample	□	example	○

MatchesRegularExpression

Das Element MatchesRegularExpression testet, ob ein Wert einem bestimmten Regulären Ausdruck entspricht. Der Reguläre Ausdruck unterstützt dabei fast den kompletten Umfang einer Perl Regular Expression.

Das caseSensitivity Attribut wird auch auf den Regulären Ausdruck angewendet, funktioniert hier aber wie in der PCRE Dokumentation beschrieben.

<Value name="userName">
    <MatchesRegularExpression>^(?:ext|int)-</MatchesRegularExpression>
</Value>

In der folgenden Tabelle siehst du einige Beispiele:

Test	CS	Wert	R
^example$	□	example	●
^ex	□	example	●
ple$	□	example	●
^example$	■	ExAmPlE	●
^\w+$	□	example	●
^[a-f]+$	□	example	○
^(?:red|blue)$	□	red	●
^(?:red|blue)$	□	blue	●
^(?:red|blue)$	□	yellow	○

Zahlen-Test Elemente

Mit den Zahlen-Test Elementen prüfst du ob Zahlen in einem bestimmten Bereich sind. Die Zahlen werden dabei immer als Fliesskommazahlen mit Nachkommastellen verglichen, unabhängig davon in welchem Format der ursprüngliche Wert ist.

Equals

Das Element Equals testet ob ein Wert exakt der angegeben Zahl entspricht.

<NumberValue name="level">
    <Equals>10</Equals>
</NumberValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	Wert	R
0	0	●
5000	5000	●
1	0	○
1	1.2	○
5234.4	5234	○

LessThan

Das Element LessThan testet ob ein Wert kleiner als die angegeben Zahl ist.

Das folgende Beispiel testet für ein Level 5, 6, 7 oder 8.

<NumberValue name="level">
    <And>
        <GreaterThan>4</GreaterThan>
        <LessThan>9</LessThan>
    </And>
</NumberValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	Wert	R
0	-5	●
5000	200	●
0	0	○
1	1.2	○
5234.4	5234	●

LessOrEqualThan

Das Element LessOrEqualThan testet ob ein Wert kleiner oder gleich wie die angegeben Zahl ist.

Das folgende Beispiel testet für ein Level 8, 9 oder 10.

<NumberValue name="level">
    <And>
        <GreaterThan>8</GreaterThan>
        <LessOrEqualThan>10</LessOrEqualThan>
    </And>
</NumberValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	Wert	R
0	-5	●
5000	200	●
0	0	●
1	1.2	○
5234.4	5234	●

GreaterThan

Das Element GreaterThan testet ob ein Wert grösser als die angegeben Zahl ist.

Das folgende Beispiel testet für ein Level 5, 6, 7 oder 8.

<NumberValue name="level">
    <And>
        <GreaterThan>4</GreaterThan>
        <LessThan>9</LessThan>
    </And>
</NumberValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	Wert	R
0	5	●
5000	5009	●
0	0	○
1.5	1	○
5234.4	5234	○

GreaterOrEqualThan

Das Element GreaterOrEqualThan testet ob ein Wert grösser oder gleich wie die angegeben Zahl ist.

Das folgende Beispiel testet für ein Level 7, 8, 9 oder 10.

<NumberValue name="level">
    <And>
        <GreaterOrEqualThan>7</GreaterOrEqualThan>
        <LessOrEqualThan>10</LessOrEqualThan>
    </And>
</NumberValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	Wert	R
0	5	●
5000	5009	●
0	0	●
1.5	1	○
5234.4	5234	○

Datum/Zeit-Test Elemente

Mit den Datum/Zeit-Test Elementen prüfst du ob ein Zeitpunkt in einem bestimmten Bereich ist. Dabei wird die Präzision, welche du mit dem precision Attribut beim DateTimeValue Element angibst berücksichtigt. Dies ist besonders wichtig, wenn du ein Datum oder eine Zeit mit dem Exactly Element testest.

Bei jedem der folgenden Elemente kannst du das getestete Datum und die Zeit in drei verschiedenen Formaten angeben:

• yyyy-MM-ddThh:mm:ss — ISO Datum und Zeit, getrennt mit einem T

• yyyy-MM-dd — ISO Datum ohne Zeit

• now[+-][n][unit] — Relative Zeit zu dem Zeitpunkt des Tests.

Das erste Format ist eine kombination aus Datum und Zeit in ISO Format. Die folgende Liste zeigt dir einige gültige Werte in diesem Format:

• 2015-12-24T08:00:00

• 2008-01-01T22:12:04

• 1996-04-30T12:00:00

• 1970-01-01T00:00:00

• 2014-12-31T23:59:59

Das zweite Format ist nur ein Datum im ISO Format. Die Zeit wird dabei immer auf 00:00:00 gesetzt, was wichtig ist wenn du damit Zeitwerte vergleichst. Die folgende Liste zeigt dir einige gültige Werte in diesem Format:

• 2015-12-24

• 2008-01-01

• 1996-04-30

• 1970-01-01

• 2014-12-31

Das letzte Format definiert einen relativen Zeitpunkt zu dem aktuellen Test. Ein solcher Eintrag startet immer mit dem Text now, in Kleinbuchstaben, gefolgt von einer positiven oder Negativen Zahl. Es folgt also ein Plus + oder Minus - Zeichen und danach die Ziffern der Zahl.

Direkt nach der Zahl, ohne Leerzeichen, folgt die Einheit für die Zahl. Mögliche Einheiten und deren Schreibweisen findest du in der folgenden Liste:

• ms — Millisekunden

• milliseconds — Millisekunden

• s — Sekunden

• seconds — Sekunden

• m — Minuten

• minutes — Minuten

• h — Stunden

• hours — Stunden

• days — Tage

• months — Monate

• years — Jahre

Die folgende Liste zeigt dir einige gültige Werte in diesem Format:

• now+1s

• now-5hours

• now+10minutes

• now+1year

• now-5months

• now-10seconds

• now+8days

Die folgenden Kapitel beschreiben jedes Element. In der Beschreibung ist auch eine Tabelle mit Beispielen enthalten. Diese Tabelle enthält eine zusätzliche Spalte „P“, in der die Präzision angegeben wird, welche beim Wert eingestellt wurde. Dabei haben die Buchstaben in dieser Spalte folgende Bedeutung:

• F — Volle Präzision

• S — Sekundenpräzision

• D — Nur Datumspräzision.

Exactly

Das Element Exactly tested ob ein Wert exakt einem angegeben Zeitpunkt entspricht. Dabei werden die beiden Zeitpunkte mit der eingestellten Präzision verglichen.

<DateTimeValue name="start" precision="Day">
    <Exactly>2021-09-29</Exactly>
</DateTimeValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	P	Wert	R
2015-01-01T08:00:00	S	2015-01-01T08:00:00	●
2015-01-01T08:00:00	S	2015-01-01T08:00:01	○
2015-01-01	D	2015-01-01T08:00:01	●
2015-01-01T08:00:00	F	2015-01-01T08:00:00.7	○
2015-01-01T08:00:00	D	2015-01-08	○

Before

Das Element Before tested ob ein Wert vor einem angegeben Zeitpunkt liegt. Dabei werden die beiden Zeitpunkte mit der eingestellten Präzision verglichen.

<DateTimeValue name="start" precision="Day">
    <Before>2021-09-29</Before>
</DateTimeValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	P	Wert	R
2015-01-01T08:00:00	S	2015-01-01T08:00:00	○
2015-01-01T08:00:00	S	2015-01-01T07:59:59	●
2015-01-01T08:00:00	D	2015-01-01T07:00:00	○
2015-01-01T08:00:00	F	2015-01-01T08:00:00.7	○
2015-01-01T08:00:00	D	2014-01-01	●

BeforeOrExactly

Das Element BeforeOrExactly tested ob ein Wert vor einem angegeben Zeitpunkt liegt oder exakt dem Zeitpunkt entspricht. Dabei werden die beiden Zeitpunkte mit der eingestellten Präzision verglichen.

<DateTimeValue name="start" precision="Day">
    <BeforeOrExactly>2021-09-29</BeforeOrExactly>
</DateTimeValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	P	Wert	R
2015-01-01T08:00:00	S	2015-01-01T08:00:00	●
2015-01-01T08:00:00	S	2015-01-01T07:59:59	●
2015-01-01T08:00:00	D	2015-01-01T07:00:00	●
2015-01-01T08:00:00	F	2015-01-01T08:00:00.7	○
2015-01-01T08:00:00	D	2014-01-01	●

After

Das Element After tested ob ein Wert nach einem angegeben Zeitpunkt liegt. Dabei werden die beiden Zeitpunkte mit der eingestellten Präzision verglichen.

<DateTimeValue name="start" precision="Day">
    <After>2021-09-29</After>
</DateTimeValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	P	Wert	R
2015-01-01T08:00:00	S	2015-01-01T08:00:00	○
2015-01-01T08:00:00	S	2015-01-01T08:00:01	●
2015-01-01T08:00:00	D	2015-01-01T09:00:00	○
2015-01-01T08:00:00	F	2015-01-01T08:00:00.7	●
2015-01-01T08:00:00	D	2015-02-01	●

AfterOrExactly

Das Element AfterOrExactly tested ob ein Wert nach einem angegeben Zeitpunkt liegt oder exakt dem Zeitpunkt entspricht. Dabei werden die beiden Zeitpunkte mit der eingestellten Präzision verglichen.

<DateTimeValue name="start" precision="Day">
    <AfterOrExactly>2021-09-29</AfterOrExactly>
</DateTimeValue>

In der folgenden Tabelle siehst du einige Beispiele:

Test	P	Wert	R
2015-01-01T08:00:00	S	2015-01-01T08:00:00	●
2015-01-01T08:00:00	S	2015-01-01T08:00:01	●
2015-01-01T08:00:00	D	2015-01-01T09:00:00	●
2015-01-01T08:00:00	F	2015-01-01T08:00:00.7	●
2015-01-01T08:00:00	D	2015-02-01	●

Objektzuordnungen

Objektzuordnungen sind eine spezielle Form der Filterausdrücke. Bei Objektzuordnungen geht es darum, Objekten einem Namen und einer Gruppe zuzuordnen. Dabei wird eine Liste von Filtern geprüft und ein Objekt dem Namen und der Gruppe des ersten passenden Filters zugeordnet.

Solche Objektzuordnungen werden auf unterschiedlichste Arten in unserer Software verwendet. Auch ist die Bedeutung des Namens und der Gruppe unterschiedlich. Das Format wie die Objektzuordnung konfiguriert wird bleibt jedoch immer dasselbe.

Die Objektzuordnungsdatei

Das folgende Beispiel zeigt eine komplette Objektzuordnungsdatei:

↓ Alles anzeigen ↓

<?xml version="1.0" encoding="utf-8" ?>
<ObjectMap
    version="1"
    xmlns="http://educateit.ch/software/FilterObjectMap/1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <ObjectGroup name="Common">
        <Object name="Test1">
            <Value name="name">
                <Matches>test1</Matches>
            </Value>
        </Object>
        <Object name="Test2">
            <Value name="name">
                <Or>
                    <Matches>test2</Matches>
                    <Matches>test2.1</Matches>
                </Or>
            </Value>
        </Object>
    </ObjectGroup>
    <ObjectGroup name="Special A">
        <Object name="Special Test 1">
            <And>
                <Value name="path">
                    <Contains caseSensitivity="CaseInsensitive">Special</Contains>
                </Value>
                <Value name="name">
                    <StartsWith>Examp</StartsWith>
                </Value>
            </And>
        </Object>
        <Object name="Special Test 2">
            <Not>
                <Value name="path">
                    <StartsWith>\\</StartsWith>
                </Value>
            </Not>
        </Object>
    </ObjectGroup>
</ObjectMap>

Das ganze Dokument ist in dem ObjectMap Element eingeschlossen. Darin muss mindestens ein ObjectGroup enthalten sein; und darin wiederum mindestens ein Object Element welches den Filterausdruck enthält.

Die folgende Illustration zeigt die Beziehungen zwischen diesen Elementen:

Die Beziehungen zwischen allen Elementen in einer Objektzuordnung.

Das ObjectMap Element

Das Dokumentelement ObjectMap schliesst alle Objektzuordnungen ein. Dieses Element muss das Attribut version enthalten, welches auf die Zahl 1 gesetzt ist.

Als Kind-Elemente muss es mindestens ein ObjectGroup Element enthalten.

Das ObjectGroup Element

Das ObjectGroup Element definiert die Gruppe, zu welcher ein Objekt zugeordnet wird. Das Element benötigt das Attribut name, welches den Namen der Gruppe definiert.

In diesem Gruppennamen sind nur Buchstaben (a-z, A-Z), Zahlen (0-9), der Bindestrich (-) und Unterstrich (_) in dem Namen erlaubt. Die maximale Länge ist 128 Zeichen.

Als Kind-Elemente muss es mindestens ein Object Element enthalten.

Das Object Element

Das Object Element definiert den Namen des Objekts und schliesst den Filterausdruck ein. Das Element benötigt das Attribut name, welches den Namen des Objekts definiert.

In diesem Objektnamen sind nur Buchstaben (a-z, A-Z), Zahlen (0-9), der Bindestrich (-) und Unterstrich (_) in dem Namen erlaubt. Die maximale Länge ist 128 Zeichen.

Vom Inhalt entspricht dieses Element dem Filter Element. Es muss also einen gültigen Filterausdruck enthalten.

Auswertung der Objektzuordnung

Die Objektzuordnung wird genau in der Reihenfolge ausgewertet, in der du die Object Elemente definierst. Es wird also jeder definierte Filter in der definition in genau dieser Sequenz getestet. Der erste Filter, der auf ein Objekt passt definiert den Namen und die Gruppe für dieses Objekt.

Wenn das Ende der Definition erreicht wird, ohne dass einer der Filter auf ein Objekt passt, wird keine Zuordnung gemacht. Entweder bleibt dabei einfach der Objekt und Gruppenname leer, oder dies kann je nach Anwendungszweck eine andere Bedeutung haben. Die genauen Details dazu, findest du in der Dokumentation bei der Konfiguration, welche eine Objektzuordnung verwendet.