ZUGFeRD PDF/A

ZUGFeRD is the German acronym for the Central User Guidelines of the Forum for Electronic Billing in Germany (Zentraler User Guide des Forums elektronische Rechnungen Deutschland). ZUGFeRD is a uniform data format for the standardization of electronic invoices and is used for the exchange of electronic invoices. It combines the advantages of both XML and PDF formats in one single file. A ZUGFeRD invoice is a PDF/A-3 file into which an XML structure containing all invoice information is embedded to provide them in a machine-readable form. Thus, they can be both processed electronically and read visually. ZUGFeRD-compatible invoices consist of a PDF/A-3 file with an embedded XML containing the data record as structured data.

Using the ZUGFeRD Utility requires a valid license!

Usage

You can use the ZUGFeRD PDF/A-3 Utility both to extract data from incoming ZUGFeRD files and to convert invoice data from the workflow into the ZUGFeRD format.

Both standards ZUGFeRD 1.0 and ZUGFeRD 2 (2.0, 2.1 and 2.2) are supported. In read mode, the ZUGFeRD version is detected automatically. In build mode, you need to select the standard for which the PDF file shall be created using the ZUGFeRD version drop-down list on the Settings dialog.

Functional concept

  • Read and extract: ZUGFeRD PDF/A-3 > XML

    The ZUGFeRD Utility can read PDF/A-3 ZUGFeRD files and extract corresponding XML invoice data. The extracted invoice data are written as ZUGFeRD-invoice.xml into the output message and additional metadata are included as a workflow variable in the output message, too. Both can be further processed in the workflow.

  • Build/create: XML + PDF/A-1 > ZUGFeRD PDF/A-3

    In order to convert documents from the workflow into the ZUGFeRD PDF/A-3 archiving format the input message is used to merge a PDF/A-1 document and two variables containing invoice information in the form of the ZUGFeRD-invoice.xml as well as the respective metadata into a ZUGFeRD file in PDF/A-3 format.

module guide 1287 1

Module Properties and Variables of the ZUGFeRD Utility

The following module properties can be set for the ZUGFeRD Utility:

Name Description/Value Default

pluginType

For reading and creating. Defines the ZUGFeRD processing mode:

0 - Read/extract

1 - Build/create

0

validateInvoice

For reading and creating.

true - The ZUGFeRD-invoice.xml is validated according to the ZUGFeRD_1p0.xsd schema.

false - No validation of ZUGFeRD-invoice.xml is performed.

false

zugferdMetaData

Only for creating. Contains ZUGFeRD-relevant metadata and is composed of the four parameters:

  • DocumentFileName

  • ConformanceLevel

  • DocumentType

  • Version

When creating a file, the ZUGFeRD metadata are written into the PDF/A-3 document.

 
<Property name="zugferdMetaData" type="Map">
    <Property name="ConformanceLevel">BASIC</Property>
    <Property name="DocumentFileName">ZUGFeRD-invoice.xml</Property>
    <Property name="DocumentType">INVOICE</Property>
    <Property name="Version">1.0</Property>
</Property>

extractAllMetaData

For reading and creating.

true - All XMP metadata of the PDF document are returned in the zugferdPdfMetaData variable (in addition to the 4 ZUGFeRD metadata).

false - Only the 4 ZUGFeRD metadata are returned.

false

zugferdNamespace

For reading and creating. Namespace of ZUGFeRD metadata.

urn:ferd:pdfa:CrossIndustryDocument:invoice:1p0#

validateInputPdf

Only for creating.

true - The document in the input message is checked for PDF/A-1 conformity.

false - PDF/A-1 check is ignored.

true

invoice

Mandatory - must be set! Only for creating.

Contains the ZUGFeRD-invoice.xml.

During the execution of the ZUGFeRD Utility, the following module variables are set as output variables and are available for the rest of the workflow’s execution.

Name Description/Value

zugferdPdfMetaData

If the extractAllMetaData variable is set, the output variable contains all XMP metadata from the document.

zugferdMetaData

Contains ZUGFeRD-relevant metadata and contains four parameters:

  • DocumentFileName

  • ConformanceLevel

  • DocumentType

  • Version

In order to be able to use the output variables in the following workflow, you must define the respective module variables in the variables mapping of the module immediately following the ZUGFeRD Utility as described in chapter Workflow Variables and Mappings.

For further information about variables and their usage, refer to Workflow Variables and Mappings.

Reading a ZUGFeRD File

You can use the INUBIT ZUGFeRD Utility to read ZUGFeRD-compliant invoices and transfer the extracted invoice data as well as metadata to the following workflow.

Prerequisites

You have made a ZUGFeRD PDF/A-3 file available to the workflow, e.g. by using a File Connector.

Proceed as follows

  1. Integrate the ZUGFeRD module into the workflow.

  2. Open the module for editing by using the context menu.

  3. In the Properties dialog, click Settings.

  4. Select the option Read ZUGFeRD file and extract XML invoice data.

  5. Optionally: If the namespace your message contains differs from the standard namespace, activate the option Overwrite default ZUGFeRD namespace and enter the differing namespace in the respective field.

  6. Optionally: If you want to validate the invoice data in your ZUGFeRD-invoice.xml, activate the respective option.

  7. Optionally: If - in addition to the ZUGFeRD metadata - you want to read and extract all other metadata, activate the respective option.

  8. Once you have defined all options for reading the file, click Finish.

The output message contains the ZUGFeRD-invoice.xml. The workflow variable zugferdPdfMetaData containing the metadata is automatically available after the module execution, if the module property extractAllMetaData has been set (refer to Module Properties and Variables of the ZUGFeRD Utility).

Creating a ZUGFeRD File

In order to create a ZUGFeRD file, you must first define the settings for creating ZUGFeRD-compliant invoices using the ZUGFeRD Utility in a workflow.

Prerequisites

  • You have created an input message by using e.g. an FO Converter (refer to FO Converter.

  • The input document (PDF) for creating a ZUGFeRD document is available in PDF/A-1 format.

  • The input message for the ZUGFeRD Utility contains the PDF/A-1 document, an XML workflow variable containing the contents of the `ZUGFeRD-invoice.xml a`nd an XML workflow variable containing metadata.

Proceed as follows

  1. Integrate a ZUGFeRD module in your workflow.

  2. Open the module for editing by using the context menu.

  3. In the Properties dialog, click Settings.

  4. Select the option Build ZUGFeRD file.

  5. Optionally: If you want to check the input document for PDF/A-1-validity, activate the Validate imported PDF option.

  6. Optionally: If necessary, activate the options in the Namespace and Further options area (refer to ZUGFeRD Settings Dialog).

  7. If you have defined the required settings for creating a file, click Finish.

  8. In order to fill the variables invoice and zugferdMetaData, you must create the respective mapping rules in the variables mapping. To do this, open the variables mapping dialog by using the context menu. (refer to chapter Workflow Variables and Mappings).

  9. Create your mapping rule for filling the variables (refer to Creating Mapping Rules for the Mapping of Variables), use Module property as Target and select the desired variable.

  10. Once you have created your mapping rule, click OK. The mapping dialog closes.

The output message contains the ZUGFeRD-PDF/A-3 file with embedded XML invoice data and XML metadata.

ZUGFeRD Settings Dialog

In this dialog, you define the functions of the respective processing mode of the ZUGFeRD Utility as well as the corresponding options.

ZUGFeRD version (for build mode only)

Select the ZUGFeRD standard version to be used for creating the ZUGFeRD file.

In read mode, the ZUGFeRD standard version is detected automatically.

Processing mode

  • Read ZUGFeRD file and extract XML invoice data

    Selecting this option activates the reading of imported ZUGFeRD-PDF/A-3 documents and the extracting of the `ZUGFeRD-invoice.xml `as well as the transfer of metadata as workflow variable.

  • Build ZUGFeRD file

    Selecting this option activates the creation of ZUGFeRD files: by merging an incoming PDF/A-1 document, a workflow variable as ZUGFeRD-invoice.xml, and a workflow variable containing metadata, a ZUGFeRD-PDF/A-3 document is created.

  • Validate imported PDF (only available in the Build ZUGFeRD file mode)

    This option checks the PDF/A-1-conformity of the input document. This format is required for the input message in order to create a ZUGFeRD-PDF/A-3-compatible document.

Namespace

  • Overwrite default ZUGFeRD namespace

    Select this option, if the ZUGFeRD metadata cannot be located by using the default namespace.

  • ZUGFeRD namespace

    Enter the correct namespace that differs from the default namespace.

    Once this option is deactivated after initial activation, the manually entered namespace is overwritten automatically by the default namespace.

Further options

  • Validate invoice data (ZUGFeRD-invoice.xml)

    Validates the invoice data embedded in the ZUGFeRD-invoice.xml against the respective schema.

  • Extract all metadata

    Select this option, if you do not only want to read the ZUGFeRD metadata but all contained metadata.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen