Hauptkomponenten

MesoWorkerService besteht aus acht Hauptkomponenten, die jeweils spezifische Aufgaben automatisch ausführen. Jede Komponente läuft als geplanter Job mit konfigurierbaren Zeitplänen.

Mail-Dienst

Funktion: Automatischer E-Mail-Versand basierend auf Workflow-Ereignissen in WinLine

Ausführung: Jede Sekunde (konfigurierbar über Quartz__MailWorkerJob__scheduler)

Funktionsweise:

Der Mail-Dienst überwacht kontinuierlich WinLine-Workflows und versendet automatisch E-Mails, wenn bestimmte Kriterien erfüllt sind.

1. Workflow-Prüfung

   • Der Dienst ruft Workflows aus WinLine ab, die den konfigurierten Filterkriterien entsprechen
   • Filter können zeitbasiert sein (z.B. nur Workflows der letzten 24 Stunden)
   • Zusätzliche Filterkriterien ermöglichen detaillierte Selektion

2. Empfänger-Ermittlung

   • Das System ermittelt automatisch die richtigen Empfänger basierend auf hierarchischen Regeln
   • Unterstützt Kunden, Ansprechpartner, Vertriebsmitarbeiter und statische Empfänger
   • Fallback-Mechanismen sorgen dafür, dass immer ein Empfänger gefunden wird

3. E-Mail-Erstellung

   • Mail-Texte werden aus Vorlagen generiert
   • Platzhalter werden automatisch durch echte Workflow-Daten ersetzt
   • Anhänge werden aus Workflows und Belegen zusammengestellt

4. Versand und Protokollierung

   • E-Mails werden über konfigurierte SMTP-Konten versendet
   • Jeder Versand wird im Mail-Journal protokolliert
   • Bei Fehlern werden Administratoren benachrichtigt

Konfiguration:

Mail-Einstellungen werden pro Mandant in der Administrationsoberfläche konfiguriert. Details zur Konfiguration finden Sie im Abschnitt Mail-Dienst Konfiguration.

Screenshots:

SMTP-Konto Einstellungen

E-Mail-Einstellungen für einen Workflow

Mail-Vorlage mit Platzhaltern

Workflow-Erzeugung aus Bestelldateizeilen

Funktion: Automatische Erstellung von CRM-Fällen aus Bestelldateizeilen

Ausführung: Alle 5 Minuten (konfigurierbar über Quartz__OrderLineWorkerJob__scheduler)

Funktionsweise:

Dieser Dienst ermöglicht es, aus Bestelldateizeilen in WinLine automatisch CRM-Fälle zu erzeugen. Dies ist besonders nützlich für wiederkehrende Serviceaufträge oder projektbasierte Tätigkeiten.

1. Beleg-Überwachung

   • Der Dienst überwacht Bestelldateizeilen (z.B. Auftragspositionen)
   • Filterkriterien bestimmen, welche Zeilen verarbeitet werden
   • Unterstützt verschiedene Belegarten (Angebote, Aufträge, Lieferscheine, Rechnungen)

2. Duplikats-Prüfung

   • Jede Zeile wird über Kontonummer, Laufnummer und Zeilennummer identifiziert
   • Bereits verarbeitete Zeilen werden übersprungen
   • Protokollierung verhindert Mehrfachverarbeitung

3. Workflow-Erstellung

   • Für jede relevante Zeile wird automatisch ein CRM-Fall erstellt
   • Workflow-Felder werden aus Belegdaten befüllt (Kurzbeschreibung, Langbeschreibung, Datumsfelder)
   • Template-basierte Textgenerierung mit Platzhaltern
   • Personenkonto- und Kontakt-Quellen (NEU): Steuert, aus welchen Beleg-Feldern die Personen-Felder des Falls befüllt werden:
     • Kundenkonto-Quelle: Kontonummer des Belegs/Rechnungsadresse (Standard), Konto der Lieferadresse oder der Zusatzadresse
     • Kontakt-Quelle: Ansprechpartner der Rechnungsadresse (Standard) oder der Lieferadresse
     • Händlerkonto-Quelle und Kontakt-Händler-Quelle: standardmäßig nicht befüllt („Nicht schreiben"), ansonsten mit denselben Quell-Optionen
     • Konto-Quellen jeweils optional mit Rückfall auf die Rechnungsadresse; bleibt die gewählte Quelle leer, wird das Feld nicht geschrieben. Eine Kontakt-Quelle „Zusatzadresse" gibt es nicht, da der Beleg keinen Ansprechpartner der Zusatzadresse führt

4. Optionale Fall-ID-Speicherung

   • Die erzeugte Fall-ID kann in eine benutzerdefinierte Spalte der Belegzeile geschrieben werden
   • Ermöglicht Rückverfolgung von Beleg zu CRM-Fall

5. Verknüpfung mit Beleg-Workflow

   • Beleg-Workflow als Elternfall verknüpfen: Verknüpft die erzeugten Belegzeilen-Workflows mit dem übergeordneten Beleg-Workflow als Tochter-Fälle
   • Warte auf Beleg-Workflow (NEU): Verhindert die Erzeugung von Belegzeilen-Workflows, bis ein Beleg-Workflow existiert
     • Wenn aktiviert, werden Belegzeilen nur verarbeitet, wenn bereits ein Workflow für den Beleg (Angebot, Auftrag, Lieferschein oder Rechnung) vorhanden ist
     • Nicht verarbeitete Zeilen werden beim nächsten Job-Lauf erneut geprüft
     • Nützlich für sequentielle Workflow-Erzeugung: erst Beleg-Workflow, dann Zeilen-Workflows

6. Anhänge anfügen

   • Beleg-Dokument anfügen: Fügt das Beleg-PDF aus der ArchivId der Belegstufe an (z.B. ArchivIdAngebot, ArchivIdAuftrag, ArchivIdLieferschein, ArchivIdFaktura)
   • Beleg-Anhänge anfügen: Fügt alle Beleganhänge aus der DokumentenId des Belegs als Anhänge zum CRM-Fall hinzu
   • Übergeordnete Fall-Anhänge: Kopiert Anhänge vom übergeordneten CRM-Fall, wenn LinkVoucherWorkflowAsParent aktiviert ist
   • Alle Anhänge werden automatisch als CrmUploads-Einträge gespeichert
   • Duplikate werden erkannt und übersprungen

Datumsfeldkonfiguration:

Der Dienst unterstützt zwei Datumsvarianten:

• Standard: Lieferdatum und bestätigtes Lieferdatum
• Kalender: Kalender-Startdatum und Kalender-Enddatum

Das Enddatum kann über verschiedene Modi berechnet werden:

• Bestätigtes Lieferdatum
• Lieferdatum
• Lieferdatum plus Zeitversatz
• Lieferdatum plus Stunden aus Menge
• NULL (kein Enddatum)

Platzhalter in Vorlagen:

Vorlagen unterstützen Platzhalter für Belegdaten. Eine vollständige Übersicht aller verfügbaren Eigenschaften finden Sie in der BestelldateiMitte-Klassendokumentation.

Zeilenebene:

• {Artikelnummer}, {Bezeichnung}, {Menge}, {Einzelpreis}, {Gesamtwert}
• {Lieferdatum}, {BestaetigtesLieferdatum}
• {Projektnummer}, {Vertreternummer}, {Kostenstelle}

Belegebene:

• {BestelldateiKopf.Auftragsnummer}, {BestelldateiKopf.Belegnummer}
• {BestelldateiKopf.Belegart}, {BestelldateiKopf.Datum}
• {BestelldateiKopf.Konto.Name}, {BestelldateiKopf.Konto.Adresse.Ort}

Formatierung:

• {Lieferdatum:dd.MM.yyyy} - Datum formatiert
• {Einzelpreis:C2} - Währung mit 2 Dezimalstellen
• {Menge:N0} - Zahl ohne Dezimalstellen

Hinweis: Für eine vollständige Übersicht aller verfügbaren Formatierungsoptionen (RTF-Konvertierung, Prefix/Suffix, etc.) siehe Formatangaben für Platzhalter.

Beispiel Kurzbeschreibung:

{BestelldateiKopf.Auftragsnummer}: {Artikelnummer} {Bezeichnung}

Ergebnis: AUF-12345: ART001 Premium-Widget

Konfiguration:

Workflow-Erzeugungseinstellungen werden pro Mandant in der Administrationsoberfläche konfiguriert. Für Details zu Platzhaltern und Formatierung siehe Formatangaben für Platzhalter.

Weitere Felder der Bestellzeilen-Workflow-Einstellungen:

Feld	Beschreibung
Priorität (Priority)	Reihenfolge, in der die Einstellungen eines Mandanten je Lauf abgearbeitet werden (aufsteigend, 1 = höchste Priorität). Standard 10. Da jede Belegzeile über Konto, Laufnummer und Zeilennummer mandantenweit nur einmal verarbeitet wird, legt bei überlappenden Filtern die Einstellung mit der kleineren Zahl den Fall an
Zu erzeugender Workflow (WorkflowToWrite)	Pflichtfeld: der Workflow (Workflownummer), mit dem für jede passende Belegzeile der Fall angelegt wird. Einstellungen ohne Workflow werden vom Dienst ignoriert – auch wenn sie aktiv sind
Benutzerdefiniertes Feld für Beleg-Laufnummer (CustomFieldForVoucherSerialNumber)	Optional: Spaltenname einer benutzerdefinierten Spalte der Fall-Tabelle (T170), z.B. C123. Dort trägt der Dienst nach dem Anlegen die Laufnummer des Belegs ein
Benutzerdefiniertes Feld für Zeilennummer (CustomFieldForLineNumber)	Optional: Spaltenname in der Fall-Tabelle (T170), in den die interne Zeilennummer der Belegzeile geschrieben wird. Zusammen mit der Laufnummer ergibt sich die Rückverfolgung vom Fall zur Belegzeile – das Gegenstück zur Fall-ID-Speicherung in der Belegzeile (CustomFieldForCaseId). Schlägt das Schreiben fehl (z.B. Spalte nicht vorhanden), bleibt der Fall bestehen; der Fehler steht im Protokoll
Bemerkung (Remark)	Freitext für die interne Dokumentation; ohne Wirkung auf die Verarbeitung

Anhangsverwaltung:

Die folgenden Optionen stehen zur Verfügung, um Dokumente automatisch an die erzeugten CRM-Fälle anzufügen:

1. Beleg-Dokument anfügen (AttachVoucherDocument)

   • Fügt das Hauptdokument des Belegs aus der ArchivId der entsprechenden Belegstufe an
   • Unterstützt alle Belegarten: Angebot (ArchivIdAngebot), Auftrag (ArchivIdAuftrag), Lieferschein (ArchivIdLieferschein), Rechnung (ArchivIdFaktura)
   • Das Dokument wird als PDF aus dem Archiv geladen

2. Beleg-Anhänge anfügen (AttachVoucherAttachments)

   • Fügt alle zusätzlichen Anhänge des Belegs aus der DokumentenId an
   • Lädt alle zum Beleg gehörenden Dokumente über ArchivBusiness.LadeBelegDokumenteAsync
   • Besonders nützlich für zusätzliche Unterlagen wie Lieferscheine, Zertifikate, etc.

3. Übergeordnete Fall-Anhänge anfügen (AttachParentWorkflowAttachments)

   • Kopiert alle Anhänge vom übergeordneten CRM-Fall
   • Funktioniert nur in Verbindung mit "LinkVoucherWorkflowAsParent"
   • Ermöglicht die Vererbung von Dokumenten entlang der Belegkette (Angebot → Auftrag → Lieferschein → Rechnung)

Wichtige Hinweise zur Anhangsverwaltung:

• Alle Anhänge werden als CrmUploads-Einträge im CRM-System gespeichert
• Duplikate werden automatisch erkannt und nicht erneut angehängt
• Die Dokumentenkonvertierung (SPL → PDF) erfolgt automatisch über den MesospoolService
• Bei Fehlern werden detaillierte Log-Einträge erstellt, ohne die Workflow-Erstellung zu unterbrechen

Terminsynchronisation

Funktion: Automatische Erstellung von Kalender-Terminen aus CRM-Einträgen über MS Graph API

Ausführung: Alle 10 Minuten (konfigurierbar über Quartz__AppointmentWorkerJob__scheduler)

Funktionsweise:

Dieser Dienst ermöglicht es, aus CRM-Einträgen (Workflows) in WinLine automatisch Termine in Microsoft Exchange/Outlook-Kalendern zu erstellen. Die Termine werden über die Microsoft Graph API direkt in den persönlichen Kalendern der Empfänger angelegt.

Zeitzone: Erstellte Termine verwenden standardmäßig Europe/Berlin. Der Standard ist global über die Einstellung DefaultTimeZone (in appsettings.json bzw. als Umgebungsvariable DefaultTimeZone) anpassbar und kann pro Termin-Einstellung über das Feld Zeitzone (IANA-Name, z.B. Europe/Vienna) überschrieben werden. Leer = globaler Standard.

1. CRM-Einträge-Auswahl

   • Der Dienst überwacht konfigurierte Workflows
   • Flexible Filterkriterien für präzise CRM-Eintrags-Selektion
   • Nur noch nicht verarbeitete Einträge werden berücksichtigt

2. Datumsfeld-Ermittlung

   • Wählbare Datumsfelder aus CRM:
     • Start-/Enddatum (C006/C007)
     • Kalenderstart-/-enddatum (C031/C032)
     • Eskalationsdatum (C018)
     • Erfassungsdatum (C005)
   • Optional: Zeitdauer-Addition zu ermittelten Datumsfeldern
   • Ganztags-Option steuerbar über konfigurierbare CRM-Eigenschaft

3. Empfänger-Ermittlung

   • Flexible Kombination mehrerer Empfänger-Quellen:
     • Verfassender Benutzer: Ersteller des Workflows
     • Delegiert an Benutzer: Zuständiger Benutzer
     • Delegiert an Gruppe: Alle Mitglieder der zugewiesenen Gruppe
     • XRM-Einträge: Alle unterstützten Typen aus CrmMehrfacheinträgen
     • XRM-Einträge (Benutzer): Nur Benutzer (Typeeigenschaft = 99)
     • XRM-Einträge (Gruppe): Nur Gruppen (Typeeigenschaft = 101)
     • XRM-Einträge (Konto): Nur Konten (Typeeigenschaft = 1)
     • XRM-Einträge (Kontakt): Nur Kontakte (Typeeigenschaft = 6)
     • XRM-Einträge (Vertreter): Nur Vertreter (Typeeigenschaft = 51)
     • Vertreter: Vertreter des zuständigen Benutzers (Incidence.Vertreter)
     • Kunde: Kundenkonto (Incidence.Kundenkonto)
     • Händler: Händlerkonto (Incidence.Haendlerkonto)
     • Kontakt Kunde: Kundenkontakt (Incidence.KontaktKunde)
     • Kontakt Händler: Händlerkontakt (Incidence.KontaktHaendler)
   • Duplikate werden automatisch entfernt

4. Termin-Inhalt

   • Betreff und Body mit VariableReplacementService
   • Unterstützt Platzhalter wie {{Fall.Kurzbeschreibung}}, {{Fall.Beschreibung}}
   • Vollständige Formatierungsmöglichkeiten verfügbar (siehe Formatangaben für Platzhalter)
   • HTML-Formatierung für Body möglich
   • Optional: Fall-Anhänge mit Filterung nach Archiv-Formular-ID

5. Termin-Erstellung

   • Termine werden über MS Graph API in persönlichen Kalendern erstellt
   • Pro Empfänger ein separater Termin
   • Authentifizierung über Azure AD Client Credentials (App-only)
   • Journal-Protokollierung mit Graph Event ID für Nachverfolgung

6. Rücksynchronisation (Optional)

   • Änderungen an Terminen in Exchange können zurück in CRM synchronisiert werden
   • Nur verfügbar wenn CRM-Eintrag zu einem einzelnen Termin führte
   • Konfigurierbar mit Zeithorizont (z.B. 7 Tage)
   • Synchronisiert Änderungen an:
     • Datum (Start/Ende) → entsprechende CRM-Datumsfelder
     • Betreff → Kurzbeschreibung
     • Body → Beschreibung

7. Folgeschritte-Unterstützung

   • CRM-Workflows können aus mehreren Schritten bestehen (Id > 0 mit verschiedenen Schrittnummern)
   • Bereits erstellte Termine für einen Fall werden unabhängig von der Schrittnummer erkannt
   • Bei Folgeschritten werden bestehende Termine automatisch erkannt:
     • Gleicher Empfänger: Termin wird aktualisiert (bei aktivierter Änderungserkennung)
     • Neuer Empfänger: Neuer Termin wird erstellt
   • Journal-Einträge verweisen auf die aktuelle Schrittnummer
   • Ermöglicht das Verschieben von Terminen über nachfolgende Workflow-Schritte

8. Änderungserkennung (Optional)

   • Aktivierbar über EnableChangeDetection in den AppointmentSettings
   • Prüft ob sich termin-relevante Felder geändert haben:
     • Datum (Start/Ende)
     • Betreff
     • Body
     • Empfänger
   • Aktualisiert bestehende Termine bei Änderungen
   • Erstellt neue Termine für neu hinzugekommene Empfänger
   • Verhindert Duplikate bei unveränderter Daten

9. Automatisches Löschen von Terminen (Optional)

   • Termine können automatisch verhindert oder gelöscht werden, wenn bestimmte Bedingungen erfüllt sind
   • Zwei Löschbedingungen stehen zur Verfügung (einzeln oder kombiniert):
     • DeleteProperty: Eigenschaft die angibt, dass der Termin nicht erstellt werden soll
     • DeleteFilter: Filterkriterium zur Ermittlung welche Termine nicht erstellt werden sollen
   • Prävention vor Erstellung: Löschbedingungen werden VOR der Terminerstellung geprüft - Termine die Bedingungen erfüllen werden gar nicht erst angelegt (Performance-Optimierung)
   • Nachträgliche Löschung: Bereits erstellte Termine werden gelöscht wenn:
     • Löschbedingungen nachträglich konfiguriert wurden
     • CRM-Daten nach Terminerstellung geändert wurden (z.B. Eigenschaft nachträglich gesetzt)
   • Löschung erfolgt pro Empfänger einzeln über die Graph API
   • Journal-Protokollierung mit Deleted und DeletedOn für Nachverfolgung

Voraussetzungen:

Für die Graph API Integration werden folgende Voraussetzungen benötigt:

1. Microsoft Entra ID App Registration:

   • Eine registrierte App in Microsoft Entra ID (ehemals Azure AD)
   • Client ID und Tenant ID
   • Client Secret zur Authentifizierung
   • Konfigurierte Application Permissions:
     • Calendars.ReadWrite - Zum Erstellen/Aktualisieren von Terminen
     • User.Read.All - Zum Abrufen von Benutzer-eMail-Adressen

2. Admin Consent:

   • Die konfigurierten Permissions benötigen Admin Consent
   • Ein Administrator mit entsprechenden Berechtigungen muss die Zustimmung erteilen

3. Microsoft 365 Lizenzen:

   • Benutzer benötigen Microsoft 365 / Exchange Online Postfächer
   • Kalender müssen für die betroffenen Benutzer verfügbar sein

Schritt-für-Schritt-Anleitung: Microsoft Entra ID App-Registrierung erstellen

Diese Anleitung beschreibt die Erstellung einer App-Registrierung in Microsoft Entra ID für eine serverseitige Integration (App-only), welche Microsoft Graph verwendet.

Erforderliche Berechtigungen:

• Entra Administrator-Rolle oder entsprechende Berechtigungen zum Erstellen von App-Registrierungen
• Berechtigung zur Erteilung der Administratorzustimmung (Admin Consent)

Schritt 1: App registrieren

1. Öffnen Sie das Microsoft Entra Admin Center
2. Navigieren Sie zu: Identity → Applications → App registrations
3. Klicken Sie auf: New registration
4. Tragen Sie folgende Werte ein:
   • Name: Mesonic CRM Integration
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URI: Leer lassen
5. Klicken Sie auf: Register

Schritt 2: Wichtige IDs notieren

1. Öffnen Sie in der erstellten App die Seite: Overview
2. Notieren Sie folgende Werte für die spätere Konfiguration:
   • Application (client) ID
   • Directory (tenant) ID

Diese Werte werden später in den Graph API Settings im MesoWorkerService benötigt.

Schritt 3: Anmeldeinformation erstellen (Client Secret)

1. Navigieren Sie zu: Certificates & secrets

2. Unter "Client secrets" klicken Sie auf: New client secret

3. Konfigurieren Sie das Secret:

   • Description: MesonicCRMIntegration-Secret
   • Expires: Nach interner Sicherheitsvorgabe (z. B. 6 oder 12 Monate)

4. Klicken Sie auf: Add

5. Wichtig: Kopieren Sie den Wert aus der Spalte "Value" sofort in einen sicheren Passwortspeicher

   ⚠️ Hinweis: Der Secret-Wert wird nur einmal angezeigt und kann später nicht mehr abgerufen werden.

Schritt 4: API-Berechtigungen hinzufügen (Microsoft Graph)

1. Navigieren Sie zu: API permissions
2. Klicken Sie auf: Add a permission
3. Wählen Sie: Microsoft Graph
4. Wählen Sie: Application permissions (nicht Delegated permissions)
5. Fügen Sie folgende Berechtigungen hinzu:
   • Calendars.ReadWrite - Ermöglicht das Erstellen und Aktualisieren von Kalenderterminen
   • User.Read.All - Ermöglicht das Abrufen von Benutzerinformationen (eMail-Adressen)
6. Klicken Sie auf: Add permissions

Schritt 5: Administratorzustimmung erteilen (Admin Consent)

1. Bleiben Sie auf der Seite: API permissions
2. Klicken Sie auf: Grant admin consent for [Ihr Organisationsname]
3. Bestätigen Sie die Aktion mit: Yes
4. Überprüfen Sie, dass in der Spalte "Status" bei beiden Berechtigungen ein grüner Haken mit "Granted for [Organisationsname]" angezeigt wird

Schritt 6: Werte für die Konfiguration zusammenstellen

Stellen Sie sicher, dass folgende Werte dokumentiert und sicher aufbewahrt wurden:

• Client ID (Application ID)
• Tenant ID (Directory ID)
• Client Secret (Value)

Diese Werte werden im nächsten Schritt in den Graph API Settings im MesoWorkerService hinterlegt.

Sicherheitsempfehlungen:

• Bewahren Sie das Client Secret ausschließlich in sicheren Passwortspeichern oder Secrets-Management-Systemen auf (z. B. Azure Key Vault)
• Dokumentieren Sie das Ablaufdatum des Secrets und implementieren Sie einen Prozess zur rechtzeitigen Erneuerung
• Verwenden Sie in Produktivumgebungen idealerweise Azure Key Vault zur Speicherung der Secrets
• Vermeiden Sie die Speicherung von Secrets in Quellcode, Konfigurationsdateien oder Datenbanken
• Implementieren Sie eine regelmäßige Rotation der Client Secrets (empfohlen: alle 6-12 Monate)

Konfiguration:

Termin-Einstellungen werden pro Mandant in der Administrationsoberfläche konfiguriert. Für Details zu Platzhaltern und Formatierung in Subject Template und Body Template siehe Formatangaben für Platzhalter.

1. Graph API Settings: Erstellen Sie zunächst wiederverwendbare Graph API Zugangsdaten unter "Graph API Settings"

   • Name: Bezeichnung für die Zugangsdaten (z.B. "Production Graph API")

   • Client ID: Azure AD Application ID

   • Tenant ID: Azure AD Directory ID

   • Client Secret: Azure AD Client Secret

   • Bemerkung (Remark): Optionaler Freitext, z.B. Ablaufdatum des Client Secrets und zuständige Person – ohne Wirkung auf die Verarbeitung

2. Appointment Settings: Konfigurieren Sie dann die Termin-Einstellungen unter "Appointment Settings"

   • Graph API Settings: Wählen Sie die zuvor erstellten Graph API Zugangsdaten
   • Date Field Type: Welches CRM-Datumsfeld verwendet werden soll
   • Duration To Add: Optional: Zeitdauer die zum Datum addiert wird
   • Recipient Sources: Kombination der Empfänger-Quellen (Mehrfachauswahl)
   • Enable Back Sync: Rücksynchronisation aktivieren
   • Back Sync Time Horizon: Zeithorizont für Rücksynchronisation (z.B. 7 Tage)
   • Delete Property: Optional: Eigenschaft die steuert ob Termine gelöscht werden sollen
   • Delete Filter: Optional: Filterkriterium zur Ermittlung zu löschender Termine

Vorteil: Die Graph API Zugangsdaten können für mehrere Termin-Einstellungen wiederverwendet werden.

Weitere Felder der Termin-Einstellungen:

Allgemein:

Feld	Beschreibung
Priorität (Priority)	Reihenfolge, in der die Termin-Einstellungen eines Mandanten je Lauf abgearbeitet werden (aufsteigend, kleinere Zahl zuerst). Standard 0
Alle Workflows auswählen (SelectAllWorkflows)	Standard aus: Je Fall wird nur der aktuelle (letzte) Schritt betrachtet. Aktiviert: alle Schritte – nötig, wenn nach dem terminrelevanten Schritt weitere Schritte geschrieben werden und der Termin trotzdem angelegt oder aktualisiert werden soll
Bemerkung (Remark)	Freitext für die interne Dokumentation; ohne Wirkung auf die Verarbeitung

Termin-Inhalt:

Feld	Beschreibung
Teams-Meeting-Eigenschaft (IsOnlineMeetingProperty)	Optional: eine CRM-Eigenschaft (Eigenschaftswert). Trägt der Fall diese Eigenschaft, wird der Termin als Online-Meeting (Microsoft Teams) angelegt; den Besprechungslink erzeugt Exchange. Leer = nie Online-Meeting
Ort-Vorlage (LocationTemplate)	Vorlage für den Termin-Ort mit denselben Platzhaltern wie Betreff- und Body-Vorlage, z.B. die Kundenadresse ({{Kunde.Adresse}}). Leer = kein Ort
Kalender-ID-Vorlage (CalendarIdTemplate)	Optional: Vorlage für den Zielkalender im Postfach des Empfängers. Das Ergebnis kann eine Kalender-ID (beginnt mit AAMk…) oder ein Kalendername sein (z.B. CRM-Termine), der im Postfach des Empfängers nachgeschlagen wird. Leer, nicht auflösbar oder Kalender nicht vorhanden = Standardkalender (Warnung im Protokoll). Damit landen Termine in einem eigenen Kalender statt im Hauptkalender

Erinnerung:

Die Erinnerungszeit (Minuten vor Terminbeginn) wird in dieser Reihenfolge ermittelt; der erste Wert größer 0 gilt:

Feld	Beschreibung
Verwende AnzahlEinheiten für Erinnerung (UseAnzahlEinheitenForReminder)	Stufe 1: Das CRM-Feld „Anzahl der Einheiten" des Falls wird als Minutenwert gelesen (z.B. 30 = Erinnerung 30 Minuten vorher). Standard aus
Verwende Spalte für Erinnerung (UseCustomColumnForReminder) und Spaltenname für Erinnerung (CustomReminderColumnName)	Stufe 2: Eine benutzerdefinierte Spalte des Falls (z.B. C123) wird als Minutenwert gelesen. Nur wirksam, wenn beide Felder gesetzt sind; ist der Wert nicht lesbar oder keine Zahl, greift die nächste Stufe. Standard aus
Standard-Erinnerung (Minuten) (DefaultReminderMinutes)	Stufe 3: fester Wert, z.B. 15. Standard 0 = keine Erinnerung, sofern auch die Stufen davor nichts liefern

Rücksynchronisation (nur mit „Rücksynchronisation aktivieren"):

Feld	Beschreibung
Rücksync Body-Zielfeld (BackSyncBodyFieldType)	In welches CRM-Feld ein in Outlook geänderter Termintext zurückgeschrieben wird: None (Standard) – Text wird nicht zurückgeschrieben, nur Datum und Betreff; LangbeschreibungIntern; LangbeschreibungExtern; UserColumn – benutzerdefinierte Spalte. Der Termintext wird dabei in Klartext gewandelt (HTML-Formatierung entfällt)
Rücksync Body-Spaltenname (BackSyncBodyUserColumnName)	Spaltenname (z.B. C123) für das Zielfeld UserColumn
Rücksync Anhänge speichern (BackSyncSaveAttachments)	Werden dem Termin in Outlook Dateien angehängt, lädt der Dienst neue Anhänge herunter und legt sie als Anhang am CRM-Fall (Archiv) ab. Standard aus
Rücksync Anhang-Archivformular-ID (BackSyncAttachmentArchiveFormId)	Archivformular (Formulartyp), unter dem diese Anhänge im Archiv beschlagwortet werden. 0 = ohne Formular

Beispiel-Setup:

Graph API Settings:
  Name: "Production Graph API"
  Client ID: "12345678-1234-1234-1234-123456789012"
  Tenant ID: "87654321-4321-4321-4321-210987654321"
  Client Secret: "***************"

Appointment Settings:
  Name: "Service-Termine"
  Graph API Settings: → "Production Graph API"
  Date Field Type: CalendarStartEndDate
  Duration To Add: 01:00:00 (1 Stunde)
  Recipient Sources: DelegatedToUser + DelegatedToGroup
  Subject Template: "Service: {{Fall.Kurzbeschreibung}}"
  Body Template: "<p>Beschreibung: {{Fall.Beschreibung}}</p>"
  Enable Back Sync: true
  Back Sync Time Horizon: 7.00:00:00 (7 Tage)
  Delete Property: → "Termin löschen" (Eigenschaft 999)
  Delete Filter: → Filter für "Stornierte Aufträge"

Beispiel für Löschbedingungen:

Die Löschbedingungen werden OR-verknüpft - das heißt, wenn entweder die Eigenschaft vorhanden ist ODER der Filter zutrifft, wird der Termin gelöscht:

DeleteProperty: Eigenschaft "Termin storniert" (Nummer 150)
  → Wenn diese Eigenschaft im CRM-Fall gesetzt ist, wird der Termin gelöscht

DeleteFilter: "c017 = 101 AND c004 = -2"
  → Alle Fälle des Workflows 101 mit Status -2 (storniert) werden gelöscht

Anwendungsfälle für Terminlöschung:

• Stornierte Aufträge: Automatisches Löschen von Terminen bei Auftragsstornierung
• Status-Änderungen: Termine löschen wenn Fall-Status auf "abgeschlossen" oder "storniert" wechselt
• Eigenschafts-basiert: Flexibles Löschen über frei definierbare CRM-Eigenschaften
• Filter-basiert: Komplexe Löschbedingungen über CRM-Filterkriterien

Sicherheitshinweis:

Das Client Secret sollte sicher verwahrt werden. Verwenden Sie idealerweise:

• Azure Key Vault für Production-Umgebungen
• Umgebungsvariablen statt hardcoded in der Datenbank
• Regelmäßige Rotation der Secrets

NextCloud-Kalendersynchronisation (MESO-WSNEXTCLOUD)

Funktion: Bidirektionaler Kalenderabgleich zwischen Microsoft 365 und NextCloud

Ausführung: Alle 10 Minuten (konfigurierbar über Quartz__NextCloudCalendarSyncJob__scheduler)

Funktionsweise:

Dieser Dienst synchronisiert Kalendereinträge bidirektional zwischen Microsoft 365 (Outlook) und NextCloud. Termine werden in beide Richtungen abgeglichen, wobei der neueste Änderungsstand automatisch die vorherige Version überschreibt (Last-Write-Wins).

1. Sync-Paare konfigurieren

   • Ein Sync-Paar verbindet einen M365-Kalender mit einem NextCloud-Kalender
   • Pro Pair: M365-Benutzer/Kalender und NextCloud-Benutzer/Kalender
   • Zeitzone (optional): IANA-Name (z.B. Europe/Berlin) für die übertragenen Termine; leer = globaler Standard aus DefaultTimeZone (Fallback Europe/Berlin)
   • Konfigurierbare Zeitfenster für bidirektionalen Abgleich
   • Standard-Zeitfenster: 30 Tage rückwirkend / 365 Tage voraus (anpassbar)
   • Für jedes Pair werden Änderungen in beiden Richtungen verarbeitet

2. Terminabruf und Delta-Erkennung

   • Abruf von Terminen aus M365 über Microsoft Graph API
   • Abruf von Terminen aus NextCloud über CalDAV-Protokoll
   • Delta-basierte Synchronisation für effiziente Updates
   • Nur geänderte oder neue Termine werden verarbeitet
   • Auf der M365-/Graph-Seite wird bei abgelaufenem Delta-Token automatisch ein voller Neuabgleich durchgeführt (Selbstheilung)

3. Terminabgleich und Konfliktauflösung

   • Erkennung von Terminen mit derselben externen ID in beiden Systemen
   • Last-Write-Wins-Strategie: Der neueste Änderungsstand gewinnt
   • Konfliktverhalten ist symmetrisch für Änderungen und Löschungen:
     • Wenn ein Termin in M365 gelöscht wird und in NextCloud geändert wurde → gelöschte Version gewinnt
     • Wenn ein Termin gleichzeitig in beiden Systemen gelöscht wird → beide Löschungen synchronisiert
   • Alle Konflikte werden im Synchronisations-Journal dokumentiert

4. Termineinträge synchronisieren

   • Folgende Felder werden synchronisiert: Betreff, Beschreibung, Start-/Enddatum, Ganztags-Status, Erinnerung (Reminder/VALARM, in beide Richtungen)
   • Teams- und Talk-Links werden als Text in Ort/Beschreibung mitgenommen (die Unterhaltungen selbst werden nicht synchronisiert)
   • Fehlerhafte oder nicht synchronisierbare Termine werden mit Fehlermeldung geloggt

5. Serientermine und Ausnahmen

   • Nur tägliche und wöchentliche Wiederholungen werden als echte Serie (RRULE) übertragen (v1)
   • Komplexere Wiederholungsmuster (monatlich, jährlich, etc.) werden nicht als Einzeltermin degradiert, sondern übersprungen und mit einem Journal-Eintrag Error protokolliert ("Wiederholungsmuster nicht unterstützt … — übersprungen"). So entstehen keine irreführenden Einzeltermine
   • Ausnahmen einer M365-Serie werden nach NextCloud übertragen: verschobene/geänderte Einzelvorkommen als RECURRENCE-ID-Overrides, abgesagte Vorkommen als EXDATE
   • v1-Einschränkung (M365 → NextCloud): Abgesagte Vorkommen (EXDATE) werden aus cancelledOccurrences von Graph abgeleitet; die Ableitung setzt das dokumentierte Graph-Datumsformat der occurrenceId voraus. Vorkommen, deren Datum nicht eindeutig gelesen werden kann, werden übersprungen (keine falschen EXDATEs)

6. Löschungen bidirektional propagieren

   • Termine, die in einem System gelöscht werden, werden auch im anderen System gelöscht
   • Löschung erfolgt pro Termin einzeln
   • Bereits gelöschte Termine werden automatisch erkannt und übersprungen
   • Umfassende Fehlerbehandlung für Edge-Cases

7. Feld-Mapping v1 (Einschränkungen)

   • NICHT synchronisiert (v1):
     • Teilnehmer / Einladungen (Attendees) — nur der Kalenderbesitzer wird synchronisiert
     • Anhänge (Attachments)
     • Kategorien / Farben (Categories)
   • Diese Einschränkungen können in künftigen Versionen aufgehoben werden

8. Erstlauf-Zusammenführung (Vermeidung von Duplikaten)

   • Beim ersten Lauf (leere Zustandstabelle) werden Termine, die bereits auf beiden Seiten existieren, zusammengeführt statt beidseitig neu angelegt — Abgleich über die iCal-UID und, falls diese nicht übereinstimmt, über Betreff + Start + Ende
   • v1-Kompromiss: Der Abgleich ist pragmatisch (exakte iCal-UID bzw. exakte Übereinstimmung von Betreff/Start/Ende). Termine mit abweichendem Betreff oder verschobener Zeit gelten als unterschiedlich; in seltenen Grenzfällen kann daher weiterhin ein Duplikat entstehen. Der Erstlauf liest dazu die betroffenen M365-Termine einmalig zusätzlich ein

9. Idempotenz gegen Absturz-Duplikate

   • Die NextCloud-UID neu angelegter Termine wird deterministisch aus der M365-Event-ID abgeleitet. Ein wiederholter Lauf nach einem Absturz (vor dem Speichern des Zustands) überschreibt dieselbe Ressource, statt ein Duplikat anzulegen

Voraussetzungen:

Für die NextCloud-Synchronisation benötigen Sie:

1. NextCloud Installation:

   • Zugriff auf eine CalDAV-fähige NextCloud-Instanz
   • Möglichkeit, App-Passwörter zu erstellen

2. Microsoft 365 Konfiguration:

   • Microsoft 365 / Exchange Online Lizenzen für die synchronisierten Benutzer
   • Kalender müssen für die betroffenen Benutzer verfügbar sein
   • Authentifizierung über die bereits vorhandene Graph API Konfiguration (ClientID, TenantID, ClientSecret)

Schritt-für-Schritt-Anleitung: NextCloud App-Passwort erstellen

Für die Authentifizierung gegen NextCloud wird ein App-Passwort benötigt. Hier ist die Anleitung zur Erstellung:

In NextCloud:

1. Melden Sie sich als Benutzer an, dessen Kalender Sie synchronisieren möchten
2. Klicken Sie auf Ihr Profilbild (rechts oben) → Einstellungen
3. Navigieren Sie zu Sicherheit (oder Personal → Sicherheit)
4. Suchen Sie den Bereich App-Passwörter (App passwords)
5. Geben Sie einen aussagekräftigen Namen ein (z.B. "MESO WorkerService")
6. Klicken Sie auf Passwort generieren oder Create
7. Kopieren Sie das generierte Passwort sofort in einen sicheren Ort
   • ⚠️ Das Passwort wird nach dem Verlassen dieser Seite nicht erneut angezeigt

Im MesoWorkerService:

Diese Anmeldedaten werden später bei der Konfiguration des Sync-Pairs benötigt.

Konfiguration:

Die Konfiguration erfolgt in zwei Schritten in der Administrationsoberfläche, jeweils in der Navigationsgruppe Termin-Synchronisation.

Schritt 1: NextCloud-Server anlegen

Der NextCloud-Server ist ein eigenständiges, wiederverwendbares Objekt. Legen Sie ihn zuerst an, bevor Sie ein Sync-Paar erstellen:

1. Navigieren Sie zu: Termin-Synchronisation → NextCloud-Server
2. Erstellen Sie einen neuen Eintrag:
   • Name: Bezeichnung für diese NextCloud-Instanz (z.B. "Firmen-NextCloud")
   • Base URL: Basis-URL des NextCloud-Servers, nur HTTPS (z.B. https://cloud.firma.de)
   • Bemerkung: Optionale interne Notiz
3. Ein NextCloud-Server kann von mehreren Sync-Paaren verwendet werden.

Schritt 2: Kalender-Sync-Paar anlegen

1. Navigieren Sie zu: Termin-Synchronisation → Kalender-Sync-Paar

2. Erstellen Sie ein neues Sync-Paar mit folgenden Informationen:

   • Name: Aussagekräftige Bezeichnung (z.B. "Vertrieb ↔ NextCloud")
   • Aktiviert: Aktiviert die Synchronisation für dieses Paar
   • Mandant: Zugeordneter Mandant (Company)
   • Graph API Zugangsdaten: Referenz auf die bestehenden Graph API Settings (Client/Tenant/Secret)
   • M365-Benutzer (UPN): E-Mail-Adresse des M365-Benutzers, dessen Kalender synchronisiert wird
   • M365-Kalender: Name des M365-Kalenders (leer = Standardkalender)
   • NextCloud-Server: Auswahl des in Schritt 1 angelegten NextCloud-Servers
   • NextCloud-Benutzer: NextCloud-Login-Name
   • NextCloud-App-Passwort: Das oben generierte App-Passwort (als Passwortfeld gespeichert; niemals das reguläre Benutzerpasswort verwenden)
   • NextCloud-Kalender: Name des NextCloud-Kalenders (leer = Standardkalender "personal")
   • Zeitfenster rückwirkend (SyncPastDays): Tage in die Vergangenheit (Standard: 30)
   • Zeitfenster voraus (SyncFutureDays): Tage in die Zukunft (Standard: 365)
   • Journal-Aufbewahrung (JournalRetentionDays): Aufbewahrungsdauer der Journal-Einträge in Tagen (Standard: 90)

3. Nach der Konfiguration:

   • Das Sync-Paar wird beim nächsten Job-Lauf automatisch berücksichtigt
   • Termine werden bidirektional synchronisiert
   • Alle Sync-Ereignisse werden im Journal protokolliert

Journal-Protokollierung:

Das NextCloud-Synchronisations-Journal dokumentiert pro Eintrag eine der folgenden Aktionen:

• Created – neu angelegter Termin (in M365 oder NextCloud)
• Updated – aktualisierter Termin
• Deleted – gelöschter Termin
• ConflictResolved – per Last-Write-Wins aufgelöster Konflikt
• Error – Fehler mit Fehlermeldung

Sicherheitsempfehlungen:

• Verwenden Sie sichere, eindeutige App-Passwörter für jeden Sync-Service
• Speichern Sie die Passwörter nicht als Plaintext in Logs oder Konfigurationsdateien
• Verwenden Sie HTTPS für alle NextCloud-Verbindungen
• Implementieren Sie regelmäßige Datensicherungen (Kalender-Backups)
• Überprüfen Sie die Sync-Journal-Einträge regelmäßig auf Anomalien

Offene Posten (OP-Versand)

Funktion: Automatischer Versand von OP-Infos an Kunden

Ausführung: Täglich um 7:00 Uhr (konfigurierbar über Quartz__OpenItemWorkerJob__scheduler)

Funktionsweise:

Der OP-Dienst ermittelt offene Posten aus der WinLine FIBU (Tabelle T019), gruppiert diese nach Kunden und versendet konfigurierbare E-Mails mit OP-Infos. So können OP-Informationen automatisiert an Kunden gesendet werden.

1. OP-Ermittlung

   • Abfrage der offenen Posten aus der WinLine FIBU-Tabelle T019
   • Filterung nach Kontoart (Debitoren, Kreditoren oder beide)
   • Optionale Einschränkung auf bestimmte Kontobereiche
   • Konfigurierbare Fälligkeits- und Mahnstufenfilter

2. Kundengruppierung

   • Offene Posten werden nach Kundenkontonummer gruppiert
   • Kundenstammdaten (Name, Adresse, E-Mail) werden aus dem Kontenstamm angereichert
   • Zusammenfassung mit Gesamtbetrag und Anzahl überfälliger Posten pro Kunde

3. Empfänger-Ermittlung

   • Mehrstufige Empfängerermittlung mit Fallback-Logik:
     • Rechnungs-E-Mail-Adresse des Kunden
     • Kunden-E-Mail-Adresse
     • Kundenkontakt
     • Mahnempfänger (über erweiterte Empfängerregeln)
     • Statische Empfänger
   • Konfigurierbar über die OpenItemSettings in der Administrationsoberfläche

4. E-Mail-Erstellung

   • Drei Template-Optionen (nach Priorität):
     • HTML-Editor-Vorlage (HtmlMailTemplate)
     • RichText-MailMerge-Vorlage (MailTemplate)
     • WinLine-Textbaustein (OverrideTextBlocknumber)
   • Standard-Template als Fallback
   • Platzhalter für OP- und Kundendaten (vollständige Referenz siehe unten)
     • {{#OP}}...{{/OP}} — Wiederholungsbereich pro offener Posten
     • {{OP.xxx}} — OP-Felder, {{Kunde.xxx}} — Kundenstamm-Felder
     • {{Beleg.xxx}} — Belegdaten, {ArchivLinkExt:...} — Archiv-Links
     • {SALUTATION} / ##Empfaenger## — Empfängerspezifische Anrede

5. Anhänge

   • Originalrechnungen aus dem Archiv: Anhängen von Belegen aus MesoArchivWeb (konfigurierbar über Archivformular-IDs)
   • OP-Blatt aus der FIBU als PDF: Automatischer Download des OP-Blatts über den WinLine Server Report-Service (/ewlservice/reports) als PDF-Anhang. Optional kann über OpenItemListFormId ein alternatives Formular angegeben werden. Der Download wird mit PDF-Validierung (Magic-Bytes-Prüfung) abgesichert.

6. Versand und Journal

   • Direktversand über konfigurierte SMTP-Konten
   • Entwurfsmodus (SaveMailsAsDraft): Mails werden als EML-Datei im Postausgang (QueuedMail) gespeichert. Der Benutzer kann die Mails in der Administrationsoberfläche prüfen, bearbeiten oder ignorieren. Der MailQueueProcessor versendet freigegebene Mails (Draft=false) automatisch und aktualisiert den OpenItemJournal-Eintrag.
   • OpenItemJournal-Eintrag pro Versand mit Status (Sent/Error/Ignored), Fehlermeldung und EML-Datei
   • Sendeintervall (SendIntervalDays): Verhindert Mehrfachversand an denselben Kunden innerhalb eines konfigurierbaren Zeitraums
   • Ignorieren-Flag: Manuelles Unterdrücken einzelner Kunden im Journal oder Postausgang

Selektionskriterien:

Einstellung	Beschreibung
AccountType	Debitoren, Kreditoren oder beide
OnlyDueItems	Nur fällige Posten berücksichtigen
MinOverdueDays	Mindestanzahl überfälliger Tage
MinDunningLevel	Mindest-Mahnstufe
CustomerFilter	Optionaler DevExpress-Filterausdruck auf den Kontenstamm
OpenItemFilter	Optionaler DevExpress-Filterausdruck auf die offenen Posten

| MaxDunningLevel („Mahnstufe bis") | Höchste Mahnstufe, 0 = kein Filter. Nur Posten mit Mahnstufe kleiner oder gleich diesem Wert werden berücksichtigt; zusammen mit MinDunningLevel ergibt sich ein Bereich, z.B. 1 bis 2 für Zahlungserinnerungen ohne die letzte Mahnung | | DueDateCutoff („Stichtag Fälligkeit") | Fester Stichtag für die Fälligkeitsprüfung: Ein Posten gilt als fällig, wenn sein Fälligkeitsdatum auf oder vor dem Stichtag liegt; auch MinOverdueDays rechnet ab diesem Stichtag. Wirkt nur, wenn „Stichtag = Heute" aus ist; leer = heutiges Datum. Gedacht für Testläufe oder einen bewusst zurückdatierten Stichtag | | UseDueDateCutoffToday („Stichtag = Heute") | Standard ein: Bei jedem Lauf gilt das aktuelle Datum als Stichtag; ein eingetragener DueDateCutoff wird dann ignoriert. Für den laufenden Betrieb eingeschaltet lassen – sonst bleibt der Stichtag stehen, und mit der Zeit werden immer weniger Posten selektiert |

Anhang-Optionen:

Einstellung	Beschreibung
AttachOriginalInvoice	Originalrechnung aus dem Archiv anhängen
AttachArchiveFormIds	Archivformulare, deren Belege angehängt werden sollen
AttachOpenItemList	OP-Blatt als PDF vom WinLine Server anhängen
OpenItemListFormId	Alternative Formular-ID für das OP-Blatt (optional, 0 = Standard-Formular)

Vorlage und Anrede:

Einstellung	Beschreibung
MailSubjectTemplate („Betreff-Vorlage")	Betreffzeile mit Platzhaltern der Kunden-Ebene, Standard Offene Posten - {{Kunde.Kontoname}}. Alle {{Kunde.xxx}}-Platzhalter und Formatangaben sind erlaubt; HTML-Formatierung wird im Betreff entfernt
DefaultSalutation („Standard-Anrede")	Anrede, wenn keine persönliche Anrede ermittelt werden kann – etwa beim Versand an die Rechnungs-Mailadresse oder an statische Empfänger. Standard Sehr geehrte Damen und Herren,. Ersetzt {SALUTATION} bzw. ##Empfaenger## in der Vorlage

Empfänger-Optionen:

Einstellung	Beschreibung
ReminderRecipientPropertyNumber („Mahnempfänger-Eigenschaftsnr.")	Nummer der Kontakt-Eigenschaft (Eigenschaftendefinition für Ansprechpartner), die einen Ansprechpartner als Mahnempfänger kennzeichnet. Wird mit „An Mahnempfänger senden" ausgewertet: alle aktiven Ansprechpartner des Kontos mit gesetzter Eigenschaft und E-Mail-Adresse erhalten die Mail. 0 (Standard) = automatische Erkennung – die erste Kontakt-Eigenschaft, deren Bezeichnung „Mahn" enthält. Findet sich keine, wird kein Mahnempfänger ermittelt (Warnung im Protokoll); dann die Nummer hier fest eintragen
StaticRecipientsBcc („Statische BCC-Empfänger")	Kommagetrennte Adressen, die jede OP-Mail als Blindkopie erhalten, z.B. ein Buchhaltungspostfach zur Ablage. Ungültige Adressen werden übersprungen
RecipientsForErrors („Empfänger bei Fehlern")	Kommagetrennte Adressen, die eine Hinweismail erhalten, wenn für ein Konto kein Empfänger ermittelt werden konnte – mit Kontonummer, Name, Anzahl der Posten und Gesamtsumme. Der Hinweis wird im OP-Versand-Journal protokolliert. Leer = kein Hinweis; das Konto wird nur im Protokoll vermerkt

Versand-Optionen:

Einstellung	Beschreibung
SaveAttachmentsInJournal („Anhänge im Journal speichern")	Legt die Anhänge der versendeten OP-Mail (OP-Blatt, Originalrechnungen) als Dateien am Eintrag im OP-Versand-Journal ab, sodass sie dort geöffnet werden können. Erhöht den Speicherbedarf der Datenbank. Standard aus. Alternativ steht mit „EML im Journal speichern" die komplette Mail samt Anhängen im Journal

Das Feld SaveInPab („Im PAB speichern") ist in der Oberfläche ausgeblendet; die Ablage von OP-Mails im WinLine-Postausgangsbuch ist noch nicht umgesetzt.

Antwort-An und Absender:

Einstellung	Beschreibung
ReplyTo („Antwort-Adresse")	Optionale Antwortadresse (Reply-To). Antworten der Kunden gehen an diese Adresse statt an den Absender, z.B. [email protected]. Leer = kein Reply-To
ReplyToName („Antwort-Name")	Anzeigename zur Antwortadresse
StaticSenderAddress („Absender-Adresse")	Feste Absenderadresse. Leer (Standard) = Adresse des verwendeten SMTP-Kontos. Ist zugleich Absender der Hinweismail an „Empfänger bei Fehlern"
StaticSenderName („Absender-Name")	Anzeigename des Absenders. Leer = Name aus dem SMTP-Konto

Platzhalter-Referenz:

Innerhalb der OP-Vorlagen stehen folgende Platzhalter zur Verfügung. Alle Platzhalter unterstützen optionale Formatangaben (z.B. :C2, :dd.MM.yyyy) — siehe Formatangaben für Platzhalter.

Wiederholungsbereich:

Der Block {{#OP}}...{{/OP}} wird pro offener Posten wiederholt. Innerhalb dieses Blocks stehen die {{OP.xxx}}-Platzhalter zur Verfügung.

OP-Platzhalter (innerhalb {{#OP}}...{{/OP}}):

Platzhalter	Beschreibung
{{OP.BelegNr}} / {{OP.Belegnummer}}	Belegnummer
{{OP.BuchungsNr}} / {{OP.Buchungsnummer}}	Buchungsnummer (z.B. "10001-RE202600032")
{{OP.Betrag}}	Ursprünglicher Betrag
{{OP.Restbetrag}}	Offener Restbetrag (berechnet)
{{OP.ZahlungBetrag}} / {{OP.Bezahlt}} / {{OP.Teilzahlung}}	Bereits bezahlter Betrag
{{OP.Skontobetrag}}	Skontobetrag
{{OP.BetragWaehrung}}	Betrag in Fremdwährung
{{OP.Waehrung}} / {{OP.Buchungstext}}	Währung
{{OP.Buchungsdatum}}	Buchungsdatum
{{OP.Rechnungsdatum}} / {{OP.ReDatum}}	Rechnungsdatum
{{OP.Faelligkeit}} / {{OP.Fälligkeitsdatum}}	Fälligkeitsdatum
{{OP.ZahlungszielTage}}	Zahlungsziel in Tagen
{{OP.TageUeberfaellig}} / {{OP.Tageüberfällig}}	Überfällige Tage (berechnet)
{{OP.Mahnstufe}}	Aktuelle Mahnstufe
{{OP.BuchungsArt}} / {{OP.Buchungsartid}}	Buchungsart-ID (0=Rechnung, 2=Gutschrift)
{{OP.BuchungsArtText}}	Buchungsart als Text ("Rechnung", "Gutschrift", etc.)
{{OP.Kontonummer}}	Kontonummer
{{OP.Status}}	Status

Zusätzlich kann über die XPO-Objektnavigation auf verschachtelte Eigenschaften des OffenePosten-Objekts zugegriffen werden (z.B. {{OP.Personenkonto.Name}}).

Kunden-Platzhalter (überall in der Vorlage verfügbar):

Platzhalter	Beschreibung
{{Kunde.Name}} / {{Kunde.Kundenname}} / {{Kunde.Kontoname}}	Kundenname
{{Kunde.Kontonummer}} / {{Kunde.Konto}}	Kontonummer
{{Kunde.Email}} / {{Kunde.EmailAdresse}}	E-Mail-Adresse
{{Kunde.RechnungsEmail}} / {{Kunde.RechnungsversandEMailAdresse}}	Rechnungsversand-E-Mail
{{Kunde.AnsprechpartnerName}} / {{Kunde.Ansprechpartner}}	Ansprechpartner
{{Kunde.AnsprechpartnerEmail}}	E-Mail des Ansprechpartners
{{Kunde.GesamtOffen}} / {{Kunde.Offen}} / {{Kunde.Summe}} / {{Kunde.Total}}	Gesamter offener Betrag
{{Kunde.GesamtBrutto}} / {{Kunde.Brutto}}	Gesamter Bruttobetrag
{{Kunde.GesamtBezahlt}} / {{Kunde.Bezahlt}}	Gesamter bezahlter Betrag
{{Kunde.Anzahl}} / {{Kunde.Count}}	Anzahl offener Posten
{{Kunde.AnzahlUeberfaellig}} / {{Kunde.Anzahlüberfällig}}	Anzahl überfälliger Posten
{{Kunde.SummeUeberfaellig}} / {{Kunde.Summeüberfällig}}	Summe überfälliger Beträge
{{Kunde.AeltesteFaelligkeit}} / {{Kunde.Ältestefälligkeit}}	Ältestes Fälligkeitsdatum
{{Kunde.MaxTageUeberfaellig}} / {{Kunde.Maxtageüberfällig}} / {{Kunde.Maxtage}}	Maximale überfällige Tage
{{Kunde.Mesocomp}}	Mandant

Zusätzlich kann über die XPO-Objektnavigation auf verschachtelte Eigenschaften des ViewKontenstamm-Objekts zugegriffen werden (z.B. {{Kunde.Adresse.Strasse1}}, {{Kunde.FaktStamm.xxx}}).

Beleg-Platzhalter (innerhalb {{#OP}}...{{/OP}}, wenn ein passender Beleg existiert):

Platzhalter	Beschreibung
{{Beleg.xxx}}	Zugriff auf Eigenschaften des BestelldateiKopf-Objekts (z.B. {{Beleg.Rechnungsnummer}}, {{Beleg.Endbetrag}})

Archiv-Link-Platzhalter (innerhalb {{#OP}}...{{/OP}}):

Platzhalter	Beschreibung
{ArchivLinkExt:Faktura|text=Rechnung ansehen|stunden=720}	Externer Link zur archivierten Rechnung (zeitbegrenzt, kein Login nötig)
{ArchivLinkInt:Faktura|text=Rechnung ansehen}	Interner Link zur archivierten Rechnung (Login erforderlich)

Unterstützte Belegarten: Faktura, Auftrag, Lieferschein, Angebot oder eine numerische DokId. Optionale Parameter: text=..., stunden=... (nur Ext), prefix=..., suffix=....

Anrede-Platzhalter:

Platzhalter	Beschreibung
{SALUTATION} / {{SALUTATION}} / ##Empfaenger##	Empfängerspezifische Anrede

Standardformatierung: Dezimalwerte werden automatisch als N2 (z.B. "1.234,56"), Datumswerte als dd.MM.yyyy formatiert (Kultur: de-DE).

Beispiel-Vorlage:

<p>{SALUTATION}</p>
<p>nachfolgend finden Sie eine Übersicht Ihrer offenen Posten:</p>
<table>
  <thead>
    <tr>
      <th>Beleg-Nr.</th><th>Datum</th><th>Fällig</th>
      <th>Betrag</th><th>Bezahlt</th><th>Offen</th>
      <th>Tage überf.</th><th>Mahnstufe</th>
    </tr>
  </thead>
  <tbody>
    {{#OP}}
    <tr>
      <td>{{OP.BelegNr}}</td>
      <td>{{OP.Rechnungsdatum:dd.MM.yyyy}}</td>
      <td>{{OP.Faelligkeit:dd.MM.yyyy}}</td>
      <td>{{OP.Betrag:N2}} €</td>
      <td>{{OP.ZahlungBetrag:N2}} €</td>
      <td>{{OP.Restbetrag:N2}} €</td>
      <td>{{OP.TageUeberfaellig}}</td>
      <td>{{OP.Mahnstufe}}</td>
    </tr>
    {{/OP}}
  </tbody>
  <tfoot>
    <tr>
      <td colspan="5"><strong>Gesamt ({{Kunde.Anzahl}} Posten)</strong></td>
      <td><strong>{{Kunde.GesamtOffen:N2}} €</strong></td>
      <td colspan="2"></td>
    </tr>
  </tfoot>
</table>
<p>Bitte überweisen Sie den offenen Betrag von <strong>{{Kunde.GesamtOffen:C2}}</strong>.</p>

Voraussetzungen:

• WinLine FIBU mit offenen Posten in Tabelle T019
• Optional: MesoArchivWeb für Archiv-Anhänge (Konfiguration unter MesoArchivWeb in appsettings.json)
• Optional: WinLine Server mit Report-Service (/ewlservice/reports) für OP-Blatt-Download als PDF (Konfiguration unter WinLineServer in appsettings.json)

Konfiguration:

OP-Einstellungen werden pro Mandant in der Administrationsoberfläche unter "OpenItemSettings" konfiguriert. Die Konfiguration umfasst sieben Registerkarten: Allgemein, Selektion, Vorlage, Empfänger, Versand, Anhänge und Antwort-An/Absender.

---

Überwachungsdienst

Funktion: Überwachung und Warnung bei fehlenden E-Mail-Versendungen

Ausführung: Täglich um 8:00 Uhr (konfigurierbar über Quartz__NoRuleWarningJob__scheduler)

Funktionsweise:

Der Überwachungsdienst hilft dabei, Probleme frühzeitig zu erkennen, die dazu führen, dass E-Mails nicht versendet werden, obwohl aktive Regeln vorhanden sind. Für jeden betroffenen Vorgang wird dabei eine konkrete Ursache ermittelt und in der Warnmail benannt – nicht nur die Feststellung, dass keine Mail verschickt wurde.

1. Workflow-Überwachung

   • Prüft alle Workflows mit aktivierten Mail-Einstellungen
   • Vergleicht CRM-Fälle mit tatsächlich versendeten E-Mails
   • Berücksichtigt nur Fälle im konfigurierten Zeitraum (z.B. letzte 24 Stunden)

2. Grace Period

   • Workflows, die jünger als die Grace Period sind, werden ignoriert
   • Verhindert Fehlalarme für Workflows, die gerade verarbeitet werden
   • Empfohlen: 15-20 Minuten

3. Warnungs-E-Mail mit Ursache und Maßnahme

   • Die Warnmail gliedert die gefundenen Vorgänge in drei Abschnitte: Handlungsbedarf (ein echtes Problem, das eine Aktion erfordert), Versand fehlgeschlagen (die Mail wurde erzeugt, der Versand ist aber gescheitert) und Bewusst übersprungen (kein Fehler, sondern eine Konsequenz der Konfiguration, z.B. vom Filter ausgeschlossen)
   • Je Vorgang stehen Betreff, Kundenkonto und -name, Ansprechpartner mit Mailadresse, Kundenmailadresse, Ersteller, der verknüpfte Beleg und die zuständige Mail-Einstellung in der Mail – Rückfragen sind so ohne Öffnen des Falls möglich
   • Ein Vorgang wird über Fall-ID und Schrittnummer und Workflow-Nummer identifiziert, weil jeder Schritt eines Falls eine eigene Mail-Konfiguration haben kann
   • Der vollständige Ursachen-Katalog mit den empfohlenen Maßnahmen steht weiter unten

4. Duplikats-Schutz

   • Versendete Warnungen werden je Vorgang und Ursache protokolliert
   • Verhindert mehrfache Warnungen für denselben Vorgang mit derselben Ursache
   • Ändert sich die Ursache (z.B. wird aus "Kein Mail-Empfänger" ein "Versand fehlgeschlagen"), wird erneut gewarnt

Einsatzszenarien:

• Fehlende Stammdaten: Kunde hat keine E-Mail-Adresse hinterlegt
• Fehlkonfiguration: Mail-Einstellungen sind nicht korrekt
• Restriktive Filter: Filterkriterien selektieren keine Fälle
• SMTP-Probleme: SMTP-Server ist nicht erreichbar

Ursachen-Katalog:

Jede Ursache trägt eine feste Beschriftung und eine empfohlene Maßnahme:

Abschnitt	Ursache	Empfohlene Maßnahme
Handlungsbedarf	Kein Mail-Empfänger	Mailadresse im Ansprechpartner oder Kundenstamm hinterlegen.
Handlungsbedarf	Nur BCC-Empfänger	Die Empfängerregel liefert nur BCC – einen To- oder CC-Empfänger ergänzen.
Handlungsbedarf	Kein SMTP-Konto	SMTP-Konto in der Mail-Einstellung hinterlegen oder ein Standardkonto festlegen.
Handlungsbedarf	Kein Mailtext	Mailvorlage der Einstellung prüfen – sie erzeugt keinen Text.
Handlungsbedarf	Workflow keiner Mail-Einstellung zugeordnet¹	Den Workflow einer Mail-Einstellung zuordnen.
Handlungsbedarf	Filterkriterium nicht auswertbar	Filterkriterium der Einstellung korrigieren – es verweist auf ein unbekanntes Feld.
Handlungsbedarf	Fehler bei der Verarbeitung	Job-Protokoll prüfen.
Handlungsbedarf	Ursache unbekannt	Job-Protokoll prüfen – lief der Mail-Dienst im Zeitraum?
Versand fehlgeschlagen	Versand fehlgeschlagen	SMTP-Zugang prüfen, Fehlermeldung siehe Zeile.
Bewusst übersprungen	Vom Filter ausgeschlossen	Nur informativ – so konfiguriert.
Bewusst übersprungen	Workflow-Eigenschaften passen nicht	Nur informativ – so konfiguriert.
Bewusst übersprungen	Außerhalb des Abholzeitraums	Nur informativ – so konfiguriert.
Bewusst übersprungen	Kein Anhang mit dem geforderten Formulartyp	Nur informativ – so konfiguriert.
Bewusst übersprungen	Kein Autoarchiv-Eintrag zum Beleg	Nur informativ – so konfiguriert.
Bewusst übersprungen	Kein Anhang vorhanden	Nur informativ – so konfiguriert.

¹ Reserviert: Diese Ursache kann derzeit nicht auftreten. Der Überwachungsdienst prüft je Mail-Einstellung nur die ihr zugeordneten, aktiven Workflows – ein Workflow, der in keiner aktiven Mail-Einstellung hinterlegt ist, wird von der Prüfung dadurch gar nicht erst erfasst und bleibt für die Diagnose unsichtbar. Der Eintrag ist im Katalog bereits vorgesehen, damit eine künftige Version auch diesen Fall ausweisen kann.

Übersprungene Mails (neues Journal):

Zusätzlich zur Warnmail hält der Mail-Dienst laufend fest, warum für einen Vorgang keine E-Mail erzeugt wurde – einsehbar in der Administrationsoberfläche unter "Mail-Dienst → Übersprungene Mails". Der Eintrag ist rein informativ: Er verhindert nicht, dass der Mail-Dienst den Vorgang beim nächsten Lauf erneut versucht. Sobald die Ursache behoben ist (z.B. eine Mailadresse nachgetragen wurde), greift die Korrektur beim nächsten Lauf automatisch – ganz ohne manuellen Eingriff am Journal, sofern der Vorgang noch im Abholzeitraum der Mail-Einstellung liegt; ältere Vorgänge müssen über das Abholdatum der Mail-Einstellung erneut freigegeben werden.

Vorschau des Berichts (Testlauf):

Auf der Überwachungseinstellung liegt die Aktion Vorschau. Sie zeigt den Bericht so, wie ihn der nächste Lauf melden würde – ohne eine Mail zu versenden und ohne etwas zu speichern. Damit lässt sich eine neu eingerichtete oder geänderte Einstellung sofort prüfen, statt bis zum nächsten Lauf um 8:00 Uhr zu warten.

Beim Aufruf wird zunächst der Rückblick-Zeitraum abgefragt, vorbelegt mit der LookbackPeriod der Einstellung. Ein längerer Zeitraum eignet sich zum Nachforschen: Die LookbackPeriod ist für den täglichen Lauf bemessen und daher oft zu kurz, um einem länger zurückliegenden Vorfall nachzugehen. Anschließend erscheint der fertige Bericht mit Betreff, den Kennzahlen je Abschnitt und dem vollständigen HTML.

Die Vorschau weicht bewusst in zwei Punkten vom echten Lauf ab:

• Der Duplikatsschutz ist abgeschaltet. Sie zeigt alle Vorgänge des Zeitraums, auch bereits gemeldete – sonst wäre sie nach dem ersten Lauf regelmäßig leer.
• Die Einstellung Informationsmail ohne Handlungsbedarf wird übergangen. Der Bericht erscheint auch dann, wenn ausschließlich bewusst übersprungene Vorgänge vorliegen.

Die Karenzzeit (GracePeriod) wirkt dagegen unverändert, damit die Vorschau denselben Ausschnitt zeigt wie der echte Lauf.

Die Auswertung läuft direkt in der Verwaltungsoberfläche – der WorkerService muss dafür nicht gestartet sein. Sie ist damit auch dann verfügbar, wenn der Dienst gerade steht. Die Aktion steht in der Web-Verwaltung und im Windows-Client zur Verfügung.

Konfiguration:

Überwachungseinstellungen werden pro Mandant in der Administrationsoberfläche unter "No Rule Warning Settings" konfiguriert.

Wichtige Einstellungen:

• LookbackPeriod: Zeitraum, wie weit zurück geprüft wird (z.B. 24 Stunden)

• GracePeriod: Mindestalterzeitspanne für Workflows (empfohlen: 15-20 Minuten)

• WarningRecipients: E-Mail-Adressen der Administratoren (kommagetrennt)

• UseSmtpAccount ("SMTP Konto"): Optionales SMTP-Konto für die Warnmail. Leer = das als Standard markierte SMTP-Konto. Gibt es weder das eine noch das andere, wird keine Warnmail versendet und im Protokoll steht „Kein SMTP-Konto für den Versand der Warnmail verfügbar". Die mandantenbezogene Kontenermittlung des Mail-Dienstes (Workflow → Workflow-Einstellung → Mandant) gilt hier nicht

• SendInfoMailWhenOnlySkipped ("Informationsmail ohne Handlungsbedarf"): Standard aus. Liegen in einem Lauf ausschließlich bewusst übersprungene Vorgänge vor (kein Handlungsbedarf, kein Versandfehler), kommt ohne diesen Schalter keine Mail. Erst wenn er aktiviert ist, wird dafür ebenfalls eine rein informative Mail versendet.

Die Schreiblast des Skip-Journals wird über die appsettings.json gedrosselt, da der Mail-Dienst im Minutentakt läuft:

{
  "MailSkipJournal": {
    "MinUpdateInterval": "00:15:00"
  }
}

MinUpdateInterval (Standard 00:15:00) legt fest, wie lange ein unverändert bleibender Skip-Grund für denselben Vorgang mindestens fortbesteht, bevor Zeitstempel und Zähler erneut aktualisiert werden. Ändert sich die Ursache, wird sofort geschrieben.

Hinweis zum ersten Lauf nach dem Update: Versandfehler und übersehene Folgeschritte werden mit dieser Funktion erstmals erfasst. Der erste Lauf nach dem Update kann dadurch einmalig umfangreicher ausfallen als gewohnt – begrenzt bleibt er in jedem Fall durch die konfigurierte LookbackPeriod.

---

Open Banking

Funktion: Automatischer Bankkonto-Abruf, Zahlungsmatching und FIBU-Buchung in WinLine

Lizenz: MESO-WSBANKK

Ausführung: Konfigurierbar über Quartz__BankingWorkerJob__scheduler (empfohlen: stündlich oder täglich)

---

Architektur und Verarbeitungsflow

Der Banking-Job verarbeitet Transaktionen in zwei Phasen pro aktivem Bankkonto:

Phase 1 – Matching (pro Transaktion):

Richtung	Verarbeitungspfad
Eingang (Amount > 0)	Debitor-OP-Matching (Score) → LLM-Fallback → Vorauszahlung → Unmatched
Ausgang (Amount < 0)	Kreditor-OP-Matching → LLM-Kreditor → Buchungsregel → LLM-Sachkonto → Unmatched
Eingang auf Verrechnungskonto	Buchungsregel mit Richtung=Eingang (z.B. PayPal-Auszahlung)

Phase 2 – Batch-Import (ein WinLine-Aufruf pro Durchgang):

• Phase 2a: Debitor-Zahlungen → FibuBankingBookingService (T331 + T340, Buchungsart DZ)
• Phase 2b: Ausgänge/Verrechnungen → FibuAusgangsbuchungService (T331, Buchungsart B/KZ)

---

Konfiguration: Banking-Konten (BankAccountSettings)

Pro Bankkonto / Zahlungsdienst wird unter Banking → Banking-Konten ein Eintrag angelegt. Die wichtigsten Felder im Überblick:

Feld	Beschreibung
Provider	GMI (GetMyInvoices), fino oder Mock (Testdaten). FinTS steht in der Auswahl, ist aber derzeit nicht implementiert – ein Konto mit diesem Provider bricht beim Abruf mit „wird nicht unterstützt" ab
ProviderAccountId	Konto-ID beim Provider (z.B. GMI bankAccountUid)
BankkontoTyp	Girokonto / Kreditkarte / PayPal / Sonstiges
WinlineBankkontonummer	WinLine-Kontonummer (KontoHaben bei B-Buchungen, z.B. 1801)
RegelbasiertesBuchenEnabled	Tab „Kostenbuchungen" → „Regelbasierte Buchungen": aktiviert die Verarbeitung von Ausgängen über Buchungsregeln. Bei Verrechnungskonten (Kreditkarte, PayPal, Sonstige) immer aktiv
KreditorOpMatchingEnabled	Aktiviert Abgleich gegen Kreditoren-OPs
SachkontoVon / SachkontosBis	Tab „KI-Unterstützung": Kontenbereich, aus dem die KI ein Sachkonto wählen darf (Sachkontenstamm T055). Standard 3000–6999
LlmKostenEnabled	Tab „KI-Unterstützung" → „KI-Kostenbuchung aktiviert": KI-Sachkonto-Vorschläge für Ausgänge ohne passende Regel (T055 + T028-Kontext)

Die vollständigen Einstellungen eines Banking-Kontos sind in Tabs gegliedert. Die folgenden Tabellen nennen je Feld die Bedeutung und den Standardwert, den ein neu angelegtes Konto erhält (Bestandskonten behalten ihre Werte). Einige Werte greifen auf globale Rückfallwerte aus der appsettings.json zurück – diese sind im Abschnitt Globale Einstellungen beschrieben.

Tab „Allgemein"

Einstellung	Bedeutung	Standard
Bezeichnung (Name)	Name dieser Banking-Konfiguration, erscheint in Journal, Buchungsstapel-Bezeichnung und Benachrichtigungen. Pflichtfeld	–
Aktiv (Enabled)	Nur aktive Konten werden im Job-Durchlauf verarbeitet; zusätzlich muss der Mandant aktiv sein. Inaktive Konten erscheinen in der Liste grau	aus
Mandant (Company)	WinLine-Mandant, in dessen FIBU gebucht wird. Pflichtfeld	–
SMTP-Konto (SmtpAccount)	Absenderkonto für die Benachrichtigungsmails dieses Kontos. Leer = SMTP-Konto des Mandanten, sonst das Standard-SMTP-Konto	leer
Konto-Typ (BankkontoTyp)	Girokonto (normales Bankkonto) oder Verrechnungskonto Kreditkarte, PayPal, Sonstiges. Verrechnungskonten buchen immer regelbasiert und lassen Buchungsregeln auch für Eingänge zu (z.B. PayPal-Auszahlung aufs Girokonto), siehe Buchungsketten	Girokonto
Vorschau-Modus (PreviewMode)	Kontoabruf, Matching und Scoring laufen vollständig, aber es wird kein Buchungsstapel importiert und keine Mail versendet. Die Ergebnisse stehen im Transaktionsjournal (Kennzeichen „Vorschau"). Geeignet für die Einrichtung neuer Konten und Regeln	aus
Zweistufiger Workflow (ZweistufigEnabled)	Stufe 1 (Job): Abruf → Matching → Buchungsvorschläge → Zusammenfassungs-Mail an die Benachrichtigungs-Empfänger. Stufe 2 (Buchhaltung): Vorschläge im Transaktionsjournal prüfen (Filter-Preset „Freigabe ausstehend") und über die Aktion Buchungen freigeben in WinLine buchen. Anders als im Vorschau-Modus sind die Vorschläge echte Buchungen, die nur auf die Freigabe warten. Empfohlen, wenn jede Buchung vorab geprüft werden soll	aus
Jetzt auslösen (TriggerNow)	Der nächste Job-Durchlauf verarbeitet dieses Konto sofort – auch wenn es nicht aktiv ist. Wird nach dem Lauf automatisch zurückgesetzt	aus
Benachrichtigungs-Empfänger (NotificationRecipients)	Kommagetrennte E-Mail-Adressen. Erhalten je eine Mail pro nicht zuordenbarer Transaktion sowie – im zweistufigen Workflow – die Freigabe-Zusammenfassung. Leer = keine Mails. Im Vorschau-Modus wird nie gesendet	leer

Tab „Bankverbindung"

Einstellung	Bedeutung	Standard
IBAN (IBAN)	IBAN des Kontos; erscheint in Benachrichtigungsmails. Bei PayPal / Verrechnungskonten nicht erforderlich	leer
Bank (BankName)	Name der Bank, nur zur Information	leer
WinLine-Bankkontonummer (WinlineBankkontonummer)	Sachkonto des Bankkontos in WinLine (z.B. 1801). Gegenkonto aller Kosten- und Kreditorbuchungen (B/KZ) sowie der Eingangs-Verrechnungsbuchungen. Ohne diese Nummer läuft die KI-Sachkonto-Klassifikation nicht	leer
Import ab (ImportFromDate)	Startdatum des ersten Abrufs. Sobald Transaktionen im Journal stehen, beginnt jeder weitere Abruf drei Tage vor dem jüngsten bekannten Buchungsdatum – das Feld wird dann nicht mehr ausgewertet	heute − 1 Monat
Provider (ProviderType)	fino Open Banking API: Zugangsdaten stehen zentral in appsettings.json (Abschnitt FinoApi), pro Konto wird nur die Provider-Konto-ID hinterlegt. GetMyInvoices (GMI): Zugangsdaten pro Konto (API-Key, Account-ID). Mock: Testdaten ohne Bankzugriff. FinTS: in der Auswahl vorhanden, derzeit nicht implementiert	fino
Provider-Konto-ID (ProviderAccountId)	Kennung des Kontos beim Provider – bei fino die Account-ID, bei GMI die bankAccountUid (ganze Zahl, z.B. 42)	leer
GMI API-Key (GmiApiKey)	Nur bei Provider GMI. Wird als Kennwort gespeichert; das Feld GMI-Key Status zeigt, ob ein Key hinterlegt ist. Fehlt der Key, meldet der Abruf einen Fehler und liefert keine Transaktionen	leer
GMI Account-ID (GmiAccountId)	Nur bei Provider GMI. Die Account-ID aus dem GetMyInvoices-Portal (oben rechts); GMI verlangt sie als Teil der Kennung, mit der sich der Dienst bei jedem Aufruf ausweist	leer

Tab „FIBU-Buchung"

Einstellung	Bedeutung	Standard
Buchungsstapel-Vorlage Nr. (BuchungsstapelTemplateNummer)	Nummer der WinLine-Importvorlage vom Typ „Buchungsstapel"; muss in WinLine angelegt sein. 0 = globaler Wert Banking:DefaultBuchungsstapelTemplateNummer. Sind beide 0, wird nicht gebucht – die Transaktionen erhalten die Fehlermeldung „BuchungsstapelTemplateNummer ist weder für '…' noch global konfiguriert"	0
Import per Dateireferenz (ImportByRef)	Der Buchungsstapel wird als XML-Datei auf die WinLine-Server-Freigabe geschrieben und per Verweis importiert. Wirkt nur, wenn Banking:WinLineServerUncPath gesetzt ist – sonst wird das XML direkt im WebService-Aufruf übertragen	ein
Stapel nach Buchungsart gruppieren (GruppierungNachBuchungsart)	Ein: je Buchungsart (KZ, B) ein eigener Stapel mit der Buchungsart im Stapelnamen. Aus: pro Richtung ein gemeinsamer Stapel, benannt nach Bankkonto und Datum. Debitor-Zahlungen (DZ) bilden immer einen eigenen Stapel	aus
Debitor-Buchungsart (DebitorBuchungsart)	Buchungsart für Zahlungseingänge von Kunden und für Vorauszahlungen	DZ
Kreditor-Buchungsart (KreditorBuchungsart)	Buchungsart für Zahlungen an Lieferanten mit OP-Bezug	KZ
Standard-Buchungsart (StandardBuchungsart)	Buchungsart für Kostenbuchungen auf Sachkonten (Regeln, KI-Sachkonto)	B
FIBU-Buchungstext (FibuBuchungstext)	Vorlage für den Buchungstext von Zahlungseingängen (DZ) und – sofern die Buchungsregel keine eigene Vorlage hat – von Kostenbuchungen (B). Leer = globaler Wert Banking:DefaultFibuBuchungstext, danach fester Text Zahlung {{BelegNr}} {{PayerName}}	DZ {{BelegNr}} {{PayerName}}
Buchungstext Kreditor (FibuBuchungstextKreditor)	Vorlage für Kreditor-Einzelzahlungen (KZ). Leer = FIBU-Buchungstext, danach Zahlung {{BelegNr}} {{PayeeName}}	leer
Buchungstext Vorauszahlung (FibuBuchungstextVorauszahlung)	Vorlage für Vorauszahlungen (Debitor per IBAN erkannt, kein passender OP). Leer = globaler Wert Banking:DefaultFibuBuchungstextVorauszahlung, danach FIBU-Buchungstext	leer
Buchungstext Sammel (Debitor) (FibuBuchungstextSammel)	Vorlage für Debitor-Sammelzahlungen (ein Zahlungseingang gleicht mehrere OPs aus). Leer = Banking:DefaultFibuBuchungstextSammel, danach FIBU-Buchungstext	leer
Buchungstext Sammel (Kreditor) (FibuBuchungstextKreditorSammel)	Vorlage für Kreditor-Sammelzahlungen (ein Ausgang begleicht mehrere Kreditor-OPs). Leer = Banking:DefaultFibuBuchungstextKreditorSammel, danach Buchungstext Kreditor bzw. FIBU-Buchungstext	leer

Buchungstexte werden nach dem Ersetzen der Variablen auf 50 Zeichen gekürzt. Verfügbare Variablen: {{BelegNr}}, {{Kontonummer}}, {{PayerName}}, {{PayeeName}}, {{PayerIban}}, {{PayeeIban}}, {{Betrag}}, {{Restbetrag}}, {{Buchungsdatum}}, {{Verwendungszweck}}, {{Month:MM/yyyy}}. Bei Kostenbuchungen hat eine in der Buchungsregel hinterlegte Buchungstext Vorlage Vorrang; bei KI-Sachkonto-Buchungen wird die Begründung der KI als Buchungstext verwendet.

Tab „Zahlungseingänge"

Einstellung	Bedeutung	Standard
Auto-Match-Schwelle (AutoMatchThreshold)	Konfidenz (0,0–1,0), ab der eine Zuordnung als sicher gilt und ohne Rückfrage gebucht wird	0,75
Vorschlag-Schwelle (SuggestMatchThreshold)	Konfidenz, ab der eine Zuordnung als Vorschlag ins Journal geht (Filter-Preset „Handlungsbedarf"). Darunter gilt die Transaktion als nicht zuordenbar	0,40
OP-Datum-Toleranz (Tage) (OpDatumToleranzTage)	Ein offener Posten wird nur zugeordnet, wenn sein Belegdatum höchstens so viele Tage nach dem Zahlungsdatum liegt – eine Zahlung kann so nicht einer erst später erstellten Rechnung zugeordnet werden. Fängt Valuta- und Zeitzonenversatz ab. 0 wird als 3 behandelt	3
Debitor-Konto von / bis (DebitorAccountFrom / DebitorAccountTo)	Kontenbereich, aus dem die offenen Debitoren-Posten für das Matching geladen werden	10000–49999
Vorauszahlung aktiviert (VorauszahlungEnabled)	Zahlungseingang, dessen Absender-IBAN eindeutig zu einem Debitor gehört, zu dem aber kein offener Posten passt: statt „nicht zuordenbar" entsteht eine Vorauszahlungsbuchung (Buchungsart = Debitor-Buchungsart) auf das Kundenkonto ohne OP-Ausgleich – WinLine legt damit einen neuen OP an. Gilt nur bei der Erst-Erkennung einer Transaktion	aus
Vorauszahlung Buchungsart (VorauszahlungBuchungsart)	Buchungsart der Vorauszahlungsbuchung, z.B. VZ. Leer = Debitor-Buchungsart	leer
VZ-Nummernkreis Präfix (VorauszahlungNummernkreisPrefix)	Präfix der OP-Nummer für Vorauszahlungen; die Nummer wird vierstellig angehängt (VZ0001, VZ0002, …)	VZ
VZ-Nächste Nummer (VorauszahlungNaechsteNummer)	Nächste zu vergebende Nummer; zählt automatisch hoch	1

Tab „Kostenbuchungen"

Einstellung	Bedeutung	Standard
Regelbasierte Buchungen (RegelbasiertesBuchenEnabled)	Ausgänge werden gegen die Buchungsregeln des Kontos bzw. Mandanten geprüft und bei Treffer als Kosten- oder Verrechnungsbuchung vorbereitet. Bei Verrechnungskonten (Kreditkarte, PayPal, Sonstige) unabhängig vom Schalter immer aktiv	aus
Rechnungsmuster-Regex (RechnungsmusterRegex)	Regulärer Ausdruck, mit dem Belegnummern im Verwendungszweck erkannt werden (Gruppe 1 = Belegnummer, für Eingänge und Ausgänge). Leer = eingebautes Muster für die Präfixe RE, RG, INV, DR, GS, LI, LS, AB, BE sowie „zwei Buchstaben + mindestens 7 Ziffern". Beispiele: RE\d{9} (nur WinLine-Format RE202600040), (?:RE|RG)\d{6,}. Das Feld Effektives Rechnungsmuster zeigt den tatsächlich verwendeten Ausdruck	leer
Kreditor-OP-Matching aktiviert (KreditorOpMatchingEnabled)	Ausgänge werden gegen offene Kreditoren-Posten abgeglichen (Buchungsart KZ). Ist der Schalter aus und der Verwendungszweck enthält dennoch eine Rechnungsreferenz (RE/RG/INV), wird die Transaktion als „Mögliche Kreditor-Zahlung" auf nicht zuordenbar gesetzt statt als Kosten gebucht zu werden	aus
Kreditor-Konto von / bis (KreditorAccountFrom / KreditorAccountTo)	Kontenbereich, aus dem die offenen Kreditoren-Posten geladen werden	60000–69999
Ausgeglichene-OP-Toleranz (Tage) (AusgeglicheneOpTageToleranz)	Bei KZ-Buchungen mit erkanntem Personenkonto wird so viele Tage rückwirkend nach einem bereits ausgeglichenen OP gesucht; wird er gefunden, gilt die Zahlung als schon verbucht und wird übersprungen (Duplikatschutz, z.B. bei manueller Vorab-Buchung). 0 wird als 7 behandelt	7
Kosten-Buchungsregeln (BuchungsRegeln)	Liste der Buchungsregeln, die auf dieses Konto eingeschränkt sind. Regeln ohne Kontoeinschränkung gelten für alle Konten des Mandanten, siehe Buchungsregeln	–

Tab „KI-Unterstützung"

Sachkonto-Klassifikation (Kostenbuchungen) – greift, wenn keine Buchungsregel passt; Details unter KI-Sachkonto-Klassifikation:

Einstellung	Bedeutung	Standard
KI-Kostenbuchung aktiviert (LlmKostenEnabled)	Schaltet KI-Sachkonto-Vorschläge für Ausgänge ohne Regeltreffer ein. Voraussetzungen: WinLine-Bankkontonummer gesetzt und entweder Sachkonten im Bereich von/bis vorhanden oder eine Whitelist gefüllt	aus
KI Auto-Buchen (≥85%) (LlmKostenAutoBook)	Vorschläge mit Konfidenz ≥ 0,85 werden ohne Bestätigung gebucht. Aus = jeder Vorschlag wartet als „KI-Vorschlag" im Journal auf Bestätigung	aus
Sachkonto von / bis (KI) (SachkontoVon / SachkontosBis)	Kontenbereich im Sachkontenstamm (T055), aus dem die KI wählen darf	3000–6999
Historiezeitraum (Monate) (KostenHistorieMonatE)	So viele Monate Buchungsjournal (T028, Buchungsart B) dienen der KI als Lernbeispiele („Anbieter X wurde 3× auf 6520 gebucht"). 0 wird als 12 behandelt	12
Sachkonten-Whitelist (Fallback) (SachkontenWhitelist)	Manuelle Kontenliste (Komma- oder zeilengetrennt), die nur verwendet wird, wenn aus dem Sachkontenstamm keine Konten geladen werden konnten. Bevorzugt: Bereich von/bis pflegen	leer

Rechnungsnummern-Erkennung (Zahlungseingänge) – letzter Rückfall, wenn Rechnungsmuster und OP-Abgleich keinen Treffer liefern; die KI wählt ausschließlich aus den tatsächlich offenen Belegnummern:

Einstellung	Bedeutung	Standard
KI-Rechnungserkennung (LlmEnabled)	Aktiviert die KI-Erkennung für dieses Konto. Ist der globale Schalter Banking:LlmEnabled gesetzt, ist die Erkennung für alle Konten aktiv, unabhängig vom Kontoschalter	aus
KI-Provider (LlmProviderType)	Anthropic (Claude), OpenAI-kompatibel (IONOS, Ollama, Azure OpenAI, LM Studio, …) oder Global. Nur bei „Global" übernimmt das Konto das Protokoll des Mandanten bzw. der appsettings.json – Neu angelegte Konten stehen auf „Global"; Konten aus älteren Versionen stehen auf „Anthropic" und müssen bei global konfiguriertem OpenAI-kompatiblem Protokoll einmal auf „Global" umgestellt werden	Global
KI-Modell (LlmModel)	Modellkennung, z.B. claude-haiku-4-5-20251001 (Anthropic), meta-llama-3.1-8b-instruct (IONOS), llama3.2 (Ollama). Leer = Mandant → Banking:LlmModel	leer
KI-API Basis-URL (LlmBaseUrl)	Nur für OpenAI-kompatible Anbieter, z.B. https://openai.ionos.com/openai, http://localhost:11434/v1 (Ollama). Leer = Mandant → Banking:LlmBaseUrl. Bei Anthropic ohne Bedeutung	leer
KI-API-Key (LlmApiKey)	Als Kennwort gespeichert; KI-Key Status zeigt, ob ein Key hinterlegt ist. Leer = Mandant → Banking:LlmApiKey → Umgebungsvariable ANTHROPIC_API_KEY bzw. OPENAI_API_KEY	leer

Namens-Matching (Personenkonto-Erkennung) – erkennt Debitor/Kreditor über die Ähnlichkeit des Gegenpartei-Namens, wenn IBAN und Belegnummer nicht weiterhelfen. Unabhängig davon prüft die Zuordnung bei jedem erkannten Partner, ob seine offenen Posten in Summe den Zahlbetrag ergeben (Sammelzahlung ohne Rechnungsnummern im Verwendungszweck); passt die Gesamtsumme nicht, wird eine eindeutige Teilmenge gesucht (bis 16 offene Posten je Partner) – bei mehreren passenden Kombinationen bleibt es bei „Personenkonto erkannt, manuelle Zuordnung":

Einstellung	Bedeutung	Standard
Namens-Matching aktiviert (NameMatchingEnabled)	Unscharfer Namensvergleich gegen die Personenkonten (z.B. „ANTHROPIC SAN FRANCISCO" → „Anthropic, PBC"). Ein Treffer wird als Vorschlag mit reduzierter Konfidenz eingetragen	aus
Mindestscore (0–100) (NameMatchingMinScore)	Ähnlichkeit, ab der ein Name als Treffer gilt; empfohlen 75–85. Niedriger = mehr Treffer, mehr Fehlzuordnungen. 0 wird als 80 behandelt	80
KI-Namensextraktion (Fallback) (NameMatchingLlmFallbackEnabled)	Findet der Namensvergleich nichts, extrahiert die KI den Firmennamen aus dem Verwendungszweck und sucht erneut (z.B. „AMZN" → „Amazon"). Setzt eine aktive KI-Rechnungserkennung voraus (Konto oder global)	aus
Betragstoleranzen (%) (NameMatchingAmountTolerancePct)	Beim anschließenden OP-Abgleich darf der Restbetrag um diesen Prozentsatz vom Zahlbetrag abweichen (Skonto-Puffer). 0 wird als 2 behandelt	2

Tab „Lernmodus"

Siehe Lernmodus.

KI-Anbindung: Auflösung über Konto, Mandant und appsettings.json

Alle KI-Funktionen (Rechnungsnummern-Erkennung, Sachkonto-Klassifikation, Namensextraktion, Lernmodus-Textverfeinerung) verwenden dieselbe Anbindung. Jedes der vier Felder Protokoll, Modell, Basis-URL und API-Key wird einzeln aufgelöst: zuerst das Banking-Konto (Tab „KI-Unterstützung"), dann der Mandant, zuletzt der globale Wert aus appsettings.json (Abschnitt Banking). Beim API-Key folgt als letzte Stufe die Umgebungsvariable ANTHROPIC_API_KEY bzw. OPENAI_API_KEY. So kann z.B. der Key zentral am Mandanten liegen, während ein einzelnes Konto ein anderes Modell verwendet.

Die Mandanten-Standards stehen in der Detailansicht des Mandanten (Navigation → Mandanten):

Einstellung	Bedeutung	Standard
Kontenrahmen (SKR) (Kontenrahmen)	Nicht konfiguriert, SKR03, SKR04 oder Individuell / Branchenkontenrahmen. Bei SKR03/SKR04 erhält die KI-Sachkonto-Klassifikation einen Hinweis auf die Kontenlogik des Rahmens und liefert präzisere Vorschläge	Nicht konfiguriert
KI Provider (LlmProviderType)	Protokoll für alle Konten des Mandanten, die auf „Global" stehen. Steht der Mandant selbst auf „Global", gilt Banking:LlmProviderType. Mandanten aus älteren Versionen stehen auf „Anthropic"	Global
KI Modell (LlmModel)	Modell für Konten ohne eigene Angabe; Empfehlung des Herstellers für deutsche Buchungskonten: claude-sonnet-4-6	leer
KI API-Schlüssel (LlmApiKey)	Schlüssel für Konten ohne eigenen Key (Kennwortfeld)	leer
KI Base-URL (LlmBaseUrl)	Basis-URL für OpenAI-kompatible Anbieter, für Konten ohne eigene Angabe	leer

Globale Einstellungen in appsettings.json (Banking und FinoApi)

Im Container werden die Werte wie üblich als Umgebungsvariablen mit doppeltem Unterstrich gesetzt (z.B. Banking__LlmApiKey, FinoApi__ClientSecret).

{
  "FinoApi": {
    "BaseUrl": "https://api.fino.io",
    "ClientId": "",
    "ClientSecret": "",
    "TokenEndpoint": "/oauth/token"
  },
  "Banking": {
    "DefaultBuchungsstapelTemplateNummer": 0,
    "WinLineServerUncPath": "",
    "DefaultFibuBuchungstext": "DZ {{BelegNr}} {{PayerName}}",
    "LlmEnabled": false,
    "LlmProviderType": "Anthropic",
    "LlmBaseUrl": "",
    "LlmApiKey": "",
    "LlmModel": "claude-haiku-4-5-20251001",
    "LlmMaxTokens": 64,
    "LlmTimeoutSeconds": 300
  }
}

FinoApi – gilt für alle Konten mit Provider fino; pro Konto wird nur die Provider-Konto-ID hinterlegt:

Einstellung	Bedeutung	Standard
BaseUrl	Basisadresse der fino-API; die Transaktionen werden unter /v2/accounts/<Provider-Konto-ID>/transactions abgerufen	https://api.fino.io
ClientId / ClientSecret	OAuth2-Zugangsdaten (Client Credentials) des Unternehmens bei fino. Der Dienst holt damit ein Zugriffstoken und erneuert es automatisch vor Ablauf	leer
TokenEndpoint	Pfad des Token-Endpunkts, wird an BaseUrl angehängt	/oauth/token

Banking – Rückfallwerte, die greifen, wenn das jeweilige Feld am Konto leer bzw. 0 ist:

Einstellung	Wann sie greift	Standard
DefaultBuchungsstapelTemplateNummer	Wenn am Konto Buchungsstapel-Vorlage Nr. = 0. Sind beide 0, wird nicht gebucht (Fehlermeldung im Journal)	0
WinLineServerUncPath	UNC-Pfad der WinLine-Server-Freigabe (z.B. \\SERVER\WinLine). Nur wenn gesetzt, wirkt Import per Dateireferenz; leer = das Stapel-XML wird direkt im WebService-Aufruf übertragen	leer
DefaultFibuBuchungstext	Wenn am Konto FIBU-Buchungstext leer ist (Zahlungseingänge und Kostenbuchungen ohne Regelvorlage)	DZ {{BelegNr}} {{PayerName}}
DefaultFibuBuchungstextVorauszahlung, …Sammel, …KreditorSammel	Wenn am Konto die jeweilige Sonderfall-Vorlage (Vorauszahlung, Debitor-Sammel, Kreditor-Sammel) leer ist	VZ {{PayerName}} {{Buchungsdatum}} / DZ {{PayerName}} Sammel / KZ {{PayeeName}} Sammel
LlmEnabled	true schaltet die KI-Rechnungsnummern-Erkennung für alle Konten ein – auch für solche, deren Kontoschalter aus ist. Zugleich Voraussetzung (alternativ zum Kontoschalter) für die KI-Namensextraktion	false
LlmProviderType	Anthropic oder OpenAiCompatible. Greift nur für Konten und Mandanten, die auf „Global" stehen	Anthropic
LlmBaseUrl, LlmApiKey, LlmModel	Letzte Stufe der Auflösung Konto → Mandant → global (der Key zusätzlich → Umgebungsvariable)	leer / leer / claude-haiku-4-5-20251001
LlmMaxTokens	Höchstlänge der KI-Antwort bei der Rechnungsnummern-Erkennung; 64 reichen für eine Liste von Belegnummern. Nicht am Konto überschreibbar	64
LlmTimeoutSeconds	Zeitlimit je KI-Anfrage in Sekunden. Lokale Modelle (Ollama, LM Studio) brauchen deutlich länger als Cloud-Dienste. Nicht am Konto überschreibbar	300

---

Buchungsketten: Girokonto, AMEX und PayPal

Hinweis: Kontonummern, Namen und Beträge in diesem Abschnitt sind frei gewählte Beispiele zur Veranschaulichung des Verrechnungsprinzips – in der Praxis werden sie durch die tatsächlichen WinLine-Kontonummern und Buchungsregeln des jeweiligen Mandanten ersetzt.

Das System unterstützt mehrstufige Zahlungswege über Verrechnungskonten.

Direkte Bankbuchungen (Girokonto)

Normale Ausgaben direkt vom Girokonto (z.B. Miete, Lohnsteuer, Versicherungen):

Girokonto (WinlineBankkontonummer = 1801):
  -1.637,42 € | PayeeName="Finanzamt" | VZ="LST 12/2025"
  → BuchungsRegel: "Finanzamt" → KontoSoll=3730
  → Buchung: 3730 (LST) / 1801 (Girokonto)  Buchungsart: B

Kreditkarte AMEX (Firmenkonto 1806, Klärungskonto 3631)

Konfiguration:

• BankAccountSettings "AMEX": BankkontoTyp=Kreditkarte, WinlineBankkontonummer=1806
• Alle AMEX-Käufe werden direkt auf das Sachkonto gegen 1806 gebucht
• Monatliche AMEX-Abbuchung vom Girokonto gleicht 1806 auf 0 aus

AMEX-Konto (WinlineBankkontonummer = 1806):
  -129,98 € | PayeeName="Amazon"
  → Regel: "Amazon" → KontoSoll=3631 (sonst. Verr. Amex klären)
  → Buchung: 3631 / 1806   Buchungsart: B
  (oder bei bekanntem Sachkonto direkt: 6300 / 1806)

  -27,00 € | PayeeName="Kreditor XY"
  → KreditorOpMatching → OP "RE-2026-100"
  → Buchung: 70109 / 1806   Buchungsart: KZ

Girokonto (WinlineBankkontonummer = 1801):
  -1.234,56 € | PayeeName="American Express"
  → Regel: "American Express" → KontoSoll=1806
  → Buchung: 1806 / 1801   Buchungsart: B

Ergebnis: Konto 1806 saldiert auf 0 ✓

PayPal (Firmenkonto 1809)

Konfiguration:

• BankAccountSettings "PayPal": BankkontoTyp=PayPal, WinlineBankkontonummer=1809
• PayPal-Käufe werden gegen 1809 gebucht
• PayPal-Auszahlungen ans Girokonto (Eingang auf Girokonto) gleichen 1809 aus

PayPal-Konto (WinlineBankkontonummer = 1809):
  -45,00 € | PayeeName="eBay Seller XY"
  → Regel (catch-all) → KontoSoll=7670
  → Buchung: 7670 / 1809   Buchungsart: B

Girokonto (WinlineBankkontonummer = 1801):
  +200,00 € | PayerName="PayPal"   ← EINGANG auf Girokonto!
  → Eingangs-Regel: PayerName="PayPal", Richtung=Eingang → KontoSoll=1809
  → Buchung: 1809 / 1801   Buchungsart: B

Ergebnis: Konto 1809 saldiert auf 0 ✓

PayPal mit AMEX als Zahlungsmittel (3-stufige Kette)

Wenn PayPal-Käufe über die AMEX-Karte finanziert werden, entstehen in GMI zwei Transaktionen für einen Kauf — eine auf PayPal, eine auf AMEX. Die Brückenregel auf dem AMEX-Konto verbindet beide Konten:

PayPal-Konto (WinlineBankkontonummer = 1809):
  -45,00 € | PayeeName="eBay Seller"
  → Regel → KontoSoll=7670
  → Buchung: 7670 / 1809   ← Aufwand HIER buchen

AMEX-Konto (WinlineBankkontonummer = 1806):
  -45,00 € | PayeeName="PAYPAL *eBay Seller"
  → Brückenregel: PayeeName enthält "PayPal" → KontoSoll=1809
  → Buchung: 1809 / 1806   ← PayPal-VC gegen AMEX-VC

Girokonto (WinlineBankkontonummer = 1801):
  -xxx € | PayeeName="American Express"
  → Regel → KontoSoll=1806
  → Buchung: 1806 / 1801   ← AMEX-VC gegen Girokonto

Ergebnis: 1809 = 0 ✓   1806 = 0 ✓   Aufwand 7670 korrekt belastet ✓

---

Buchungsregeln (BuchungsRegel)

Regeln erkennen Ausgangstransaktionen anhand von:

• EmpfaengerIban: exakter IBAN-Vergleich (Ausgänge: PayeeIban; Eingänge: PayerIban)

• EmpfaengerNameFilter: Name enthält Text (Regex möglich)

• BetragVon / BetragBis: Betrag-Bereich (absolut)

• VerwendungszweckFilter: alle Suchbegriffe (durch Leerzeichen getrennt) müssen im Verwendungszweck vorkommen – Lohn Gehalt trifft nur, wenn beide Wörter enthalten sind (Groß-/Kleinschreibung wird ignoriert)

Alle gesetzten Merkmale müssen gemeinsam zutreffen (UND-Verknüpfung); mindestens eines ist Pflicht. Der Namensfilter vergleicht als „enthält", mit dem Kennzeichen Name als Regex (EmpfaengerNameAlsRegex) als regulärer Ausdruck.

Buchungsrichtung steuert wann eine Regel greift:

• Ausgang: normale Buchungsregel (Amount < 0)
• Eingang: Verrechnungsbuchung (Amount > 0), z.B. PayPal-Auszahlung ans Girokonto
• Beide: richtungsunabhängig

Buchungsziel und weitere Felder

Eine Regel hat genau ein Buchungsziel: ein Gegenkonto (Sachkonto), ein Personenkonto oder Split-Zeilen (siehe Splitbuchungen) – nicht mehrere zugleich, nicht keines; das Speichern prüft das.

Feld	Bedeutung	Standard
Bezeichnung (Bezeichnung)	Name der Regel, z.B. „Monatsmiete Büro Wien"; erscheint als {{Regelbezeichnung}} in Buchungstexten. Pflichtfeld	–
Aktiv (Aktiv)	Inaktive Regeln werden ignoriert und in der Liste grau dargestellt	ein
Priorität (Prioritaet)	0–99, aufsteigend: bei mehreren treffenden Regeln gewinnt die niedrigste Zahl. Empfehlung: manuelle Regeln 10–30, automatisch erzeugte 50, Auffangregeln (z.B. „Ungeklärt") 99	0
Gegenkonto (Gegenkonto)	Sachkonto der Buchung. Ausgang: Soll = Gegenkonto, Haben = Bankkonto (z.B. 4100 Löhne, 6520 Versicherungen). Eingang: Soll = Bankkonto, Haben = Gegenkonto (z.B. 1540 Forderungen Finanzamt). Auch Verrechnungskonten wie 1806 (AMEX) oder 1809 (PayPal)	leer
Personenkonto (PersonenkontoNummer)	Alternative zum Gegenkonto: Debitor/Kreditor-Konto. Ausgang → KZ auf den Kreditor, Eingang → DZ auf den Debitor – für wiederkehrende Zahlungen ohne erkennbare Belegnummer	leer
Personenkonto-Buchung erlauben (ErlaubePersonenkontoBuchung)	Lässt die Sachkonto-Buchung (B) auf das Gegenkonto auch dann zu, wenn die Gegenpartei als Debitor/Kreditor erkannt wurde. Nur für Sonderfälle, z.B. Bankgebühren, die über ein Lieferantenkonto laufen	aus
Buchungsart (Buchungsart)	WinLine-Buchungsart. Leer = automatisch: B bei Gegenkonto, KZ/DZ bei Personenkonto	leer
Steuerzeile (Steuerzeile)	1 = WinLine leitet Steuer/Vorsteuer aus der Sachkonto-Einstellung ab (auch für steuerfreie Konten); 0 = keine Steuerzeile im Buchungssatz. Für Verrechnungsbuchungen (PayPal ↔ AMEX ↔ Bank) immer 1	1
OP-Nummer Vorlage (OpNummerTemplate)	Text für das OP-Nummern-Feld der Buchung, z.B. {{Month:MM/yyyy}} → 01/2026. Leer = Name der Gegenpartei	leer
Buchungstext Vorlage (BuchungstextTemplate)	Buchungstext dieser Regel; hat Vorrang vor dem FIBU-Buchungstext des Kontos. Variablen: {{PayeeName}}, {{PayerName}}, {{PayeeIban}}, {{PayerIban}}, {{Verwendungszweck}}, {{Month:MM/yyyy}}, {{Betrag}}, {{Buchungsdatum}}, {{Regelbezeichnung}}; nach dem Ersetzen auf 50 Zeichen gekürzt	leer
Mandant (Company)	Mandant, für den die Regel gilt. Pflichtfeld	–
Bankkonto (optional) (BankAccountSettings)	Schränkt die Regel auf ein Banking-Konto ein – nötig für die Brückenregeln der Buchungsketten. Leer = gilt für alle Konten des Mandanten	leer
Automatisch erzeugt (IsAutoGenerated)	Kennzeichnet Regeln, die der Job selbst anlegt, sobald eine per KI-Sachkonto oder Namens-Matching zugeordnete Transaktion erfolgreich gebucht wurde (Bezeichnung „Auto: …", Priorität 50, je Gegenpartei höchstens eine Regel), sowie Regeln aus angenommenen Lernmodus-Vorschlägen. Filter-Preset „KI-generiert"; können wie manuelle Regeln bearbeitet oder deaktiviert werden	aus

Empfohlene Regeln für typische Betriebe (Österreich/Deutschland):

Konto	Bezeichnung	Filter	KontoSoll	Richtung
Girokonto	LST/Lohnsteuer	Name: Finanzamt	3730	Ausgang
Girokonto	SV-Beiträge	Name: Österr. Gesundheitskasse / GKK	3631	Ausgang
Girokonto	Versicherung allg.	Name: Versicherung	6520	Ausgang
Girokonto	AMEX-Abrechnung	Name: American Express	1806	Ausgang
Girokonto	PayPal-Auszahlung	Name: PayPal, Richtung=Eingang	1809	Eingang
AMEX	Amazon	Name: Amazon	3631	Ausgang
AMEX	Kreditor XY	IBAN: DE… oder Name: Kreditor XY	(via KZ)	Ausgang
AMEX	PayPal-Brücke	Name: PayPal	1809	Ausgang
AMEX	Ungeklärt (Fallback)	BetragVon: 0,01, Prio=999	3631	Ausgang
PayPal	Sonstiges	BetragVon: 0,01, Prio=999	7670	Ausgang

---

Splitbuchungen

Für Transaktionen mit mehreren Buchungspositionen (z.B. Darlehens-Leistungen mit Tilgung + Zinsen) können Buchungsregeln Split-Zeilen definieren. Jede Split-Zeile hat ein eigenes Gegenkonto, Steuerzeile und Buchungstext.

Betrags-Ermittlung pro Split-Zeile:

• Regex: Betrag per regulärem Ausdruck aus dem Verwendungszweck extrahieren (z.B. Tilgung\s+([\d.,]+))
• Fest: Fester Betrag
• Prozent: Prozentwert vom Gesamtbetrag
• Rest: Differenz zum Gesamtbetrag (letzte Zeile)
• LLM-Fallback: Wenn Regex fehlschlägt, extrahiert die KI die Teilbeträge

Beispiel Darlehen:

• Verwendungszweck: „Darl.-Leistung 6130402974 ... Tilgung 58,91 Zinsen 121,09"
• Split 1: Gegenkonto 0940 (Darlehen), Betrag per Regex „Tilgung", Steuerzeile 0
• Split 2: Gegenkonto 7320 (Zinsaufwand), Betrag per Regex „Zinsen", Steuerzeile 1
• WinLine: 3 T331-Zeilen (1× Gegenbuchung Bank + 2× Sachkonto-Splits)

---

KI-Sachkonto-Klassifikation (optional)

Wenn keine Regel greift, kann das LLM (Claude Haiku, IONOS, Ollama, lokal) das Sachkonto vorschlagen:

1. T055 (Sachkontenstamm): Alle Sachkonten im konfigurierten Bereich (z.B. 3000–6999) mit ihren Bezeichnungen werden dem LLM als Auswahlmenge übergeben.
2. T028 (Buchungshistorie): Die häufigsten B-Buchungen der letzten 12 Monate dienen als Few-Shot-Lernbeispiele — "VHV Versicherung wurde 3× auf 6520 gebucht".
3. Konfidenz-Schwellen:
   • ≥ 0,85 + KI Auto-Buchen (LlmKostenAutoBook): direkt buchen
   • 0,60–0,84: KiSachkontoVorschlag — manuelle Bestätigung im Journal
   • < 0,60: kein Vorschlag (sicheres Schweigen)

Voraussetzungen und Steuerung liegen im Tab KI-Unterstützung des Banking-Kontos (Schalter KI-Kostenbuchung aktiviert, Kontenbereich, Historiezeitraum, Whitelist) – die Klassifikation läuft nur, wenn am Konto die WinLine-Bankkontonummer gesetzt ist. Ist am Mandanten ein Kontenrahmen (SKR03/SKR04) hinterlegt, erhält die KI zusätzlich einen Hinweis auf dessen Kontenlogik. Welcher KI-Dienst antwortet, regelt die Auflösung Konto → Mandant → appsettings.json, siehe KI-Anbindung. Sobald eine per KI zugeordnete Transaktion gebucht ist (automatisch oder nach Bestätigung im Journal), legt der Job für dieselbe Gegenpartei eine automatisch erzeugte Buchungsregel an (Priorität 50), damit der Fall künftig ohne KI gebucht wird.

---

Filter-Presets im Transaktionsjournal

Die Transaktionsliste bietet vordefinierte Filter-Presets im SetFilter-Dropdown der Toolbar. Damit lassen sich typische Geschäftsvorfälle mit einem Klick filtern:

Preset	Beschreibung
Offene Vorgänge (Standard)	Alle nicht abgeschlossenen Transaktionen (ohne gebuchte/ausgeglichene)
Alle Transaktionen	Kein Filter — zeigt alle Einträge
Zahlungseingänge	Nur eingehende Zahlungen (positiver Betrag)
Zahlungsausgänge	Nur ausgehende Zahlungen (negativer Betrag)
Handlungsbedarf	Vorschläge, nicht zuordenbare Transaktionen und Fehler
Automatisch zugeordnet	Durch Regel, IBAN oder Name erkannte Transaktionen
Gebucht	Erfolgreich in WinLine gebuchte Transaktionen
Fehler	Transaktionen mit Fehlermeldung
KI-Vorschläge	Sachkonto-Vorschläge der KI zur manuellen Prüfung
Freigabe ausstehend	Zur FIBU-Buchung freigegebene, noch nicht verarbeitete Transaktionen
Vorauszahlungen	Als Vorauszahlung erkannte Eingänge

Tipp: Der Standardfilter „Offene Vorgänge" zeigt nur handlungsrelevante Transaktionen. Über „Alle Transaktionen" können auch bereits gebuchte Einträge eingesehen werden.

---

Lernmodus

Funktion: Lernt aus manuell in der WinLine gebuchten Transaktionen automatisch Buchungsregel-Vorschläge – auch als Nachbesserung: Hat das System eine falsche Regel oder einen falschen KI-Sachkonto-Vorschlag gemacht und die Buchhaltung stattdessen von Hand richtig gebucht, erkennt der Lernmodus das Muster und schlägt eine Korrektur vor (die betroffene Regel anpassen bzw. den KI-Pfad künftig übersteuern).

Aktivierung: Banking-Konten → Tab „Lernmodus" → Aktiviert. Je Konto lassen sich drei Schwellwerte einstellen:

Schwellwert	Standard	Bedeutung
Mindestanzahl	3	Mindestzahl gleichartiger Buchungen, bevor ein Vorschlag entsteht
Konsistenz %	90	Mindestanteil der Buchungen eines Musters, die auf dasselbe Konto gebucht sein müssen – uneinheitliche Muster erzeugen keinen Vorschlag
Datums-Toleranz (Tage)	5	Toleranz zwischen Bank-Buchungsdatum und WinLine-Buchungsdatum bei der Zuordnung

Ist am Konto die KI-Rechnungserkennung aktiviert, verfeinert die KI zusätzlich die Texte der Vorschläge: eine sprechende Bezeichnung (z.B. „Miete Büro – Hausverwaltung Müller" statt „Gelernt: Hausverwaltung Müller → 6310") und stabilere Verwendungszweck-Suchbegriffe. Ein KI-Suchbegriff wird nur übernommen, wenn er auf allen gelernten Belegen tatsächlich zutrifft; ohne KI-Konfiguration oder bei Fehlern bleiben die automatisch abgeleiteten Texte – Vorschläge entstehen immer.

Bei Verrechnungskonten (Kreditkarte, PayPal, Sonstige) gilt automatisch eine Datums-Toleranz von mindestens 45 Tagen: dort liegen manuelle Buchung und Kontoumsatz regelmäßig weit auseinander (der Beleg wird bei Rechnungseingang gebucht, der Umsatz erscheint erst zur Monatsabrechnung – oder umgekehrt). Finden sich dadurch mehrere gleich hohe Buchungen im Fenster, wird trotzdem gelernt, sofern alle auf dasselbe Konto gebucht sind – typisch bei Abo-Zahlungen desselben Anbieters; nur bei widersprüchlichen Zielkonten wird der Fall verworfen.

Vorschläge erscheinen unter Banking → Buchungsregel-Vorschläge, standardmäßig gefiltert auf „Offene Vorschläge" (weitere Filter-Presets: Korrekturen, Angenommen, Abgelehnt, Alle). Erkennt der Lernmodus im selben Lauf mehrere Muster derselben Gegenpartei mit unterschiedlichen Zielkonten (z.B. Finanzamt: Umsatzsteuer- und Lohnsteuerzahlungen), steht in der Begründung des Vorschlags ein entsprechender Warnhinweis – ebenso, wenn eine Regel-Korrektur eine Regel betrifft, die im selben Zeitraum auch korrekt gebucht hat. Je Vorschlag stehen zwei Aktionen zur Verfügung:

• Annehmen legt eine neue Buchungsregel an oder passt bei einer Regel-Korrektur die bestehende Regel an. KI-Korrekturen legen ebenfalls eine neue Regel an, um den KI-Vorschlag künftig zu übersteuern
• Ablehnen markiert das Muster als abgelehnt – es wird nicht erneut vorgeschlagen

Die Aktion „Historie analysieren" an einem Bankkonto öffnet einen Dialog mit den optionalen Feldern „Zeitraum von" / „Zeitraum bis": bleiben beide leer, analysiert der Lauf alle noch ungeprüften Transaktionen dieses Kontos; mit gesetztem Zeitraum (z.B. für eine rückwirkende Nachanalyse eines bestimmten Quartals) wird auch bereits geprüftes Material im gewählten Zeitraum erneut analysiert. Für die Automatisierung steht derselbe Aufruf auch als HTTP-Endpoint POST /banking/lernmodus mit SettingsOid, Von und Bis zur Verfügung.

---

Berichte

Funktion: Eigene Berichte auf WinLine-Daten – im Report-Designer entworfen, von Hand oder zeitgesteuert ausgeführt und in eine Dateiablage geschrieben

Ausführung: Von Hand jederzeit aus der Berichtsliste. Zeitgesteuert prüft der Dienst alle 5 Minuten, ob ein Auftrag fällig ist (konfigurierbar über Quartz__ReportWorkerJob__scheduler); im Standard abgeschaltet. Beides setzt das lizenzierte Modul Berichtswesen voraus

Funktionsweise:

Das Berichtswesen besteht aus drei Bausteinen, die getrennt gepflegt und einzeln wiederverwendet werden. Alle drei liegen im Navigationsbereich Berichte:

Baustein	Beantwortet die Frage	Wiederverwendung
Berichts-Datenquelle	Welche Daten werden geladen?	über beliebig viele Berichte
Bericht	Wie sehen die Daten aus, in welchem Kontext laufen sie?	über beliebig viele Aufträge
Berichtsauftrag	Wann läuft der Bericht, und wohin geht das Ergebnis?	–

Die Reihenfolge beim Einrichten ist dieselbe: erst die Datenquelle, dann den Bericht mit seinem Layout, zuletzt – falls der Bericht ohne Zutun laufen soll – den Auftrag.

Berichts-Datenquelle

Eine Datenquelle beschreibt, welche Daten geladen werden. Sie besteht aus einer oder mehreren Abfragen und deren Beziehungen untereinander. Jede Abfrage wird im Bericht zu einer Tabelle mit dem eingetragenen Tabellennamen; die Abfrage mit dem kleinsten Index ist die Hauptabfrage. Nur Datenquellen mit gesetztem Kennzeichen Aktiv stehen im Bericht zur Auswahl – so lässt sich eine Datenquelle überarbeiten, ohne dass sie versehentlich verwendet wird.

Jede Abfrage hat eine Zeilenobergrenze (Standard 10.000). Sie schützt vor versehentlichen Vollabzügen: Wird sie erreicht, bricht die Abfrage nicht ab, sondern liefert nur so viele Zeilen – der Bericht ist dann stillschweigend gekürzt und lediglich das Protokoll vermerkt es. Wer vollständige Auswertungen braucht, setzt die Grenze bewusst herauf.

Die vier Arten von Abfragen:

1. MesoXPO-Entität – der Regelfall. Sie geben den Entitätstyp an (z.B. MesoXPO.Models.Ansprechpartner), wählen die Spalten und können einen XPO-Vorfilter setzen, z.B. [Vertreter] = 7. Die MESOSAFE-Filterung des WinLine-Benutzers greift hier automatisch
2. Freie Abfrage – eine lesende SELECT-Abfrage, wahlweise gegen die Mandanten-, System-, Archiv- oder BI-Datenbank. Für Auswertungen, die sich mit Entitäten nicht oder nur umständlich abbilden lassen. Platzhalter werden als gebundene SQL-Parameter eingesetzt und nicht in den Abfragetext kopiert
3. WinLine PowerReport – greift eine in WinLine gepflegte PowerReport-Datenquelle ab. Der bequemste Weg ist die Schaltfläche Datenquelle wählen: sie zeigt alle in WinLine vorhandenen Datenquellen und übernimmt Name, Application, Mandant, Benutzer, Filter und Selektionen in einem Zug. Von Hand genügt der Name der Datenquelle; alle übrigen Angaben grenzen nur ein, falls es mehrere gleichnamige gibt. Der Name der BI-Datenbank ist mit CWLBI vorbelegt
4. WinLine LIST-Definition – wertet eine in WinLine angelegte Liste über ihre Listennummer aus. Zwei Wege stehen zur Wahl: SQL aus der Listendefinition erzeugen (empfohlen) baut das SQL direkt aus der Listendefinition – ohne dass dafür etwas in WinLine vorbereitet sein muss – und berücksichtigt die CRM-Leserechte der Liste (T174), wenn der Berichtslauf einen WinLine-Benutzer trägt; Spalten, die sich nicht abbilden lassen, werden übersprungen und im Protokoll benannt. Listenarten, deren Aufbau noch nicht belegt ist, sowie nicht übersetzbare Filter oder Selektionen lehnt der Bericht mit einer klaren Fehlermeldung ab, statt ein falsches Ergebnis zu liefern. Die verknüpfte BI-Datenquelle ist vorberechnet und damit schneller, muss aber zuvor in WinLine erzeugt worden sein

Wichtig zur MESOSAFE-Filterung: Nur Abfragen der Art MesoXPO-Entität werden nach den Zeilenschutzprofilen des WinLine-Benutzers gefiltert. Freie Abfragen, PowerReport- und LIST-Definitionen liefern das, was ihre jeweilige Definition hergibt – wer den Zeilenschutz auch dort braucht, muss ihn in der Abfrage selbst abbilden.

Die richtigen Angaben zu einer PowerReport-Datenquelle finden:

In WinLine stehen sie unter WinLine BI → Verwaltung und Administration → Datenquellenverwaltung, Register „Datenquellen" (aus dem Power Report heraus: Hauptmenü → Datenquellen verwalten). Die dortigen Spalten entsprechen den Feldern der Abfrage: Bezeichnung ist der Datenquellenname, Typ nennt den Benutzer („Öffentlich" entspricht -1, die Zahl hinter „Privat" ist die Benutzernummer), dazu Mandant, Filter und Selektion 1 bis 4. Einige Spalten sind optional und erst über die rechte Maustaste einzublenden.

Nur die Application ist dort nirgends ablesbar – sie steckt in der Definition der Datenquelle und benennt die WinLine-Anwendung, aus der die Datenquelle erzeugt wurde (z.B. FIBU, FAKT, LIST, INFO, START, KORE). Zwei naheliegende Stellen führen in die Irre:

• Das Präfix der Spalte „ID" (LIST_, PR_, FORM_, T…) bezeichnet die Art der Datenquelle, nicht die Application – eine Datenquelle mit der ID LIST_40126 kann durchaus die Application INFO haben.
• Die Typen-Liste links gruppiert nach derselben Art (Anwendung, Enterprise Cube, List, FORM) und innerhalb von „List" nach der Listenart – LIST_40126 steht deshalb unter List → Projekterfassung, obwohl seine Application INFO lautet.

Deshalb darf das Feld leer bleiben – dann wird die Application beim Lauf selbst ermittelt – und deshalb gibt es Datenquelle wählen.

Umgekehrt gibt es zwei Angaben, die genau so aussehen wie in WinLine und deshalb von Hand nachvollziehbar sind: die Kennung (der Wert der Spalte „ID") und der Benutzername. Die Kennung wird beim Auswählen mitgesetzt und ist mehr als Zierde – sie trennt Fälle, die sonst nicht unterscheidbar sind: dieselbe Auswertung als Snapshot (LIST_39388) und als View (VDQ1_LIST_39388) hat denselben Namen, dieselbe Application, denselben Mandanten und denselben Benutzer – erst die Kennung macht daraus eine eindeutige Angabe. Eine Abfrage kann statt des Namens auch nur über die Kennung bestimmt werden.

Gibt es mehrere Datenquellen desselben Namens, gewinnt die zuletzt aktualisierte. Wer eine bestimmte davon braucht, grenzt mit Mandant, Benutzer, Filter oder Selektion ein – oder wählt sie über den Dialog aus, der alle Angaben zusammen übernimmt.

Jede Abfrage hat ein Feld Validierungshinweis, das offene Probleme der Definition benennt. Solange dort etwas steht, lässt sich die Datenquelle nicht speichern – ein unvollständig eingerichteter Bericht fällt damit beim Einrichten auf und nicht erst im nächtlichen Lauf.

Platzhalter in Abfragen und Filtern:

In SQL-Abfragen und XPO-Vorfiltern sind Platzhalter erlaubt. Ihre Werte ergeben sich aus dem Kontext des jeweiligen Laufs, nicht aus der Datenquelle:

{{Mandant}}, {{Wirtschaftsjahr}}, {{Benutzer.Nummer}}, {{Benutzer.Name}}, {{Benutzer.Mail}}, {{Benutzer.Vertreter}}, {{Heute}}, {{Monatsanfang}}, {{Monatsende}}, {{Vormonat.Anfang}}, {{Vormonat.Ende}}, {{Jahresanfang}}

Sie werden als gebundene Parameter eingesetzt und nicht in den Abfragetext kopiert – ein Benutzername mit Apostroph zerlegt die Abfrage also nicht. Am Berichtsauftrag gesetzte Parameter haben Vorrang vor dem gleichnamigen Standard-Platzhalter, siehe Berichtsaufträge.

Spalten wählen:

Die zu ladenden Spalten stehen im Feld Spalten, eine je Zeile. Navigationspfade über Verweise sind erlaubt, z.B. Personenkonto.Name. Drei Wege führen zum Ziel:

• Tippen mit Vorschlägen: Während der Eingabe erscheinen die Eigenschaften des gewählten Entitätstyps mit technischem Pfad und Anzeigename. Die Auswahl einer Verweiseigenschaft (gekennzeichnet mit ›) führt in die nächste Ebene
• Aktion „Spalten wählen": Öffnet den vollständigen Eigenschaftsbaum der Entität zum Ankreuzen. Übernehmen ersetzt den Inhalt des Feldes durch die Auswahl
• Von Hand eintragen: Pfade, die der Baum nicht kennt – etwa berechnete Eigenschaften – bleiben erhalten. Sie werden im Feld dezent gekennzeichnet und beim Übernehmen hinten angehängt, statt stillschweigend gelöscht zu werden

Master-Detail-Beziehungen:

Sollen im Bericht Detailzeilen unter ihrem Kopfdatensatz erscheinen (z.B. Belegzeilen unter dem Belegkopf), verbindet eine Beziehung zwei Abfragen derselben Datenquelle:

• Der Beziehungsname ist der Name, unter dem der Detailbereich im Report-Designer gebunden wird
• Die Spaltenpaare stellen die Verknüpfung her. WinLine-Schlüssel sind meist mehrspaltig, entsprechend viele Paare sind nötig
• Die Detailabfrage muss einen größeren Index als die Masterabfrage haben. Andernfalls greift der Schlüsselfilter nicht, und die Detailabfrage lädt still alles bis zur Zeilenobergrenze
• Der Schlüsselfilter (Kennzeichen „Nur Zeilen zu geladenen Schlüsseln") lädt nur die Detailzeilen zu den tatsächlich geladenen Kopfdatensätzen. Nur ausschalten, wenn die Detailmenge ohnehin klein ist
• Am schnellsten geht es über den Spaltenbaum: Eine Sammlung wird dort per Als Detailabfrage anlegen zur zweiten Abfrage samt Beziehung. Spaltenpaare und Vorfilter werden aus der Sammlung hergeleitet und vor dem Anlegen zur Bestätigung gezeigt; die beteiligten Spalten kommen automatisch in beide Abfragen
• Beim Speichern wird geprüft, ob jede Beziehungsspalte auch in der Spaltenliste ihrer Abfrage steht. Fehlt eine, meldet das Speichern den Fehler; Details stehen an der Beziehung im Feld Validierungshinweis

Bericht

Ein Bericht verbindet eine Datenquelle mit einem Layout und legt fest, in welchem Kontext er ausgewertet wird. Neuer Bericht legt einen leeren Bericht an und öffnet ihn.

1. Zuordnung und Kontext

   • Datenquelle: eine der aktiven Datenquellen
   • Kontext: „Ein Mandant" oder „Mandantenübergreifend". Bei mandantenübergreifenden Berichten entsteht später eine gemeinsame Ausgabe über alle beteiligten Mandanten statt einer je Mandant. Welche Mandanten das sind, wird erst beim Ausführen bzw. am Auftrag festgelegt
   • Wirtschaftsjahr: „Aktuelles Wirtschaftsjahr" des Mandanten, ein „Festes Wirtschaftsjahr" oder „Jahresübergreifend". Das feste Jahr wird im WinLine-Format angegeben – Monate seit dem 01.01.1900, z.B. 1512
   • Kategorie und Beschreibung sind frei und dienen nur der Übersichtsliste

2. Vorschau-Kontext

   • Vorschau-Mandant und Vorschau-Benutzernummer gelten für den Designer und die Schnellvorschau. Auch ein mandantenübergreifender Bericht braucht hier genau einen Mandanten – das Schema ist dasselbe, nur die Zeilenmenge unterscheidet sich
   • Benutzernummer 0 bedeutet: ohne Benutzerkontext, also ohne MESOSAFE-Filterung. Das setzt die Berechtigung Report ohne Benutzerkontext ausführen (MesoReport.ExecuteWithoutUserContext) voraus, weil sonst jeder, der Berichte bauen darf, den Zeilenschutz umgehen könnte

3. Layout im Report-Designer

   • Die Feldliste zeigt die Tabellen der Datenquelle. Detailtabellen stehen verschachtelt unter ihrer Mastertabelle, sodass Detailbereich einfügen die Beziehung direkt anbietet
   • Ist die Feldliste unvollständig – etwa weil eine Beziehung auf fehlende Spalten verweist oder der Schema-Aufbau scheitert –, meldet der Designer das beim Öffnen sichtbar. Der Designer öffnet trotzdem, damit ein vorhandenes Layout gerettet werden kann
   • Ein von Hand eingefügter Detailbereich, der ausschließlich Felder einer Master-Detail-Beziehung zeigt, wird automatisch an diese Beziehung gebunden

4. Ausführen und Exportieren

   • Ausführen fragt Mandant, WinLine-Benutzernummer und Wirtschaftsjahr ab – vorbelegt aus dem Bericht – und zeigt das Ergebnis. Bei mandantenübergreifenden Berichten können weitere Mandantennummern kommagetrennt ergänzt werden, z.B. 600M,700M
   • Exportieren als rendert den Bericht im gewählten Format: PDF, Excel (XLSX/XLS), Word, Rich Text, CSV, Text, HTML, Web-Archiv, XPS sowie PNG, JPEG und TIFF
   • Mit Benutzerkontext enthält der Bericht nur die Daten, die dieser WinLine-Benutzer sehen darf

Berichtsaufträge

Ein Berichtsauftrag führt einen Bericht ohne Zutun aus und legt das Ergebnis ab. Ein neu angelegter Auftrag ist zunächst nicht aktiv – erst Mandanten und Ausgabeziele einrichten, dann bewusst scharfschalten.

1. Zeitplan

   • Täglich, wöchentlich oder monatlich zu einer festen Uhrzeit, oder über einen freien Cron-Ausdruck
   • Die Uhrzeit gilt in der am Auftrag eingestellten Zeitzone und bleibt über die Sommerzeitumstellung erhalten – 7:00 Uhr bleibt 7:00 Uhr
   • Bei monatlichem Turnus bedeutet der Tag 31 „letzter Tag des Monats", im Februar also der 28. oder 29.
   • War der Dienst mehrere Termine lang nicht erreichbar, läuft der Bericht einmal nach und nicht für jeden ausgefallenen Termin – die Zahl der ausgefallenen Termine steht am Journaleintrag
   • Über Jetzt einmalig ausführen läuft ein Auftrag beim nächsten Durchlauf des Dienstes, unabhängig vom Zeitplan und auch dann, wenn er nicht aktiv ist. Der Dienst setzt das Kennzeichen danach selbst zurück

2. Mandanten und Benutzerkontext

   • Ein Auftrag kann mehrere Mandanten enthalten. Je nach Einstellung des Berichts entsteht je Mandant eine eigene Ausgabe oder eine gemeinsame, mandantenübergreifende Ausgabe über alle
   • Ohne Benutzerkontext läuft der Bericht ungefiltert – dafür ist die Berechtigung MesoReport.ExecuteWithoutUserContext erforderlich. Mit Benutzerkontext greift die MESOSAFE-Filterung des jeweiligen WinLine-Benutzers, der Bericht enthält also nur die Daten, die dieser Benutzer sehen darf
   • Die Benutzer werden einzeln benannt, als Liste geführt oder über einen Filter auf den Benutzerstamm bestimmt, zum Beispiel [Vertreter] > 0 für alle Vertreter. Je Benutzer entsteht eine eigene Ausgabe
   • Jeder eingetragene Benutzer braucht eine Benutzernummer größer 0. Lässt sich zu einer Ausgabe kein Benutzerkontext ermitteln, wird sie nicht ausgeführt und im Journal als fehlgeschlagen protokolliert – ein Lauf ohne Kontext wäre der ungefilterte Vollzugriff, der eine eigene Berechtigung voraussetzt
   • Es muss mindestens ein Mandant hinterlegt sein. Entsteht aus Mandanten, Benutzern und Zielen keine einzige Ausgabe, meldet der Auftrag das mit Grund im Journal und in „Letzter Lauf"

3. Ausgabeziele

   • Je Auftrag beliebig viele, in der Reihenfolge ihres Index. Das Ausgabeformat gehört zum Ziel – derselbe Bericht kann so gleichzeitig als PDF in eine Ablage und als XLSX in eine andere gehen

   • Zur Verfügung stehen alle von XtraReports unterstützten Formate. Als Art des Ziels stehen Dateiablage, E-Mail und CRM-Workflow zur Wahl

   • Platzhalter sind nicht nur im Dateinamensmuster und im Zielverzeichnis erlaubt, sondern in jedem Feld, das Platzhalter unterstützt – also auch in den Empfängerfeldern, Betreff und Text eines E-Mail-Ziels sowie in den Fall-Feld-Werten eines CRM-Workflow-Ziels. Zur Verfügung stehen unter anderem {{Bericht}}, {{Auftrag}}, {{Mandant}}, {{Benutzer.Name}}, {{Benutzer.Nummer}}, {{Heute}} und {{Monatsanfang}}. Die Dateiendung ergibt sich aus dem Format. Eine vorhandene Datei wird überschrieben – wer Läufe trennen will, nimmt {{Heute:dd.MM.yyyy}} in das Muster

   • Jeder Platzhalter versteht optional ein Format sowie Präfix und Suffix: {{Heute:yyyy-MM}} liefert 2026-08, {{Mandant|prefix=[|suffix=]}} liefert [500M] – Präfix und Suffix entfallen, wenn der Wert leer ist. Formatiert wird immer nach deutscher Schreibweise, unabhängig von der Ländereinstellung des Servers; die vollständige Syntax steht unter Formatangaben für Platzhalter. Ohne Formatangabe zeigt {{Heute}} Datum und Uhrzeit (z.B. „17.08.2026 00:00:00") – das enthält Doppelpunkte und eignet sich deshalb nicht für Verzeichnis oder Dateiname. Dort und überall sonst, wo nur das Datum gemeint ist, empfiehlt sich {{Heute:dd.MM.yyyy}}

   • Ein unbekannter oder falsch geschriebener Platzhalter bleibt wörtlich im Text stehen, statt kommentarlos zu Leere zu werden – ein Tippfehler fällt so auf, statt einen Wert stillschweigend verschwinden zu lassen. In einem Fall-Feld landet der Platzhaltertext dann unverändert im Feld; in einem Zahlen- oder Datumsfeld lässt er die Ausgabe mit sprechendem Grund fehlschlagen

   • Das voreingestellte Muster lautet {{Bericht}}_{{Mandant}}_{{Benutzer.Name}}_{{Heute:dd.MM.yyyy}} – mit Formatangabe, damit im Dateinamen nur das Datum und nicht auch die Uhrzeit mit ihren Doppelpunkten steht. Läuft der Auftrag für mehrere Benutzer, muss das Muster {{Benutzer.Name}} oder {{Benutzer.Nummer}} enthalten – sonst schreiben alle Benutzer nacheinander auf denselben Pfad und übrig bleibt die Sicht des letzten. Das Speichern weist ein Muster ohne Benutzer in diesem Fall zurück. Leer bleibende Platzhalter hinterlassen keine doppelten Trennzeichen im Dateinamen

   • Liefert der Bericht keine Zeilen, wird die Ausgabe übersprungen und im Journal begründet. Mit „Auch bei leerem Ergebnis ausgeben" entsteht die Ausgabe trotzdem

   • Das Zielverzeichnis einer Dateiablage muss aus Sicht des Dienstkontos erreichbar sein, nicht aus Sicht des Anwenders

   • Zeichensatz der Textformate: Text- und CSV-Ausgaben werden immer in UTF-8 geschrieben, unabhängig davon, ob der Dienst unter Windows oder im Linux-Container läuft. CSV bekommt zusätzlich ein Byte-Order-Mark, weil Excel den Zeichensatz sonst nicht erkennt und Umlaute als Zeichensalat anzeigt. HTML und MHT tragen ihren Zeichensatz ohnehin im Dokument. Wer eine Textausgabe bisher unter Windows weiterverarbeitet hat, bekommt damit andere Bytes als zuvor – vorher schrieb Windows in seiner ANSI-Codepage

   • Ziel E-Mail: Der Bericht geht als Anhang je Einzelausgabe in einer eigenen Mail hinaus – bei einer Benutzerliste bekommt so jeder Benutzer seine eigene, MESOSAFE-gefilterte Auswertung statt einer Sammelmail. Die Felder An, Kopie und Blindkopie nehmen mehrere Adressen getrennt durch Semikolon oder Komma auf. An Kontextbenutzer senden ergänzt die Mailadresse des WinLine-Benutzers, in dessen Kontext die Ausgabe lief; hat dieser Benutzer keine Adresse im Benutzerstamm, schlägt die Ausgabe mit seinem Namen als Grund fehl. Eine Adresse, die schon in einem ranghöheren Feld steht – An vor Kopie vor Blindkopie, ohne Rücksicht auf Groß-/Kleinschreibung –, wird in einem niedrigeren nicht doppelt angeschrieben. Betreff und Text (als HTML) unterstützen Platzhalter, der Dateiname des Anhangs kommt aus dem Dateinamensmuster des Ziels. Eine einzige ungültige Adresse – auch eine ohne Domainanteil – lässt die gesamte Ausgabe fehlschlagen; es wird dann keine Mail verschickt, auch nicht an die gültigen Adressen. Bleibt SMTP-Konto leer, gilt das Konto des Mandanten der Ausgabe, sonst das Standardkonto. Läuft der Bericht über mehrere Mandanten, ist das der erstgenannte – eine Mail hat nur einen Absender

   • Ziel CRM-Workflow: Je Einzelausgabe entsteht ein Fall, an den der Bericht als Archivdokument gehängt wird. Workflownummer bestimmt die Prozessvorlage, nach der der Fall angelegt wird, Archivformular das Formular für den Anhang (0 = Standardformular). Welche Fall-Felder mit welchen Werten belegt werden, steht in der Tabelle Fall-Felder mit den Spalten Feld, Wert und Reihenfolge; bei „Andere" lässt sich eine freie Feldnummer der Tabelle T170 eintragen. Ein Beispiel:

     Feld	Wert
     Kurzbeschreibung	Auswertung {{Bericht}} für {{Mandant}}
     Langbeschreibung intern	Erzeugt am {{Heute:dd.MM.yyyy}}, {{Benutzer.Name}}
     Vertreter	{{Benutzer.Vertreter}}

     Jeder Wert wird nach Auflösung der Platzhalter in den Datentyp seines Feldes gewandelt (Ganzzahl, Zahl, Datum oder Text) – passt der Wert nicht zum Feld, schlägt die Ausgabe mit sprechendem Grund fehl, statt einen falschen Wert nach WinLine zu schreiben. Löst sich ein Platzhalter zu nichts auf, bleibt das zugehörige Feld unangetastet, damit ein Vorgabewert aus der Prozessvorlage nicht mit Leere überschrieben wird; sind alle konfigurierten Felder leer, schlägt die Ausgabe fehl, statt einen leeren Fall anzulegen. Ein Fall gehört zu genau einem Mandanten – bei einer mandantenübergreifenden Auswertung entsteht er im erstgenannten Mandanten, der Journaleintrag nennt ihn. Voraussetzung ist die Einstellung WinLineSettings:TemplateForWorkflowImport; fehlt sie, nennt die fehlgeschlagene Ausgabe genau diesen Schlüssel. Meldet WinLine keine verwendbare Fallnummer zurück, gilt die Ausgabe als fehlgeschlagen – im Journal steht dann die Meldung von WinLine und keine Fallnummer, damit ein Folgeziel keinen Fall benennt, den es nicht gibt. Entsteht der Fall, WinLine hat aber trotzdem etwas anzumerken, gilt die Ausgabe als erfolgreich und die Meldung steht hinter der Fallnummer im Journaleintrag

   • Mailversand und Fallanlage laufen nur im MESO WorkerService. In der Weboberfläche und im Windows-Client meldet ein E-Mail- oder CRM-Workflow-Ziel, dass der Versand dort nicht eingerichtet ist – zum Ausführen und Testen solcher Ziele wird der Dienst benötigt

   • {{FallId}} und {{Schrittnummer}}: In Zielen, die nach einem CRM-Workflow-Ziel desselben Mandanten und Benutzers laufen, stehen diese beiden Platzhalter zur Verfügung. Die Reihenfolge ergibt sich aus dem Index der Ziele – ein E-Mail-Ziel mit Fall {{FallId}} im Betreff, das nach dem Workflow-Ziel läuft, kann so den gerade angelegten Fall benennen. Die Fall-Id steht zusätzlich am Journaleintrag jeder betroffenen Ausgabe – auch bei einer fehlgeschlagenen, damit erkennbar bleibt, zu welchem Fall sie gehörte

4. Parameter

   • Parameter des Berichts lassen sich am Auftrag mit einem festen Wert oder einem Platzhalter belegen: Mandant, Wirtschaftsjahr, Heute, Monatsanfang, Monatsende, Vormonat.Anfang, Vormonat.Ende, Jahresanfang, Benutzer.Nummer, Benutzer.Name, Benutzer.Mail, Benutzer.Vertreter
   • Ohne Eintrag bleibt der im Designer gesetzte Standardwert stehen
   • Ein am Auftrag gesetzter Parameter hat Vorrang vor dem gleichnamigen Standard-Platzhalter und gilt überall gleich: im Bericht, in den Platzhaltern der SQL-Abfragen und Kriterien sowie in Zielverzeichnis und Dateiname

5. Journal

   • Jede Einzelausgabe erzeugt einen Eintrag mit Mandant, Benutzer, Ziel, Zeilenzahl und Ergebnis. Ein Fehler in einer Ausgabe hält die übrigen nicht auf
   • Das Journal wird nach jedem Auftrag gespeichert. Wird der Dienst mitten im Durchlauf beendet, bleiben die Einträge der bereits abgelegten Dateien erhalten
   • Auf Wunsch wird auch das erzeugte Dokument aufbewahrt; das ist standardmäßig aus, weil es Platz in der Datenbank belegt
   • Einträge werden nach der eingestellten Zahl von Tagen gelöscht (Standard 90 Tage, 0 bedeutet unbegrenzt aufbewahren)

Dashboards versenden

Ein Berichtsauftrag kann statt eines Berichts auch ein Dashboard ausführen – ein im Navigationsbereich Dashboards entworfenes XAF-Dashboard. Am Auftrag wird genau eines von Bericht und Dashboard gewählt; beides gleichzeitig oder beides leer lässt sich nicht speichern. Zeitplan, Mandanten, Ausgabeziele (Dateiablage, E-Mail, CRM-Workflow) und Journal funktionieren identisch zu Berichtsaufträgen – siehe Berichtsaufträge.

Formate: Dashboard-Aufträge unterstützen nur PDF, Excel (XLSX) und Bild (PNG) – ein Ausgabeziel mit einem anderen Format lässt sich am Auftrag nicht speichern. Ein Bild wird immer in 1920×1080 Pixeln erzeugt, unabhängig von der Größe des Dashboards im Designer.

Datenquellen im Dashboard:

• SQL-Datenquellen verwenden dieselben Platzhalter wie Berichts-Abfragen ({{Mandant}}, {{Wirtschaftsjahr}}, {{Benutzer.Nummer}}, {{Heute}} usw.). Auch hier werden sie als gebundene SQL-Parameter eingesetzt, nicht in den Abfragetext kopiert. Als Verbindung dient automatisch die WinLine-Datenbank des Mandanten, für den die Ausgabe gerade läuft – die im Dashboard-Designer hinterlegte Verbindung wird dafür nicht verwendet. Das im Dashboard gespeicherte SQL wird dabei ungeprüft gegen die Mandanten-Datenbank ausgeführt – bewusst dasselbe Vertrauensmodell wie bei den Berichts-Datenquellen: Wer Dashboards gestalten darf, kann darüber beliebiges SQL ausführen
• Objekt-Datenquellen (auf BusinessObjects der WorkerService-Datenbank, z.B. Vorgänge oder Mail-Journal) zeigen dieselben Daten wie der Dashboard-Viewer der Weboberfläche. Zugelassen sind nur XPO-Persistenztypen – verweist eine Datenquelle auf einen anderen Typ, schlägt die Ausgabe mit Fehlermeldung fehl, statt ihn stillschweigend zu ignorieren

Einschränkungen (Stand V1):

• Kein Benutzerkontext: Dashboard-Aufträge laufen immer „Ohne" Benutzerkontext (MESOSAFE) – ein anderer Modus lässt sich am Auftrag nicht speichern
• „Auch bei leerem Ergebnis ausgeben" ohne Wirkung: Anders als ein Bericht hat ein Dashboard keine Haupttabelle, deren Zeilenzahl geprüft werden könnte – Dashboard-Ausgaben gelten deshalb immer als gefüllt und werden immer erzeugt

Fehlerverhalten: Eine fehlgeschlagene Datenquelle, ein unzulässiger Objekttyp oder ein Export ohne Inhalt (0 Byte) lassen die Ausgabe mit sprechendem Grund im Journal fehlschlagen. Das deckt technische Fehler ab – ein Dashboard, dessen Abfragen schlicht keine Zeilen liefern, wird dagegen bewusst mit leeren Kacheln ausgeliefert (siehe „Auch bei leerem Ergebnis ausgeben" oben: die Prüfung greift bei Dashboards nicht).

Vorschau in der Oberfläche: Ein Dashboard mit SQL-Datenquellen lässt sich auch außerhalb eines Berichtsauftrags ansehen – im Blazor-Dashboard-Viewer und -Designer sowie im Windows-Client-Viewer. Damit dabei nicht der DevExpress-eigene Verbindungsdialog erscheint (die im Dashboard-Designer hinterlegte Verbindung wird auch hier nicht verwendet), wird die Verbindung zur Laufzeit auf die WinLine-Datenbank eines fest konfigurierten Vorschau-Mandanten aufgelöst – Schlüssel Dashboard:VorschauMandant:

• Blazor: MesoWorker.Blazor.Server/appsettings.json (bzw. das kundenspezifische Profil), Abschnitt Dashboard → VorschauMandant, z.B. "500M"
• Windows-Client: appSettings-Eintrag Dashboard:VorschauMandant in App.config, z.B. <add key="Dashboard:VorschauMandant" value="500M"/>

Ist der Schlüssel nicht gesetzt, scheitert die Vorschau mit einer sprechenden Fehlermeldung („Für die Dashboard-Vorschau ist kein Mandant konfiguriert…") statt eines Verbindungsdialogs. Der WinForms-Dashboard-Designer bleibt außen vor: dort erscheint der Verbindungsdialog weiterhin, weil DevExpress ihn dort nicht über dasselbe Ereignis führt wie im Viewer.

Wie beim Dashboard-Versand über den Berichtsauftrag laufen {{Mandant}}/{{Wirtschaftsjahr}} und die übrigen Platzhalter auch in der Vorschau als gebundene SQL-Parameter, nicht als Textersatz. Der Blazor-Dashboard-Configurator sperrt benutzerdefinierte SQL-Abfragen standardmäßig (AllowExecutingCustomSql); die Vorschau schaltet das frei – bewusst dasselbe Vertrauensmodell wie beim Dashboard-Versand: Wer Dashboards gestalten darf, kann darüber beliebiges SQL gegen die Mandanten-Datenbank ausführen, auch schon beim bloßen Ansehen.

---