Vorlagenformat

Aufbau auf einen Blick

Eine Vorlage ist ein JSON-Objekt. Die wichtigsten Schlüssel an der Wurzel:

• name, culture und die Zahlen- und Datumseinstellungen,
• page: Blattgröße und Ränder,
• brand: Standardschrift und Zeilenabstand,
• sources: die Datenquellen mit Beziehungen und Regeln,
• variables: eigene Variablen,
• body: alles, was auf dem Blatt steht (Texte, Bilder, Codes, Gruppen, Tabellen, Formen, Seitenumbrüche),
• eRechnung: wenn eingeschaltet, die E-Rechnung zum Beleg (Zuordnung zu einem Standard).

{
  "name": "Sample",
  "culture": "en-US",
  "page": { "widthMm": 210, "heightMm": 297 },
  "body": []
}

Grundregeln

• Schreibweise: Schlüssel in camelCase, genau wie in den Tabellen. Der Druck liest viele Schlüssel auch in anderer Groß- und Kleinschreibung, der Designer nicht. Werte von type (zum Beispiel "Group") unterscheiden Groß und Klein immer.
• Einheiten: Lagen und Größen in Millimetern (Schlüssel enden auf Mm), Strichstärken und Schriftgrößen in Punkt (Pt), Drehung in Grad (rotDeg).
• Zahlen als Zahlen: "xMm": 10, nicht "xMm": "10". Nur unter page wandelt der Designer Zahlentext um.
• Farben: #RGB, #RRGGBB oder #RRGGBBAA (das # darf fehlen) oder eine Farbvariable {{@Name}}. Farbnamen wie red gelten als »keine Farbe« und werden gemeldet.
• Fehlt ein Schlüssel, gilt seine Vorgabe. null überschreibt keine Vorgabe.
• Unbekannte Schlüssel sind kein Fehler, sie wirken aber nicht. Der Druck meldet sie als Warnung (an der Wurzel, unter page und page.margins, an jedem Objekt, in style, columns[], variables[] und sources[]). Unter brand, page.border, rows, cells, bild, anchor, sorts, borders, variants, in Wenn-Dann-Zweigen sowie in relations[], fields[] und rules[] (samt select, group, vars) werden sie still übergangen.
• Schlüssel mit _ am Anfang sind Vermerke des Designers. Sie wirken nicht und werden nicht gemeldet (außer unter page und page.margins). Schreiben Sie keine eigenen.
• Strenges JSON: keine Kommentare, kein Komma am Ende, ohne BOM. Höchstens 128 JSON-Ebenen; jede Gruppe zählt zwei, das reicht für rund 60 ineinanderliegende Gruppen.

Die Wurzel

Diese Schlüssel kommen vor, sollen aber nicht geschrieben werden: templateId, version, rendererVersion und dataSource (ohne Wirkung), warmhalten und istAktiv (Spiegel von Spalten des Datensatzes), pageHeader und pageFooter (Altform, wird beim Lesen zu Wiederhol-Gruppen umgebaut).

Blatt und Ränder (page)

Schrift und Zeilenabstand (brand)

logoAssetId, accentColor, accentColor2 und headingColor kommen in älteren Vorlagen vor und wirken auf den Druck nicht.

Werte mit Wenn-Dann

currencySymbol, currencyDecimals, numberStyle, thousandSeparator, optionLabelLanguage und pdfName stehen als Objekt mit festem Wert und Zweigen. Ein blanker Wert ("currencySymbol": "$") wird ebenfalls gelesen und gilt als fester Wert ohne Zweige.

"currencySymbol": { "value": "€", "rules": [ { "when": "country == 'US'", "value": "$" } ] }

• Ausgewertet wird einmal je Dokument am Hauptdatensatz.
• In der Bedingung gelten auch eigene Variablen (@Name), im Wert ebenso ({{@Name}}). Hängt eine solche Variable selbst von dieser Einstellung ab (Kreis), gilt die Wahl mit den festen Werten der Vorlage, und das Dokument meldet eine Warnung (»template setting '…' is circular«).
• Ein zutreffender Zweig mit leerem Wert liefert die eingebaute Vorgabe (€, 2 Stellen, Stil der Sprache, bei optionLabelLanguage die Sprache aus culture, bei pdfName den Namen der Vorlage wie im E-Mail-Anhang), nicht den festen value.
• optionLabelLanguage mit { "value": "", "rules": [ { "when": "country == 'US'", "value": "1033" } ] } druckt die Optionslabels für Kunden in den USA englisch, sonst in der Sprache aus culture.
• pdfName mit { "value": "Rechnung {{invoicenumber}}", "rules": [ { "when": "country == 'US'", "value": "Invoice {{invoicenumber}}" } ] } nennt die Datei für Kunden in den USA Invoice_R-1.pdf, sonst Rechnung_R-1.pdf.
• Der Haken »Währung aus dem Datensatz übernehmen« hat keinen eigenen Schlüssel. Er besteht aus einer Beziehung der Hauptquelle mit "kind": "lookup" auf transactioncurrency (vom deutschen Designer Waehrung genannt) und dem festen Wert {{Waehrung.currencysymbol}} in currencySymbol sowie {{Waehrung.currencyprecision}} in currencyDecimals; trägt die Beziehung einen anderen Namen, steht dieser im Platzhalter. Der Designer erkennt den Haken an dieser Beziehung und am Platzhalter in currencySymbol. Lassen Sie beides stehen.

Eigene Variablen (variables)

Eine eigene Variable hat überall im Dokument einen einzigen Wert. Im Text heißt sie {{@Name}}, in Bedingungen @Name.

• Alle eigenen Variablen werden einmal je Dokument am Hauptdatensatz gerechnet, nachdem die Daten geladen sind und bevor die erste Regel läuft. Sie sehen deshalb keine Regel-Ergebnisse.
• Ein Kreis (A liest B, B liest A) macht alle Beteiligten leer und wird gemeldet.
• Anzeige je Typ: number im Zahlenstil, currency mit Symbol, date im dateFormat, boolean als Ja/Nein der Vorlagensprache, text und color wörtlich.

"variables": [
  { "name": "PaymentTerms", "type": "text", "default": "14 days",
    "rules": [ { "when": "totalamount > 1000", "value": "30 days" } ] },
  { "name": "Gross", "type": "currency", "default": "{{sum(quote_details.baseamount)}} * 1.19" },
  { "name": "Due", "type": "date", "default": "{{dateadd(createdon, 30, day)}}" }
]

Datenquellen (sources)

sources ist eine Liste von Quellen. Die Hauptquelle ist der Datensatz, für den gedruckt wird (zum Beispiel ein Angebot). Weitere Quellen sind Listen, die unabhängig davon geladen werden (zum Beispiel alle Währungen). Unter jeder Quelle hängen Beziehungen, unter Quellen und Beziehungen hängen Regeln.

Quelle

set, nameAttr, locked, sampleName und sampleMissing pflegt der Designer selbst.

Feld

Beziehung

Fehlt name oder entity, wird die Beziehung still übersprungen; fehlt refAttr, mit Hinweis. Fehlt kind oder steht dort etwas anderes als collection, gilt sie als N:1. Geben Sie deshalb immer alle vier an. Geholt wird eine Beziehung nur, wenn etwas darin gebunden ist. Beziehungen werden höchstens sechs Ebenen tief geladen.

Regel

Eine Regel nimmt die Zeilen einer Liste (Beziehung collection oder weitere Quelle) und filtert, fasst zusammen, sortiert und wählt aus. Ihr Ergebnis liegt als Geschwister der Beziehung am Elternknoten unter dem Regelnamen.

Reihenfolge in einer Regel: Filter → Zusammenfassen und Berechnungen → Sortieren → Auswählen → Regel-Variablen. Nach group gibt es nur noch die by-Felder und die Berechnungen.

Wo das Ergebnis einer Regel liegt

Was eine Regel sehen darf

• Erlaubt: die eigene Zeile, Felder über Verweise, Felder der Elternzeilen bis zur Wurzel, Zusammenfassungen über eigene Unterlisten, Ergebnisse von Regeln darunter und auf derselben Beziehung, eigene Variablen, System.*.
• Verboten: Ergebnisse von Regeln weiter oben, auch die Ergebnisse von Regeln an einer Quelle (sie liegen an der Wurzel und gelten als »über allem«), die Regel selbst, Kreise. Ein Bezug nach oben wird gelöscht und gemeldet. Ein Kreis schaltet alle Regeln ab.
• Eine weitere Quelle wird immer ganz geladen; die Regel kürzt erst danach.
• Eine Regel rechnet nur, wenn ihr Ergebnis irgendwo gebunden ist (Tabelle, Platzhalter, andere Regel).
• Leer bleibt leer: Steht ein Feld auf der Zeile, ist aber leer, gilt das für diese Zeile, auch für seinen Rohwert <feld>_code; ein gleichnamiges Feld weiter oben springt nicht ein. Weiter oben gesucht wird nur, was die Zeile gar nicht hat.

"sources": [ {
  "id": "src1", "name": "Quote", "entity": "quote", "primary": true, "basePath": "", "idAttr": "quoteid",
  "fields": [ { "name": "name" }, { "name": "totalamount" } ],
  "relations": [ {
    "name": "quote_details", "kind": "collection", "entity": "quotedetail", "refAttr": "quoteid",
    "fields": [ { "name": "productdescription" }, { "name": "quantity" }, { "name": "baseamount" }, { "name": "sequencenumber" } ],
    "rules": [ { "id": "r1", "name": "Items", "filterExpr": "",
                 "select": { "mode": "", "sorts": [ { "by": "sequencenumber", "dir": "asc" } ] }, "vars": [] } ]
  } ],
  "rules": []
} ]

Eine Tabelle auf dieser Regel hat "itemsPath": "Items".

Platzhalter

Ein Platzhalter steht in doppelten geschweiften Klammern im Text: {{…}}. Pfade unterscheiden Groß und Klein und bestehen aus Buchstaben, Ziffern und _, getrennt durch Punkte.

Formatierer

Ohne Formatierer druckt ein Datum als ISO-Text und eine Zahl mit Punkt. Auswahl- und Ja/Nein-Felder aus Dynamics erscheinen mit ihrer Beschriftung (»Ja«/»Nein«, »Bezahlt«) in der Sprache der Optionslabels; echte Wahrheitswerte (_code, Regel-Variablen ohne Typ) erscheinen als True/False, eine Regel-Variable vom Typ boolean mit einem Wahrheitswert als »Ja«/»Nein« der Vorlagensprache (ihr Rohwert steht unter <Name>_code). Formatieren Sie deshalb immer. Die Namen unterscheiden Groß und Klein.

Wo ein Platzhalter sucht

• Im Dokumenttext: an der Wurzel (Hauptdatensatz).
• In einer Tabellenzelle: in der Zeile. Was die Zeile nicht hat, bleibt leer; nur eigene Variablen, System.*, Page.* und Zusammenfassungen über Pfade außerhalb der Zeile gehen an die Wurzel.
• In einer Tabelle in einer Tabellenzelle: itemsPath und alle Pfade relativ zur äußeren Zeile.
• Im einfachen Spaltenkopf header werden keine Platzhalter aufgelöst; dafür headerCell verwenden.

Bedingungen

Bedingungen stehen in filterExpr, in when von Wenn-Dann-Zweigen und Textversionen (variants), in visibleIf, in wenn von Bildregeln und von Fällen unter wahlen sowie in w der Zweige eines dynamischen Textes. Sie nennen Felder ohne {{ }}.

• Keine Arithmetik in Bedingungen: sum(a) * 1.19 > 5 geht nicht. Bilden Sie dafür eine Variable.
• Nicht =, <>, &, |, AND, OR, UND, ODER oder not schreiben. Das wird gemeldet, und der Ausdruck wirkt falsch.
• Unvollständig: Fehlt ein Teil (a == 1 &&, || b == 2, status != ohne Wert, ! ohne etwas dahinter, ()), wird das gemeldet, und der fehlende Teil gilt nie als erfüllt: a == 1 && trifft nie zu, a == 1 || nur, wenn a == 1 zutrifft. Eine ganz leere Bedingung bedeutet weiter »immer«.
• Auswahl und Ja/Nein aus Dynamics kommen als Beschriftung an (»Aktiv«, »Ja«). Zahlen vergleichen Sie über den Rohwert mit _code: statecode_code == 0. Eine Mehrfachauswahl hat als Rohwert eine Liste von Zahlen: contoso_tags_code contains 100000001 prüft, ob diese Option gewählt ist, notContains das Gegenteil (die Zahl ohne Anführungszeichen; in Anführungszeichen vergleicht contains Text). So schreibt auch der Designer, wenn der Wert aus der Liste gewählt wird. contoso_print == true und contoso_print == false richten sich bei einem Ja/Nein-Feld aus Dynamics nach seinem Rohwert, auch bei eigenen Beschriftungen wie »Unbezahlt«; ebenso der blanke Name (contoso_print, !contoso_print) und eine Ja/Nein-Variable, die das Feld übernimmt: eine eigene druckt dann »Nein«, eine Regel-Variable druckt weiter die Beschriftung und trägt den Rohwert als <Name>_code daneben. Ohne Rohwert (eigene Daten) zählt die Beschriftung: alles außer den Nein-Wörtern ist wahr. Verglichen wird die Beschriftung in der Sprache des Benutzers, der den Beleg erzeugt, nicht die der Optionslabels, in der gedruckt wird.
• Datum: == und != vergleichen zwei Datumswerte immer nur nach dem Kalendertag. <, > und Co. vergleichen tagesgenau, sobald eine Seite keine Uhrzeit trägt (createdon >= '2026-08-01').
• Text: == vergleicht exakt, Groß und Klein zählen.
• Leer prüfen: !field heißt »leer«, field heißt »ausgefüllt«. Als »leer« gelten dabei auch 0 und jede Null mit Punkt (0.00), false sowie »nein«, »no«, »off«, »n«, »non«, »nee« und »nie« (ohne Groß und Klein); »0,00« mit Komma gilt dagegen als ausgefüllt. Bei Zahlenfeldern prüft field == null sicherer auf »fehlt«. field == '' ist bei einem fehlenden Wert falsch.
• Unbekannte Variable: Das Ergebnis ist immer Nein, auch mit ! und !=.

"filterExpr": "statecode_code == 0 && (totalamount > 1000 || prioritycode_code == 1)"
"when": "count(quote_details) > 0 && name contains 'Ltd'"
"visibleIf": "discountamount == null"

Formeln

Formeln stehen in default und value von Variablen. Jeder Bezug steht in {{ }}. Bleiben nach dem Einsetzen nur Zahlen, + - * /, Klammern und Leerraum übrig, wird gerechnet; sonst wird der Text zusammengesetzt.

• Dezimalzahlen mit Punkt: {{net}} * 1.19. Ein Komma (1,19) macht die Formel zu Text.
• Ein fehlendes Feld zählt 0. Ein echter Wahrheitswert (zum Beispiel {{contoso_print_code}}) zählt 1 oder 0; das Ja/Nein-Feld selbst ist Text (»Ja«) und macht die Formel zu Text, ebenso eine Regel-Variable vom Typ boolean.
• Ein Formatierer im Bezug gilt in einer Formel nicht: {{Currency:net}} * 2 rechnet mit net, {{Bool:contoso_print}} setzt den Wert des Felds ein (seine Beschriftung).
• Teilen durch 0 ergibt leer, mit Meldung.
• Es gibt keine weiteren Funktionen (round, %, ^).
• Erst runden, dann summieren: sum und avg runden jeden Einzelwert auf die Anzeigestellen, bevor sie summieren. So stimmt die Summe mit den gedruckten Zeilen überein.

Datumsrechnung

dateadd(Basis, Anzahl, Einheit) rechnet mit ganzen Tagen, Monaten oder Jahren.

• Basis: ein Feld, @Variable, ein ISO-Datum (2026-01-31), System.Now oder ein weiteres dateadd.
• Anzahl: Zahl, Feld, -Feld oder @Variable; Nachkommastellen werden abgeschnitten.
• Einheit: day (Vorgabe), month oder year (auch tag, monat, jahr).
• Ein Monat mehr auf den 31.01. ergibt den 28.02.
• Ergebnis ist ein ISO-Text; zum Anzeigen {{Date:dateadd(createdon, 30, day)}}.
• dateadd steht immer allein, nichts davor oder dahinter.

Objekte im Dokument (body)

body ist eine Liste von Objekten. Jedes Objekt hat einen type. Objekte stehen auch in children einer Gruppe und in Tabellenzellen (columns[].cell, columns[].headerCell, rows[].cells[].content, subRows[].cells[].content).

Lage und Größe

• pageIndex: Entwurfsblatt, ab 0. Jedes Objekt direkt in body außer Kopf und Fuß braucht es. Trägt kein Objekt ein pageIndex, gilt ein älteres Modell: yMm ist dann ein Versatz im Fluss, und einige Regeln (Mitwandern, Tabellen) wirken anders. Fehlt es, legt der Designer das Blatt beim Öffnen selbst fest, und das kann den Druck ändern; die Prüfung beim Einlesen nennt es als Hinweis, eine KI-Änderung, die ein Objekt ohne pageIndex hinterlässt, wird abgelehnt (Kurzregel 9).
• wMm: Breite. Bei einem Text Pflicht (ohne steht ein Wort je Zeile). Gruppe und Raster ohne wMm: volle Breite. Tabellen: Summe der Spaltenbreiten.
• hMm: Höhe. heightMm ist die ältere Schreibweise und gilt nur, wenn hMm fehlt; der Designer schreibt sie bei neuen Gruppen in body (25).
• Die Breite zwischen den Rändern eines A4-Blatts mit Hausrändern ist 175 mm.

Gemeinsame Schlüssel

Fehlt place: Direkt in body verhält sich jedes Objekt wie auto. In einer Gruppe oder Zelle stehen Text, Bild, Codes und Formen fest (static), Gruppen, Tabellen und Raster wie auto. Der Designer schreibt bei neuen Texten, Bildern, Codes und Formen in body "place": "auto"; neue Gruppen, Tabellen und Umbrüche bekommen kein place.

• static bleibt genau an seiner Stelle und darf überlappen. Ausnahmen: Eine Tabelle beginnt an ihrer Entwurfsstelle, bricht aber normal über Seiten um; ein Raster direkt in body verhält sich wie auto.
• auto bleibt an seiner Stelle und weicht nur nach unten aus, wenn ein Objekt darüber es sonst überlappen würde.
• flow hält den gezeichneten Abstand zum Objekt darüber und rückt um genau so viel nach unten, wie dieses wächst. Es rutscht nie nach oben. Damit es nachrückt, braucht das Objekt darüber eine gezeichnete Unterkante (Tabelle mit Daten, Gruppe mit Höhe oder Text mit autoHeight: false).

Kopf und Fuß

Eine Gruppe mit "repeatEveryPage": true erscheint auf jeder Seite. Ist ihr yMm höchstens 0.5 (sie beginnt also höchstens 0,5 mm unter dem oberen Rand), ist sie ein Kopf, und der übrige Inhalt beginnt darunter. Endet sie höchstens 0,5 mm über dem unteren Ende des bedruckten Bereichs oder tiefer, ist sie ein Fuß, und er endet darüber. Dazwischen ist sie ein frei stehender Bereich: Der übrige Inhalt setzt unter ihm fort, wenn er sonst hineinliefe, über die ganze Breite.

• Lage des Fußes: yMm = Blatthöhe − unterer Rand − Höhe − oberer Rand. Bei A4 und Hausrändern mit 12 mm Höhe: 297 − 18 − 12 − 18 = 249.
• pageRule: first, notFirst, last, notLast, even, odd; leer = alle Seiten.
• excludePagesText: Seiten ausnehmen, zum Beispiel "1, 3-5".
• reserveSpace kommt in älteren Vorlagen vor und wirkt nicht.

Text

Auszeichnung in value: <b>, <i>, <u>, <sup>, <sub>, <br>, <span style="color:#C00000; font-size:12pt">, Absätze und Listen <p a="l" e="0" m="•"> (a: l, c, r, j; e: Einzugsstufe 0 bis 5; m: Marke) (Marken •, –, ▪, 1., a), i.), Links <a href="https://…"> (nur http, https, mailto, tel), Bild im Text <img k="logo_full" w="25" h="15">. Dynamischer Text: <cif d="…">Beschriftung</cif>; d ist Base64 (UTF-8) einer Liste [{ "w": Bedingung, "h": Inhalt }]. Gedruckt wird h des ersten Zweigs mit leerer oder wahrer Bedingung; trifft keiner zu, nichts. Die Beschriftung zwischen den Tags zeigt nur der Designer. Formel: <formel w="…" h="…" u="…" q="…" d="…">; q ist die LaTeX-Quelle, die Maße und d berechnet der Designer daraus. Übernehmen Sie beide unverändert; neue legt der Designer an. Andere Tags (zum Beispiel <ul>) bleiben samt Klammern als Text stehen; eine nicht erlaubte Listenmarke m="…" ergibt einen Absatz ohne Marke. rich: true schreibt der Designer selbst; der Druck braucht es nicht.

Bild

Ältere Bilder tragen binding ("@logo") und fit; mit bild werden sie nicht gelesen.

Barcode, QR-Code und GiroCode

"type": "Barcode" ist ein Strichcode, ein QR-Code oder ein GiroCode (EPC-QR-Code nach EPC069-12, für SEPA-Überweisungen in Euro); welcher, sagt barcode.art. Lage, Größe, visibleIf und place wie beim Bild. Ein Code wird nie geteilt und an der Unterkante einer Gruppe mit fester Höhe nie gekürzt: passt er dort nicht ganz hinein, wird er weggelassen, und das Dokument warnt (ein GiroCode verhindert dann den Beleg).

• Ein ungültiger Strich- oder QR-Code (falsche EAN-Prüfziffer, ein Zeichen, das die Art nicht kann, zu langer Inhalt, Kasten zu klein) wird nicht gedruckt; die Stelle behält ihren Platz, und das Dokument warnt.
• Ein sichtbarer, ungültiger GiroCode (zum Beispiel falsche IBAN-Prüfziffer, Betrag 0 oder negativ, eine andere Währung) verhindert den Beleg. Für Gutschriften blenden Sie ihn mit visibleIf aus.
• {{Page.Total}} (die Gesamtseitenzahl) geht im Inhalt eines Codes nur in einer Gruppe, die auf jedem Blatt steht (Kopf- oder Fußzeile); im Körper wird der Code sonst nicht gedruckt (Strich- oder QR-Code: Warnung, GiroCode: der Beleg entsteht nicht).
• Code 128: Buchstaben ohne Umlaute, Ziffern, Leerzeichen und Satzzeichen (ASCII ohne Steuerzeichen); EAN-13 und EAN-8: 12 bzw. 7 Ziffern (die Prüfziffer wird ergänzt) oder 13 bzw. 8 mit Prüfziffer; Code 39: 0–9, A–Z, Leerzeichen und - . $ / + %; ITF: Ziffern in gerader Anzahl.
• QR Code is a registered trademark of DENSO WAVE INCORPORATED.

{ "type": "Barcode", "xMm": 140, "yMm": 230, "wMm": 30, "hMm": 30, "pageIndex": 0, "place": "auto",
  "barcode": { "art": "epc",
    "zahlung": { "empfaenger": "{{@Payment recipient}}", "iban": "{{@Payment IBAN}}", "betrag": "{{totalamount}}",
                 "verwendungszweck": "Invoice {{invoicenumber}}" } } }

Formen

Farben und Strich stehen in style: strokeColor, strokeWidthPt (0 = kein Strich), fillColor, dash (solid, dashed, dotted; wirkt nicht beim Rechteck).

Gruppe

Fläche und Rahmen kommen aus style: fillColor, strokeColor, strokeWidthPt, borderSides (Komma-Liste aus top, right, bottom, left; leer = keine Linie; fehlt = ganzer Rahmen). Ohne Fläche und Rahmen ist die Gruppe im PDF unsichtbar.

Tabelle

Filtern gehört in die Regel; ein Schlüssel filter an der Tabelle wird nicht gelesen.

In rows[].cells[] und subRows[].cells[]: content (das Objekt), colSpan, rowSpan (nur in subRows). Steht ein Text direkt als content, hüllt der Designer ihn beim Öffnen in eine Gruppe.

Raster und Seitenumbruch

• Grid (ältere Form, im Designer nicht mehr neu anzulegen; für neue Vorlagen eine Freie Tabelle): rows mit Zellen wie oben, je Zeile optional heightMm (Mindesthöhe dieser Zeile; sie wächst mit dem Inhalt), colWidthsMm (leer = gleich verteilt), rowMinHeightMm, borders (color, widthPt, outer, rowLines, colLines), Zellfarbe fill je Zelle.
• PageBreak: steht direkt in body mit pageIndex und yMm (Stelle des Schnitts). Er bricht nur, wenn auf dem Blatt schon etwas steht. Was auf demselben Entwurfsblatt darunter liegt, rückt auf der Folgeseite um dieses yMm nach oben (ein Objekt bei 120 unter einem Umbruch bei 100 steht dort bei 20). Mit visibleIf falsch wirkt er nicht.

Stil

E-Rechnung (eRechnung)

eRechnung an der Wurzel macht den Beleg zusätzlich zu einer elektronischen Rechnung nach einem Standard. Mitgeliefert sind »XRechnung 3.0« (Kennung xrechnung-ubl, nur XML) und »ZUGFeRD 2.5.2 (EXTENDED)« (zugferd-extended, auch als PDF mit eingebetteter XML). Der Schlüssel ordnet jeder Angabe des Standards einen Wert zu: ein Feld, eine Variable oder einen festen Wert. Smart Templates rechnet nichts selbst. Es schreibt, was zugeordnet ist, rundet Beträge und prüft das Ergebnis mit den Regeln des Standards. Fehlt der Schlüssel oder ist aktiv nicht true, entsteht keine E-Rechnung, und der Beleg bleibt, wie er ist.

Angaben und Kennungen

Die Kennungen sind die des Standards: BT-… der Norm EN 16931 (Begleitangaben mit -1, etwa BT-34-1), BG-… für Listen und Gruppen, bei ZUGFeRD dazu eigene Kennungen ZX-… und ZXG-…. Welche Angaben ein Standard hat, welche Pflicht sind und welche Codes gelten, steht in seiner Übersicht: über die Aktion st_StandardLesen (Teile uebersicht, pflicht, abschnitt:<id>, codeliste:<id>), im KI-Paket im Abschnitt »E-Rechnung«. Eine unbekannte Kennung, eine Angabe auf der falschen Ebene oder eine Liste unter werte ist ein Fehler.

• Formatierer ({{Currency:…}}, {{Date:…}} …) sind nur bei Text-Angaben erlaubt; Beträge, Daten und Codes stehen ohne.
• Beträge schreibt Smart Templates kaufmännisch auf 2 Nachkommastellen gerundet, auch aus einer Variablen. Einzelpreise, Mengen und Prozentsätze bleiben, wie sie sind. Die Rechenprobe prüft die gerundeten Werte.
• Codes (Länder, Einheiten, Steuerarten …): ein Code der Codeliste, ein üblicher Name (»Deutschland« wird DE) oder eine Zeile in umsetzung. Was sich nicht erkennen lässt, ist ein Fehler.
• Leer bleibt leer: Es gibt keinen Ersatzwert. Fehlt eine Pflichtangabe, entsteht der Beleg nicht und eine Meldung nennt sie; nur die Voll-Vorschau warnt und zeigt das PDF ohne XML.
• Die Art der Rechnung (BT-3: Rechnung 380, Gutschrift 381 …) ist eine Angabe wie jede andere. Kommt sie aus einem Auswahlfeld, ordnen Sie eine Wenn-Dann-Variable nach dem Rohwert zu, mit Zweigen wie { "when": "<field>_code == 2", "value": "381" }. Leiten Sie die Art nie aus dem Vorzeichen, der Nummer oder der Beschriftung ab. Bei XRechnung entsteht für eine Gutschrift von selbst ein Gutschrift-Dokument.
• Summen und Steuern ordnen Sie so zu, wie der Beleg sie druckt. Die Rechenprobe des Standards deckt jede Abweichung auf.

Listen

listen ordnet jeder Liste des Standards ihre Einträge zu, zum Beispiel BG-25 (Positionen), BG-23 (Steuer je Steuersatz), BG-20 (Nachlass auf die ganze Rechnung) oder BG-21 (Zuschlag auf die ganze Rechnung). Ob eine Liste eine Regel, feste Einträge oder beides nimmt, sagt die Übersicht (quelle).

"eRechnung": {
  "aktiv": true, "standard": "xrechnung-ubl", "ausgabe": "nurXml",
  "werte": { "BT-1": "{{invoicenumber}}", "BT-2": "{{createdon}}", "BT-3": "{{@InvoiceType}}",
             "BT-5": "{{transactioncurrencyid.isocurrencycode}}", "BT-106": "{{sum(Items.Net)}}",
             "BT-109": "{{@NetTotal}}", "BT-110": "{{totaltax}}", "BT-112": "{{totalamount}}", "BT-115": "{{totalamount}}" },
  "listen": {
    "BG-25": { "itemsPath": "Items",
               "werte": { "BT-126": "{{#}}", "BT-129": "{{quantity}}", "BT-146": "{{priceperunit}}", "BT-131": "{{Net}}",
                          "BT-151": "S", "BT-152": "19" },
               "listen": { "BG-27": { "eintraege": [ { "name": "Discount", "wenn": "manualdiscountamount > 0",
                                                      "werte": { "BT-136": "{{manualdiscountamount}}", "BT-140": "95" } } ] } } },
    "BG-21": { "eintraege": [ { "name": "Freight", "wenn": "freightamount > 0",
                                "werte": { "BT-99": "{{freightamount}}", "BT-102": "S", "BT-103": "19", "BT-105": "FC" } } ] }
  },
  "umsetzung": { "EINHEIT": { "hrs": "HUR" } }
}

Dazu gehören die Regel Items auf den Positionen mit der Regel-Variablen Net ({{baseamount}} - {{manualdiscountamount}}; den Mengenrabatt enthält baseamount schon) und die eigenen Variablen InvoiceType (Wenn-Dann nach dem Rohwert des Typfelds) und NetTotal ({{totalamount}} - {{totaltax}}). Im Beispiel fehlen noch Angaben, die jede Rechnung braucht, etwa Ihr Unternehmen; welche, sagt der Teil pflicht der Übersicht.

Vorschläge für die Dynamics-Rechnung

Ist die Hauptquelle die Rechnung (invoice), kennt Smart Templates Vorschläge aus den Standardfeldern von Dynamics, nie aus eigenen Feldern eines Unternehmens. Im Designer übernimmt sie »Vorschläge übernehmen« im Zuordnungsfenster; die Tabelle liefert die Aktion st_StandardLesen mit dem Teil vorschlaege (mit Kennung zugeschnitten auf den Standard). Ein Vorschlag gilt nur, wenn es sein Feld in den Quellen der Vorlage gibt und die Angabe noch leer ist; mehrere pfade heißen: der erste, den es gibt. Die Einträge im Teil kopf tragen dazu eine art:

Im Teil positionen stehen die Regel-Variable (regelVariable, an der Regel der Positionstabelle) und die Angaben je Zeile mit den Arten laufendeNummer, fest (fester Wert für jede Position), vorgabe (die Vorgabe des Standards) und regelVariable; kopfListen und positionen.listen nennen feste Einträge mit Bedingung (eintrag) und den Steuereintrag (art steuer). Was pruefen trägt, ist ein Ersatz, eine Vorbelegung oder ein Wert für jeden Beleg: Der Anwender muss es ansehen und bestätigen. Ein Eintrag, der eine Variable anlegt, trägt zusätzlich pruefenVorhanden: Gab es die Variable schon (Regel-Variable: gleicher Name; variable: gleicher Name und gleiche Formel) und wird sie benutzt, gilt dieser Satz statt pruefen, dessen Anfang »Neu angelegt« dann nicht stimmte.

Eigene Standards

Einen eigenen Standard beschreibt eine Anmerkungsdatei, selbst ein XSD neben dem unveränderten offiziellen Schema. Ihren Aufbau beschreibt die Seite »Eigene Standards für die E-Rechnung« (Aktion st_StandardLesen mit dem Teil format); hochgeladen wird sie im Designer unter »Standards verwalten …« oder mit der Aktion st_StandardHochladen.

Ein vollständiges Beispiel

Ein Angebot mit Logo und Linie oben, Kunde und Titel, Positionstabelle auf einer Regel, Summe darunter und Seitenzahl unten.

{
  "name": "Quote",
  "culture": "en-US",
  "page": { "size": "A4", "widthMm": 210, "heightMm": 297,
            "margins": { "topMm": 18, "rightMm": 15, "bottomMm": 18, "leftMm": 20 } },
  "brand": { "bodyFont": "Arimo", "headingFont": "Arimo" },
  "sources": [ {
    "id": "src1", "name": "Quote", "entity": "quote", "primary": true, "basePath": "", "idAttr": "quoteid",
    "fields": [ { "name": "name" }, { "name": "_customerid_value" } ],
    "relations": [ {
      "name": "quote_details", "kind": "collection", "entity": "quotedetail", "refAttr": "quoteid",
      "fields": [ { "name": "productdescription" }, { "name": "quantity" }, { "name": "baseamount" }, { "name": "sequencenumber" } ],
      "rules": [ { "id": "r1", "name": "Items", "filterExpr": "",
                   "select": { "mode": "", "sorts": [ { "by": "sequencenumber", "dir": "asc" } ] }, "vars": [] } ]
    } ],
    "rules": []
  } ],
  "body": [
    { "type": "Group", "repeatEveryPage": true, "xMm": 0, "yMm": 0, "hMm": 20, "children": [
      { "type": "Image", "xMm": 0, "yMm": 0, "wMm": 45, "hMm": 14, "place": "static",
        "bild": { "art": "asset", "pfad": "logo_full", "einpassung": "einpassen" } },
      { "type": "Line", "xMm": 0, "yMm": 16, "wMm": 175, "hMm": 4, "place": "static",
        "style": { "strokeColor": "#2B4CC4", "strokeWidthPt": 1.5 } } ] },
    { "type": "Group", "pageIndex": 0, "yMm": 0, "heightMm": 30, "children": [
      { "type": "Text", "value": "{{_customerid_value}}", "xMm": 0, "yMm": 0, "wMm": 90, "place": "static" },
      { "type": "Text", "value": "Quote {{name}}", "xMm": 0, "yMm": 14, "wMm": 175, "place": "static",
        "style": { "font": "heading", "sizePt": 18, "bold": true, "color": "#16234B" } } ] },
    { "type": "Table", "pageIndex": 0, "yMm": 34, "place": "auto", "itemsPath": "Items",
      "headerStyle": { "fillColor": "#2B4CC4", "color": "#FFFFFF", "sizePt": 9, "bold": true },
      "rowStyle": { "sizePt": 9, "color": "#222222", "paddingMm": 1.5 },
      "columns": [
        { "key": "c1", "header": "Description", "widthMm": 105, "align": "left", "value": "{{productdescription}}" },
        { "key": "c2", "header": "Quantity", "widthMm": 30, "align": "right", "value": "{{Number:quantity|2}}" },
        { "key": "c3", "header": "Amount", "widthMm": 40, "align": "right", "value": "{{Currency:baseamount}}" } ] },
    { "type": "Text", "pageIndex": 0, "xMm": 95, "yMm": 50, "wMm": 80, "place": "flow",
      "value": "Total: {{Currency:sum(Items.baseamount)}}", "style": { "align": "right", "bold": true } },
    { "type": "Group", "repeatEveryPage": true, "xMm": 0, "yMm": 249, "hMm": 12, "children": [
      { "type": "Text", "value": "Page {{Page.Current}} of {{Page.Total}}", "xMm": 140, "yMm": 2, "wMm": 35, "place": "static",
        "style": { "sizePt": 7.5, "align": "right", "color": "#888888" } } ] }
  ]
}

Ältere und wirkungslose Schlüssel

Diese Schlüssel stehen in älteren Vorlagen. Der Druck liest die meisten noch, der Designer baut sie beim Öffnen um. Neue Vorlagen brauchen sie nicht.

Was der Designer selbst pflegt

Diese Schlüssel schreibt der Designer selbst. Lassen Sie sie stehen, wenn sie schon da sind, aber legen Sie keine neuen an:

• in sources: set, nameAttr, locked, sampleName, sampleMissing, an Feldern label, stellen, stellenQuelle, schreibname, mehrzeilig, schreibbar, pflicht, anlegbar, weg, an Beziehungen linkLabel, weg;
• alle Schlüssel mit _ am Anfang (zum Beispiel _loaded, _refLabel, _ot51b);
• die Baukasten-Spiegel visGroup (zu visibleIf), filter (zu filterExpr), condGroup und cond (zu when) sowie gruppe (zu wenn, an Bildregeln und an den Fällen unter wahlen). Ändern Sie einen Ausdruck, entfernen Sie seinen Spiegel. Bleibt ein alter Spiegel stehen, kann der Designer den Ausdruck beim Öffnen des Editors aus dem Spiegel neu schreiben. Ohne Spiegel zeigt er einen Regelfilter als »nicht mit dem Baukasten gebaut« und lässt ihn stehen; Sichtbarkeit, Bildregeln und Variablen-Zweige liest er in die Bausteine zurück, soweit sie den Ausdruck darstellen können.

Kurzregeln für KI-Werkzeuge

1. Aufbau: Quelle → Beziehung → Regel. Eine Datentabelle steht auf einer Regel, nicht direkt auf einer Beziehung: itemsPath = Pfad des Elternknotens plus Pfadstück des Regelnamens (»Open items« → Open_items).
2. Benutzen Sie nur Tabellen, Felder und Beziehungen, die es gibt. Jedes benutzte Feld steht mit exaktem logischem Namen in fields seiner Ebene; ein Verweis heißt _<spalte>_value.
3. Beziehungen brauchen name, kind (lookup oder collection), entity und refAttr. Höchstens sechs Ebenen tief.
4. Regelnamen sind in der ganzen Vorlage eindeutig. Eine Regel liest keine Ergebnisse von Regeln weiter oben (auch keine Quellregeln); Felder darüber und eigene Variablen darf sie lesen. Ein Bezug nach oben wird gelöscht, ein Kreis schaltet alle Regeln ab.
5. Bedingungen nennen Felder ohne {{ }}, Text in Anführungszeichen, Zahlen mit Punkt, && || !. Formeln setzen jeden Bezug in {{ }} und rechnen nur + - * /.
6. Zusammenfassungen (sum, avg, count, min, max, first) gehen über ein Feld einer Liste (Beziehung collection oder Regel-Ergebnis): sum(Items.baseamount). last() gibt es nicht.
7. Zahlen und Daten im Text immer formatieren: {{Currency:…}}, {{Number:…|2}}, {{Date:…}}, {{Bool:…}}.
8. Ein Text braucht wMm. Eine Gruppe mit Höhe, aber ohne autoHeight: true schneidet ab, was über ihre Unterkante ragt.
9. Jedes Objekt direkt in body außer Kopf und Fuß trägt pageIndex; fehlt es, wird die Änderung abgelehnt (in einer Vorlage ganz ohne pageIndex: nur Hinweis).
10. Auswahl- und Ja/Nein-Felder vergleichen Sie über _code (statecode_code == 0); ohne _code steht dort die Beschriftung.
11. select (topN, first) kürzt nur das Ergebnis; weniger geladen wird nur mit einem Filter.
12. In Tabellenzellen sind Pfade relativ zur Zeile. Platzhalter im Spaltenkopf nur über headerCell.
13. Seitenzahlen nur über {{Page.Current}} und {{Page.Total}} im Text, nie in Bedingungen oder Formeln.
14. Eigene Variablen immer mit type; sie werden vor den Regeln gerechnet und sehen keine Regel-Ergebnisse.
15. Behalten Sie alle Schlüssel, die Sie nicht ändern sollen, auch unbekannte. Ändern Sie einen Ausdruck, entfernen Sie seinen Baukasten-Spiegel (visGroup, filter, condGroup, cond, gruppe).
16. Werte von type exakt schreiben (Group, nicht group). Zahlen als Zahlen, Farben als #RRGGBB.
17. Etwas unter eine Tabelle setzen: direkt in body hinter die Tabelle, mit demselben pageIndex, einem yMm unterhalb dem der Tabelle und "place": "flow" (wie die Summe im Beispiel). Es hält dann den gezeichneten Abstand und rückt um genau so viel nach unten, wie die Tabelle wächst. Ohne place wirkt es wie auto: Es bleibt stehen, bis die Tabelle es erreicht, und sitzt dann ohne Abstand (nur marginTopMm) darunter. Steht unter der Tabelle schon eine Gruppe, etwa ein Summenblock, können Sie es auch dort hineinsetzen.
18. Codes: "type": "Barcode" mit barcode.art. Der Inhalt steht in barcode.wert (beim GiroCode in barcode.zahlung mit empfaenger und iban); Nummern und Beträge dort ohne Formatierer. Drehung nur 0, 90, 180, 270.

Das Beispiel im Designer

Das Beispiel aus Ein vollständiges Beispiel sieht auf der Entwurfsfläche des Designers so aus. Felder stehen dort als blaue Marken mit ihrem Namen; im PDF steht an dieser Stelle der Wert.

1 2 3 4 5

Was die Prüfung beim Import meldet

Bevor der Designer eine Vorlagendatei öffnet, prüft Dynamics sie gegen den Aufbau auf dieser Seite (siehe Vorlagen verwalten: Importieren). Fehler sperren das Öffnen, Hinweise fragen nur nach. Der Bericht nennt vor jedem Satz die Stelle im Aufbau der Vorlage, etwa body[0].type; die Sätze sind für die KI bestimmt, die die Datei erzeugt hat.

Fehler sperren das Öffnen. Die Prüfung meldet unter anderem:

• Die Datei ist beschädigt. Der Bericht nennt die Stelle als Zeile und Spalte, den Inhalt der Zeile und den Grund, etwa einen Zeilenumbruch mitten in einem Text, ein fehlendes Zeichen, ein Komma zu viel, eine zu früh endende Datei oder eine zu tief verschachtelte Vorlage (es gibt eine Höchstzahl an Ebenen).
• Der Aufbau stimmt nicht: Die Vorlage selbst, ihre Seite, ihre Marke, Listen und Einzelteile müssen die richtige Form haben.
• Jedes Objekt braucht eine gültige Art: Text, Bild, Gruppe, Tabelle, Raster, Linie, Rechteck, Ellipse, Dreieck, Stern, Pfeil, Vieleck oder Seitenumbruch. Der Bericht nennt sie mit ihren englischen Namen; auf Groß- und Kleinschreibung kommt es an.
• Maße und Winkel müssen Zahlen sein.
• Eine Tabelle braucht mindestens eine Spalte, und jede Spalte eine Breite größer als 0.
• Regeln und Variablen brauchen einen Namen, der nur einmal vorkommt. Für die Auswahl einer Regel sind nur diese Modi erlaubt: leer, die obersten n Zeilen, die erste, die letzte und die n-te Zeile.
• Beziehungen brauchen Name, Art (N:1 oder 1:N), Tabelle und Verknüpfungsfeld; Quellen brauchen eine Tabelle, weitere Quellen auch den Namen ihrer Liste.
• Im Text steht ein Feld einer eigenen Variablen, die es nicht gibt.

Hinweise fragen nur nach. Die Prüfung meldet unter anderem:

• Die Datei enthält mehrere Textblöcke; gelesen wird der größte. Oder: Vor oder nach der Vorlage steht Text; gelesen wird nur der Teil mit der Vorlage.
• Die Vorlage hat keinen Inhalt. Oder: Sie hat keine Datenquelle; der Designer fragt beim Öffnen nach der Hauptquelle.
• Ein Text hat keine Breite und steht dann mit einem Wort je Zeile.
• Ein Seitenumbruch steht nicht direkt im Dokument und wirkt deshalb nicht.
• Ein Filter an der Tabelle wird nicht gelesen; er gehört in die Regel.
• Eine Variable hat keinen Typ und gilt deshalb als Text, oder ihr Typ ist unbekannt.
• Ein mitgeliefertes Bild ist kein PNG, JPEG oder SVG oder größer als 5 MB; die Stelle bleibt leer.
• Eine Beziehung liegt tiefer als sechs Ebenen; gedruckt wird dort nichts.
• Objekte direkt im Dokument haben kein pageIndex (das Blatt, gezählt ab 0). Beim Öffnen legt der Designer ihr Blatt selbst fest, und das kann den Druck ändern; prüfen Sie danach die »Voll-Vorschau«. Kopf und Fuß brauchen kein Blatt. Bei »KI-Änderungen hochladen« und beim KI-Assistenten ist dasselbe ein Fehler, sobald die Änderung ein solches Objekt hinterlässt (siehe Kurzregeln für KI-Werkzeuge, Regel 9).
• Die Nachkommastellen einer Berechnung (nachkomma) liegen nicht zwischen 0 und 6. Bei mehr als 6 wird mit 6 gerechnet, bei einer negativen Zahl oder einem Wert, der keine Zahl ist, mit den Stellen der Vorlage.