ADV Vorlagen

Die Klasse InvoiceTemplate (Namespace DPlus.ADV.Models, Datei InvoiceTemplate.cs) beschreibt eine ADV-Vorlage zur Erkennung von Werten aus einem Beleg (Rechnung oder Dokument). Die Vorlage wird in der DB-Spalte PAV_YML der Tabelle dbo.NET_PROJEKT_ADV_VORLAGEN als YAML persistiert und mit YamlDotNet (PascalCase NamingConvention) deserialisiert (siehe IAdvVorlagenOMServiceExtension.CheckTemplate).

Hinweis: Da PascalCaseNamingConvention verwendet wird, entsprechen die YAML-Schlüssel exakt den C#-Property-Namen.

Aufbau einer Vorlage

Eine Vorlage besteht aus drei Bereichen:

1. Auswahl – wann die Vorlage greift (Identifier, Keywords, BillerId).
2. Felderkennung – wie Werte gefunden werden (InvoiceField-Properties).
3. Aktionen / Parameter – was nach der Erkennung mit dem Beleg passiert (Parameters, Actions, Split).

Top-Level-Properties

Property	Typ	Beschreibung
Identifier	string?	Eindeutiger Text/Token (z.B. UID-Nr.), bei dessen Vorkommen die Vorlage automatisch ausgewählt wird (TemplateMatcherSelectTemplates.SelectTemplatesByIdentifierAsync).
Keywords	List<List<string>>?	Liste von Schlüsselwortgruppen. Eine Gruppe matched, wenn alle Wörter der inneren Liste im Belegtext vorkommen.
BillerId	string?	Fix hinterlegte Kreditor-ID (KR_ID). Wird gesetzt, wenn die Vorlage immer demselben Kreditor zugeordnet ist.
CompanyId	string?	Fix hinterlegte Mandanten-ID (CO_ID). Übersteuert die automatische Mandantenerkennung.
OrderNumber	InvoiceField?	Erkennungsregel für die Auftragsnummer.
SchadenNumber	InvoiceField?	Erkennungsregel für die Schadennummer.
VertragNumber	InvoiceField?	Erkennungsregel für die Vertragsnummer.
TicketNumber	InvoiceField?	Erkennungsregel für die Ticketnummer.
InvoiceDate	InvoiceField?	Erkennungsregel für das Rechnungsdatum (Wert wird als Datum geparsed).
InvoiceNumber	InvoiceField?	Erkennungsregel für die Rechnungsnummer.
PaymentReference	InvoiceField?	Erkennungsregel für den Zahlungsreferenz-/Verwendungszweck.
NetAmount	InvoiceField?	Erkennungsregel für den Nettobetrag.
TotalGrossAmount	InvoiceField?	Erkennungsregel für den Bruttobetrag (Gesamtbetrag).
Objekt	InvoiceField?	Erkennungsregel für die Objektzuordnung.
VATMatchers	List<WordMatch>?	WordMatch-Regeln zur Erkennung von Umsatzsteuer-Positionen über IVatDetection.
Autogenerated	InvoiceTemplate?	Verschachtelte Vorlage, die durch das ADV-Lernen automatisch erzeugt wurde. Wird zusätzlich zur manuellen Vorlage angewendet.
Split	List<List<string>>?	Splitregeln für Mehrfachdokumente (Dokumenten-Vorlagen): Pro Treffer einer Gruppe wird der PDF-Stapel an dieser Seite getrennt.
Parameters	List<TemplateParameter>?	Vorlagen-Parameter (statisch oder über Matcher), werden in den DMS-Aktionen verwendet.
Actions	List<TemplateAction>?	Aktionen, die nach der Erkennung ausgeführt werden (DMS-Verlinkung, SQL, Mandantensetzen, …).
KR_ID	string?	(YamlIgnore) Laufzeit-Info: aufgelöste Kreditor-ID. Wird nicht serialisiert.
PAV_ID	string?	(YamlIgnore) Laufzeit-Info: Vorlagen-ID aus der DB. Wird nicht serialisiert.
PAV_NAME	string?	(YamlIgnore) Laufzeit-Info: Vorlagenname aus der DB. Wird nicht serialisiert.

InvoiceField

Beschreibt, wie ein einzelner Wert aus dem Belegtext extrahiert wird. Die Erkennung läuft in dieser Reihenfolge (siehe TemplateMatcher.MatchTemplateField):

1. Value – Wenn gesetzt, wird dieser fixe Wert direkt zurückgegeben.
2. Matchers – RegEx-Matcher gegen den gesamten Belegtext.
3. MatchReplace – RegEx-Match mit anschließendem Replace.
4. WordMatchers – Wortbasierte Suche über WordMatch (positions-/zeilenbasiert).
5. Positions – Werte aus festen Bildschirmbereichen (WordRectangle).

Property	Typ	Beschreibung
Value	string?	Fixer Wert. Wenn gesetzt, werden die übrigen Regeln nicht ausgewertet.
Matchers	List<string>?	RegEx-Patterns mit benannter Capture-Group (?<value>…) (oder erste Gruppe). Match gegen text.
MatchReplace	List<WordMatchReplace>?	RegEx-Suche + Replace; produziert den finalen Wert per Regex.Replace.
WordMatchers	List<WordMatch>?	Wortbasierte Suche – siehe WordMatch.
Positions	List<WordRectangle>?	Liste von Rechtecken; alle Wörter, deren Bounding-Box vollständig enthalten ist, werden zurückgegeben.
Strip	string?	Zeichenmenge, die vom finalen Wert per string.Trim(chars) entfernt wird. Wirkt auf Matchers und MatchReplace.

WordMatch

Wortbasierte Erkennungsregel (z.B. „Rechnungsnummer …… RE3345565").

Property	Typ	Beschreibung
Match	string[]?	Konkrete Suchwörter. Nicht zusammen mit MatchRegExpr verwenden.
MatchRegExpr	string[]?	RegEx-Patterns als Alternative zu Match.
IgnoreWordsRegExpr	string?	RegEx für Zeichen/Wörter, die zwischen Suchwort und Wert ignoriert werden (z.B. [\.:]+ für Rechnungsnummer..............RE3345565).
PartialSearch	bool (default false)	Wenn true, wird das Suchwort als Teilstring eines Tokens erkannt (Rechnungsnummer:RE33453).
ValueRegExpr	string?	RegEx, dem der gefundene Wert genügen muss (z.B. „mind. eine Ziffer").
ValueInSameLine	bool?	Wenn true, muss der Wert in derselben Zeile wie das Suchwort stehen.

WordMatchReplace

Such-/Ersetzen-Paar, das in InvoiceField.MatchReplace verwendet wird.

Property	Typ	Beschreibung
Search	string?	RegEx für die Suche (RegexOptions.IgnoreCase).
Replace	string?	Replacement-Pattern für Regex.Replace.

WordRectangle

Rechteck in OCR-Pixelkoordinaten (Top-Left/Right-Bottom). Wird zur positionsbasierten Erkennung in InvoiceField.Positions verwendet.

Property	Typ	Beschreibung
Left, Top, Right, Bottom	int	Begrenzung des Rechtecks.

TemplateParameter

Definiert einen benannten Parameter, der in Actions (DMS-Properties, SQL-Statements) referenziert werden kann.

Property	Typ	Beschreibung
Name	string?	Parametername (Pflicht; Parameter ohne Namen werden ignoriert).
Value	string?	Statischer Wert.
Matchers	List<string>?	RegEx-Matcher; der erste Treffer im Belegtext überschreibt Value.

TemplateAction

Aktion, die nach der Erkennung gegen den Beleg ausgeführt wird (siehe DocumentTemplateMatcher).

Property	Typ	Beschreibung
Type	TemplateActionType	Aktionstyp (siehe unten).
Name	string?	Zielname (z.B. DMS-Property oder Parameter).
Sql	string?	SQL-Statement (für ExecuteSql, SetCompany, SetDmsLink, SetDmsProperty, SetDmsConName/Subject/Number). Parameter aus Parameters/Erkennung werden gebunden.
Database	Database	Auf welcher DB das SQL ausgeführt wird.

TemplateActionType

Wert	Beschreibung
SetCompany	Mandant über SQL bestimmen; setzt den Beleg auf den ermittelten Mandanten und verwirft konkurrierende Erkennungen.
CreateParameter	Parameter aus SQL-Ergebnis erzeugen.
SetDmsLink	DMS-Verknüpfung setzen (Name = Linktyp, Wert(e) aus SQL).
SetDmsProperty	DMS-Property setzen (Name = Property, Wert(e) aus SQL).
ExecuteSql	Beliebiges SQL ausführen (z.B. Insert).
SetDmsConName	DMS-Container-Name setzen (Wert = erstes SQL-Ergebnis).
SetDmsConSubject	DMS-Container-Betreff setzen.
SetDmsConNumber	DMS-Container-Nummer setzen.

Database

Wert	Beschreibung
System	Systemdatenbank.
Company	Aktueller Mandant.
CompanyAll	Alle erkannten Mandanten.

Vorlagenauswahl

Eine Vorlage wird angewendet, wenn eine der folgenden Bedingungen zutrifft (siehe TemplateMatcherSelectTemplates):

• Ein Wort im Beleg entspricht Identifier (case-insensitive).
• Eine Keyword-Gruppe aus Keywords ist vollständig im Belegtext enthalten.
• Der Kreditor wurde über BillerId aufgelöst.
• Die Vorlage ist als „Immer verwenden" markiert (PAV_IMMER_VERWENDEN in der DB).

Eine ggf. vorhandene Autogenerated-Sub-Vorlage wird zusätzlich zur ausgewählten Vorlage angewendet.

Beispiel (YAML)

Identifier: ATU12345678
BillerId: 04557DB2-03C2-49F2-96B5-73DBCCF799F5
Keywords:
  - [Rechnung, Fair, Rescue]
InvoiceNumber:
  Matchers:
    - 'Rechnungsnummer\s+(?<value>RE\d+)'
  Strip: ' '
InvoiceDate:
  WordMatchers:
    - Match: [Rechnungsdatum]
      ValueInSameLine: true
      ValueRegExpr: '\d{2}\.\d{2}\.\d{4}'
NetAmount:
  Matchers:
    - 'Nettobetrag\s+(?<value>[0-9]+,[0-9]+)\s+EUR'
TotalGrossAmount:
  Matchers:
    - 'Gesamtbetrag\s+(?<value>[0-9]+,[0-9]+)\s+EUR'
VATMatchers:
  - Match: ['20,0%', 'Mwst.']
    ValueInSameLine: true
Parameters:
  - Name: Sachbearbeiter
    Matchers:
      - 'Sachbearbeiter:\s+(?<value>\w+)'
Actions:
  - Type: SetDmsProperty
    Name: Kostenstelle
    Database: Company
    Sql: |
      select KS_NAME from KOSTENSTELLEN where KS_ID = @Sachbearbeiter

Validierung

Vor dem Speichern kann eine YAML-Vorlage mit IAdvVorlagenOMServiceExtension.CheckTemplate validiert werden; Fehler liefern Zeilen-/Spaltenangabe der YamlException.