Verarbeitung von Anlagen

Diese Dokumentation beschreibt, wie Anlagen ("Attachments") bei Mail-Importen gehandhabt werden. Das dokumentierte Verhalten ist unabhängig vom verwendeten Mail-Protokoll, es spielt also keine Rolle, ob Mails mittels IMAP, EWS, usw. importiert werden sollen.

Diese Seite beschreibt, wie Anhänge einer bereits importierten E-Mail klassifiziert und verarbeitet werden. Ob eine E-Mail überhaupt importiert wird, regeln davon unabhängig Absender- und Betreff-Filter, siehe Filterung mittels Black- und Whitelisting.

Anlagen mit Passwörtern

Im täglichen Geschäft können über die digitalen Eingangskanäle ihres Unternehmens, eine Vielzahl von verschlüsselten Anlagen erreichen. In folgenden Abschnitt gehen wir auf die zur Verfügung stehenden Möglichkeiten in Squeeze ein.

Komprimierte Archive(.zip)

Erhalten Sie verschlüsselte ZIP-Archive von ihren Absendern so bietet Squeeze Ihnen ab der Version >=2.4.1 eine Möglichkeit Passwörter für die eindeutigen Email-Adressen zu hinterlegen. 

Für die Konfiguration müssen Sie als Admin die Email-Registerkarte öffnen:

im nächsten Schritt gibt es nun eine weitere Registerkarte innerhalb der Email-Konfigurationsoberfläche. Dort können sie die Registerkarte Passwörter auswählen.

im Unteren Teil der Oberfläche finden Sie nun ein Button um ein neuen Eintrag hinzuzufügen. 

Nun können Sie mit der Verwendung einer eindeutigen E-Mail und durch die Eingabe eines Passwort die Daten speichern.

---

Achten Sie bitte auf folgende Hinweise in der Handhabung dieser Funktionalität:

1. Sie müssen vollwertige E-Mails angeben, dass bedeutet Sie müssen immer ganze Email-Adressen angeben ansonsten schlägt der Speichervorgang fehl
2. Um eventuell mehrere Passwörter einer E-Mail zuzuordnen legen Sie einfach mehrere Einträge an.
3. Wenn Emails Anhänge enthalten die nicht entschlüsselt werden können, werden diese Emails in den spezifizierten Error E-Mail Ordner verschoben.

Die hinterlegten Passwörter werden nicht für passwortgeschützte PDF-Datein verwendet.

Eine eindeutige E-Mail Adresse ist zum Beispiel: dexpro@test.com und nicht Konstrukte wie:  *pro@test.com

Anlagen-Filter (Email Attachment Filters)

Funktionsweise

Für jede Mail werden die Anlagen auf Basis von Import-Regeln geprüft. Die erste Regel deren Sender und Dateimuster zu einem Anhang passen entscheidet was mit dem Anhang geschieht. Dabei erhalten die Regeln, die nicht global sind, die höchste Priorität. 

Beispiel:

Prioritäten	Beispiel
Erste Priorität	spezifscher Sender(support@dexpro.de) + spezifisches Dateimuster(Rechnung.pdf)
Zweite Priorität	spezifische Domäne(dexpro.de)  + unspezifisches Dateimuster (*.pdf)
usw.	-

Wenn keine der Regeln passen, wird die Anlage ignoriert.

Für die Ausführung der PDF-Zusammenführung oder PDF-Trennung verwendet Squeeze die Software-Bibliothek "PDFBox". Die Verfügbarkeit der Bibliothek ist für die Anlagen-Filterung dringend notwendig. Ab der Squeeze Version 2.3.4 wird diese Bibliothek mit in die System-Prüfungen aufgenommen. Dies ermöglicht Ihnen eine schnelle Identifikation von möglichen Fehlerursachen.

Genauer betrachtet werden die Regeln für Dokument- und Anlage-Typ unabhängig voneinander aufgelöst: Für jeden Typ wird zunächst nach exaktem Absender gesucht, dann nach Domain, dann (bei Dokument-Regeln automatisch; bei Anlage-Regeln nur sofern die globale Regel danach noch erreicht wird) nach der globalen Regel (*). Innerhalb der so ermittelten Kandidaten-Regeln entscheidet am Ende die Länge des Dateimusters (längstes Muster gewinnt) — die Tabelle oben vereinfacht das für den Regelfall.

Das Dateimuster (filenamepattern) wird als Shell-Wildcard-Muster ausgewertet (*, ?, [abc]). Schlägt der Dateinamen-Abgleich fehl, wird zusätzlich der MIME-Typ als Fallback geprüft, sofern das Muster *.pdf bzw. *.xml lautet.

Die Stammdatentabelle emailattachmentfilters wird verwendet um SQUEEZE mitzuteilen, ob und wie Anlagen für die Erkennung relevant sind.

Die Tabelle hat folgende Struktur:

Name	Beschreibung	Bedeutung
id	ID	Eindeutige technische ID
batchclassid	Stapelklassen ID	ID der Stapelklasse für die die Regel definiert wird
sender	Sender	Absender der Email (Wildcards erlaubt, siehe Hinweis)
filenamepattern	Dateimuster	Dateinamenfilter (Wildcards erlaubt)
type	Typ	Relevantes Dokument für die Extraktion oder begleitende Anlage
singledocument	Einzeldokument	Kennzeichen, ob die Datei ein eigenständiges Dokument werden soll (X)
newbatchclassid	Neue Stapelklassen ID	Sofern das Dokument in eine andere Stapelklasse verschoben werden soll, ist hier die Stapelklassen-ID der neuen Stapelklasse anzugeben.
newdocumentclassid	Neue Dokumentenklassen ID	Sofern auch eine neue Dokumentenklasse gesetzt werden soll, ist hier die ID der Dokumentenklasse anzugeben.

Beispiel-Konfigurationen

Beispiel

ID	Stapel-klasse	Sender	Muster	Typ	Einzel-Dokument	neue Stapelklasse	neue Dokumentenklasse
1	1	*	*.pdf	D
2	1	*	AGB.pdf	A
3	1	dexpro.de	INV*.pdf	D	X
4	1	payment@dexpro.de	Avis*.pdf	D	X	2	2
5	1	dexpro.de	*.xml	A
6	1	invoice@squeeze.one	*.xml	D
7	1	invoice@squeeze.one	*.pdf	A

Erklärung der Regeln

Regel ID 1:
Diese Regel bedeutet, dass für jeden Absender jedes PDF einer Email als Dokument für die Extraktion behandelt wird und alle PDFs zu einem Dokument zusammengefasst werden.

Regel ID 2:
Diese Regel bedeutet dass für jeden Absender die PDF mit dem Namen AGB.pdf als Anlage beibehalten wird.

Regel ID 3:
Diese Regel greift nur bei Absendern der Domain dexpro.de und bedeutet, dass PDFs die dem Dateinamenmuster INV*.pdf entsprechen als Dokument erhalten bleiben. Dabei gilt zusätzlich, dass jede Datei, die diesem Muster entspricht, zu einem eigenständigen Dokument werden.

Regel ID 4:
Diese Regel greift nur bei dem Absender payment@dexpro.de und bedeutet, dass PDFs die dem Dateinamenmuster Avis*.pdf entsprechen als Dokument erhalten bleiben. Dabei gilt zusätzlich, dass jede Datei, die diesem Muster entspricht, zu einem eigenständigen Dokument einer neuen Stapel- und Dokumentenklasse werden.

Regel ID 5:
Diese Regel greift nur bei Absendern der Domain dexpro.de und bedeutet, dass XML Dateien (bspw. eine XRechnungen) als Anlagen beibehalten werden. Dabei wird vorausgesetzt, dass es eine gültige PDF in der E-Mail gibt (z.B. aus Regel ID 3), die den Hauptvorgang bildet.

Regel ID 6 & 7:
Diese Regel greift nur bei dem Absender invoice@squeeze.one und bedeutet, dass XML Dateien (bspw. eine XRechnung) als Dokument erhalten bleibt. Alle zusätzlich angehangenen PDF-Dokumente werden als Anlagen weitergeführt.

Hinweis zum Sender-Feld

Im Sender-Feld sind keine Wildcards in Kombination mit Text erlaubt.
Folgende Eingaben sind zulässig:
- *
- domain.de
- foobaa@domain.de
Nicht zulässig sind Kombinationen von Wildcard und String:
- *domain*
- *domain.de

Für die Steuerung der Verarbeitung von E-Mails, die sowohl XRechnungs-Dokumente als auch ZUGFeRD Belege enthalten,
können entsprechende Regeln definiert werden.

Mehrere PDF-Rechnungen (inkl. ZUGFeRD) in einer E-Mail einzeln verarbeiten

Symptom

Ein Absender schickt mehrere Rechnungen als separate PDF-Anhänge in einer einzigen E-Mail — zum Beispiel mehrere ZUGFeRD-/Hybrid-Rechnungen (PDF mit eingebetteter XML) in einer Sammel-Mail. Ohne passende Konfiguration werden diese PDFs zu einem Dokument zusammengeführt (PDF-Merge), oder es wird nur die XML des "falschen" PDFs für die Extraktion herangezogen.

Ursache

Trifft für mehrere Anhänge einer E-Mail dieselbe Dokument-Regel zu und ist deren Spalte singledocument leer, werden alle passenden Anhänge zu einem gemeinsamen Dokument zusammengefasst. Dieses Verhalten ist unabhängig davon, ob es sich um reine PDFs oder ZUGFeRD-/Hybrid-PDFs mit eingebetteter XML handelt.

Lösung: singledocument = X

Ist bei der zutreffenden Regel singledocument auf X gesetzt, wird für jeden passenden Anhang ein eigenes Dokument erzeugt — die Rechnungen werden also einzeln extrahiert, statt zusammengeführt zu werden.

Beispiel:

ID	Stapelklasse	Sender	Muster	Typ	Einzel-Dokument	neue Stapelklasse	neue Dokumentenklasse
8	1	invoices@customer.de	*.pdf	D	X

Mit dieser Regel wird jede PDF-Datei aus einer E-Mail von invoices@customer.de als eigenständiges Dokument behandelt — egal wie viele PDFs (inkl. ZUGFeRD-Hybride) in derselben E-Mail enthalten sind.

Über newbatchclassid / newdocumentclassid lässt sich zusätzlich jedes einzeln erzeugte Dokument in eine andere Stapel- bzw. Dokumentenklasse umleiten — etwa wenn Rechnungen und Gutschriften gemeinsam ankommen, aber unterschiedlich verarbeitet werden sollen.

Zusammenspiel mit ZUGFeRD Strict Mode

Ist ZUGFeRD Strict Mode aktiv (seit Version 2.33 standardmäßig aktiv), werden passende PDF-Dokumentregeln zur Laufzeit zugunsten der XML-Verarbeitung übersteuert (siehe Update-Hinweis unten). Der Wert von singledocument bleibt dabei jedoch erhalten — eine Regel mit singledocument = X sorgt also weiterhin dafür, dass jede Rechnung einzeln verarbeitet wird, auch wenn Strict Mode aktiv ist.

Weitere Hintergründe zu XRechnung/ZUGFeRD-Verarbeitung: Digitale Formate (XML, XRechnung, ZUGFeRD).

Troubleshooting

Werden Rechnungen von einem Absender trotz singledocument = X weiterhin zusammengeführt, prüfen Sie:

1. Ob eine andere, länger passende Regel (z. B. eine globale *.pdf-Regel ohne singledocument) zuerst greift — siehe Abschnitt "Funktionsweise" oben zur Längen-Priorisierung der Dateimuster.
2. Ob die Regel wirklich für den korrekten Absender bzw. die korrekte Domain hinterlegt ist (Absender vor Domain vor global).
3. Das konkrete Troubleshooting-Beispiel für einen ähnlich gelagerten Fall.

Update-Hinweis

Trennung von Anlagen und Dokument ab Squeeze 1.10

In den Squeeze 1.9 (und älter) wurden Dokumente und Anlagen beim Import zwar unterschiedlich behandelt, allerdings in den Folge-Schritten der Verarbeitung als eine Datei behandelt. Ergebniss war, dass primär zu verarbeitendes Dokument und die Anlagen als eine PDF zusammengeführt und dann auch so extrahiert wurden, als wäre eine einzelne Datei importiert worden.

Ab Squeeze 1.10 werden die Anlagen getrennt behandelt und sind somit nicht Teil des Dokumentes, welches extrahiert wird. Zusätzlich kann dies Export-Schnittstellen betreffen, die nur eine Datei pro Dokument exportieren können (Bspw. NavisionSoap). Diese exportieren in der neueren Version nur noch das Hauptdokument, Anlagen werden nicht exportiert.

Falls das Verhalten vor Squeeze 1.10 beibehalten werden soll, dann sind in den Anlagenfiltern alle Anlagen als Dokument zu markieren.

Priorisierung von XML-Rechnungen gegenüber PDF-Dateien ab Squeeze 2.17

Mit der Einführung der Version 2.17 wird das Standardverhalten von Squeeze dahingehend angepasst, dass Rechnungen im XML-Format gegenüber PDF-Dateien bevorzugt werden. Der Hintergrund dieser Änderung ist, dass zunehmend Kunden und Partner darauf hingewiesen haben, dass Rechnungssteller häufig sowohl Belege im XML- als auch im PDF-Format übermitteln. Je nach Konfiguration kann dies zu Dubletten oder Fehlern in der Verarbeitung führen.

Um eine einheitliche Handhabung der Belege im Standard zu gewährleisten, wird in der Version 2.17 festgelegt, dass Belege im XML-Format vorrangig behandelt werden. Dieses Verhalten kann jedoch durch die oben beschriebenen Regeln an individuelle Anforderungen angepasst werden. Eine generelle Priorisierung der PDF-Dateien ist derzeit nicht vorgesehen.

ZUGFeRD Strict Mode - Priorisierung der XML bei hybriden E-Rechnungsformaten

Mit der Einführung der Version 2.30 (April 2026) wird der strikte ZUGFeRD Modus als Eigenschaft eingeführt. 
Wenn dieser aktiv ist, werden die Anlagenfilter zugunsten der XML Verarbeitung übersteuert.
Sollte es sich also um einen ZUGFeRD Prozess handeln, werden bestehende Filter, welche PDFs bevorzugen, übersteuert.
Dieses Verhalten wird geloggt, um eine nachvollziehbare Verarbeitung zu gewährleisten.

Zusätzlich gibt es eine Systemprüfung, mit der eine eventuelle Fehlkonfiguration festgestellt werden kann.

Weitere Informationen zum Strict Mode sind hier zu finden.