EPO Consulting Wiki - ZUGFeRD - installation


This is an old version of this page. To the new page please click here

Das ist eine alte Version dieser Seite. Zur neuen Seite klicken sie hier

Create a PDFA-3B pdf file from an invoice - PDF and a CII XML-invoice by means of an ADS server. Please note, that this package is intended to be used with other packages, which supplies the XML and PDF files (e.g. EInvoice_-_ZUGFeRD, which is used by the EPO outgoing invoice Ledger).

Installation

Requirements
  • 'EPO connector' installed
  • Adobe ADS server installed and reachable
important: 'standard' fonts of the PDF (like Courier, Helvetica) has to be installed at the ADS server; otherwise, the ADS server will responde with an error message instead of a PDF/A; this is due to the fact, that PDF/A requires all fonts to be embedded, therefore the fonts need to be available at the ADS server
  • RFC destination 'ADS' (or similar name) to the ADS server maintained
  • EPO number range /EPO1/NOR is already defined

Download the installation package from the EPO NextCloud:

  • folder 'EPO eInvoice ZUGFeRD'
  • EPO_eInvoice_ZUGFeRD_v<version>_...zip


Installation

Import the latest version from each of the ZIP file - see importing EPO transport packages.

 

redefinition of user exit methods

If an 'user exit' method should be redefined, create a new class with the base class /EPO1/CL_INVOICE_ZUGFERD_PDF. In order to use this new class, the class name has to be maintained in table /EPO1/SUBCLASSES (see below).

method UE_GET_XML_FILENAME
override the default file names 'faktur-x.xml' / 'xrechnung.xml'

EPO customizing

Transaction /EPO1/EXC

create the ADS service

This recipee assumes, that there is only one ADS server available, for both - test- and productive SAP system.

  • EPO Connector Area Menu
  • EPO Connector Configuration
  • Maintain EPO Connector services
ClipCapIt-210112-173602.PNG

Create a new outgoing service:

  • Service: ADS
  • Direction: O - out of SAP
  • check 'Operation mandatory
  • Description: 'Adobe Document Server - webservice'

 

map a service id to the service

  • EPO Connector Area Menu
  • EPO Connector Configuration
  • Outbound Service Configuration
  • Maintain service assignment by SY-SYSID
ClipCapIt-210112-174928.PNG


Create an entry for each SAP - system (development, test, productive):

  • SAP system ID: ..the SAP ID
  • Service name id: ADS
  • Service: ADS

 

create the ADS operation

  • EPO Connector Area Menu
  • EPO Connector Configuration
  • Outbound Service Configuration
  • EPO Client
  • Out: Maintain EPO Client service configuration
ClipCapIt-210112-173831.PNG


Create a new operation:

  • Service: ADS
  • Operatition: create_pdf
  • NR object: /EPO1/NOR
  • Number Range Number: 01
  • Protocol: 0 http
  • Processing type: S synchronous
  • Message (+hd): X (store outgoing and incoming messages)
  • Meta data (+dh): X (store outgoing and incoming messages)
  • Compress: X
  • Destination: ADS (the RFC connection to the ADS server)
  • Description: Adobe Document Server: create PDFA-3B for ZUGFeRD

 

Customizing - table /EPO1/SUBCLASSES

Optional - this chapter applies only, if a new ZUGFERD-PDF-class has been created.

This table switches from the default - baseclass to a userdefined class.

Use transaction SM30 in order to create a new line with the base class /EPO1/CL_INVOICE_ZUGFERD_PDF and the name of the just created subclass.

 

Customizing - table /EPO1/INV_ZUG_VE

Optional - this mapping table assigns the ZUGFeRD version to a single customer. Only required in order to support the old version 1.0.

The content of this table is indirectly used by the transformation /EPO1/INVOICE_ZUGFERD_UBL_CII, using the class /EPO1/CL_INVOICE_ZUGFERD_VERS.

Use transaction SM30 in order to maintain this table (not a customizing table, to be maintained in each SAP system separately).


A line with empty customer number can be used to define the default version, which is then applied to all custumers without defined version.

 

Customizing for e-mail

ZUGFeRD invoices can be send via e-mail.

See page ZUGFeRD installation e-mail for details.

 

errors during PDF/A conversion

Sometimes, the ADS server cannot create a valid PDF/A file. The stack trace contains the string

Validation of PDFA output generated failed because its not satisfying 3b compliance test

..which describes an error, but does not help to solve the problem.


embedded fonts

Usually, this error is caused by missing fonts in the generated PDF/A.

SAP will embed only 'non-standard' fonts, so the 'standard' fonts are not embedded. In some SAP-releases, the ebedding of fonts can be forced. We try this solution in the adapted customer-print program by filling the modified parameter table: 

      ...
      " force the embedding of standard fonts
      ls_modified_parameter-name  = 'PREPARE_FOR_PDFA'.
      ls_modified_parameter-value = 'X'.
      APPEND ls_modified_parameter TO lt_modified_parameters.

      CALL FUNCTION 'CONVERT_OTF'
        EXPORTING
          format                = 'PDF'
          modified_param_table  = lt_modified_parameters
        ...


If this solution does not help, try installing the SAP-note 2989312.

 

SAP-note 2989312

As reference: SAP-note 2989312 describes this in detail.

SAP-note 2165275 describes the 'MODIFIED_PARAM_TABLE' more in detail.

The note also states, that the device type 'PDFUC' should be used (not sure, what this means).


Manual steps - add texts to class CL_RSTX_PDF_PARAMETER:

  • 094 Verwende Identity-H als Encoding für alle eingefügten True Type Fonts
  • 095 Bereite PDF-Datei vor, daß sie nach PDF/A konvertiert werden kann

 

install fonts on ADS

If the modified parameter table does not work, missing fonts has to be installed a the ADS server. This task has to be performed by the basis - team.

Inspect the generated PDF for 'not embedded' fonts and ask for their installation (Arial, Helvetica, ..)

ClipCapIt-211214-092021.PNG

 

coding of special characters

When fonts are not embedded, special characters are coded with the help of a 'Differences'-table - which seems to be not PDF/A - conform.

In order to locate this error, the log file of the ADS is required (the stack trace is too limited).


Example from the ADS-log:
#BC-SRV-FP#com.adobe~DocumentServicesConfiguration#C0000A0A1C0509E100000000000104F6#7561551000000005#com.adobe/AdobeDocumentServices#com.adobe.AdobeDocumentServices#deploy_service#2#JTA Transaction : 14087#C2BBAB41582711EC819D005056955849#c2bbab41582711ec819d005056955849##0#Thread[HTTP Worker [@388749585],5,Dedicated_Application_Thread]#Plain#com.sap.engine.services.monitor.mbeans.MonitorResourceBundle# Unfixable issue(s)- Resource Hierarchy: Font (/TrueType): ,Arial C006Description: TrueType font has Differences array but does not contain a Microsoft Unicode encoding.,Font not embedded (and text rendering mode not 3).,Encoding of non-Symbolic TrueType font is not MacRomanEncoding or WinAnsiEncoding.,#

..which means: there is a mapping table for characters outside the 1..255 ASCII - code table, and the mapping does not contain a proper 'microsoft unicode encoding'. Also, the font is not embedded and the text rendering mode is not '3'.


See the details in bold: 'C006' and 'font has Differences array'. So we have a coding with invalid character mapping.


Inspect the PDF in a text editor, search for 'C006': 

%Devtype SAPWIN   Font ZARIAL   normal Lang DE Script: 55 ->/C006
80 0 obj
<<
/Type /FontDescriptor
/Ascent 720
/CapHeight 660
/Descent -270
/Flags 32
/FontBBox [-665 -325 2000 1005 ]
/FontName /Arial
/ItalicAngle 0
/StemV 105
>>
endobj
81 0 obj
<<
/Type /Encoding
/Differences
[ 0   /uni2000
 1   /uni2001
 2   /uni2002
 3   /uni2003
 4   /uni2004
 5   /uni2005
 6   /uni2006
 7   /uni2007
...
19   /endash
...


Maybe, the problem is not the 'differences' mapping, but the missing 'microsoft unicode encoding' - whatever this means.


Look further for 'C006' and we can find the occurance in the text representation:
<72204665737470756E6B74736368656C6C65205479702031373020464C>Tj ET 0 g BT 76.50 341.95 Td 0 Tw 0.00 Tw <2837362C31>Tj /C006 10.00 Tf <13>Tj /C001 10.00 Tf 0.00 Tw <3136382C33206D6D292C2048>Tj /C002 10.00 Tf <F6>Tj /C001 10.00 Tf 0.00 Tw


This reads as:

  • '<72204665737470756E6B74736368656C6C65205479702031373020464C>' is the ASCII - representation of the string 'r Festpunktschelle Typ 170 FL'
  • '<2837362C31>' is the ASCII - representation of the string '(76,1'
  • '/C006' switches to the coding 'C006'
  • '<13>' is the mapped character with index 19, which is '/endash'
  • '/C001' switches back to the ANSI - encoding
  • '<3136382C33206D6D292C2048>' is the ASCII - representation of the string '168,3 mm), H'

If we inspect the PDF, we can identify the 'bad' character:

ClipCapIt-211214-091038.PNG


..and possibly remove/replace this character.


Nicer solution: let SAP generate a better 'differences' mapping.. has to be searched, how the mapping should look like; and then, ask SAP to create the 'other' mapping (to be done in the future). See 'https://unicode-table.com/en/2013/': the character 'endash' could be coded as 'U+2013'; so - we could be able to correct the mapping in the differences-table, if we only knew all unicode representations of all characters; note also, that SAP will create such a table, even if there is only one single character used. So - much work, but the result is unsave, if there is another character, which requires another (additional ??) differences-table.

text rendering mode not 3: it would be nice to know, if the text rendering mode could be changed in the generated PDF - and maybe, it could solve the problem (to be done in the future).

 

ZUGFeRD versions

A very short introduction into the supported versions.


CII version 1.0
  • starts with tag CrossIndustryDocument
  • using the transformation /EPO1/INVOICE_ZUGFERD_CII_1
  • uses the XML filename ZUGFeRD-invoice.xml


CII version 2.1.1
  • starts with tag CrossIndustryInvoice
  • using the transformation /EPO1/INVOICE_ZUGFERD_UBL_CII
  • uses the XML filename factur-x.xml

 

Debugging - UBL

In order to debug the XML-conversion, set a breakpoint in the method UBL_TRANSFORM_XML2XML (of the redefined invoice/credit-note- class).

Invoke transaction VF02, enter the invoice number and select from the menue 'Faktura | ausgeben', select the message ZUGF and press the button for the print preview.

 

Changelog - ZUGFeRD

PDF conversion routines

Product: 'ZUGFERD' (for Z_TRANSPORT_TOOL)

NextCloud: Kundenprojekte / EPO / SoftwareDownload / EPO eInvoice ZUGFeRD

EPO_eInvoice_ZUGFeRD_v<version>_<ta>.zip


Version 1.5.3

Transport order WK1K90???? 24.04.2024

  • bugfix for value of BilledQuantity

Aktivities before import:

  • none

 

Version 1.5.2

Transport order WK1K902811 01.07.2022

  • version 1.0: support for DeliveryNoteReferencedDocument, sign-correction for credit note (allowance)

Aktivities before import:

  • none

 

Version 1.5.1

Transport order WK1K902700 18.03.2022

  • support for field DeliveryNoteReferencedDocumen
  • XML corrections for CII 2.1.1

Aktivities before import:

  • none

 

Version 1.5.0

Transport order WK1K902656 02.03.2022

  • support for 'project reference', requires a redefinition in the UBL class /EPO1/CL_UBL_INVOICE_OUT_SD - method H33_..

Aktivities before import:

  • none

 

Version 1.4.8

Transport order WK1K902542 14.01.2022

  • correction of decimals of TaxTotal (calculated)

Aktivities before import:

  • none

 

Version 1.4.7

Transport order WK1K902498 03.01.2022

  • correction for optional due date

Aktivities before import:

  • none

 

Version 1.4.6

Transport order WK1K902354 22.11.2021

  • correction CII 1.0, allowance/surcharge: no BaseUnit, if there is no BaseAmount

Aktivities before import:

  • none

 

Version 1.4.5

Transport order WK1K902339 18.11.2021

  • new transformation ro read profile/version from the XML: /EPO1/INVOICE_ZUGFERD_GET_V_P

Aktivities before import:

  • none

 

Version 1.4.4

Transport order WK1K902141 01.09.2021

  • SKONTO correction: selection for OrderLineReference .. ID

Aktivities before import:

  • none

 

Version 1.4.3

Transport order WK1K902135 29.08.2021

  • SKONTO correction: sign for credit note, reference to customer commission info, delivery reference

Aktivities before import:

  • none

 

Version 1.4.2

Transport order WK1K902106 16.08.2021

  • SKONTO: calculate measure period - tag (number of days), basis amount, description text

Aktivities before import:

 

Version 1.4.1

Transport order WK1K902063 05.08.2021

  • correction OrderReferenceID - mapping
  • SKONTO: omit entries with 0.00 %

Aktivities before import:

  • none

 

Version 1.4.0

Transport order WK1K901990 25.06.2021

  • support for SKONTO (only extended profile)

Aktivities before import:

 

older versions

Version 1.3.2

Transport order WK1K901936 04.06.2021

  • correction of XML filename for version 2.1.1 'factur-x.xml'

Aktivities during import:

  • none

  Version 1.3.1

Transport order WK1K901913 21.05.2021

  • correction of meta-XML and percent-formatting for version 1.0

Aktivities during import:

  • none

  Version 1.3.0

Transport order WK1K901867 06.05.2021

  • support for version 1.0 (except attachments)

Aktivities during import:

  Version 1.2.0

Transport order WK1K901810 02.04.2021

  • first support for version 1.0, using table /EPO1/INV_ZUG_VE

Aktivities after import:

  • none

  Version 1.1.0

Transport order WK1K901692 01.03.2021

  • new user exit - method in order to adjust the name of the XML file

Aktivities after import:

  • none

  Version 1.0.2

Transport order WK1K901656 23.02.2021

  • correction transformation UBL -> CII

Aktivities after import:

  • none

  Version 1.0.1

Transport order WK1K901653 22.02.2021

  • correction transformation UBL -> CII

Aktivities after import:

  • none

  Version 1.0.0

Transport order WK1K901530 12.01.2021

  • initial version

Aktivities after import:

  • none