Creating and Adding Files
AddExternalFile()
One or more external files from the file system are added to the xSuite Interface document as attachments by this function.
Notice
Deviating from the standard behavior of a file macro, no existing file attachments are used as the source, so the first default parameter for the source file pattern has no meaning here.
The name pattern for the target files is %FileName% by default and refers to the external files whose original names are adopted through this.
Parameter | Data Type | Description |
|---|---|---|
2 | Text | |
3* | Text | Path of the root directory from which the external files are searched for |
4* | Text | Name filter for the files to be searched for All files found under this pattern will be adopted. |
5 | Bool | Boolean value determining whether the file attachments attached this way will be included in the backup of the batch in question (i.e., backed up to complete the process and – if Default value: Unlike normal input files from the file system, the backup directory does not replicate the relative source directory structure; rather, the files are always copied to the root of the backup directory. |
Examples
AddExternalFile( , , "c:/test", "*.pdf|*.xml") adds all PDF files and XML files from the specified directory as file attachments under their original file names.
AddFileFromBase64()
This function decodes a Base64-encoded string and creates a file attachment with the decoded value as content.
Notice
Deviating from the standard behavior of a file macro, no existing file attachments are used as the source, so the first default parameter for the source file pattern has no meaning here.
As there is no reference to a file and the file type is unknown, the default name of the target file is only fromBase64.bin. A meaningful name for the file should therefore be explicitly specified in the second standard parameter.
Parameter | Data Type | Description |
|---|---|---|
2 | Text | |
3* | Text | Base64-encoded string The decoded value of this string is transferred to a file attachment. |
Examples
AddFileFromBase64( , "test.txt", "SGVsbG8gV29ybGQ=") adds a file attachment test.txt with the decoded content Hello World.
AddFileFromField()
This function creates a text file attachment from the content of a document field. Field contents that are not of the data type "Text" are converted into a text representation in the program's internal string notation.
Notice
Deviating from the standard behavior of a file macro, no existing file attachments are used as the source, so the first default parameter for the source file pattern has no meaning here.
The default name for the target file is %FileBaseName%.txt. In the absence of a source file, the FileBaseName has the name of the source field from the field catalog.
Parameter | Data Type | Description |
|---|---|---|
2 | Text | |
3* | Text | Name of the field from the field catalog whose content is transferred to a file attachment |
4 | Text | Indicates the character encoding of the file attachment file to be created:
|
Examples
AddFileFromField( , , "Field1", "Utf8") adds a file attachment Field1.txt with the UTF-8-encoded text content of the Field1 field.
AddFileFromWebService()
The function executes a query against an external web service and adds the HTTP body content from its response as an attachment to the xSuite Interface document.
Notice
Deviating from the standard behavior of a file macro, no existing file attachments are used as the source, so the first default parameter for the source file pattern has no meaning here.
By default, the name pattern for the target file is %FileName%. The program attempts to read the file name from the response header ("Content-Disposition") of the web service. Alternatively, an attempt is made to determine the file extension using the "Content-Type." If this is not successful, the default value for the base file name and the base file extension will be download and bin.
Parameter | Data Type | Description |
|---|---|---|
2 | Text | |
3* | Text | Name of the |
4 | Text | Value that is transferred to the web service as HTTP body content |
5 | Text | Alternative to the fourth parameter: name filter for a file attachment whose content is transferred to the web service as an HTTP body Only the first attachment found will be taken into account. The data from the fourth parameter and from a file of text, JSON, or XML type is always transferred in text form. Other file types are transferred as binary data. |
6 | Text | Value of the associated "Content-Type" header for the data transferred in the HTTP body (according to parameter 4 or 5) (e.g., For data in JSON format, this might be application/json, for example. If the data originates from a file attachment, an attempt will be made to determine the value implicitly based on the file type if this value is omitted. |
Examples
AddFileFromWebService( , "result.json", "WebService1", "{}", , "application.json") sends the data of a (in this example empty) JSON object to a web service. The connection parameters of the web service are defined in the configuration under the name WebService1. The response is added as a file attachment result.json.
AddFileFromWebService( , "google.html", "Google") loads the HTML data of the Google homepage if a web service connection named Google is configured with the URL https://www.google.com and the GET method, and adds the response as a file attachment google.html.
AddToZip()
This function adds additional file attachments to an existing ZIP container file.
Deviating from the standard behavior of a file macro, in this case no new target file is generated; only the content of the source file is changed. If the source file is to be given a new name in this process, then by default the name pattern for this is %FileBaseName%.zip.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | |
2 | Text | |
3* | Text | Name filter of the files that are to be inserted into the ZIP file The ZIP file itself is selected via the name filter in the first default parameter. |
4 | Text | Relative path specification under which the files are inserted into the ZIP file (optional) |
Examples
AddToZip("test.zip", "%FileBaseName%.extended.zip", "*.doc|*.docx", "docs") inserts all Microsoft Word file attachments into an existing ZIP file attachment in the docs subfolder and renames this ZIP file to test.extended.zip.
CreateKositVisualization()
This function creates a visualization of an XRechnung XML file in HTML format using KoSIT XSL transformation files (see https://github.com/itplr-kosit/xrechnung-visualization). The default name of the target file is %FileBaseName%.html.
The standard transformation is executed via a .NET API version of the external XSLT processor "Saxon-HE". This version is included in the delivery. Alternatively, it is possible to call a command-line version of the processor. In this case, additional program files must be provided. These program files are included in the .NET version of the Saxon-HE package (for more information, see a source such as https://sourceforge.net/projects/saxon/files/Saxon-HE/10/Dotnet).
Parameter | Data Type | Description |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | Full path of the This parameter is only relevant if the transformation is carried out via the command line version of the Saxon XSLT processor. |
4* | Text | Full path of the directory with the KoSIT XSL transformation files (subfolder |
5 | Bool | Boolean value determining whether a failed creation of the visualization file will be treated only as a warning instead of an error (meaning that processing will continue regardless) Default value: |
Examples
CreateKositVisualization("test.xml", , , "c:/kosit/xsl") creates a file attachment test.html with the visualization from an XRechnung XML file attachment.
CreateKositValidatorReport()
This function calls the external KoSIT validator with an (XRechnung) XML file and attaches the reports generated by the validator in XML format and HTML format as new file attachments. The default name for the target files is %FileBaseName%.report.%FileExt%, where the file extensions %FileExt% here are those of the report files (i.e., xml and html).
With a suitable JAVA runtime environment and suitable check schemas (for example, see https://github.com/itplr-kosit/xrechnung-schematron), the KoSIT validator (see https://github.com/itplr-kosit/validator) is required to run the validation. Ready-made bundles for specific XRechnung versions are provided by KoSIT at https://xeinkauf.de/xrechnung/versionen-und-bundles.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | Mode in which the validator is called:
By default, the validator is started anew via the command line for each validation job and then is terminated again. Alternatively, it offers an operating mode in which it runs permanently in the background and accepts requests as a web service, which performs much better. To use this option, start the validator in said background mode (e.g., by a job in Windows Task Scheduler). If the web service is to run locally on the same computer as xSuite Interface, then xSuite Interface can start it itself. This might be necessary if it is not accessible at the configured address and therefore presumably not yet running. |
4(*) | Text | Full path of the KoSIT-validator .jar file to be executed This parameter is needed in |
5(*) | Text or array | Full path or (in relation to the fourth parameter) relative path of the test scenario configuration file used to call the KoSIT Validator By default, this is the NoticeIn addition, the KoSIT validator requires the repository folder for the test scenario to be specified when it is called. For this purpose, the folder path of the configuration file is used implicitly, i.e. it is not freely configurable. This parameter is needed in To call up the validator with multiple scenarios to be used in parallel, an array with a list of multiple scenario paths can be transferred instead of a single parameter. |
6 | Text | Folder path of the By default, it is found via a JAVA_HOME environment variable that with the settings for this. This parameter is needed in |
7 | Text | IP address of the web service in Default value: |
8 | Number | IP port of the web service in Default value: |
Examples
CreateKositValidatorReport("test.xml", , "CommandLine", "c:/kosit/validationtool-1.5.0-standalone.jar", "scenarios.xml", "c:/java/bin") creates the file attachments test.report.xml and test.report.html for an XRechnung XML file attachment.
CreatePeppolInvoiceVisualization(), CreateXRechnungVisualization()
This function generates a visualization of a PEPPOL invoice file or an XRechnung XML file in Microsoft Word format or in PDF format.
The default name of the target file is %FileBaseName%.%FileExt%. The file extension %FileExt% is derived from the desired target format.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | |
2 | Text | |
3* | Text | The visualization is based on a Microsoft Word document that serves as a template. Specify the full path of this file here. |
4 | Text | Target format in which the visualization file will be output:
|
5 | Text | Output format for field values that are of type "code" (optional) For these field values, a conversion to the plain text name in English takes place automatically using code lists provided by KoSIT. The default value for the parameter is |
6 | Number | maximum number of item data lines available in an invoice up to which the detailed view of the item data lines is to be output If this value is exceeded, the detailed view will be omitted entirely and only the summarized short view of the item data is output. By default, this parameter is empty so that no artificial limitation of the output takes place. |
The visualization is based on a Word file. This Word file defines the layout. The program inserts the field values of the electronic invoice at the defined positions in the Word file.
Notice
A sample file for each of the two supported invoice formats is available in the Templates subfolder of the program directory. The sample files include all relevant fields and can serve as a basis for individual customizations.
Observe the following conventions:
Text marks are used to define the positions of the field contents to be inserted into the file. The names of the text marks correspond as far as possible to the names used by the index data readers of the corresponding invoice formats (see Index Data Reader Processing). However, due to an internal Word length restriction for text mark identifiers, some of them are shortened by name. The concrete identifiers used can be read from the example files.
If the same field content is to be displayed multiple times in the document, append the name of the bookmark for each additional occurrence with a counter in the syntax
_{number}. The number count starts at 2 and goes up to a maximum of 10.For scalar values, the bookmark extends over the corresponding placeholder text. For multiple values that are displayed in tabular form, enter a bookmark for the complete table column. Tabular data does not mean line-item rows here; these are handled differently (see next point).
Item data can be displayed in two different ways:
As a summary quick view in the form of a flat table
In this view, each line corresponds to an item. Only scalar values can be displayed (i.e., no multiple values in the form of sub-tables). Define a bookmark with the fixed name "INVOICE_LINES" across the entire table element in the template, and enter a bookmark for each complete table column.
As a detailed view in the form of a document area
Define the document area exactly once in the file serving as a template under the fixed bookmark name "INVOICE_LINE". A copy of this document area is then created at runtime for each individual line. For technical reasons, the area must be a table element, but in terms of content it does not represent a flat table with a uniform line structure. The table element serves only as a structuring element. As such, it might contain both individual field values and sub-tables for multiple values in the table cells. Within the area, the same conventions for the bookmark definition apply as described above, only restricted to item data fields.
Exclusively for PEPPOL invoices, an additional logic applies, analogous to the detailed view of item data: a table element can be provided with the bookmark "PAYMENT_MEANS," so that this element is copied at runtime for each occurrence of payment instructions.
Examples
CreateXRechnungVisualization("test.xml", , "c:/template.docx", "PDF") creates a file attachment test.pdf from an XRechnung XML file attachment with the visualization using the Microsoft Word template template.docx.
CreateZip()
This function creates a ZIP container file from the selected source files.
The default name of the target file is %FileBaseName%.zip; here, the name of the first source file is used.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | |
2 | Text | |
3 | Text | Relative path specification under which the source files are inserted into the ZIP file (optional) |
Examples
CreateZip("*.doc|*.docx", "test.zip", "docs") creates a new file attachment test.zip and places all existing Microsoft Word file attachments in a subfolder called docs.