PDF/A und ZUGFeRD - MonkeyBread Software...Christian Schmitz (Jg. 1981) entwickelt seit 1998 Software und seit 2006 auch FileMaker Plugins. Außerdem Plugins für Real Studio und allerlei
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Christian Schmitz(Jg. 1981) entwickelt seit 1998 Software und seit 2006 auch FileMaker Plugins. Außerdem Plugins für Real Studio und allerlei Software für macOS, Windows, Linux und [email protected]
PDF/A und ZUGFeRDRechnungen mit eingebettetem XML
Der „ZUGFeRD“-Standard (Akronym für: Zentraler User Guide des Forums elektronische Rechnung Deutschland1) ist eine Spezifikation für das gleichnamige Format elek-tronischer Rechnungen, das am 25. Juni 2014 veröffent-licht wurde. Jeder kann es nutzen und damit seine Rech-nungen kompatibel machen.
Der ZUGFeRD-Standard2 definiert, wie Rechnungen erstellt und verarbeitet werden können. Die Rechnungen wer-den grundsätzlich als PDF/A-Datei ausgeliefert, wobei der PDF-Teil die grafische Darstellung und das Drucken auf Pa-pier erlaubt. Für die Computerauswertung befinden sich alle Daten strukturiert in einem XML-Block innerhalb der PDF-Datei. PDF/A bedeutet, dass die PDF-Variante zur Archivie-rung verwendet wird, weshalb vorhandene PDF-Dateien gege-benenfalls als PDF/A konvertiert werden müssen.
Der Aufbau mit einer PDF-Datei und die Definition des Standards machen diese Lösung sehr interessant. Zum einen kann jeder den Standard verwenden und implementieren und zum anderen gibt es Validatoren, um eine Datei auf Konformi-tät zu testen. Außerdem erlaubt die Weitergabe als PDF-Datei es jedem Empfänger, die Datei abzulegen oder auszudrucken, selbst wenn er von ZUGFeRD noch nie etwas gehört hat.
Schritt 1: XML
Den Aufbau des XMLs kann man in der Spezifikation nach-lesen, doch es ist empfehlenswert, sich zunächst das Beispiel „XML“ zu holen (von der Webseite oder aus dem MBS-Bei-
spiel). Bisher habe ich für die meisten Kunden aus dem Beispiel „XML“ einige Optionen entfernt und eine XML-Vorlage er-stellt, in der Platzhalter platziert sind, die später in FileMaker mit dem „Ersetzen“-Befehl leicht mit Werten gefüllt werden.
Texte können Sie natürlich selbst per Eigener Funktion auf das XML-Format vorbereiten, also einige Sonderzeichen richtig kodieren. Alternativ können Sie die Funktion „Text.EncodeToXML“ des MBS-Plugins nutzen. Außerdem sollten Sie darauf achten, dass alle Zahlen, die Geldbeträge darstellen, im XML mit Dezimalpunkt anstelle des Kommas ausgegeben werden.
Schritt 2: DynaPDF
Optional zum MBS-Plugin kön-nen Sie die DynaPDF-Bibliothek lizenzieren und dann die entspre-chenden Funktionen nutzen. Ohne Lizenz ist es zwar möglich, die Funktionen zu testen, man be-kommt aber Wasserzeichen und Warndialoge angezeigt. Für ZUGFeRD benötigen Sie idealerweise die Pro-Variante plus PDF/A-Erweiterung. Letztere können Sie einsparen, wenn Sie das PDF komplett in DynaPDF zusammenbauen, doch falls Sie das PDF-Dokument für eine Rechnung in FileMaker er-stellen, muss es einmal durch den PDF/A-Konverter geschickt werden.
Zum Laden der DynaPDF-Bibliothek beim Starten des Programms rufen Sie die „DynaPDF.IsInitialized“-Funktion auf. Wird eine „1“ zurückgegeben, haben Sie schon alles initi-
alisiert. Ansonsten rufen Sie bitte „DynaPDF.Initialize“ auf und übergeben den Namen bzw. Pfad zur Bibliothek und die Seriennummer.
Die DynaPDF-Bibliothek liegt dem MBS-Plugin bei den DynaPDF-Beispielen bei: dynapdf.dll bzw. dynapdf64.dll für Windows 32-bit bzw. 64-bit, dynapdf.dylib für Mac OS und dynapdf.so für Linux (FileMaker Cloud). Sie können den vollen nativen Pfad für die Datei angeben, z. B. „/Library/ FileMaker Server/dynapdf.dylib“ und die Datei an einem be-liebigen Ort speichern. Eine weitere Möglichkeit besteht darin, die Datei direkt neben die Plugindatei zu legen und nur den Dateinamen zu übergeben. In diesem Fall sucht das Plugin in dem passenden Ordner nach der Datei.
Den Lizenzschlüssel erhalten Sie nach dem Kauf per E-Mail von Monkeybread Software. Solange Sie keine Lizenz gekauft haben, können Sie DynaPDF im Demo-Modus testen, also PDF-Dateien mit Wasserzeichen erzeugen. Alternativ können Sie den Text „Pro“, „Lite“ oder „Starter“ als Lizenz-schlüssel übergeben, um die entsprechenden Funktion für die jeweilige Lizenz freizuschalten. Funktionen, die nicht in der Lizenz enthalten sind, geben dann einen Fehler zurück. Vor der Auslieferung sollten Sie dann den Lizenzschlüssel eintra-gen bzw. via Feld in einer Einstellungstabelle eingeben.
7 Eigenes Dialogfeld anzeigen[ "DynaPDF konnte nicht initialisiert werden." ; $r ]
8 Ende (wenn)
9 Ende (wenn)
Wenn alles geklappt hat, liefert „DynaPDF.IsInitialized“ im Anschluss eine „1“ zurück und mit korrektem Lizenzschlüssel verschwinden die Wasserzeichen.
Schritt 3: PDF mit XML bauen
Wenn Sie die PDF-Datei erstellt haben, die XML-Daten vor-liegen und Ihr XML validiert ist, können Sie alles per MBS-Plugin zusammenbauen. Hier zunächst das gesamte Script, das ich anschließend im Detail erklären werde:
Zuerst fragt das Script beim Plugin eine neue DynaPDF-Umgebung an, wofür Sie eine Nummer zugewiesen bekom-men. Da Sie mehrere Nummern erhalten können, dürfen Sie gerne beim Server mehrere Scripts gleichzeitig laufen las-sen, die verschiedene PDFs verarbeiten. Auch kann ein Un-terscript oder eine Eigene Funktion parallel mit einer anderen DynaPDF-Umgebung an einem anderen PDF arbeiten. Die Referenznummern zur PDF-Umgebung werden in der Va-riablen $pdf abgespeichert und bei den folgenden Aufrufen immer angegeben. Am Ende des Scripts wird der Speicher mit dem Aufruf von „DynaPDF.Release“ wieder freigegeben.
Um ein vorhandenes PDF-Dokument zu ändern, muss es natürlich erst eingelesen werden. Die Import-Flags sind stan-dardmäßig so gesetzt, dass alles (inkl. z. B. Anmerkungen) importiert wird – Seiten werden als Seiten eingelesen und nicht als Vorlagen – und schon sind die Vorarbeiten für die Konvertierung nach PDF/A erledigt. Man kann die Import-Flags natürlich auch so setzen, dass z. B. nur die reinen Seiten ohne Extras wie JavaScripts, Formularfelder oder Anmerkun-gen geladen werden. Der Import als Vorlage ist immer dann hilfreich, wenn man eine Seite auf einer größeren platzieren möchte, z. B. bei einer Bogenmontage.
Der Befehl „DynaPDF.OpenPDFFromContainer“ öff-net eine PDF-Datei in einem FileMaker Container. Wenn Sie das PDF-Dokument als Datei vorliegen haben, können Sie den Pfad der Funktion „DynaPDF.OpenPDFFromFile“ übergeben. Falls die Datei einen Passwortschutz hat, kann das Passwort natürlich optional übergeben werden. Aus einem ge-öffneten PDF können Sie einzelne Seiten in das Arbeits-PDF importieren. In unserem Beispiel nutzen wir „DynaPDF.Im-portPDFFile“, um alle Seiten aus dem PDF zu importieren. Sollten Sie nur einige Seiten benötigen, steht Ihnen die Funk-tion „DynaPDF.ImportPDFPage“ zur Verfügung. Wenn Sie in einer Schleife mehrere PDF-Dateien hintereinander öffnen und daraus importieren, können Sie diese zusammenfügen und als ein neues Dokument abspeichern.
Die nächste Script-Zeile ruft die „DynaPDF.SetLanguage“-Funktion auf, mit der die Sprache für das PDF-Dokument gesetzt wird, denn für den PDF/A-Standard ist eine Sprache zwingend erforderlich. Ebenso muss ein Struk-turbaum im Dokument enthalten sein, der mithilfe die Funk-tion „DynaPDF.CreateStructureTree“ erzeugt wird. Weiter-hin benötigt ein PDF/A-Dokument einen Output Intent, also ein Farbprofil für die Ausgabe. Auch jeder Farbraum in Grafiken und Bildern muss ein ICC-Farbprofil besitzen. Da eventuell ein Profil fehlen könnte, werden drei ICC-Profil-dateien für RGB, Graustufen und CMYK-Farbräume an
das Plugin übergeben, damit fehlende Profile ersetzt werden können. Falls Sie kein Ersatzprofil angeben und eines fehlt, bekommen Sie im Script eine entsprechende Fehlermeldung. Die Standard-PDF-Profile kann man sich von der Adobe-Webseite laden.3
Das XML wird mit dem Befehl „DynaPDF.AttachFile-Text“ in das neue PDF-Dokument eingebettet. Als Parameter übergeben Sie im Script den Inhalt der XML-Datei als Text, die Textkodierung „UTF-8“ und den Namen für diesen An-hang im PDF „ZUGFeRD-invoice.xml“. Sie haben die Mög-lichkeit, einen Kommentar zu ergänzen oder mehrere Dateien in ein PDF einzubetten. Für das PDF/A-XML wird „Dyna-PDF.AssociateEmbFile“ aufgerufen, um das PDF als Alterna-tive zum normalen PDF-Catalog einzusetzen. Das XML ist somit eine alternative Darstellung des PDF-Inhalts.
Der Befehl „DynaPDF.CheckConformance“ prüft die Konformität mit dem PDF/A-Standard. In unserem Fall ist das „ZUGFeRD Basic“, was automatisch PDF/A 3b impli-ziert. Vom ZUGFeRD-Standard und PDF/A-Standard gibt es mehrere Versionen mit verschiedenen Features. Die De-tails dazu finden Sie auf der ZUGFeRD-Webseite. Für unser Beispiel bleiben wir beim Basic-Level. Wenn eine PDF/A-Konverter-Lizenz in DynaPDF vorhanden ist, wird auch das PDF korrigiert und nach PDF/A gewandelt. Fehlt dieses Lizenz, erhalten Sie eventuell die Fehlermeldung, dass das PDF-Dokument nicht konform ist. Ansonsten meldet die „DynaPDF.CheckConformance“-Funktion, welches Output Intent empfohlen wird. Je nach Bedarf wird ein ICC-Profil für RGB, CMYK oder Graustufe hinzugefügt, sodass für das PDF-Dokument festgelegt ist, mit welchem Farbprofil es aus-gegeben werden möchte.
Zum Schluss wird das PDF-Dokument in einem Con-tainerfeld gespeichert, wobei die Funktion „DynaPDF.Save“ einen Containerwert zurückgibt. Wenn Sie lieber in eine Da-tei ausgeben möchten, so rufen Sie bitte vorher „DynaPDF.Open OutputFile“ auf, um die Datei zu öffnen. Beim Aufruf von „DynaPDF.Save“ kommt nur noch „OK“ zurück, die Da-tei wird geschlossen und die Rechnung ist fertig.
Das oben dargestellte Script stellt die Variante mit impor-tiertem PDF aus FileMaker dar. Alternativ können Sie das PDF-Dokument natürlich auch komplett via Plugin-Aufruf in DynaPDF zusammenbauen. Die Beispiele „Invoice“ und „Catalog“ liegen dem MBS-Plugin bei und zeigen, wie man mit Tabellen Layouts definieren und somit PDF-Dokumente ohne FileMaker erzeugen kann. Diesen Weg müssen Sie ge-hen, wenn Sie PDF-Dokumente in einer Runtime erstellen möchten oder auf einem FileMaker Server, der eine ältere Ver-sion als 16 verwendet.
Schritt 4: XML auslesen
Auch das Auslesen einer XML-Datei aus einer ZUGFeRD-Rechnungsdatei ist mit dem MBS-Plugin möglich. Im fol-genden Beispielscript werden alle eingebetteten Dateien da-hingehend betrachtet, ob sie den richtigen Namen und Typ
klemenskegebein
Nachdruckstempel
Plugins & Tools
26 FMM_201801
haben. Wenn ja, wird die Datei ausgelesen und in ein Feld gespeichert. Anschließend können Sie das XML auseinander-nehmen:
Für die hier beschriebene Vorgehensweise benötigen Sie das MBS FileMaker Plugin in passender Lizenz für Arbeits-plätze oder Server. Dazu kommen DynaPDF-Lizenzen nach Bedarf: entweder eine Lite oder Pro allein, falls die PDF-
Dokumente komplett in DynaPDF gebaut werden und keine vorhandenen PDFs importiert werden. Oder DynaPDF Pro plus PDF/A-Erweiterung, falls Sie vorhandene PDF-Dateien importieren, wozu auch die von FileMaker generierten PDF-Dokumente gehören. Bei Fragen zu den Lizenzen können Sie sich gern beim K&K Verlag melden. Bitte beachten Sie, dass die DynaPDF-Lizenz pro Entwickler anfällt, also nicht pro Kunde, Server oder Arbeitsplatz. So können Sie eventuell ein-mal DynaPDF kaufen und für mehrere Kunden verwenden, sofern diese weder die Seriennummer sehen noch die Lizen-zen selber besitzen möchten. ■