Datums-Funktionen ermöglichen die professionelle Verarbeitung und Formatierung von Datumsangaben in Vorlagen. Sie sind besonders wichtig für Abrechnungsperioden, Vertragsfristen und Zeitberechnungen.

Datums-Datenquellen: Datumswerte werden oft in einem bestimmten Format in den JSON-Daten bereitgestellt. Bei Fehlern ist oft der Grund, dass Output.Rocks das richtige Format noch nicht erkennt.

Lösung:
Geben Sie das inputFormat als Parameter der Funktion nach Ihrem System-Format mit an! Überprüfen Sie dafür genau, wie die Daten in ihrem JSON-Payload aussehen mit <<$dump:ihreVariable>>.

Beispiel:
JSON: "ableseTermin": "20230615"
Vorlage: <<{dateFormat(ableseTermin, 'dd.MM.yyyy', 'yyyyMMdd')}>>
Ergebnis: 15.06.2023

Verfügbare Datumsfunktionen

Funktion	Beschreibung	Beispiel
`dateFormat(datum, outputFormat)`	Formatiert ein Datum nach Muster	`dateFormat('2023-06-01', 'dd.MM.yyyy')` → 01.06.2023
`dateFormat(datum, outputFormat, inputFormat)`	Mit spezifischem Eingabeformat	`dateFormat('01/06/2023', 'dd.MM.yyyy', 'dd/MM/yyyy')` → 01.06.2023

Format-Zeichen:

yyyy = Jahr (4-stellig), yy = Jahr (2-stellig)
MM = Monat (2-stellig), MMM = Monat (kurz), MMMM = Monat (lang)
dd = Tag (2-stellig), d = Tag (1-stellig)
HH = Stunde (24h), mm = Minute, ss = Sekunde

Vollständige Funktions-Syntax

Datumsfunktionen können mit noch mehr Parametern verwendet werden, wie Locales und Einheiten.

dateFormat (vollständig):

dateFormat(value [, outputFormat [, inputFormat [, outputLocale [, inputLocale [, outputFormatLocalized [, inputFormatLocalized]]]]]])

dateAdd (vollständig):

dateAdd(date, amt, units [, outputFormat [, inputFormat]])

dateDiff (vollständig):

dateDiff(date1, date2, units [, inputFormat])

Parameter-Erklärung:

date / value = Zeitstempel, der verarbeitet wird
outputFormat / inputFormat = Muster der Ausgabe/Eingabe-Zeitstempel
amt = Anzahl der Einheiten zum Addieren/Subtrahieren (kann negativ sein), z.B. '7' für 7 Tage oder '-30' für 30 Tage zurück
units = Einheit der Zeit, z.B. 'days', 'weeks', 'months', 'years', 'hours', 'minutes', 'seconds'
outputLocale / inputLocale = Sprache für Monatsnamen und regionale Formatierung (z.B. 'DE', 'FR')
outputFormatLocalized / inputFormatLocalized = Format in Locale-spezifischen Format-Zeichen interpretieren (selten verwendet)

Was sind Locales?

Locales bestimmen die Sprache und regionale Formatierung (z.B. 'DE' für Deutschland, 'US' für USA, 'FR' für Frankreich). Sie steuern Monats-/Wochentagsnamen und Datumsreihenfolge.

Alle Infos zu Locales finden Sie in der Locale-Dokumentation.

Liste aller Format-Zeichen

Die folgenden Format-Zeichen können für outputFormat und inputFormat verwendet werden:

Zeichen	Komponente	Darstellung	Beispiele
`G`	Ära-Bezeichnung	Text	AD
`y`	Jahr	Jahr	1996; 96
`M`	Monat im Jahr	Monat	Juli; Jul; 07
`w`	Woche im Jahr	Zahl	27
`W`	Woche im Monat	Zahl	2
`D`	Tag im Jahr	Zahl	189
`d`	Tag im Monat	Zahl	10
`F`	Wochentag im Monat	Zahl	2
`E`	Wochentag	Text	Dienstag; Di
`a`	AM/PM-Markierung	Text	PM
`H`	Stunde im Tag (0-23)	Zahl	0
`k`	Stunde im Tag (1-24)	Zahl	24
`K`	Stunde in AM/PM (0-11)	Zahl	0
`h`	Stunde in AM/PM (1-12)	Zahl	12
`m`	Minute in der Stunde	Zahl	30
`s`	Sekunde in der Minute	Zahl	55
`S`	Millisekunde	Zahl	978
`z`	Zeitzone (allgemein)	Text	Pacific Standard Time; PST; GMT-08:00
`Z`	Zeitzone (RFC 822)	Text	-0800

Format-Zeichen-Wiederholung: Die Anzahl der Zeichen bestimmt die Darstellung:

y = 96, yy = 96, yyyy = 1996
M = 7, MM = 07, MMM = Jul, MMMM = Juli
E = Di, EE = Di, EEE = Die, EEEE = Dienstag

Wichtig: Diese Format-Zeichen sind standardisiert und nicht lokalisiert. Für lokalisierte Pattern-Zeichen (z.B. französisches 'a' für Jahr statt 'y') verwenden Sie die Parameter outputFormatLocalized und inputFormatLocalized.

Vollständiges Beispiel

# dateAdd mit allen Parametern
Kündigungsfrist (3 Monate vor Ende): <<{dateAdd(vertragsbeginn, {vertrag_monate - 3}, 'months', 'dd.MM.yyyy', 'yyyy-MM-dd')}>>

# dateFormat mit allen Parametern
Französisch → Deutsch: <<{dateFormat(fr_datum, 'EEEE, dd. MMMM yyyy', 'jj MMMM aaaa', 'DE', 'FR', false, true)}>>

Input-Aspekt: FR-Locale erkennt "décembre" Output-Aspekt: DE-Locale gibt "Dezember" aus FormatLocalized: Konvertiert Format-Zeichen z.B. 'jj' (französisch Tag) → 'dd' (Standard Tag), 'aaaa' (französisch Jahr) → 'yyyy' (Standard Jahr)

InputFormat-Tipp: Wenn Ihre Datumsdaten nicht automatisch erkannt werden, geben Sie das inputFormat explizit an. Häufige Formate: 'dd.MM.yyyy', 'MM/dd/yyyy', 'yyyy-MM-dd'

Beispiele für Datumsformatierung

Grundlegende Formatierung

Rechnungsdatum: <<{dateFormat(rechnungsdatum, 'dd.MM.yyyy')}>>
Rechnungsmonat: <<{dateFormat(rechnungsdatum, 'MMMM yyyy')}>>
Kurzformat: <<{dateFormat(rechnungsdatum, 'dd.MM.yy')}>>
ISO-Format: <<{dateFormat(rechnungsdatum, 'yyyy-MM-dd')}>>
Mit Wochentag: <<{dateFormat(rechnungsdatum, 'EEEE, dd. MMMM yyyy')}>>
Zeit: <<{dateFormat(zeitstempel, 'HH:mm:ss')}>>

InputFormat-Behandlung für verschiedene Datenquellen

# Automatische Erkennung (funktioniert oft):
ISO-Datum: <<{dateFormat(iso_datum, 'dd.MM.yyyy')}>>

# Mit explizitem inputFormat (sicherer):
US-Format: <<{dateFormat(us_datum, 'dd.MM.yyyy', 'MM/dd/yyyy')}>>
Deutsches Format: <<{dateFormat(de_datum, 'yyyy-MM-dd', 'dd.MM.yyyy')}>>
Zeitstempel: <<{dateFormat(timestamp, 'dd.MM.yyyy HH:mm', 'yyyy-MM-dd HH:mm:ss')}>>

# System-spezifische Formate:
SAP-Format: <<{dateFormat(sap_datum, 'dd.MM.yyyy', 'yyyyMMdd')}>>
Excel-Export: <<{dateFormat(excel_datum, 'dd.MM.yyyy', 'dd/MM/yyyy')}>>

Lokalisierte Formatierung

# Basis-Lokalisierung:
Datum (Deutsch): <<{dateFormat(datum, 'dd. MMMM yyyy', '', 'DE')}>>
Datum (Englisch): <<{dateFormat(datum, 'MMMM dd, yyyy', '', 'US')}>>
Datum (Französisch): <<{dateFormat(datum, 'dd MMMM yyyy', '', 'FR')}>>

# Mit inputFormat und Lokalisierung:
US-Eingabe → Deutsch: <<{dateFormat(us_eingabe, 'dd. MMMM yyyy', 'MM/dd/yyyy', 'DE')}>>
DE-Eingabe → Englisch: <<{dateFormat(de_eingabe, 'MMMM dd, yyyy', 'dd.MM.yyyy', 'US')}>>

# Vollständige Lokalisierung (input + output):
Französisch → Deutsch: <<{dateFormat(fr_eingabe, 'dd. MMMM yyyy', 'dd MMMM yyyy', 'DE', 'FR')}>>

Locale-Tipp: Verwenden Sie Locale-Codes wie 'DE', 'US', 'FR' für automatische Übersetzung von Monats- und Wochentagsnamen.

Datumsberechnungen

Addition und Subtraktion

Abrechnungsperiode:
Von: <<{dateFormat(periode_start, 'dd.MM.yyyy')}>>
Bis: <<{dateFormat(periode_ende, 'dd.MM.yyyy')}>>

Berechnungen:
+ 30 Tage: <<{dateFormat(dateAdd(periode_start, 30, 'days'), 'dd.MM.yyyy')}>>
+ 1 Monat: <<{dateFormat(dateAdd(periode_start, 1, 'months'), 'dd.MM.yyyy')}>>
+ 1 Jahr: <<{dateFormat(dateAdd(periode_start, 1, 'years'), 'dd.MM.yyyy')}>>
- 7 Tage: <<{dateFormat(dateAdd(periode_ende, -7, 'days'), 'dd.MM.yyyy')}>>

# Mit expliziter Format-Kontrolle:
System-Datum + 30T: <<{dateAdd(system_datum, 30, 'days', 'dd.MM.yyyy', 'yyyyMMdd')}>>

Differenzberechnungen mit verschiedenen Eingabeformaten

Ableseperiode:
Letzter Ablesung: <<{dateFormat(ablesung_alt, 'dd.MM.yyyy')}>>
Aktuelle Ablesung: <<{dateFormat(ablesung_neu, 'dd.MM.yyyy')}>>

# Standardberechnung (automatische Erkennung):
Tage zwischen Ablesungen: <<{dateDiff(ablesung_alt, ablesung_neu, 'days')}>> Tage

# Mit explizitem inputFormat für spezielle Datenquellen:
Systemdaten (yyyyMMdd): <<{dateDiff(system_alt, system_neu, 'days', 'yyyyMMdd')}>> Tage
US-Daten (MM/dd/yyyy): <<{dateDiff(us_alt, us_neu, 'days', 'MM/dd/yyyy')}>> Tage
Deutsche Daten (dd.MM.yyyy): <<{dateDiff(de_alt, de_neu, 'days', 'dd.MM.yyyy')}>> Tage

Weitere Analysen:
Wochen zwischen Ablesungen: <<{dateDiff(ablesung_alt, ablesung_neu, 'weeks')}>> Wochen
Monate zwischen Ablesungen: <<{dateDiff(ablesung_alt, ablesung_neu, 'months')}>> Monate
Durchschn. Tage/Monat: <<{round(dateDiff(ablesung_alt, ablesung_neu, 'days') / dateDiff(ablesung_alt, ablesung_neu, 'months'), 1)}>> Tage

Berechnungsgenauigkeit: Monatsdifferenzen können je nach Monatslänge variieren. Für exakte Berechnungen verwenden Sie Tage als Basis.

Komplexe Abrechnungsbeispiele

Stromabrechnung mit Zeitberechnungen

<<$abrechnungstage=dateDiff(periode_von, periode_bis, 'days')>>
<<$tage_pro_monat=round({{$abrechnungstage / 12}}, 1)>>
<<$zahlungsziel=dateAdd(rechnungsdatum, 14, 'days')>>

STROMABRECHNUNG <<{dateFormat(periode_von, 'yyyy')}>>
=====================================
Abrechnungszeitraum: <<{dateFormat(periode_von, 'dd.MM.yyyy')}>> bis <<{dateFormat(periode_bis, 'dd.MM.yyyy')}>>
Abrechnungstage: <<{$abrechnungstage}>> Tage
Durchschn. Tage/Monat: <<{$tage_pro_monat}>> Tage

Rechnungsdetails:
Rechnungsdatum: <<{dateFormat(rechnungsdatum, 'dd.MM.yyyy')}>>
Zahlungsziel: <<{dateFormat($zahlungsziel, 'dd.MM.yyyy')}>>
Zahlbar bis: <<{dateFormat($zahlungsziel, 'EEEE, dd. MMMM yyyy')}>>

<<cs_{{dateDiff(rechnungsdatum, $zahlungsziel, 'days') < 0}}>>
⚠️ ACHTUNG: Zahlungsfrist bereits überschritten!
<<es_>>

Nächste Ablesung: <<{dateFormat(dateAdd(periode_bis, 1, 'years'), 'MMMM yyyy')}>>

Fristenüberwachung für Verträge

<<$vertragsende=vertrag.laufzeit_ende>>
<<$heute='2024-01-15'>>
<<$kuendigungsfrist_tage=90>>
<<$kuendigungstermin=dateAdd($vertragsende, -$kuendigungsfrist_tage, 'days')>>
<<$tage_bis_kuendigung=dateDiff($heute, $kuendigungstermin, 'days')>>

VERTRAGSINFORMATION
===================
Vertragsnummer: <<{vertrag.nummer}>>
Vertragsende: <<{dateFormat($vertragsende, 'dd.MM.yyyy')}>>
Kündigungsfrist: <<{$kuendigungsfrist_tage}>> Tage
Kündigung möglich bis: <<{dateFormat($kuendigungstermin, 'dd.MM.yyyy')}>>

Status-Analyse:
<<cs_{{$tage_bis_kuendigung > 0}}>>
✅ Kündigung noch möglich - noch <<{$tage_bis_kuendigung}>> Tage Zeit
<<else>>
❌ Kündigungsfrist verpasst - Vertrag verlängert sich automatisch
<<es_>>

Automatische Verlängerung: <<{dateFormat(dateAdd($vertragsende, 1, 'years'), 'dd.MM.yyyy')}>>

Best Practice: Verwenden Sie Variablen für wiederverwendbare Datumsberechnungen und kombinieren Sie diese mit bedingten Abschnitten für dynamische Statusanzeigen.

Formatierungs-Referenz

Häufige Datums-Formatierungen

Format-String	Eingabe	Ausgabe	Verwendung
'dd.MM.yyyy'	2023-06-15	15.06.2023	Deutsches Datumsformat
'MMMM yyyy'	2023-06-15	Juni 2023	Abrechnungsmonate
'yyyy-MM-dd'	15.06.2023	2023-06-15	ISO-Standard
'HH:mm:ss'	2023-06-15T14:30:45	14:30:45	Zeitangaben
'EEEE, dd. MMMM'	2023-06-15	Donnerstag, 15. Juni	Ausführliche Darstellung

InputFormat-Referenz für häufige Datenquellen

Datenquelle	Beispiel-Eingabe	InputFormat	Verwendung
SAP-System	20230615	'yyyyMMdd'	ERP-Export
US-System	06/15/2023	'MM/dd/yyyy'	US-Standard
Excel-Export	15/06/2023	'dd/MM/yyyy'	Excel-Standard
Zeitstempel	2023-06-15 14:30:45	'yyyy-MM-dd HH:mm:ss'	Datenbank-Timestamp
Deutsche Eingabe	15.06.2023	'dd.MM.yyyy'	Deutschland-Standard
ISO-Standard	2023-06-15	Automatisch erkannt	Meist kein inputFormat nötig

Wichtiger Hinweis: String-Parameter in Datumsfunktionen müssen mit einfachen Anführungszeichen (') geschrieben werden: dateFormat(datum, 'dd.MM.yyyy') ist korrekt.