© 1994 – 2018 K&K Verlag GmbH, Hamburg 23 FMM_201801

Plugins & Tools

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 iOS.support@monkeybreadsoftware.de

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-

Christian Schmitz

Shop MBS-Plugin

Plugins & Tools

24 FMM_201801

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.

Das Script sieht zum Beispiel so aus:

1 Wenn[ MBS("DynaPDF.IsInitialized") ≠ 1 ]

2 # DynaPDF initialisieren

3 Variable setzen[ $path ; Wert: "dynapdf.dylib" ]

4 Variable setzen[ $licenseKey ; Wert: "Pro" /* Demo Modus */ ]

5 Variable setzen[ $r ; Wert: MBS( "DynaPDF.Initialize"; $path; $licenseKey)]

6 Wenn[ $r ≠ "OK" ]

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:

1 # Neue PDF Umgebung

2 Variable setzen[ $pdf ; Wert: MBS("DynaPDF.New") ]

3 # Import Flags setzen, so dass für PDF/A vorarbeiten geleistet werden

4 Variable setzen[ $r ; Wert: MBS( "DynaPDF.SetImportFlags"; $pdf;"ImportAll¶ImportAsPage¶PrepareForPDFA" ) ]

5 # PDF aus Container öffnen

6 Variable setzen[ $r ; Wert: MBS("DynaPDF.OpenPDFFromContainer"; $pdf;ZUGFeRD Invoice::Invoice Template) ]

7 # Alle Seiten importieren

8 Variable setzen[ $r ; Wert: MBS("DynaPDF.ImportPDFFile"; $pdf) ]

9 # Für PDF/A muss eine Sprache gesetzt sein

10 Variable setzen[ $r ; Wert: MBS("DynaPDF.SetLanguage"; $pdf; "de-DE") ]

11 #PDF/A braucht einen Strukturbaum

12 Variable setzen[ $r ; Wert: MBS("DynaPDF.CreateStructureTree"; $pdf) ]

13 #Eventuell brauchen wir ICC Profile, falls welche fehlenfür Bilder.

14 Variable setzen[ $r ; Wert: MBS( "DynaPDF.SetReplaceICCProfile"; $pdf;"RGB"; "/Profiles/Generic RGB Profile.icc" ) ]

15 Variable setzen[ $r ; Wert: MBS( "DynaPDF.SetReplaceICCProfile"; $pdf;"Gray"; "/Profiles/Generic Gray Profile.icc" ) ]

16 Variable setzen[ $r ; Wert: MBS( "DynaPDF.SetReplaceICCProfile"; $pdf;"CMYK"; "/Profiles/Generic CMYK Profile.icc" ) ]

17 # XML hinzufügen

18 Variable setzen[ $FileHandle ; Wert: MBS("DynaPDF.AttachFileText"; $pdf;ZUGFeRD Invoice::Invoice XML;"UTF-8"; "ZUGFeRD-invoice.xml";"Invoice as XML") ]

19 Variable setzen[ $r ; Wert: MBS("DynaPDF.AssociateEmbFile"; $pdf;"Catalog"; -1;"Alternative"; $FileHandle) ]

20 # Auf Konformität prüfen für PDF/A 3b mit ZUGFeRD Basic

21 Variable setzen[ $c ; Wert: MBS("DynaPDF.CheckConformance"; $pdf;"ZUGFeRD Basic") ]

22 Wenn[ $c = 1 ]

23 # Ein RGB Profil muss als Output Intent gesetzt werden

24 Variable setzen[ $r ; Wert: MBS("DynaPDF.AddOutputIntentEx"; $pdf;ZUGFeRD Invoice::RGB ICC Profile) ]

25 Sonst, wenn[ $c = 2 ]

26 # Ein CMYK Profil muss als Output Intent gesetzt werden

27 Variable setzen[ $r ; Wert: MBS("DynaPDF.AddOutputIntentEx"; $pdf;ZUGFeRD Invoice::CMYK ICC Profile) ]

28 Sonst, wenn[ $c = 3 ]

29 # Ein RGB, Grau oder CMYK Profil muss als Output Intent gesetzt werden

30 Variable setzen[ $r ; Wert: MBS("DynaPDF.AddOutputIntentEx"; $pdf;ZUGFeRD Invoice::RGB ICC Profile) ]

31 Ende (wenn)

32 # Sichern in einen Container

Plugins & Tools

25 FMM_201801

33 Variable setzen[ $PDFData ; Wert: MBS("DynaPDF.Save"; $pdf; "invoice.pdf")]

34 Feldwert setzen[ ZUGFeRD Invoice::Output PDF ; $PDFData ]

35 Schreibe Änderung Datens./Abfrage[ Mit Dialog: Ein ]

36 # Speicher freigeben

37 Variable setzen[ $r ; Wert: MBS("DynaPDF.Release"; $pdf) ]

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

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:

1 # Neue PDF Umgebung

2 Variable setzen[ $pdf ; Wert: MBS("DynaPDF.New") ]

3 # PDF Dokument lesen

4 Variable setzen[ $r ; Wert: MBS("DynaPDF.OpenPDFFromContainer"; $pdf;ZUGFeRD Extract XML::Input PDF) ]

5 Variable setzen[ $r ; Wert: MBS("DynaPDF.ImportPDFFile"; $pdf) ]

6 # Schleife über alle eingebetteten Dateien

7 Variable setzen[ $FileCount ; Wert: MBS("DynaPDF.GetEmbeddedFileCount";$pdf) ]

8 Wenn[ $FileCount > 0 ]

9 Variable setzen[ $index ; Wert: 0 ]

10 Schleife (Anfang)

11 # Eigenschaften abfragen

12 Variable setzen[ $Name ; Wert: MBS( "DynaPDF.GetEmbeddedFile"; $pdf;$index; "Name") ]

13 Variable setzen[ $MimeType ; Wert: MBS( "DynaPDF.GetEmbeddedFile"; $pdf;$index; "MimeType") ]

14 Variable setzen[ $Description ; Wert:MBS( "DynaPDF.GetEmbeddedFile"; $pdf;$index; "Description") ]

15 Wenn[ $MimeType = "text/xml" UND $MimeType ="ZUGFeRD-invoice.xml" ]

16 Variable setzen[ $Content ; Wert: MBS( "DynaPDF.GetEmbeddedFile"; $pdf;$index; "Content"; "UTF8") ]

17 Feldwert setzen[ ZUGFeRD Extract XML::Output XML ; $Content ]

18 Ende (wenn)

19 # nächste Datei

20 Variable setzen[ $index ; Wert: $index + 1 ]

21 Verlasse Schleife wenn[ $index = $FileCount ]

22 Schleife (Ende)

23 Sonst

24 Eigenes Dialogfeld anzeigen[ "No embedded files." ]

25 Ende (wenn)

26 # Speicher freigeben

27 Variable setzen[ $r ; Wert: MBS("DynaPDF.Release"; $pdf) ]

Lizenzen

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. ■

Fußnoten

1) FeRD: www.ferd-net.de

2) ZUGFeRD Format: https://konik.io/ZUGFeRD-Spezifikation/Das-ZUGFeRD-Format_1p0.pdf

3) ICC Farbprofil Download: www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html

2017

02

Das unabhängige Magazin für FileMaker Anwender und Entwickler FMM_201702

© Ir

ene

Karg

er

FileMaker CloudIndividuelle Software-Bereitstellung

Es kann nur einen geben

Datensätze sperren

Perfekte Wahl

Tastensymbole

Per Script gesteuert

PDF-Scans

Datensätze bearbeiten

Ausschnitte

Praxisanwendung

Logische Operationen

2017

04

Das unabhängige Magazin für FileMaker Anwender und Entwickler FMM_201704

Tite

lbild

: © iS

tock

.com

/ ale

xtkt

Mit SicherheitExternes Backup von Serverdateien

Die 100-Tage-Bilanz

FileMaker 16

Kundenfreundlich

Komfortable Eingabe

Verteilungsstrategien

Mobile Lösungen

Jetzt noch magischer

Magic Value Lists 2.0

FileMaker Konferenz

Salzburg 4.0

ISSN 1431-71762017

03

Das unabhängige Magazin für FileMaker Anwender und Entwickler FMM_201703

Tite

lbild

: © P

hoto

creo

Bed

nare

k/Fo

tolia

Hallo Welt!FileMaker 16 öffnet neue Türen

Überblick

Neue Funktionen

Karte

Neuer Fensterstil

Namensgebung

Schöner exportieren

Konferenz

Einladung nach Salzburg

Programmierung

Rekursion

Das FileMaker Magazinn Einzige, deutschsprachige Fachzeitschrift zu FileMaker

n Wissen aus erster Hand von anerkannten FileMaker Fachautoren

n Große Themenvielfalt für Anwender und Entwickler

Exklusiv für Premium-Abonnentenn Sechs FMM Ausgaben pro Jahr

n Kostenlose Nutzung des Abonnentenbereichs auf www.filemaker-magazin.den PDF-Archiv mit allen bisher veröffentlichen Ausgaben

n Jede Ausgabe mit kostenlosen Beispieldateien und Zusatzinfos zum Download

Unser Servicen Aktuelle Neuheiten, Tipps und Infos, Kleinanzeigen und vieles mehr jederzeit auf

unseren Webseiten

n Hilfe bei allen Fragen zu FileMaker im FMM Forum

n Kompetente Beratung zum Kauf von FileMaker Lizenzen: Einfach anrufen +49 (0)40 589 65 79 70.

Hier finden Sie Aktuelles zu FileMaker Lizenzen, egal ob Sie kaufen, mieten oder sich einfach informieren möchten.

Eine kostenlose Leseprobe des FileMaker Magazins erhalten Sie, wenn Sie hier klicken.

Wenn Sie sich für ein FileMaker Magazin Abo interessieren, klicken Sie bitte hier!