Erstellung und Hinzufügen von Dateien
AddExternalFile()
Diese Funktion fügt eine oder mehrere externe Dateien aus dem Dateisystem nachträglich als Anlagen zum xSuite-Interface-Dokument hinzu.
Hinweis
Abweichend vom Standardverhalten eines Dateimakros werden keine bestehenden Dateianlagen als Quelle herangezogen. Der erste Standardparameter für das Quelldateimuster hat hier daher keine Bedeutung.
Das Namensmuster für die Zieldateien lautet standardmäßig %FileName% und bezieht sich auf die externen Dateien, deren Originalnamen somit übernommen werden.
Parameter | Datentyp | Beschreibung |
|---|---|---|
2 | Text | |
3* | Text | Pfad des Wurzelverzeichnisses, von dem aus nach den externen Dateien gesucht wird |
4* | Text | Namensfilter für die zu suchenden Dateien Alle Dateien, die unter diesem Muster gefunden werden, werden übernommen. |
5 | Bool | Wahrheitswert, ob die auf diesem Wege angefügten Dateianlagen in das Backup des betreffenden Stapels einbezogen werden, d.h. abschließend gesichert und – sofern Standardwert: Anders als bei normalen Eingabedateien aus dem Dateisystem wird im Sicherungsverzeichnis nicht die relative Quellverzeichnisstruktur nachgebildet, sondern die Dateien werden immer in die Wurzel des Sicherungsverzeichnisses kopiert. |
Beispiele
AddExternalFile( , , "c:/test", "*.pdf|*.xml") fügt alle PDF-Dateien und XML-Dateien aus dem angegeben Verzeichnis unter dem Original-Dateinamen als Dateianlagen hinzu.
AddFileFromBase64()
Diese Funktion dekodiert eine Base64-kodierte Zeichenfolge und erzeugt eine Dateianlage mit dem dekodierten Wert als Inhalt.
Hinweis
Abweichend vom Standardverhalten eines Dateimakros werden keine bestehenden Dateianlagen als Quelle herangezogen. Der erste Standardparameter für das Quelldateimuster hat hier daher keine Bedeutung.
Da kein Bezug zu einer Datei vorhanden ist und der Dateityp unbekannt ist, ist der Standardname der Zieldatei nur fromBase64.bin. Im zweiten Standardparameter sollte daher explizit ein sinnvoller Name für die Datei angegeben werden.
Parameter | Datentyp | Beschreibung |
|---|---|---|
2 | Text | |
3* | Text | Base64-kodierte Zeichenfolge Der dekodierte Wert dieser Zeichenfolge wird in eine Dateianlage überführt. |
Beispiele
AddFileFromBase64( , "test.txt", "SGVsbG8gV29ybGQ=") fügt eine Dateianlage test.txt mit dem dekodierten Inhalt Hello World hinzu.
AddFileFromField()
Diese Funktion erzeugt aus dem Inhalt eines Dokumentenfeldes eine Textdateianlage. Feldinhalte, die nicht den Datentyp "Text" haben, werden in eine Textdarstellung in programminterner String-Notation überführt.
Hinweis
Abweichend vom Standardverhalten eines Dateimakros werden keine bestehenden Dateianlagen als Quelle herangezogen. Der erste Standardparameter für das Quelldateimuster hat hier daher keine Bedeutung.
Der Standardname für die Zieldatei ist %FileBaseName%.txt. Der FileBaseName hat mangels Quelldatei den Namen des Quellfeldes aus dem Feldkatalog.
Parameter | Datentyp | Beschreibung |
|---|---|---|
2 | Text | |
3* | Text | Name des Feldes aus dem Feldkatalog, dessen Inhalt in eine Dateianlage überführt wird |
4 | Text | Zeichenkodierung der zu erstellenden Dateianlage:
|
Beispiele
AddFileFromField( , , "Field1", "Utf8") fügt eine Dateianlage Field1.txt mit dem UTF-8-kodierten Textinhalt des Feldes Field1 hinzu.
AddFileFromWebService()
Die Funktion führt eine Abfrage gegen einen externen Webservice aus und fügt den HTTP-Body-Inhalt aus dessen Antwort als Anlage zum xSuite-Interface-Dokument hinzu.
Hinweis
Abweichend vom Standardverhalten eines Dateimakros werden keine bestehenden Dateianlagen als Quelle herangezogen. Der erste Standardparameter für das Quelldateimuster hat hier daher keine Bedeutung.
Das Namensmuster für die Zieldatei ist standardmäßig %FileName%. Das Programm versucht, den Dateinamen aus dem Antwort-Header ("Content-Disposition") des Webservices auszulesen. Alternativ wird versucht, die Dateiendung anhand des "Content-Type" zu ermitteln. Wenn dies nicht erfolgreich ist, ist der Standardwert für den Basisdateiname und die Basisdateiendung download und bin.
Parameter | Datentyp | Beschreibung |
|---|---|---|
2 | Text | |
3* | Text | Name der Eigenschaft |
4 | Text | Wert, der als HTTP-Body-Inhalt an den Webservice übertragen wird |
5 | Text | Alternative zu Parameter 4: Namensfilter für eine Dateianlage, deren Inhalt als HTTP-Body an den Webservice übertragen wird Dabei wird nur die erste gefundene Anlage berücksichtigt. Die Daten aus Parameter 4 sowie aus einer Text-, JSON- und XML-Datei werden immer in Textform übertragen. Sonstige Dateitypen werden als Binärdaten übertragen. |
6 | Text | Wert des zugehörigen "Content-Type"-Headers zu den im HTTP-Body übertragenen Daten (gemäß Parameter 4 oder 5) , z. B. Wenn die Daten aus einer Dateianlage stammen, wird bei Weglassung dieses Wertes versucht, diesen implizit anhand des Dateityps zu ermitteln. |
Beispiele
AddFileFromWebService( , "result.json", "WebService1", "{}", , "application.json") sendet die Daten eines (im Beispiel leeren) JSON-Objekts an einen Webservice. Die Verbindungsparameter des Webservices sind unter dem Namen WebService1 in der Konfiguration definiert. Die Antwort wird als Dateianlage result.json hinzugefügt.
AddFileFromWebService( , "google.html", "Google") lädt die HTML-Daten der Startseite von Google, wenn eine Webservice-Verbindung namens Google mit der URL https://www.google.com und der Methode GET konfiguriert ist, und fügt die Antwort als Dateianlage google.html hinzu.
AddToZip()
Diese Funktion fügt zu einer bestehenden ZIP-Containerdatei weitere Dateianlagen hinzu.
Abweichend vom Standardverhalten eines Dateimakros wird in diesem Fall keine neue Zieldatei generiert, sondern nur die Quelldatei inhaltlich verändert. Wenn die Quelldatei in diesem Zuge einen neuen Namen erhalten soll, lautet das Namensmuster dafür standardmäßig %FileBaseName%.zip.
Parameter | Datentyp | Beschreibung |
|---|---|---|
1 | Text | |
2 | Text | |
3* | Text | Namensfilter der Dateien, die in die ZIP-Datei eingefügt werden Die ZIP-Datei selbst wird über den Namensfilter im ersten Standardparameter selektiert. |
4 | Text | optionale relative Pfadangabe, unter der die Dateien in die ZIP-Datei eingefügt werden |
Beispiele
AddToZip("test.zip", "%FileBaseName%.extended.zip", "*.doc|*.docx", "docs") fügt alle Microsoft-Word-Dateianlagen in eine bestehende ZIP-Dateianlage im Unterordner docs ein und benennt diese ZIP-Datei in test.extended.zip um.
CreateKositVisualization()
Diese Funktion erstellt eine Visualisierung einer XRechnung-XML-Datei im HTML-Format mit Hilfe der KoSIT-XSL-Transformationsdateien (siehe https://github.com/itplr-kosit/xrechnung-visualization). Der Standardname der Zieldatei ist %FileBaseName%.html.
Die Ausführung der Transformation wird im Standard über eine die .NET-API-Version des externen XSLT-Prozessors "Saxon-HE" durchgeführt. Diese Version ist in der Auslieferung enthalten. Alternativ ist der Aufruf einer Kommandozeilenversion des Prozessors möglich. In diesem Fall sind zusätzliche Programmdateien bereitzustellen, die in der .NET-Version des Saxon-HE-Paketes enthalten sind (siehe z. B. https://sourceforge.net/projects/saxon/files/Saxon-HE/10/Dotnet).
Parameter | Datentyp | Beschreibung |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | optionaler, vollständiger Pfad der Programmdatei Dieser Parameter ist nur relevant, wenn die Transformation über die Kommandozeilenversion des Saxon-XSLT-Prozessors erfolgt. |
4* | Text | vollständiger Pfad des Verzeichnisses mit den KoSIT-XSL-Transformationsdateien (Unterordner |
5 | Bool | Wahrheitswert, ob eine fehlgeschlagene Erstellung der Visualisierungsdatei nur als Warnung statt als Fehler behandelt wird, d.h. die Verarbeitung dennoch fortgesetzt wird Standardwert: |
Beispiele
CreateKositVisualization("test.xml", , , "c:/kosit/xsl") erzeugt aus einer XRechnung-XML-Dateianlage eine Dateianlage test.html mit der Visualisierung.
CreateKositValidatorReport()
Diese Funktion ruft den externen KoSIT-Validator mit einer (XRechnung-) XML-Datei auf und fügt die vom Validator im XML-Format und HTML-Format generierten Reports als neue Dateianlagen an. Der Standardname für die Zieldateien ist %FileBaseName%.report.%FileExt%, wobei die Dateiendungen %FileExt% hier die der Report-Dateien sind, also xml und html.
Für die Ausführung der Validierung werden der KoSIT-Validator (siehe https://github.com/itplr-kosit/validator) mit einer passenden JAVA-Laufzeitumgebung sowie geeignete Prüfschemata (siehe z. B. https://github.com/itplr-kosit/xrechnung-schematron) benötigt. Fertige Bundles für bestimmte XRechnung-Versionen werden von der KoSIT unter https://xeinkauf.de/xrechnung/versionen-und-bundles bereitgestellt.
Parameter | Datentyp | Beschreibung |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | Modus, in dem der Validator aufgerufen wird:
Standardmäßig wird der Validator für jeden Prüfauftrag über die Kommandozeile neu gestartet, um sich danach wieder zu beenden. Alternativ bietet er einen Betriebsmodus, in dem er dauerhaft im Hintergrund läuft und als Webservice Anfragen entgegennimmt, was deutlich performanter ist. Dazu muss er einmalig in diesem Modus gestartet werden, z. B. durch einen Job in der Windows-Aufgabenplanung. Wenn der Webservice lokal auf demselben Rechner wie xSuite Interface laufen soll, kann dieses ihn auch selbst zu starten versuchen, wenn er unter der konfigurierten Adresse nicht erreichbar ist und daher mutmaßlich noch nicht läuft. |
4(*) | Text | vollständiger Pfad der auszuführenden .jar-Datei des KoSIT-Validators Dieser Parameter wird im Modus |
5(*) | Text oder Array | vollständiger Pfad oder (bezogen auf Parameter 4) relativer Pfad der Prüfszenario-Konfigurationsdatei, mit der der KoSIT-Validator aufgerufen wird Im Standard ist das die Datei HinweisZusätzlich benötigt der KoSIT-Validators beim Aufruf eine Angabe des Repository-Ordners für das Prüfszenario. Dazu wird implizit, d.h. nicht frei konfigurierbar, der Ordnerpfad der Konfigurationsdatei verwendet. Dieser Parameter wird im Modus Um den Validator mit mehreren parallel zu nutzenden Szenarien aufzurufen, kann statt eines einzelnen Parameters auch ein Array mit einer Auflistung mehrerer Szenariopfade übergeben werden. |
6 | Text | optionaler Ordnerpfad des Verzeichnisses Standardmäßig wird diese über eine entsprechend gesetzte Umgebungsvariable JAVA_HOME gefunden. Dieser Parameter wird im Modus |
7 | Text | IP-Adresse des Webservices im Modus Standardwert: |
8 | Number | IP-Port des Webservices im Modus Standardwert: |
Beispiele
CreateKositValidatorReport("test.xml", , "CommandLine", "c:/kosit/validationtool-1.5.0-standalone.jar", "scenarios.xml", "c:/java/bin") erzeugt für eine XRechnung-XML-Dateianlage die Dateianlagen test.report.xml und test.report.html.
CreatePeppolInvoiceVisualization(), CreateXRechnungVisualization()
Diese Funktion generiert eine Visualisierung einer PEPPOL-Rechnung- Datei oder einer XRechnung-XML-Datei im Microsoft Word-Format oder im PDF-Format.
Der Standardname der Zieldatei ist %FileBaseName%.%FileExt%. Die Dateiendung %FileExt% leitet sich aus dem gewünschten Zielformat ab.
Parameter | Datentyp | Beschreibung |
|---|---|---|
1 | Text | |
2 | Text | |
3* | Text | Die Visualisierung basiert auf einem Microsoft Word-Dokument, das als Vorlage dient. Hier muss der vollständige Pfad dieser Datei angegeben werden. |
4 | Text | Zielformat, in dem die Visualisierungsdatei ausgegeben wird:
|
5 | Text | optionales Ausgabeformat für Feldwerte, die vom Typ "Code" sind Für diese Feldwerte findet automatisch eine Umsetzung in den (englischen) Klartextnamen statt, anhand von Code-Listen, die von der KoSIT vorgegeben sind. Der Standardwert für den Parameter ist |
6 | Number | maximale Anzahl in einer Rechnung vorhandener Positionsdatenzeilen, bis zu der die Detailansicht der Positionsdatenzeilen ausgegeben werden soll Bei Überschreitung dieses Wertes wird die Detailansicht vollständig weggelassen und nur die zusammenfassende Kurzansicht der Positionsdaten ausgegeben. Als Standardwert ist dieser Parameter leer, sodass keine künstliche Begrenzung der Ausgabe erfolgt. |
Die Visualisierung erfolgt auf Basis einer Word-Datei. Diese Word-Datei definiert das Layout. Das Programm fügt an den definierten Stellen in der Word-Datei die Feldwerte der elektronischen Rechnung ein.
Hinweis
Für beide unterstützten Rechnungsformate ist jeweils eine Beispieldatei im Unterordner Templates des Programmverzeichnisses verfügbar. Die Beispieldateien umfassen alle relevanten Felder und können als Grundlage für individuelle Anpassungen dienen.
Dabei sind folgende Konventionen zu beachten:
Textmarken werden genutzt, um die Positionen der in die Datei einzufügenden Feldinhalte festzulegen. Die Namen der Textmarken entsprechen weitestgehend den Namen, die von den Indexdatenlesern der entsprechenden Rechnungsformate genutzt werden (siehe Verarbeitung – Indexdatenleser). Aufgrund einer Word-internen Längenbeschränkung für Textmarkenbezeichner sind einige von ihnen allerdings abweichend davon namentlich gekürzt. Die konkret verwendeten Bezeichner sind aus den Beispieldateien ablesbar.
Wenn derselbe Feldinhalt mehrfach im Dokument angezeigt werden soll, muss für alle zusätzlichen Vorkommnisse der Name der Textmarke mit einem angehängten Zähler in der Syntax
_{Nummer}versehen werden. Die Zählung der Nummer beginnt bei 2 und geht bis maximal 10.Für Einzelwerte erstreckt sich die Textmarke über den entsprechenden Platzhaltertext. Für multiple Werte, die tabellarisch dargestellt werden, ist die komplette Tabellenspalte mit einer Textmarke zu versehen. Mit tabellarischen Daten sind hier keine Positionszeilen gemeint, denn diese werden anders behandelt (siehe nächster Punkt).
Positionsdaten können auf 2 Arten dargestellt werden:
Als zusammenfassende Kurzansicht in Form einer flachen Tabelle
In dieser Ansicht entspricht jede Zeile einer Position. Dabei sind ausschließlich Einzelwerte darstellbar, d.h. keine multiplen Werte in Form von Untertabellen. Über das gesamte Tabellenelement ist in der Vorlage eine Textmarke mit dem festen Namen "INVOICE_LINES" zu definieren. Für die einzelnen Felder muss die obige Konvention eingehalten werden, d.h. die betreffenden Spalten müssen als Ganzes jeweils mit einer Textmarke versehen werden.
Als Detailansicht in Form eines Dokumentbereiches
Der Dokumentbereich muss in der als Vorlage dienenden Datei nur genau einmal unter dem festen Textmarkennamen "INVOICE_LINE" definiert werden. Von diesem Dokumentbereich wird dann zur Laufzeit für jede einzelne Zeile eine Kopie erstellt. Aus technischen Gründen muss der Bereich zwar ein Tabellenelement sein, stellt inhaltlich aber keine flache Tabelle mit einheitlicher Zeilenstruktur dar. Das Tabellenelement dient nur als Strukturierungselement, das in den Tabellenzellen sowohl einzelne Feldwerte als auch Untertabellen für multiple Werte enthalten kann. Innerhalb des Bereiches gelten die gleichen Konventionen für die Textmarkendefinition wie oben beschrieben, nur eben beschränkt auf Positionsdatenfelder.
Ausschließlich für PEPPOL-Rechnungen gilt eine zusätzliche Logik, die analog zur beschriebenen Detailansicht von Positionsdaten ist: Ein Tabellenelement kann mit der Textmarke "PAYMENT_MEANS" versehen werden, sodass dieses Element zur Laufzeit für jedes Vorkommen einer Zahlungsanweisung kopiert wird.
Beispiele
CreateXRechnungVisualization("test.xml", , "c:/template.docx", "PDF") erzeugt aus einer XRechnung-XML-Dateianlage eine Dateianlage test.pdf mit der Visualisierung unter Nutzung der Microsoft-Word-Vorlage template.docx.
CreateZip()
Diese Funktion erstellt eine ZIP-Containerdatei aus den selektierten Quelldateien.
Der Standardname der Zieldatei ist %FileBaseName%.zip, wobei hier der Name der ersten Quelldatei zugrunde gelegt wird.
Parameter | Datentyp | Beschreibung |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | optionale relative Pfadangabe, unter der die Quelldateien in die ZIP-Datei eingefügt werden |
Beispiele
CreateZip("*.doc|*.docx", "test.zip", "docs") erzeugt eine neue Dateianlage test.zip und fügt alle bestehenden Microsoft-Word-Dateianlagen in einen Unterordner docs ein.