Kurzbeschreibung

Das XML-Element <DateDiff> berechnet die Differenz zwischen zwei Datumswerten.

Das Ergebnis kann in Tagen oder Wochen ausgegeben werden.

Die beiden Datumswerte können entweder als feste Werte angegeben oder über Variablenpfade gelesen werden.

Einordnung

Bereich: Funktionen

Schwierigkeitsgrad: ⭐⭐⭐☆☆

Vorkenntnisse: Variable · Datumsformate

Status des Artikels

Die grundsätzliche Funktion und die verfügbaren Attribute stammen aus der Elementkonfiguration.

Da derzeit kein belastbares Anwendungsbeispiel vorliegt, müssen die dargestellte Subtraktionsrichtung und die Beispielsyntax noch praktisch im Developer geprüft werden.

Siehe auch

• DateAdd
• Converter
• Variable
• Math

Zweck

Mit <DateDiff> lässt sich der zeitliche Abstand zwischen zwei Datumswerten ermitteln.

Typische Anwendungsfälle sind:

• Anzahl der Tage zwischen zwei Terminen,
• Dauer eines Zeitraums,
• verbleibende Tage bis zu einem Termin,
• vergangene Tage seit einem Ereignis,
• Umrechnung eines Zeitraums in Wochen.

<DateDiff> verändert die verwendeten Datumswerte nicht.

Es berechnet aus beiden Werten ein neues Ergebnis.

Berechnungsprinzip

Aus den Namen und Beschreibungen der Attribute ergibt sich voraussichtlich folgende Berechnung:

Left − Right = Ergebnis

Dabei ist:

• Left der Datumswert, von dem abgezogen wird,
• Right der Datumswert, der abgezogen wird.

Beispiel:

31.08.2026 − 01.08.2026 = 30 Tage

Wichtig

Die Subtraktionsrichtung wurde aus den Attributbeschreibungen abgeleitet.

Sie sollte beim ersten praktischen Einsatz mit eindeutig unterscheidbaren Datumswerten geprüft werden.

Position innerhalb der Dokumentvorlage

Da <DateDiff> ein Ergebnis erzeugt, wird es voraussichtlich innerhalb eines <Content> verwendet.

<Block>

    <Content>

        <DateDiff
            Ausgabe="Tage"
            LeftValue="31.08.2026"
            LeftFormat="dd.MM.yyyy"
            RightValue="01.08.2026"
            RightFormat="dd.MM.yyyy">
        </DateDiff>

    </Content>

</Block>

Das berechnete Ergebnis wird an der Position von <DateDiff> ausgegeben.

Hinweis

Die Verwendung innerhalb von <Content> ist aus dem Ausgabecharakter der Funktion abgeleitet und muss noch praktisch bestätigt werden.

Attribute

Hinweis

Die Beschreibungen von LeftFormat und RightFormat scheinen in der Elementkonfiguration sprachlich vertauscht zu sein.

In diesem Artikel werden die Attribute entsprechend ihrer Namen dem jeweiligen linken beziehungsweise rechten Datumswert zugeordnet.

Werte für Ausgabe

Für das Attribut Ausgabe stehen aktuell folgende Werte zur Verfügung:

Beispiel:

<DateDiff
    Ausgabe="Tage"
    ...>
</DateDiff>

Die Schreibweise sollte entsprechend der IntelliSense übernommen werden.

Fester Wert oder Variablenpfad

Für beide Seiten der Berechnung stehen jeweils zwei Möglichkeiten bereit:

Für dieselbe Seite sollte jeweils entweder Value oder Path verwendet werden.

LeftValue oder LeftPath

RightValue oder RightPath

Eine gleichzeitige Verwendung beider Varianten für dieselbe Seite ist zu vermeiden, solange nicht geklärt ist, welcher Wert Vorrang besitzt.

Datumsformate

Mit LeftFormat und RightFormat wird beschrieben, in welchem Format die jeweiligen Datumswerte vorliegen.

Mögliche Formatmasken sind beispielsweise:

Das angegebene Format muss zum tatsächlichen Datumswert passen.

Beispiel:

<DateDiff
    LeftValue="31.08.2026"
    LeftFormat="dd.MM.yyyy"
    RightValue="2026-08-01"
    RightFormat="yyyy-MM-dd"
    Ausgabe="Tage">
</DateDiff>

Vorläufige Beispiele

Die folgenden Beispiele wurden aus den verfügbaren Attributen abgeleitet und müssen noch im Developer getestet werden.

Zwei feste Datumswerte vergleichen

<DateDiff
    Ausgabe="Tage"
    LeftValue="31.08.2026"
    LeftFormat="dd.MM.yyyy"
    RightValue="01.08.2026"
    RightFormat="dd.MM.yyyy">
</DateDiff>

Voraussichtliches Ergebnis:

30

Zwei Variablen vergleichen

<DateDiff
    Ausgabe="Tage"
    LeftPath="custom.enddatum"
    LeftFormat="dd.MM.yyyy"
    RightPath="custom.startdatum"
    RightFormat="dd.MM.yyyy">
</DateDiff>

Dabei wird voraussichtlich folgende Differenz berechnet:

custom.enddatum − custom.startdatum

Festes Datum und Variable kombinieren

<DateDiff
    Ausgabe="Tage"
    LeftPath="custom.enddatum"
    LeftFormat="dd.MM.yyyy"
    RightValue="01.08.2026"
    RightFormat="dd.MM.yyyy">
</DateDiff>

Damit kann ein dynamischer Datumswert mit einem fest definierten Datum verglichen werden.

Differenz in Wochen

<DateDiff
    Ausgabe="Wochen"
    LeftValue="29.08.2026"
    LeftFormat="dd.MM.yyyy"
    RightValue="01.08.2026"
    RightFormat="dd.MM.yyyy">
</DateDiff>

Bei einer Differenz von 28 Tagen wäre ein Ergebnis von vier Wochen zu erwarten.

Noch zu prüfen

Bei einer Differenz, die keine vollständige Anzahl von Wochen ergibt, ist derzeit nicht bekannt, ob <DateDiff>

• abrundet,
• aufrundet,
• kaufmännisch rundet oder
• einen Dezimalwert ausgibt.

Negative Ergebnisse

Ergibt die linke Seite ein früheres Datum als die rechte Seite, könnte die Berechnung ein negatives Ergebnis erzeugen.

Beispiel:

01.08.2026 − 31.08.2026

Das erwartete mathematische Ergebnis wäre:

−30 Tage

Ob <DateDiff> tatsächlich negative Werte ausgibt oder stattdessen den absoluten Abstand berechnet, muss noch praktisch geprüft werden.

Zusammenspiel mit Converter

Datumswerte müssen in einem Format vorliegen, das von <DateDiff> korrekt verarbeitet werden kann.

Liefert eine Datenquelle ein ungeeignetes Format, kann zuvor ein <Converter> verwendet werden.

Variable

        │

        ▼

Converter

        │

        ▼

DateDiff

Dabei ist zu prüfen, ob <DateDiff> verschachtelte Funktionen als Operanden unterstützt oder ob der konvertierte Wert zunächst mit einem <Setter> gespeichert werden muss.

Typische Einsatzgebiete

<DateDiff> könnte beispielsweise verwendet werden für:

• Laufzeiten,
• Bearbeitungsdauern,
• Fristberechnungen,
• Zeiträume zwischen Beginn und Ende,
• verbleibende Tage bis zu einem Termin,
• vergangene Tage seit einem Ereignis,
• Ausgabe vollständiger Wochen zwischen zwei Datumswerten.

DateDiff oder DateAdd?

<DateDiff> und <DateAdd> verarbeiten beide Datumswerte, erfüllen jedoch unterschiedliche Aufgaben.

Als Faustregel gilt:

• <DateDiff>, wenn der Abstand zwischen zwei Daten benötigt wird.
• <DateAdd>, wenn aus einem Datum ein neues Datum berechnet werden soll.

Best Practices

• Für jede Seite entweder Value oder Path verwenden.
• Das Datumsformat immer passend zum tatsächlichen Wert angeben.
• Die Subtraktionsrichtung mit eindeutigen Testdaten prüfen.
• Berechnungen sowohl mit positiven als auch möglichen negativen Ergebnissen testen.
• Die Wochenberechnung auch mit unvollständigen Wochen prüfen.
• Leere oder ungültige Datumswerte in den Testfällen berücksichtigen.
• Die von der IntelliSense angebotene Schreibweise verwenden.

Developer-Tipp

Verwenden Sie beim ersten Test zwei Datumswerte, deren Differenz eindeutig erkennbar ist.

Beispiel:

11.08.2026 und 01.08.2026

So lässt sich schnell feststellen,

• in welcher Richtung gerechnet wird,
• ob das Ergebnis positiv oder negativ sein kann und
• wie die Ausgabe in Wochen behandelt wird.

Offene Prüfpunkte

Für die praktische Überprüfung sollten folgende Fragen geklärt werden:

1. Erfolgt die Berechnung tatsächlich nach Left − Right?
2. Können negative Ergebnisse entstehen?
3. Wie werden angebrochene Wochen behandelt?
4. Was geschieht bei einem leeren LeftPath oder RightPath?
5. Was geschieht bei einem ungültigen Datumsformat?
6. Wird das Ergebnis unmittelbar innerhalb von <Content> ausgegeben?
7. Können konvertierte oder zusammengesetzte Werte als Unterelemente verwendet werden?
8. Welche Kombinationen aus Value und Path werden technisch akzeptiert?

XML-Wissen

<DateDiff> ist laut Elementkonfiguration ein Container.

Die bekannte Konfiguration steuert die beiden Datumswerte jedoch vollständig über Attribute.

Welche Unterelemente innerhalb des Containers tatsächlich zulässig und sinnvoll sind, geht aus den derzeit verfügbaren Informationen nicht hervor.

Bis zur praktischen Prüfung sollte <DateDiff> daher ohne zusätzliche Unterelemente verwendet werden.

Fazit

<DateDiff> berechnet voraussichtlich die Differenz zwischen einem linken und einem rechten Datumswert.

Beide Werte können als feste Daten oder über Variablenpfade bereitgestellt werden. Die Ausgabe erfolgt in Tagen oder Wochen.

Da das Element bislang nur sehr selten in vorhandenen Vorlagen vorkommt, sollte dieser Artikel anhand eines gezielten Tests weiter geschärft werden. Die offenen Prüfpunkte bieten dafür eine konkrete Testliste.