Skip to main content
Qargo

Dokumentvorlagen: was, warum und wie

Dieser Artikel bietet einen Leitfaden zu Dokumentvorlagen: was sie sind und wie sie eingerichtet und verwendet werden.

Inhaltsverzeichnis
  1. Zusammenfassung
  2. Terminologie
  3. Aufbau einer Vorlage
  4. Bearbeitungssymbole
  5. Neue Vorlage hinzufügen
  6. Zeilen gruppieren und Zwischensummen
  7. Fehlerbehebung in der Praxis: Beispiele für Rechnungsvorlagen

Zusammenfassung

  • Was ist eine Qargo-Vorlage?

    • Anpassbare, wiederverwendbare Vorlage zum Erstellen von Geschäftsdokumenten wie Rechnungen, Lieferscheinen, Ladungsblättern, Angeboten usw.
    • Kann in Aufgaben verwendet werden, um Dokumente automatisch zu erstellen und/oder zu versenden.
  • Warum Vorlagen verwenden?

    • Mit Vorlagen legen Nutzer fest, wie Dokumente aussehen und welche Daten sie enthalten.
    • Jedes Unternehmen kann Dokumente im bevorzugten Format erstellen, abgestimmt auf die eigenen Arbeitsabläufe, die Sprache und das Branding.
    • Stellt sicher, dass alle erforderlichen Daten dynamisch aus dem TMS ausgefüllt werden.
  • Wie werden Vorlagen verwendet?

    • Zum Erstellen von Dokumenten, die mit Aufträgen und Fahrten verknüpft sind.
    • In Kombination mit Workflow-Aufgaben lassen sich Dokumente nahtlos zum passenden Zeitpunkt erstellen.
    • Die automatische Erstellung reduziert Fehler bei der Dateneingabe. In Kombination mit Kontaktaufgaben steigert sie die Effizienz der Arbeitsabläufe, z. B. beim Versand von POD oder Rechnung per E-Mail.

Beispiel: Aufgaben vom Typ „Dokument erstellen“

  • 3 Kernkomponenten:

    • Handlebars-Vorlage: dynamische Platzhalter zum Einfügen von Daten
    • Vorlagenschema: strukturierte Definition aller in der Vorlage verfügbaren dynamischen Felder; kann Listen, Tabellen, Text usw. enthalten
    • Datenmodell: die tatsächlichen Daten, die beim Erstellen an die Vorlage übergeben werden (z. B. Auftragswert)
  • Die Felder im Vorlagenschema legen fest, welche dynamischen Datenelemente abgerufen und angezeigt oder wiederholt werden können.

    • Möglich sind einfache Felder, z. B. „Titel“, oder komplexere Felder für Listen und Tabellen, die Parameter benötigen.
  • Vorlagen lassen sich durch Bearbeiten der Schemas und des visuellen Layouts konfigurieren.

    • Anzuzeigende Felder auswählen und Logik festlegen (z. B. If/Else, Bedingungen usw.)
  • Dokumenterstellung: Die Vorlage ruft die neuesten Daten ab und füllt die dynamischen Felder gemäß Vorlagenschema und Datenmodell aus.

    • Das Ergebnis ist ein sofort verwendbares Dokument im gewünschten Format (z. B. PDF, CSV).
  • Vorlagen können global oder mandantenspezifisch sein.

    • Globale Vorlage = Basislayout, das überschrieben oder um eigene Variablen erweitert werden kann
    • Mandantenvorlage = auf besondere Anforderungen zugeschnitten, z. B. zur Erfüllung rechtlicher oder regulatorischer Vorgaben
  • Unterstützte Funktionen in Vorlagen:

    • Mehrsprachigkeit (Lokalisierung), sofern aktiviert
    • Tabellen und kontextspezifische Schleifen
    • Benutzerdefinierte Hilfsfunktionen (z. B. zum Formatieren von Datumsangaben, Barcodes usw.)
    • Behandlung von Sonderfällen und Bedingungen, z. B.: Feld nicht anzeigen, wenn es leer ist
    • Anhänge oder Bilder, z. B. Unterschriften
  • Handlebars-Ausdrücke ermöglichen erweiterte Logik.


Terminologie

Begriff Definition
Qargo-Vorlage: Standardisierte, globale Vorlagenversionen, die von Qargo bereitgestellt und gepflegt werden. Sie dienen als Referenzbibliothek und lassen sich bei Bedarf einfach an Branding, Sprache, besondere Datenanforderungen usw. anpassen.
Mandantenvorlage Angepasste Vorlage, die spezifisch für den Mandanten (das Konto) ist
Externe Vorlage Dokumentvorlagen aus einer externen Quelle, die verwendet oder referenziert werden können. Dazu gehören z. B. von mehreren Organisationen oder Standorten gemeinsam genutzte Vorlagen, branchenübliche Formate oder aus externen Systemen importierte Vorlagen, z. B. Gutschriften, Eigenrechnungen, Fahrtblätter, CMRs.
Basisvorlage Allgemeine Vorlage, auf deren Grundlage eine neue Dokumentvorlage erstellt wird. Sie wird aus einer Dropdown-Liste vordefinierter Optionen ausgewählt, abhängig von der Kategorie des zu erstellenden Dokuments, z. B. „Rechnung“.
Archivierte Vorlage Vorlagen, die in der Plattform nicht mehr unterstützt werden; meist durch eine aktualisierte Version ersetzt.
Handlebars-Ausdruck Handlebars-Ausdrücke sind spezielle Platzhalter und Logikblöcke in Vorlagen. Sie fügen beim Erstellen von Dokumenten oder E-Mails Daten ein und ergänzen bedingte oder wiederholende Logik.
Kontext-Markierung (blau) Wird im Vorlageneditor neben bestimmten Feldern oder Zeilen angezeigt. Sie zeigt an, dass das Feld an einen bestimmten Teil der zugrunde liegenden Daten gebunden ist, z. B. an Stopps, die dann als eine Zeile pro Stopp erscheinen.


Aufbau einer Vorlage

Beim Hinzufügen einer neuen Vorlage muss zuerst eine Basisvorlage ausgewählt werden. Danach werden die Datenzeilen und der Vorschaubereich (Nr. 3 Visualisieren) angezeigt. Die Vorlage erscheint zunächst mit allgemeinen Beispieldaten.

  1. Auf der Seite Neue Vorlage die passende „Basisvorlage“ aus der Dropdown-Liste auswählen.
  2. Die neue Vorlage konfigurieren. Der neuen Vorlage einen Namen geben, an dem sich der Anwendungsfall leicht erkennen lässt. Felder ändern, um die Vorlage anzupassen, oder die Basisvorlage unverändert verwenden.
  3. Das Vorlagenformat im Vorschaubereich visualisieren. Ein Klick auf ein Element im Vorschaubereich hebt die zugehörige Datenzeile hervor. Wenn die angezeigten Daten geändert werden müssen, in die Zeile klicken.
  • Die Vorlagendaten bearbeiten, indem in die entsprechende Zeile geklickt und der Inhalt bearbeitet wird.

    • Ein Klick in die Zeile oder auf das Augensymbol hebt die Daten dieser Zeile im Vorschaubereich hervor.
    • Ein Klick auf Informationen im Vorschaubereich hebt die entsprechende Zeile hervor, in der die Daten bearbeitet werden können.
    • Über das Feld „Dateneigentümer“ lassen sich Live-Daten anzeigen. Die angezeigten Optionen beziehen sich speziell auf das Dokument. Im folgenden Beispiel handelt es sich um einen Rechnungsvorschlag, daher zeigt das Feld „Dateneigentümer“ Einkaufsrechnungen als Optionen an.

Bearbeitungssymbole

  • Ein Klick in eine Zeile zum Bearbeiten von Details zeigt eine Auswahl an Bearbeitungsoptionen an.

  1. Optionen zur Textbearbeitung, darunter fett, kursiv und unterstrichen sowie Schriftgröße und -farbe. H und h formatieren die Daten als Überschrift 1 (H) bzw. Überschrift 2 (h).
  2. Einen URL-Link zu einer Website hinzufügen. Dazu öffnet sich ein Pop-up-Fenster.
  3. Daten als Aufzählungspunkte oder nummerierte Liste hinzufügen.
  4. Syntaxblöcke zum Erstellen komplexerer Bedingungen mit Ausdrücken, die mehrere Variablen oder Bedingungen kombinieren.
  5. Formatierungsoptionen zum Einfügen eines Seitenumbruchs oder HTML-Blocks

Syntaxblöcke verwenden

  • Beim Bearbeiten einer Vorlage stehen Syntaxoptionen zur Verfügung, mit denen sich Vorlagen für bestimmte Bedingungen erstellen lassen.

Handlebars-Ausdrücke

  • Handlebars-Ausdrücke dienen zur Auswahl von Variablen, die mit dem Dokument verknüpft sind. Die in der Dropdown-Liste angezeigten Variablen sind spezifisch für das Dokument und die zugehörige Zeile.

IF-Block

  • Der IF-Block wird in einer Dokumentvorlage verwendet, um bestimmte Inhalte oder Formatierungen nur unter bestimmten Bedingungen anzuzeigen, abhängig von den Daten. So lässt sich z. B. ein Feld nur anzeigen, wenn es nicht leer ist, oder eine Zeile nur hervorheben, wenn ein Wert einen Schwellenwert überschreitet.⁠⁠​

  • Häufige Szenarien:

    • Gebühren mit Betrag 0 ausblenden: Mit einem IF-Block wird eine Gebühr nur angezeigt, wenn ihr Wert größer als null ist.
    • Inhalte bedingt anzeigen: z. B. eine Notiz oder einen Abschnitt nur anzeigen, wenn ein Feld einen bestimmten Text enthält (etwa einen bestimmten Subunternehmernamen oder einen ausgefüllten Kommentar).
    • Bedingte Formatierung: Text fett darstellen oder besondere Stile anwenden, wenn ein Wert eine Bedingung erfüllt (z. B. einen Standort fett darstellen, wenn eine zugehörige Notiz vorhanden ist).⁠⁠​

FOR-Block

  • Der FOR-Block ist eine leistungsstarke Funktion im Qargo-Dokumentvorlageneditor und ermöglicht eine dynamische, datengesteuerte Dokumenterstellung.

  • Um alle Produkte eines Auftrags aufzulisten, jeweils mit Produkt und Beschreibung in einer neuen Zeile, einen FOR-Block für das Warenarray hinzufügen und die Produktdetails innerhalb des Blocks platzieren. Der FOR-Block stellt sicher, dass jedes Produkt im fertigen Dokument eine eigene Zeile erhält⁠⁠.

COMBINE-Anweisung

  • Der COMBINE-Block wird verwendet, wenn in der Vorlage eine zusammengeführte oder aggregierte Liste aus einem Array angezeigt werden soll, z. B. um eine Liste von Werten zu einer kommagetrennten Zeichenfolge zu verbinden.

  • Anders als ein FOR-Block, der jedes Element durchläuft und Inhalte wiederholt ausgibt, verarbeitet der COMBINE-Block das Array zu einem einzigen Ergebnis. Meist werden die Elemente dazu verkettet oder auf andere Weise aggregiert.

  • Eine wichtige Einschränkung: Innerhalb eines COMBINE-Blocks sind keine IF-Anweisungen (bedingte Logik) möglich. Der COMBINE-Block eignet sich daher am besten für einfache Aggregationen ohne Bedingungen auf Elementebene.


Neue Vorlage hinzufügen

  • Zu Konfiguration > Vorlagen navigieren.

  • Auf „Vorlage hinzufügen“ klicken.

  • Den Dokumenttyp aus der Dropdown-Liste auswählen.

    • Hinweis: Möglicherweise stehen weitere Optionen zur Verfügung, z. B. bietet „Rechnung“ die Wahl zwischen Rechnung und Gutschrift, „Ladungsblatt“ die Wahl zwischen Fahrt und Ressource.
  • Eine Basisvorlage aus der Dropdown-Liste auswählen.

  • Ein Klick in das Feld „Dateneigentümer“ im Bereich „Visualisieren“ zeigt passende Datensätze für diesen Dokumenttyp an. Wird einer davon ausgewählt, zeigt die Vorlagenvorschau Kundendaten an.

    • Wenn die Basisvorlage alle Daten im gewünschten Layout enthält, der Vorlage einen Namen geben und auf Speichern klicken.
  • Wenn das Vorlagenlayout geändert werden muss, die Daten über die Zeilen im Bereich „Konfigurieren“ aktualisieren.

Vorlage ändern

  • Das Vorlagenformat ist entweder HTML oder PDF.

  • Bei PDF stehen zusätzliche Formatierungsoptionen zur Verfügung. Dazu die Zeile „PDF-Konfiguration“ aufklappen.

    • Änderungen im Konfigurationsbereich werden im rechten Bereich in der Vorschau angezeigt.

  • Um einzelne Elemente zu ändern, auf das Element klicken. Dadurch wird die Zeile hervorgehoben, in der die Änderung vorgenommen werden muss.

    • In die Zeile klicken, um die Bearbeitungsoptionen anzuzeigen.
    • Die passende Aktion aus den Optionen auswählen.
    • Nach der Auswahl werden die geänderten Daten zur Bestätigung im Vorschau- bzw. Visualisierungsfenster aktualisiert.
  • Mit der Option „Hintergrund“ einen vorhandenen Briefkopf hochladen, der als Hintergrundlayout einer Rechnung dient.

  • Sobald die Vorlage dem gewünschten Layout und Inhalt entspricht, auf Speichern klicken.


Sortierreihenfolge der Zeilen konfigurieren

Im Dokumentvorlageneditor lassen sich Zeilen jetzt nach einem ausgewählten Feld sortieren. Jedes PDF, das aus dieser Vorlage erstellt wird, folgt dieser Reihenfolge: Ausgangsrechnungen, Gutschriften, Eigenrechnungen für Subunternehmer, Rechnungsvorschläge und Fahrtexporte. Die Einstellung wird einmal in der Vorlage festgelegt und gilt jedes Mal.

Bisher wurden Zeilen immer in derselben festen Reihenfolge ausgegeben (nach der geplanten Startzeit des ersten Stopps, dann nach Gebührenname), ohne dass sich dies ändern ließ. Diese Reihenfolge ist jetzt konfigurierbar.

Sortierschlüssel festlegen

  1. Navigieren zu Konfiguration > Vorlagen und die zu bearbeitende Vorlage öffnen oder eine neue hinzufügen.
  2. Den Block für die Zeileniteration auswählen, der die Auftrags- oder Gebührenzeilen ausgibt.
  3. Im Abschnitt Sortierung unter Sortieren nach das Feld festlegen, nach dem sich das Dokument richten soll, und dann als Richtung Aufsteigend oder Absteigend wählen.
  4. Optional ein zweites Sortieren nach als Kriterium bei Gleichstand hinzufügen, z. B. zuerst den Fahrernamen und danach den geschätzten Startzeitpunkt.
  5. Die Vorlage speichern. Jedes aus dieser Vorlage erstellte PDF berücksichtigt dann die konfigurierte Sortierung.

Verfügbare Sortierschlüssel

Welche Schlüssel angeboten werden, hängt vom Zeilentyp ab, den der ausgewählte Block ausgibt.
Für Auftragszeilen (Vorlagen für Ausgangsrechnungen und Gutschriften):

  • Auftragsnummer
  • Kundenreferenz
  • Liefertermin (gewünscht)
  • Liefertermin (tatsächlich)
  • Abholtermin (gewünscht)
  • Abholtermin (tatsächlich)
  • Zeitstempel des letzten Sendungsstopps (die bisherige Standardeinstellung)

Für Gebührenzeilen (Vorlagen für Einkaufsrechnungen und Rechnungsvorschläge bzw. Eigenrechnungen):

  • Fahrername
  • Ressourcenname (Fahrzeug)
  • Fahrtnummer
  • Geschätzter Startzeitpunkt (die bisherige Standardeinstellung)
  • Gebührenname

Vorlagen für Fahrtexporte bieten zusätzlich Fahrzeug und Fahrer als Sortierschlüssel.

Häufige Anwendungsfälle

  • Eine Ausgangsrechnung, sortiert nach Kundenreferenz oder Liefertermin, damit Kunden sie mit ihren eigenen Unterlagen abgleichen können.
  • Eine Eigenrechnung für Subunternehmer oder ein Rechnungsvorschlag, gruppiert nach Fahrername (primär) und dann chronologisch nach Geschätzter Startzeitpunkt (sekundär), sodass die Fahrten jedes Fahrers zusammenstehen.
  • Ein Fahrtexport, gruppiert pro Fahrzeug, mit Ressourcenname (Fahrzeug) als Sortierschlüssel.

Zeilen gruppieren und Zwischensummen

Rechnungsvorlagen können Gebührenzeilen in Blöcken ausgeben, mit einer Zwischensumme unter jedem Block. Das hilft Kunden und Subunternehmern, die eine Summe pro Lkw, pro Fahrer, pro Auftrag oder pro Fahrt benötigen, ohne sie von Hand zu berechnen. Die Gesamtsumme steht immer am Ende des Dokuments.

Es stehen zwei Optionen zur Verfügung:

  • Zwei Basisvorlagen mit gruppierten Zeilen, die Zeilen nach einem gewählten Schlüssel gruppieren.
  • Eine optionale Zwischensummenzeile nach jedem Auftrag oder jeder Fahrt in den bestehenden Rechnungsvorlagen.

Zeilen nach Auftrag, Fahrt, Fahrzeug oder Fahrer gruppieren

  1. Zu Konfiguration > Vorlagen navigieren und auf Vorlage hinzufügen klicken.

Die Seite „Vorlagen“ mit der Schaltfläche „Vorlage hinzufügen“

  1. Den Dokumenttyp auswählen und dann die Basisvorlage wählen: Rechnungsvorlage – gruppierte Zeilen für Ausgangsrechnungen und Gutschriften oder Einkaufsrechnungsvorlage – gruppierte Zeilen für Rechnungsvorschläge und Eigenrechnungen.

Auswahl des Dokumenttyps

Die Liste der Basisvorlagen mit Rechnungsvorlage – gruppierte Zeilen

  1. Vorlagenoptionen aufklappen und Einstellungen zur Zeilengruppierung öffnen.
  2. Zeilen gruppieren nach auf den Schlüssel setzen, dem das Dokument folgen soll.

Das Feld „Zeilen gruppieren nach“ in den Einstellungen zur Zeilengruppierung

  1. Die Vorlage speichern. Jedes aus ihr erstellte Dokument gibt einen Block pro Gruppe aus.

Vorschau einer nach Auftrag gruppierten Ausgangsrechnung mit einer Zwischensumme unter jedem Auftrag

Welche Schlüssel angeboten werden, hängt vom Dokument ab:

  • Ausgangsrechnungen und Gutschriften: Auftrag, Fahrzeug und Fahrer.
  • Rechnungsvorschläge und Eigenrechnungen: Fahrt, Auftrag (der Kostenauftrag der Zeile), Fahrzeug und Fahrer.

Die Optionen unter „Zeilen gruppieren nach“ in einer Einkaufsrechnungsvorlage: Fahrer, Auftrag, Fahrt und Fahrzeug

Jeder Block hat eine Kopfzeile (zum Beispiel die Auftragsnummer, das Kennzeichen oder den Fahrernamen), seine Gebührenzeilen und eine Zwischensumme. Zwischensummen werden standardmäßig ausgegeben. Um sie auszublenden, das Feld group_subtotal_label in der Vorlage leeren. Gruppenköpfe und Zeilen bleiben bestehen.

Das Feld group_subtotal_label und die Zwischensummenzeile in der Vorschau

Zeilen ohne Wert für den gewählten Schlüssel werden in einem Block am Ende des Dokuments mit eigener Zwischensumme zusammengefasst. Der Block ist nach dem Schlüssel benannt: „Kein Fahrzeug zugewiesen“ oder „Kein Fahrer zugewiesen“.

So werden Zeilen einem Fahrzeug oder Fahrer zugeordnet:

  • In Verkaufsdokumenten wird ein Auftrag nie auf zwei Gruppen aufgeteilt. Alle seine Gebührenzeilen werden unter dem Fahrzeug oder Fahrer des Lieferstopps ausgegeben.
  • Fahrzeug bedeutet die primäre Sattelzugmaschine, den Lkw ohne Anhänger oder den Van. Ein Trailer wird nie als Gruppe verwendet.
  • Eine Fahrt mit zwei primären Sattelzugmaschinen zeigt beide Kennzeichen in einer Kopfzeile. Dasselbe gilt für zwei primäre Fahrer.

Zwischensummenzeile in bestehenden Rechnungsvorlagen hinzufügen

Die bestehenden Vorlagen für Ausgangsrechnungen (1, 2 und 3 Spalten, Gesamtsumme mit Details sowie Gesamtsumme mit gruppierten Gebühren und Details) und die passenden Vorlagen für Einkaufsrechnungen können nach jedem Auftrag (Verkauf) oder jeder Fahrt (Einkauf) eine Zwischensummenzeile ausgeben.

  1. Zu Konfiguration > Vorlagen navigieren und die zu ändernde Vorlage öffnen.
  2. order_subtotal_label in Verkaufsvorlagen oder shipment_subtotal_label in Einkaufsvorlagen ausfüllen, zum Beispiel mit „Zwischensumme“.

Das Feld order_subtotal_label in einer Vorlage für Ausgangsrechnungen

  1. Die Vorschau im Bereich Visualisieren prüfen. Die Zeile erscheint unter der letzten Gebührenzeile jedes Auftrags oder jeder Fahrt, im selben Spaltenlayout wie die Gebührenzeilen.
  2. Die Vorlage speichern.

Beide Felder sind standardmäßig leer, sodass sich bestehende Dokumente erst ändern, wenn eine Bezeichnung eingetragen wird. Um die Zeile wieder zu entfernen, das Feld vollständig leeren.

Gut zu wissen

  • Es gibt keine Seitensumme und keine Einstellung für die Zeilen pro Seite. Eine mehrseitige Rechnung zeigt ihre Gesamtsumme nur auf der letzten Seite.
  • Es gibt keinen Zusammenfassungsblock, der die Summe jeder Gruppe vor den Detailzeilen auflistet.

Fehlerbehebung in der Praxis: Beispiele für Rechnungsvorlagen

  • Hintergrund wird nicht angezeigt: Prüfen, ob das Dateiformat einem unterstützten Typ entspricht, und sicherstellen, dass die Option „In PDF anzeigen“ beim Bearbeiten aktiviert ist.

  • Fehler Preview could not be rendered or updated. Please verify that all open '#{{' tags have a corresponding '}}' tag.: Dies kann darauf hindeuten, dass die Vorschau aufgrund der Größe des Dokuments nicht dargestellt werden kann. Mit einem kleineren Dokument (nur wenige Aufträge) testen, ob die Vorschau funktioniert. Die Dokumenterstellung selbst ist davon nicht betroffen.

  • Probleme beim Entfernen von Elementen: Wenn unerwünschte Elemente wie eine E-Mail-Adresse Teil einer Hintergrunddatei sind, diese Datei extern bearbeiten, z. B. mit einem PDF-Editor, und sie anschließend erneut in den Konfigurationseinstellungen der Vorlage hochladen.

  • Wiederkehrende Probleme mit dem Hintergrund: Änderungen an der Hintergrunddatei immer speichern, bevor sie erneut hochgeladen wird, und die Aktualisierung über die Vorschaufunktion prüfen.

  • Falsche Referenznummern: So wird die Referenznummer aktualisiert, die auf Rechnungen erscheint:

    1. In Qargo zum Bereich Vorlagen navigieren.
    2. Die Vorlage öffnen, die für die Rechnungen des betreffenden Kunden verwendet wird.
    3. In das Adressfeld klicken. Dadurch wird im linken Bereich das Feld hervorgehoben, in dem die Referenz gespeichert ist.
    4. Die Referenznummer auf den gewünschten Wert ändern.
    5. Die Vorlage speichern. Die aktualisierte Referenz gilt für alle neu erstellten Rechnungen. Hat eine Rechnung bereits den Status „Fakturiert“, lässt sich das PDF aktualisieren, indem das Rechnungs-PDF erneut ausgelöst wird, um sicherzustellen, dass die neue Referenz erscheint.
  • Kundenreferenzen im Peppol-XML prüfen: So lässt sich bestätigen, dass eine Kundenreferenz im Peppol-XML einer Rechnung enthalten ist:

    1. Die Rechnung in Qargo öffnen.
    2. Die Peppol-XML-Vorschau aufrufen.
    3. Mit der Suchfunktion nach dem Referenzwert suchen, indem die erwartete Referenznummer eingefügt wird.
    4. Prüfen, ob die Referenz im XML im rechten Vorschaubereich erscheint.