Skip to main content
Qargo

Benutzerdefinierte Exporte: Den Ausdrucks-Generator verwenden

Inhaltsverzeichnis
  1. Was ist der Ausdrucks-Generator?
  2. Warum ihn verwenden?
  3. Begriffe
  4. Hinweise und aktuelle Einschränkungen
  5. Anleitung: Den Ausdrucks-Generator konfigurieren und verwenden
  6. Filteroptionen nach Gebührentyp
  7. 1. Zuschläge – jetzt vollständig unterstützt
  8. 2. Umsatz aus Extras (neue Kategorie)
  9. 3. Einheitliche Filterung in UI und Export
  10. 4. Dokumente einbeziehen
  11. Tipps
  12. Erweitert: Ausdrucksmodus
  13. Fehlerbehebung

Dieser Artikel erklärt, was der Ausdrucks-Generator ist und warum er für benutzerdefinierte Exporte sinnvoll ist. Außerdem stellt er gängige Begriffe vor und führt Schritt für Schritt anhand eines Beispiels durch die Konfiguration. Funktionen und Begriffe entsprechen der aktuellen Implementierung des Ausdrucks-Generators und des zugrunde liegenden Abfragemodells.


Was ist der Ausdrucks-Generator?

Mit dem Ausdrucks-Generator lassen sich Daten für benutzerdefinierte Exporte aufbereiten, ohne Code zu schreiben. Möglich ist Folgendes:

  • Listen auf die gewünschten Elemente filtern
  • Werte aggregieren, z. B. als Summe, Anzahl, Minimum oder Maximum
  • Datumsangaben, Datum/Uhrzeit und Zahlen für das Zielsystem formatieren
  • Ergebnisse bereits während der Konfiguration in der Vorschau anzeigen

Warum ihn verwenden?

  • Flexibilität: Maßgeschneiderte CSV- oder Tabellenausgaben für Partner, BI-Tools oder Finanzsysteme erstellen.
  • Konsistenz: Export-Mappings speichern und teamübergreifend wiederverwenden.
  • Präzision: Direkt beim Export filtern und aggregieren, sodass nachgelagerte Tabellen einfach bleiben.

Begriffe

Begriff Definition
Pfad Ein Verweis auf die zu extrahierenden Daten. Beispiel: trip > charges verweist auf die Liste der Gebühren einer Fahrt.
Filter Eine Bedingung, die eine Liste auf die passenden Elemente eingrenzt. Beispiel: charge_type = “Transport”.
Operator Der in einem Filter verwendete Vergleich, z. B. EQ, NEQ, GT, GTE, LT, LTE, IN, NONE_IN.
Aggregation Eine Möglichkeit, eine Liste auf einen einzelnen Wert zu reduzieren. Zur Auswahl stehen SUM, COUNT, DISTINCT, MIN, MAX, EXISTS, NOT_EXISTS.
Formatierung Einstellungen für die Ausgabedarstellung von Datumsangaben, Datum/Uhrzeit und Zahlen sowie eine optionale Umwandlung in einen String für eine sichere CSV-Ausgabe.
Ausdrucksmodus\
(Erweitert) Ein Editor für Roh-Ausdrücke, der Admins für komplexe Transformationen zur Verfügung steht.
Vorschau Eine Live-Darstellung, die das Ergebnis der Konfiguration vor dem Export anzeigt.

Hinweise und aktuelle Einschränkungen

  • Enum-Werte werden noch nicht übersetzt.
  • Das Filtern innerhalb bestimmter verschachtelter Listen kann Umwege erfordern, wenn kein typisierter Pfad verfügbar ist.
  • Einheitenumrechnungen und „mehrere Felder in einer Spalte zusammenführen“ werden separat verfolgt.

Anleitung: Den Ausdrucks-Generator konfigurieren und verwenden

Im Folgenden wird ein typisches Szenario in zwei Exportspalten umgesetzt: der Export der Summe der Transportgebühren einer Fahrt und eines formatierten Abholdatums mit Uhrzeit.
Vor dem Start:

  • Sicherstellen, dass ein benutzerdefiniertes Export-Mapping geöffnet ist, oder ein neues erstellen.
  • Die Entität bestimmen, aus der exportiert wird, z. B. Aufträge.

Spalte A: Summe der Transportgebühren

  1. Neue Spalte hinzufügen

    1. Name: Total Transport Charge
  2. Pfad auswählen

    1. Pfad: orders > charges
    2. Dieser verweist auf die Liste aller Gebühren der Fahrt.
  3. Filter hinzufügen

    1. Filterpfad: charge_type
    2. Operator: EQ
    3. Wert: Transport
    4. Ergebnis: Nur Gebühren vom Typ Transport werden berücksichtigt.
  4. Aggregation festlegen

    1. Aggregation: SUM
    2. Summiertes Feld: amount
    3. Ergebnis: Summiert den Betrag über die gefilterten Gebühren.
  5. Formatierung

    1. Zahlenformat: #,###.00
    2. In String umwandeln: Ein, um sicherzustellen, dass CSV-Zellen nie leer sind und bei Bedarf als Text behandelt werden.
  6. Vorschau

    1. Mit der Vorschau prüfen, ob die resultierende Zahl den Erwartungen entspricht.

Was dies bewirkt

  • Beginnt mit der Liste der Gebühren
  • Filtert auf charge_type = Transport
  • Summiert den Betrag
  • Gibt einen formatierten String aus, der sich für den CSV-Import in Buchhaltungstools eignet.

Spalte B: Abholdatum/-uhrzeit (US-Format)

  1. Neue Spalte hinzufügen

    1. Name: Pickup Date/time (US)
  2. Pfad auswählen

    1. Pfad: trip > pickup_datetime
  3. Formatierung

    1. Datum-Uhrzeit-Format: yyyy-MM-dd HH:mm:ss
    2. Beispiel: 2025-12-31 16:45:00
    3. In String umwandeln: Ein, um eine einheitliche CSV-Ausgabe zu gewährleisten.
  4. Vorschau

    1. Prüfen, ob Datum und Uhrzeit im gewünschten Format angezeigt werden.

Was dies bewirkt

  • Liest Abholdatum und -uhrzeit der Fahrt und gibt sie in einem klaren, einheitlichen Format für nachgelagerte Tools aus.

Export

  • Das Mapping speichern und den Export ausführen. Die CSV-Datei enthält beide Spalten mit den konfigurierten Transformationsregeln.


Filteroptionen nach Gebührentyp

Filter können jetzt auf Ausdrücke angewendet werden, die auf Gebühren verweisen. So lässt sich genau steuern, welche Gebühren in die Berechnung einfließen.

1. Zuschläge – jetzt vollständig unterstützt

Bisher stellte der Datenfeed nur Index-Zuschläge (Kraftstoffzuschläge) bereit, sodass die Logik in der UI und im Export nicht übereinstimmte.
Der Ausdrucks-Generator unterstützt jetzt zwei Konfigurationsoptionen:

  • Zuschläge (alle Typen)
    Umfasst alle in der UI verwendeten Zuschlagstypen:

    • Allgemeine Zuschläge
    • Index-Zuschläge (FSC)
    • Alle künftigen Zuschlagstypen
  • Sonstige Zuschläge (ohne FSC)
    Gedacht für Fälle wie Mulgrews, in denen der FSC nicht mit den übrigen Zuschlägen zusammengefasst werden soll.

So können Teams das Verhalten wählen, das zu ihrem Reporting-Modell passt.

2. Umsatz aus Extras (neue Kategorie)

Extras kann jetzt als eigene Kategorie ausgewählt werden.
Extras umfassen:

  • Alle Gebühren, bei denen addon_type ≠ surcharge
  • Alle Ad-hoc-Gebühren

Damit lässt sich einfach „der gesamte Umsatz außer Transport/Kraftstoff“ berechnen oder über sonstige Gebührenpositionen berichten.

3. Einheitliche Filterung in UI und Export

Der Ausdrucks-Generator verwendet jetzt dieselbe Logik zur Gebührenfilterung wie die Preisberechnungs-UI von Qargo, einschließlich:

  • Herausfiltern genehmigter DONT_INVOICE-Gebühren
  • Korrekte Behandlung von Transportgebühren
  • Vollständige Übereinstimmung mit dem bestehenden Frontend-Verhalten

So ist sichergestellt, dass das, was Nutzer in der UI sehen, mit dem übereinstimmt, was sie in Exporten und automatisierten Berechnungen erhalten – ohne Überraschungen.

4. Dokumente einbeziehen

Nutzer können jetzt Dokumentdetails in Berichte aufnehmen. Dazu dient die Aggregationsoption „Exists“ im Ausdrucks-Generator. Zu den Details gehören:

  • Name, Beschreibung, Datums- und Zeitstempel

  • Mit der Aggregation „Exists“ wird die Spalte mit den Werten „true/false“ hinzugefügt

    • True = Dokumente an den Auftrag angehängt
    • False = keine Dokumente an den Auftrag angehängt

Tipps

  • Mit einem Pfad und einem einzelnen Filter beginnen, dann Aggregation und Formatierung hinzufügen, sobald die Vorschau stimmt.
  • COUNT oder EXISTS verwenden, wenn ein Ja/Nein oder eine einfache Anzahl an Treffern benötigt wird.
  • DISTINCT verwenden, um Werte beim Export von Listen in eine einzelne Zelle zu deduplizieren.

Erweitert: Ausdrucksmodus

Admins des Arbeitsbereichs können in einen Modus für Roh-Ausdrücke wechseln, um komplexe Logik direkt zu schreiben. Das ist nützlich für Sonderfälle, in denen der formularbasierte Generator zu eingeschränkt ist. Gespeicherte Ausdrücke sollten im Hinblick auf die Wartbarkeit dokumentiert werden.


Fehlerbehebung

  • Leere Zellen: In String umwandeln aktivieren, damit leere Werte von Tabellenkalkulationsprogrammen nicht falsch interpretiert werden.
  • Unerwartete Summen: Filteroperator und Schreibweise des Werts prüfen. Sicherstellen, dass der Pfad auf die gewünschte Liste verweist.
  • Datumsformatierung: Den Formatstring für Datum/Uhrzeit prüfen und kontrollieren, ob das Quellfeld ein Datum oder ein Datum mit Uhrzeit enthält.