Direkt zum Hauptinhalt

Hauptkomponenten

MesoWorkerService besteht aus sechs 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 SMTP-Konto Einstellungen

E-Mail Einstellungen E-Mail-Einstellungen für einen Workflow

Mail-Template 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.

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

  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.

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

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)

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}})
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)
  • 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.

Keine Kommentare vorhanden

nach oben