Direkt zum Hauptinhalt

Dokumentation

CSS EDV Support Logo

Automatisierungsdienst für Mesonic WinLine Hintergrunddienst zur Automatisierung von E-Mail-Versand, Workflow-VerwaltungVerwaltung, CRM basierter Terminerstellung (nur für M365) und Überwachung in WinLine-Umgebungen.

Schnellstart

Diese Anleitung führt Sie durch die wichtigsten Schritte zur Inbetriebnahme des MesoWorkerService. Für detaillierte Informationen konsultieren Sie bitte die entsprechenden Abschnitte in dieser Dokumentation.

WICHTIG: Richtige Reihenfolge beachten

Die Datenbank muss IMMER ZUERST erstellt werden, bevor der Service gestartet werden kann!

Die Einrichtung erfolgt in dieser Reihenfolge:

  1. Datenbank erstellen (Anwendungsdatenbank MesoWorkerDb)
  2. ConnectionStrings konfigurieren (auf die erstellte Datenbank zeigen)
  3. Service starten und einrichten

Schritt 1: Datenbank erstellen

Die Anwendungsdatenbank (MesoWorkerDb) muss vor dem ersten Start des Services erstellt werden. Wählen Sie eine der folgenden Methoden:

Option A: Windows-Applikation (empfohlen für Windows-Installation)

  1. Download und Entpacken:

  2. ConnectionStrings konfigurieren:

    Erstellen Sie die Datei connectionStrings.Local.config im entpackten Verzeichnis:

    <?xml version="1.0"?>
<connectionStrings>
    <add name="ConnectionString" 
         connectionString="Integrated Security=false;Pooling=false;Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=sql-passwort;TrustServerCertificate=True" />
    <add name="WinLineSystemDBConnectionString" 
         connectionString="Integrated Security=false;Pooling=false;Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=sql-passwort;TrustServerCertificate=True" />
</connectionStrings>

    Passen Sie folgende Werte an:

    • SQL-SERVER: Ihr SQL Server Hostname oder IP-Adresse
    • sql-user und sql-passwort: Ihre SQL-Anmeldedaten
    • Oder verwenden Sie Integrated Security=true für Windows-Authentifizierung

  3. Datenbank erstellen:

    Führen Sie im Verzeichnis folgenden Befehl aus:

    MesoWorker.Win.exe -updateDatabase -silent

    Erfolgreich, wenn Exit Code = 0

Option B: Container (für Container-Deployment)

Führen Sie den folgenden Docker-Befehl aus, um die Datenbank zu erstellen:

docker run --rm \
  -e ConnectionStrings__ConnectionString="Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=***;TrustServerCertificate=true" \
  -e ConnectionStrings__WinLineSystemDBConnectionString="Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=***;TrustServerCertificate=true" \
  ghcr.io/css-edv-support/mesoworkerservice-blazor:latest \
  -updateDatabase -forceUpdate -silent

Passen Sie folgende Werte an:

  • SQL-SERVER: Ihr SQL Server Hostname oder IP-Adresse
  • sql-user und ***: Ihre SQL-Anmeldedaten

Erfolgreich, wenn Exit Code = 0

Alternativ können Sie auch einen separaten Update-Service in Ihrer docker-compose.yml definieren (siehe Datenbank-Ersteinrichtung (Container)).

Schritt 2: ConnectionStrings konfigurieren

Nachdem die Datenbank erfolgreich erstellt wurde, konfigurieren Sie die ConnectionStrings des MesoWorkerService:

Windows-Dienst

Bearbeiten Sie die Datei appsettings.json im Installationsverzeichnis des MesoWorkerService:

{
  "ConnectionStrings": {
    "ConnectionString": "Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;Integrated Security=true;TrustServerCertificate=true",
    "WinLineSystemDBConnectionString": "Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;Integrated Security=true;TrustServerCertificate=true"
  },
  "License": {
    "CustomerNr": "12345",
    "LicenseNr": "LIZENZNUMMER"
  }
}

Wichtig: Ersetzen Sie:

  • SQL-SERVER: Ihr SQL Server Hostname
  • 12345 und LIZENZNUMMER: Ihre Lizenzinformationen
  • Die ConnectionStrings müssen auf die in Schritt 1 erstellte Datenbank zeigen

Container-Deployment

Konfigurieren Sie die Umgebungsvariablen in Ihrer docker-compose.yml oder im Portainer Stack:

environment:
  # Lizenzierung
  - LICENSE_CUSTOMER_NR=12345
  - LICENSE_LICENSE_NR=LIZENZNUMMER
  
  # Datenbankverbindungen (müssen auf die in Schritt 1 erstellte Datenbank zeigen!)
  - ConnectionStrings__ConnectionString=Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true
  - ConnectionStrings__WinLineSystemDBConnectionString=Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true

Wichtig:

  • Die ConnectionStrings müssen exakt auf dieselben Datenbankverbindungen zeigen, die in Schritt 1 verwendet wurden
  • Ersetzen Sie SQL-SERVER, sql-user, sql-pass mit Ihren tatsächlichen Zugangsdaten
  • Ersetzen Sie 12345 und LIZENZNUMMER mit Ihrer Lizenz

Schritt 3: Service starten

Windows-Dienst

  1. Service installieren (siehe Option 1: Windows-Dienst für Details):

    New-Service -Name "MESO-WorkerService" `
            -BinaryPathName "C:\MesoWorkerService\MesoWorkerService.exe" `
            -DisplayName "MESO Worker Service" `
            -Description "Automatisierungsdienst für Mesonic WinLine" `
            -StartupType Automatic

  2. Service starten:

    Start-Service -Name "MESO-WorkerService"

  3. Web-Interface öffnen:

    • Öffnen Sie http://localhost:5000 im Browser
    • Melden Sie sich mit Benutzername Admin an (Passwort muss bei Erstanmeldung gesetzt werden)

Container-Deployment

  1. Container starten:

    docker-compose up -d

  2. Web-Interface öffnen:

    • Blazor UI: http://server:8012 (oder Ihr konfigurierter Port)
    • Melden Sie sich mit Benutzername Admin an (Passwort muss bei Erstanmeldung gesetzt werden)

Nächste Schritte

Nach der erfolgreichen Inbetriebnahme sollten Sie:

  1. Admin-Passwort setzen bei der Erstanmeldung
  2. SMTP-Konten einrichten für E-Mail-Versand (siehe SMTP-Konten einrichten)
  3. Mandanten aktivieren in der Administrationsoberfläche
  4. Mail-Einstellungen konfigurieren für Ihre Workflows

Für detaillierte Konfigurationsoptionen konsultieren Sie die entsprechenden Abschnitte in dieser Dokumentation.

Übersicht

Was ist MesoWorkerService?

MesoWorkerService ist ein Automatisierungsdienst für Mesonic WinLine, der Hintergrundaufgaben selbstständig ausführt. Der Dienst basiert auf .NET 9 und kann sowohl als Windows-Dienst als auch als Container betrieben werden.

Hauptfunktionen

Der MesoWorkerService bietet vier Hauptfunktionen:

1. Automatischer E-Mail-Versand

  • Versendet E-Mails automatisch basierend auf Workflow-Ereignissen in WinLine
  • Unterstützt hierarchische Empfängerregeln mit flexiblen Prioritäten
  • Ermöglicht die Verwendung mehrerer SMTP-Konten inkl. Microsoft 365 mit OAuth
  • Fügt automatisch Anhänge aus Workflows und Belegen hinzu
  • Protokolliert alle versendeten E-Mails im Mail-Journal

2. Workflow-Erzeugung aus Bestelldateizeilen

  • Erstellt automatisch CRM-Fälle aus Bestelldateizeilen (z.B. für Serviceaufträge)
  • Filtert relevante Zeilen nach konfigurierbaren Kriterien
  • Verhindert Mehrfachverarbeitung durch intelligente Protokollierung
  • Ermöglicht flexible Datumsfelder und Template-basierte Beschreibungen

3. Terminsynchronisation

  • Erstellt automatisch Kalender-Termine aus CRM-Einträgen über MS Graph API
  • Synchronisiert Termine direkt in Microsoft Exchange/Outlook-Kalender
  • Flexible Empfänger-Ermittlung über verschiedene CRM-Quellen
  • Optionale Rücksynchronisation von Terminänderungen zurück in CRM
  • Unterstützt dynamische Inhalte und Anhänge aus CRM-Einträgen

4. Überwachung und Warnung

  • Überwacht Workflows mit aktiven E-Mail-Regeln
  • Benachrichtigt Administratoren bei fehlenden E-Mail-Versendungen
  • Hilft bei der frühzeitigen Erkennung von Konfigurationsfehlern oder fehlenden Stammdaten

Systemarchitektur

┌─────────────────────────────────────────────────────────────┐
│                    MesoWorkerService                         │
│               (.NET 9 Hintergrunddienst)                    │
└─────────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┬───────────────┐
            │               │               │               │
            ▼               ▼               ▼               ▼
    ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐
    │ Mail-Dienst  │  │  Workflow-  │  │   Termin-    │  │ Überwachungs-  │
    │              │  │  Erzeugung  │  │ synchroni-   │  │    dienst      │
    │              │  │              │  │   sation     │  │                │
    └──────────────┘  └─────────────┘  └──────────────┘  └────────────────┘
            │               │               │               │
            └───────────────┼───────────────┼───────────────┘
                            │               │
                            ▼               ▼
            ┌───────────────────────────────┐  ┌─────────────────────┐
            │   WinLine Datenbanken         │  │  MS Graph API       │
            │   • CWLSYSTEM                 │  │  (Exchange/Outlook) │
            │   • Mandanten-DB              │  └─────────────────────┘
            └───────────────────────────────┘
                            │
                            ▼
            ┌───────────────────────────────┐
            │   Anwendungsdatenbank         │
            │   (MesoWorkerDb)              │
            │   • Konfiguration             │
            │   • Mail-Journal              │
            │   • Termin-Journal            │
            │   • Protokollierung           │
            └───────────────────────────────┘

Administrationsoberflächen:

  • Blazor Web-UI (browserbasiert, Port 5000)
  • Windows Desktop-Client

Eine detaillierte Architekturübersicht finden Sie in assets/systemarchitektur.md.

Systemvoraussetzungen

WinLine:

  • Mesonic WinLine Edition 2022 oder neuer
  • MDP Runtime Lizenz (vom Mesonic Vertriebspartner)
  • Mesonic Server 64 Bit (optional, nur für automatische Workflow-Schritt-Erstellung erforderlich)

Betriebssystem und Runtime:

  • Windows Server 2016 oder neuer (für Windows-Dienst)
  • .NET 9 Runtime (Download)
  • Alternativ: Container-Runtime (Docker, Podman) für Container-Deployment

Netzwerk:

  • Zugriff auf WinLine-Datenbank (SQL Server)
  • Zugriff auf SMTP-Server für E-Mail-Versand
  • Optional: Zugriff auf Mesonic Server für Workflow-Schritte

Installation

Hinweis: Für eine schnelle Inbetriebnahme folgen Sie dem Schnellstart.

Der MesoWorkerService kann auf zwei Arten betrieben werden:

Option 1: Windows-Dienst

Der Service wird als Windows-Dienst auf einem Server installiert und läuft permanent im Hintergrund.

WICHTIG: Vor der Installation muss die Datenbank erstellt werden! Siehe Schritt 1: Datenbank erstellen.

Voraussetzungen:

  • Windows Server 2016 oder neuer
  • .NET 9 Runtime installiert
  • Netzwerkzugriff zur WinLine-Datenbank
  • Datenbank MesoWorkerDb muss bereits erstellt sein

Installationsschritte:

  1. Download der Anwendung

    • Laden Sie das Windows-Dienst-Paket herunter: MesoWorkerService-win-x64.zip
    • Entpacken Sie das Archiv in ein Verzeichnis (z.B. C:\MesoWorkerService)

  2. Konfigurationsdatei anpassen

    WICHTIG: Konfigurieren Sie die appsettings.json VOR der Dienst-Installation!

    Öffnen Sie die Datei appsettings.json im Installationsverzeichnis und passen Sie die Einstellungen an:

    • ConnectionStrings: Müssen auf die in Schritt 1 erstellte Datenbank zeigen
    • License: Ihre Lizenzinformationen

    Siehe Windows-Dienst Konfiguration für Details.

  3. Installation als Windows-Dienst

    Der Service kann als Windows-Dienst installiert werden. Öffnen Sie eine PowerShell-Konsole mit Administratorrechten und navigieren Sie zum Installationsverzeichnis.

    Option A: Installation mit PowerShell (empfohlen)

    # Service erstellen und konfigurieren
New-Service -Name "MESO-WorkerService" `
            -BinaryPathName "C:\MesoWorkerService\MesoWorkerService.exe" `
            -DisplayName "MESO Worker Service" `
            -Description "Automatisierungsdienst für Mesonic WinLine - E-Mail-Versand, Workflow-Verwaltung und Überwachung" `
            -StartupType Automatic

# Service starten
Start-Service -Name "MESO-WorkerService"

# Service-Status prüfen
Get-Service -Name "MESO-WorkerService"

    Option B: Installation mit sc.exe

    REM Service erstellen
sc.exe create "MESO-WorkerService" binPath= "C:\MesoWorkerService\MesoWorkerService.exe" DisplayName= "MESO Worker Service" start= auto

REM Service-Beschreibung setzen
sc.exe description "MESO-WorkerService" "Automatisierungsdienst für Mesonic WinLine - E-Mail-Versand, Workflow-Verwaltung und Überwachung"

REM Service starten
sc.exe start "MESO-WorkerService"

REM Service-Status prüfen
sc.exe query "MESO-WorkerService"

    Service deinstallieren (falls erforderlich):

    # Service stoppen und entfernen (PowerShell)
Stop-Service -Name "MESO-WorkerService"
Remove-Service -Name "MESO-WorkerService"

    REM Service stoppen und entfernen (sc.exe)
sc.exe stop "MESO-WorkerService"
sc.exe delete "MESO-WorkerService"

    Wichtig:

    • Passen Sie den Pfad C:\MesoWorkerService\MesoWorkerService.exe an Ihr Installationsverzeichnis an
    • Bei sc.exe ist das Leerzeichen nach binPath=, DisplayName= und start= erforderlich
    • Für weitere Unterstützung kontaktieren Sie den Support: [email protected]

  4. Dienst starten

    Starten Sie den Windows-Dienst über die Dienste-Verwaltung oder mit PowerShell:

    Start-Service -Name "MESO-WorkerService"

Vorteile der Windows-Dienst-Installation:

  • Direkter Zugriff auf lokale WinLine-Installation
  • Optimale Performance bei lokaler Datenbank
  • Vollständige Kontrolle über das System
  • Einfache Integration in bestehende Windows-Infrastruktur

Nachteile der Windows-Dienst-Installation:

  • Erfordert Windows Server-Umgebung
  • Manuelle Installation und Wartung
  • .NET 9 Runtime muss installiert werden

Option 2: Container-Deployment

Der Service wird als Container betrieben und kann auf verschiedenen Plattformen ausgeführt werden.

WICHTIG: Vor dem Container-Start muss die Datenbank erstellt werden! Siehe Schritt 1: Datenbank erstellen.

Verfügbare Container Images:

  • Service: ghcr.io/css-edv-support/mesoworkerservice-service:latest
  • Blazor UI: ghcr.io/css-edv-support/mesoworkerservice-blazor:latest

Deployment-Optionen:

  • Docker Compose
  • Portainer Stacks
  • Kubernetes
  • Docker Swarm

Installationsschritte:

  1. Container-Runtime installieren

    Installieren Sie Docker oder Podman auf Ihrem System.

  2. Datenbank erstellen (ZUERST!)

    WICHTIG: Die Datenbank muss VOR dem ersten Container-Start erstellt werden!

    Siehe Schritt 1: Datenbank erstellen - Option B: Container.

  3. Stack-Datei erstellen

    Erstellen Sie eine docker-compose.yml Datei oder nutzen Sie Portainer Stack (siehe Portainer Stack Konfiguration).

  4. Umgebungsvariablen konfigurieren

    WICHTIG: Die ConnectionStrings müssen auf die in Schritt 2 erstellte Datenbank zeigen!

    Passen Sie die Umgebungsvariablen in der Stack-Datei an Ihre Umgebung an (siehe Portainer Stack Konfiguration).

  5. Container starten

    Mit Docker Compose:

    docker-compose up -d

    Mit Portainer:

    • Stack in Portainer importieren
    • Umgebungsvariablen anpassen
    • Stack deployen

Vorteile des Container-Deployments:

  • Plattformunabhängig (Linux, Windows, macOS)
  • Einfache Skalierung und Deployment
  • Isolierte Umgebung mit definierten Abhängigkeiten
  • Keine lokale .NET-Installation erforderlich
  • Einfache Updates über Image-Tags
  • Geeignet für moderne DevOps-Umgebungen

Nachteile des Container-Deployments:

  • Erfordert Container-Runtime (Docker, Podman)
  • Zusätzliche Netzwerk-Konfiguration für Datenbankzugriff
  • Container-Orchestrierung kann komplex sein

Konfiguration

Die Konfiguration des MesoWorkerService erfolgt je nach Installationsmethode unterschiedlich:

  • Windows-Dienst: Über die Datei appsettings.json
  • Container: Über Umgebungsvariablen

Lizenzierung

Für den Betrieb des MesoWorkerService benötigen Sie eine gültige Lizenz, die Sie von Ihrem Mesonic Partner erhalten.

Erforderliche Angaben:

  • Kundennummer: Identifiziert den Lizenzinhaber
  • Lizenznummer: Aktiviert die Software

Wichtig: Ohne gültige Lizenz startet der Service nicht.

Datenbankverbindungen

Der MesoWorkerService benötigt Zugriff auf zwei Datenbanken:

1. Anwendungsdatenbank (MesoWorkerDb)

  • Speichert Konfigurationsdaten, Mail-Journal und Protokolle
  • Wird beim ersten Start automatisch erstellt (falls nicht vorhanden)
  • Connection String Format: Data Source=SERVER;Initial Catalog=MesoWorkerDb;...

2. WinLine Systemdatenbank (CWLSYSTEM)

  • Zugriff auf WinLine Mandanten und Systemdaten
  • Connection String Format: Data Source=SERVER;Initial Catalog=CWLSYSTEM;...

Authentifizierungsoptionen:

  • Windows-Authentifizierung: Integrated Security=true
  • SQL-Authentifizierung: User ID=user;Password=pass

Wichtig: Für Container-Deployment muss SQL-Authentifizierung verwendet werden, da Windows-Authentifizierung in Containern nicht unterstützt wird.

WinLine-Integration

WinLine-Pfad:

  • Pfad zur WinLine-Installation (z.B. C:\WinLine\ oder /app/winline/)
  • Erforderlich für Zugriff auf WinLine-Konfigurationsdateien
  • Wichtig für Container (Linux): Der WinLine-Pfad ist typischerweise eine Windows-UNC-Freigabe (z.B. \\winline-server\WinLine), die als Linux-Mountpoint oder Volume in den Container eingebunden werden muss
  • Wird auch für die Erstellung von CRM-Workflow-Schritten über den WinLine WebService benötigt

Mesospool Service:

  • URL zum Mesospool-Service für Dokumentenarchivierung
  • Format: http://server:42024
  • Erforderlich für Anhang-Funktionen
  • Wichtig für Container (Linux): Bei Linux-Containern ist der Mesospool-Service zwingend erforderlich, da die unter WinLinePath vorhandene mesospool.exe nicht unter Linux lauffähig ist
  • Wird generell zur Konvertierung von Archiv-Dateien im WinLine .SPL-Format in PDF-Dateien verwendet
  • Falls keine .SPL-Dateien vorliegen, ist der Service optional

WinLine Server (optional):

  • URL zum WinLine WebService (z.B. http://server:8080)
  • Erforderlich wenn automatische CRM-Workflow-Schritte erstellt werden sollen (z.B. für Workflow-Erzeugung aus Bestelldateizeilen)
  • Verwendet den WinLine-Pfad für die Workflow-Schritt-Erstellung
  • Benötigt separate Mesonic WebService-Lizenz

Session-Einstellungen:

  • Standard-Anmeldedaten für WinLine-Sessions
  • Mindestanzahl aktiver Sessions
  • Validierungsintervall für Sessions

Windows-Dienst Konfiguration

Bei der Windows-Dienst-Installation erfolgt die Konfiguration über die Datei appsettings.json:

{
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://0.0.0.0:5000" }
    }
  },
  "License": {
    "CustomerNr": "12345",
    "LicenseNr": "LIZENZNUMMER"
  },
  "ConnectionStrings": {
    "ConnectionString": "Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;Integrated Security=true;TrustServerCertificate=true",
    "WinLineSystemDBConnectionString": "Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;Integrated Security=true;TrustServerCertificate=true"
  },
  "WinLineSettings": {
    "WinLinePath": "C:\\WinLine\\",
    "MesospoolServiceUrl": "http://winline-server:42024",
    "TemplateForWorkflowImport": 101
  },
  "WinLineServer": {
    "Url": "http://winline-server:8080"
  },
  "SessionSettings": {
    "MinimumSessions": 1,
    "DefaultUser": "winline-user",
    "DefaultPassword": "passwort",
    "DefaultCompany": "500M",
    "ValidationInterval": "01:00:00"
  },
  "MailSettings": {
    "EmailFrom": "[email protected]",
    "DisplayName": "MesoWorkerService",
    "SmtpHost": "smtp.firma.de",
    "SmtpPort": 587,
    "SmtpUser": "smtp-user",
    "SmtpPass": "smtp-passwort",
    "UseSSL": false,
    "UseStartTls": true,
    "AdminMailRecipients": ["[email protected]"]
  },
  "Quartz": {
    "quartz.scheduler.instanceName": "MesoWorker Scheduler",
    "MailWorkerJob": {
      "scheduler": "0/30 * * * * ?",
      "enabled": true,
      "startnow": false
    },
    "OrderLineWorkerJob": {
      "scheduler": "0 */5 * * * ?",
      "enabled": true,
      "startnow": false
    },
    "NoRuleWarningJob": {
      "scheduler": "0 0 8 * * ?",
      "enabled": true,
      "startnow": false
    },
    "AppointmentWorkerJob": {
      "scheduler": "0 */10 * * * ?",
      "enabled": true,
      "startnow": false
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Information",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console"
      },
      {
        "Name": "File",
        "Args": {
          "path": "Logs/MesoWorkerService-.txt",
          "rollingInterval": "Day"
        }
      }
    ]
  }
}

Wichtige Einstellungen:

  • Kestrel: Web-Server-Konfiguration (Standard: Port 5000)
  • License: Kundennummer und Lizenznummer (erforderlich)
  • ConnectionStrings: Datenbankverbindungen (erforderlich)
  • WinLineSettings: WinLine-Integration (erforderlich)
  • SessionSettings: WinLine-Session-Verwaltung
  • MailSettings: E-Mail-Versand-Konfiguration (wird meist über Admin-Oberfläche verwaltet)
  • Quartz: Job-Zeitplanung für automatische Ausführungen (Cron-Expressions)
  • Logging/Serilog: Protokollierungseinstellungen

Portainer Stack Konfiguration

Bei Container-Deployment erfolgt die Konfiguration über Umgebungsvariablen:

version: '3.8'

services:
  mesoworkerservice-ui:
    image: ghcr.io/css-edv-support/mesoworkerservice-blazor:latest
    container_name: mesoworkerservice-ui
    restart: unless-stopped
    ports:
      - "8012:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:5000
      - TZ=Europe/Berlin
      
      # Datenbank (erforderlich)
      - ConnectionStrings__ConnectionString=Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true
      - ConnectionStrings__WinLineSystemDBConnectionString=Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true

  mesoworkerservice:
    image: ghcr.io/css-edv-support/mesoworkerservice-service:latest
    container_name: mesoworkerservice
    restart: unless-stopped
    ports:
      - "8013:5000"
    
    # Volume-Mapping für WinLine-Pfad (erforderlich für Linux-Container)
    volumes:
      - type: bind
        source: //winline-server/WinLine  # Windows UNC-Pfad
        target: /app/winline               # Linux-Mountpoint im Container
        read_only: true
    
    environment:
      # Container-Konfiguration
      - ASPNETCORE_ENVIRONMENT=Production
      - DOTNET_RUNNING_IN_CONTAINER=true
      - ASPNETCORE_URLS=http://+:5000
      - TZ=Europe/Berlin
      - LANG=de_DE.UTF-8
      
      # Lizenzierung (erforderlich)
      - LICENSE_CUSTOMER_NR=12345
      - LICENSE_LICENSE_NR=LIZENZNUMMER
      
      # Datenbankverbindungen (erforderlich)
      - ConnectionStrings__ConnectionString=Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true
      - ConnectionStrings__WinLineSystemDBConnectionString=Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=sql-pass;TrustServerCertificate=true
      
      # WinLine-Konfiguration (erforderlich)
      - WinLineSettings__WinLinePath=/app/winline/
      - WinLineSettings__MesospoolServiceUrl=http://winline-server:42024
      - WinLineSettings__TemplateForWorkflowImport=101
      
      # WinLine Server (optional, nur für Workflow-Schritte)
      - WinLineServer__Url=http://winline-server:8080
      
      # Session-Einstellungen
      - SessionSettings__MinimumSessions=1
      - SessionSettings__DefaultUser=winline-user
      - SessionSettings__DefaultPassword=passwort
      - SessionSettings__DefaultCompany=500M
      - SessionSettings__ValidationInterval=01:00:00
      
      # E-Mail-Konfiguration (optional, kann über Admin-UI konfiguriert werden)
      - [email protected]
      - MailSettings__DisplayName=MesoWorkerService
      - MailSettings__SmtpHost=smtp.firma.de
      - MailSettings__SmtpPort=587
      - MailSettings__SmtpUser=smtp-user
      - MailSettings__SmtpPass=smtp-passwort
      - MailSettings__UseSSL=false
      - MailSettings__UseStartTls=true
      - [email protected]
      
      # Job-Konfiguration
      - Quartz__quartz.scheduler.instanceName=MesoWorker Scheduler Production
      - Quartz__MailWorkerJob__scheduler=0/30 * * * * ?
      - Quartz__MailWorkerJob__enabled=true
      - Quartz__MailWorkerJob__startnow=false
      - Quartz__OrderLineWorkerJob__scheduler=0 */5 * * * ?
      - Quartz__OrderLineWorkerJob__enabled=true
      - Quartz__OrderLineWorkerJob__startnow=false
      - Quartz__NoRuleWarningJob__scheduler=0 0 8 * * ?
      - Quartz__NoRuleWarningJob__enabled=true
      - Quartz__NoRuleWarningJob__startnow=false
      - Quartz__AppointmentWorkerJob__scheduler=0 */10 * * * ?
      - Quartz__AppointmentWorkerJob__enabled=true
      - Quartz__AppointmentWorkerJob__startnow=false
      
      # Protokollierung
      - Logging__LogLevel__Default=Information
      - Logging__LogLevel__Microsoft.Hosting.Lifetime=Information
      - Serilog__MinimumLevel__Default=Information
      - Serilog__MinimumLevel__Override__Microsoft=Information
      - Serilog__MinimumLevel__Override__System=Warning

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 3600s
      timeout: 10s
      retries: 3
      start_period: 60s
    
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M
          cpus: '0.5'

Konfigurationshinweise:

  • Ersetzen Sie SQL-SERVER, sql-user, sql-pass mit Ihren Datenbankzugangsdaten
  • Ersetzen Sie winline-server, winline-user, passwort mit Ihren WinLine-Zugangsdaten
  • Ersetzen Sie 12345 und LIZENZNUMMER mit Ihrer Lizenz
  • Passen Sie smtp.firma.de, smtp-user, smtp-passwort an Ihren SMTP-Server an
  • Die E-Mail-Einstellungen können auch später über die Admin-Oberfläche konfiguriert werden
  • Wichtig für Linux-Container: Der MesospoolServiceUrl ist bei Linux-Containern zwingend erforderlich, da die mesospool.exe aus dem WinLinePath nicht unter Linux lauffähig ist. Dieser Service wird zur Konvertierung von WinLine .SPL-Archivdateien in PDF verwendet.
  • Volume-Mapping für WinLine-Pfad: Der WinLine-Pfad (typischerweise eine Windows-UNC-Freigabe wie \\winline-server\WinLine) muss als Volume in den Container eingebunden werden. Passen Sie source an Ihren WinLine-Server an. Der Container greift dann über /app/winline darauf zu.

Cron-Expressions für Job-Zeitplanung:

  • 0/30 * * * * ? = Alle 30 Sekunden (Mail-Dienst)
  • 0 */5 * * * ? = Alle 5 Minuten (Workflow-Erzeugung)
  • 0 */10 * * * ? = Alle 10 Minuten (Terminsynchronisation)
  • 0 0 8 * * ? = Täglich um 8:00 Uhr (Überwachungsdienst)

Ersteinrichtung

Hinweis: Für eine schnelle Inbetriebnahme folgen Sie dem Schnellstart.

WICHTIG: Richtige Reihenfolge beachten!

Die Einrichtung muss in dieser Reihenfolge erfolgen:

  1. ZUERST: Datenbank erstellen (siehe unten)
  2. DANN: ConnectionStrings im Service konfigurieren
  3. ZULETZT: Service starten

Ein anderes Vorgehen führt zu Fehlern beim Service-Start!

Nach der Installation und Konfiguration sind folgende Schritte zur Ersteinrichtung erforderlich:

Datenbank-Ersteinrichtung

Bei der Erstinstallation muss die Anwendungsdatenbank angelegt werden. Die Vorgehensweise unterscheidet sich je nach Installationsmethode.

WICHTIG: Diese Schritte müssen VOR dem ersten Start des MesoWorkerService durchgeführt werden!

Datenbank-Ersteinrichtung (Windows)

Bei der Windows-Installation verwenden Sie den Desktop-Client MesoWorker.Win.exe mit dem Kommandozeilenparameter -updateDatabase:

Download:

Voraussetzungen:

  1. Erstellen Sie die Datei connectionStrings.Local.config im Verzeichnis von MesoWorker.Win.exe
  2. Die Datei MesoWorker.Win.Dll.Config verweist auf diese Datei mit: <connectionStrings configSource="connectionStrings.Local.config" />

Aufbau der connectionStrings.Local.config:

<?xml version="1.0"?>
<connectionStrings>
    <add name="ConnectionString" 
         connectionString="Integrated Security=false;Pooling=false;Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=sql-passwort;TrustServerCertificate=True" />
    <add name="WinLineSystemDBConnectionString" 
         connectionString="Integrated Security=false;Pooling=false;Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=sql-passwort;TrustServerCertificate=True" />
</connectionStrings>

Wichtige Parameter:

  • Data Source: SQL Server Hostname oder IP-Adresse
  • Initial Catalog: Datenbankname (MesoWorkerDb für die Anwendungsdatenbank, CWLSYSTEM für WinLine)
  • User ID / Password: SQL-Authentifizierung (oder Integrated Security=true für Windows-Authentifizierung)
  • TrustServerCertificate=True: Akzeptiert selbstsignierte SSL-Zertifikate

Datenbank erstellen:

Führen Sie im Installationsverzeichnis folgenden Befehl aus:

MesoWorker.Win.exe -updateDatabase

Optional mit zusätzlichen Parametern:

# Datenbank aktualisieren mit Benutzerinteraktion
MesoWorker.Win.exe -updateDatabase

# Datenbank aktualisieren ohne Benutzerinteraktion
MesoWorker.Win.exe -updateDatabase -silent

# Datenbank zwingend aktualisieren (auch wenn Version passt)
MesoWorker.Win.exe -updateDatabase -forceUpdate -silent

Parameter:

  • -updateDatabase - Startet den Datenbankaktualisierungsmodus
  • -forceUpdate - Erzwingt Update auch wenn Versionen übereinstimmen (optional)
  • -silent - Keine Benutzerinteraktion erforderlich (optional)
  • -h oder --help - Zeigt Hilfe an

Exit Codes:

  • 0 - Update erfolgreich abgeschlossen
  • 1 - Fehler beim Update
  • 2 - Update nicht erforderlich

Datenbank-Ersteinrichtung (Container)

Bei Container-Deployment muss die Datenbank bei Erstinstallation oder Updates manuell aktualisiert werden:

Option 1: Separater Update-Service im Stack (empfohlen)

Fügen Sie diesen Service zu Ihrer docker-compose.yml hinzu:

services:
  mesoworkerservice-db-update:
    image: ghcr.io/css-edv-support/mesoworkerservice-blazor:latest
    container_name: mesoworkerservice-db-update
    command: ["-updateDatabase", "-forceUpdate", "-silent"]
    environment:
      - ConnectionStrings__ConnectionString=Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=***;TrustServerCertificate=true
      - ConnectionStrings__WinLineSystemDBConnectionString=Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=***;TrustServerCertificate=true
    restart: "no"  # Wird nur manuell gestartet

Starten Sie den Update-Container manuell:

docker-compose up mesoworkerservice-db-update

Option 2: Manuelle Ausführung mit docker run

docker run --rm \
  -e ConnectionStrings__ConnectionString="Data Source=SQL-SERVER;Initial Catalog=MesoWorkerDb;User ID=sql-user;Password=***;TrustServerCertificate=true" \
  -e ConnectionStrings__WinLineSystemDBConnectionString="Data Source=SQL-SERVER;Initial Catalog=CWLSYSTEM;User ID=sql-user;Password=***;TrustServerCertificate=true" \
  ghcr.io/css-edv-support/mesoworkerservice-blazor:latest \
  -updateDatabase -forceUpdate -silent

Parameter:

  • -updateDatabase - Startet den Datenbankaktualisierungsmodus
  • -forceUpdate - Erzwingt Update auch wenn Versionen übereinstimmen
  • -silent - Keine Benutzerinteraktion erforderlich

Exit Codes:

  • 0 - Update erfolgreich abgeschlossen
  • 1 - Fehler beim Update
  • 2 - Update nicht erforderlich

Wichtig: Führen Sie das Datenbank-Update vor dem ersten Start der Service- und Blazor-Container durch.

Automatische Datenbankerstellung

Die Datenbank kann auch automatisch erstellt werden, wenn der Datenbankbenutzer die Berechtigung hat, Datenbanken zu erstellen.

Automatischer Prozess:

  1. Der Service prüft beim Start, ob die Datenbank existiert
  2. Falls nicht vorhanden, wird die Datenbank automatisch angelegt
  3. Alle benötigten Tabellen werden erstellt
  4. Standard-Benutzer und -Rollen werden eingerichtet

Wichtig:

  • Stellen Sie sicher, dass der Datenbankbenutzer die Berechtigung hat, Datenbanken zu erstellen
  • Falls dies nicht der Fall ist, erstellen Sie die Datenbank manuell vor dem ersten Start oder verwenden Sie die -updateDatabase Option (siehe Datenbank-Ersteinrichtung)

Für Container-Deployment:

Bei Container-Deployment (insbesondere wenn nur Blazor.Server verwendet wird) empfehlen wir die manuelle Datenbankerstellung mit dem -updateDatabase Parameter. Siehe Datenbank-Ersteinrichtung (Container).

Für Windows-Dienst:

Bei Windows-Dienst-Installation empfehlen wir die Verwendung von MesoWorker.Win.exe -updateDatabase für die initiale Datenbankerstellung. Siehe Datenbank-Ersteinrichtung (Windows).

Benutzeranmeldung

Nach der Datenbankerstellung können Sie sich an den Administrationsoberflächen anmelden.

Standard-Administrator:

  • Benutzername: Admin
  • Passwort: (leer - muss bei erster Anmeldung gesetzt werden)
  • Rolle: Administrators (volle Berechtigungen)

Automatisch erstellte Rollen:

  • Administrators: Vollzugriff auf alle Funktionen
  • Default: Standardrolle für normale Benutzer mit eingeschränkten Rechten

Wichtig: Setzen Sie bei der ersten Anmeldung ein sicheres Passwort für den Admin-Benutzer.

Administrationsoberflächen

Für die Verwaltung und Konfiguration stehen zwei Oberflächen zur Verfügung:

Option A: Blazor Web-Interface

  • URL: http://localhost:5000 (oder konfigurierter Port)
  • Zugriff: Über jeden modernen Webbrowser
  • Vorteile:
    • Plattformunabhängiger Zugriff
    • Ideal für Remote-Administration
    • Moderne Web-Oberfläche
    • Mehrere Administratoren können gleichzeitig arbeiten

Verwendung:

  1. Öffnen Sie einen Webbrowser
  2. Navigieren Sie zu http://localhost:5000 (oder IP-Adresse des Servers)
  3. Melden Sie sich mit Benutzername Admin und gesetztem Passwort an

Option B: Windows Desktop-Client (nur bei Windows-Dienst)

  • Start: MesoWorker.Win.exe
  • Download: MesoWorker.Win (Desktop, Win x64)
  • Zugriff: Direkter Zugriff auf dem Server
  • Vorteile:
    • Erweiterte Desktop-Funktionalität
    • Optimiert für umfangreiche Konfigurationsarbeiten
    • Zusätzliche Administrationsfunktionen

Verwendung:

  1. Starten Sie MesoWorker.Win.exe im Installationsverzeichnis
  2. Melden Sie sich mit Benutzername Admin und gesetztem Passwort an

Datenbank-Update bei Erstinstallation:

Für die initiale Datenbankerstellung verwenden Sie den -updateDatabase Parameter. Siehe Datenbank-Ersteinrichtung (Windows) für detaillierte Anweisungen.

Erste Schritte nach der Anmeldung

Nach der erfolgreichen Anmeldung sollten Sie folgende Schritte durchführen:

  1. Passwort ändern

    • Ändern Sie das Admin-Passwort über die Benutzerverwaltung
    • Empfehlung: Starkes Passwort mit mindestens 12 Zeichen

  2. Lizenz prüfen

    • Überprüfen Sie, ob die Lizenz korrekt hinterlegt ist
    • Der Service zeigt einen Fehler, falls die Lizenz ungültig ist

  3. Datenbankverbindungen testen

    • Stellen Sie sicher, dass beide Datenbanken erreichbar sind
    • WinLine-Daten sollten sichtbar sein

  4. SMTP-Konten einrichten (siehe SMTP-Konten einrichten)

    • Mindestens ein SMTP-Konto für E-Mail-Versand konfigurieren
    • Kennzeichnen Sie ein Konto als Standard-Konto

  5. Mandanten aktivieren

    • Prüfen Sie, welche Mandanten in der Liste angezeigt werden
    • Aktivieren Sie die Mandanten, für die der Service arbeiten soll

Hauptkomponenten

MesoWorkerService besteht aus vier 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: Alle 30 Sekunden (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

  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

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:

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

Beispiel Kurzbeschreibung:

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

Ergebnis: AUF-12345: ART001 Premium-Widget

Konfiguration:

Workflow-Erzeugungseinstellungen werden pro Mandant in der Administrationsoberfläche konfiguriert.

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.

  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: Benutzer/Gruppen aus CrmMehrfacheinträgen
      • Vertreter: Vertreter des zuständigen Benutzers
    • Duplikate werden automatisch entfernt

  4. Termin-Inhalt

    • Betreff und Body mit VariableReplacementService
    • Unterstützt Platzhalter wie {{Fall.Kurzbeschreibung}}, {{Fall.Beschreibung}}
    • 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

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:

  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)

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)

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

Ü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.

  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 bei 30-Sekunden-Mail-Job-Intervall

  3. Warnungs-E-Mail

    • Bei fehlenden E-Mails wird eine Warnung an Administratoren gesendet
    • Enthält detaillierte Liste aller betroffenen Fälle
    • Inkl. Fall-ID, Workflow-Nummer, Kurzbeschreibung und Erstellungsdatum

  4. Duplikats-Schutz

    • Versendete Warnungen werden protokolliert
    • Verhindert mehrfache Warnungen für denselben Fall

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

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)

Mail-Dienst Konfiguration

Dieser Abschnitt beschreibt die detaillierte Konfiguration des Mail-Dienstes. Die Konfiguration erfolgt in der Administrationsoberfläche und umfasst SMTP-Konten, Mail-Einstellungen, Empfängerverwaltung, Vorlagen und Anhänge.

SMTP-Konten einrichten

SMTP-Konten definieren, über welchen E-Mail-Server Nachrichten versendet werden. Sie können mehrere SMTP-Konten einrichten und diese unterschiedlichen Workflows oder Mandanten zuordnen.

SMTP-Konto-Prioritäten:

Das System wählt das SMTP-Konto in folgender Reihenfolge aus:

Priorität 1: Workflow-spezifisches SMTP-Konto

  • Konfiguration: Workflow -> Verwende dieses SMTP Konto
  • Verwendung: Wenn ein spezifischer Workflow ein eigenes SMTP-Konto definiert hat
  • Anwendungsfall: Spezielle Workflows mit besonderen Absenderanforderungen

Priorität 2: Mandanten-spezifisches SMTP-Konto

  • Konfiguration: Mandant -> Verwende dieses SMTP Konto
  • Verwendung: Fallback wenn kein Workflow-spezifisches SMTP-Konto definiert ist
  • Anwendungsfall: Mandanten-spezifische E-Mail-Absender

Priorität 3: Standard-SMTP-Konto

  • Konfiguration: SMTP-Konto mit Standard-Konto = Aktiviert
  • Verwendung: Systemweiter Fallback wenn keine spezifischen Konten definiert sind
  • Anwendungsfall: Allgemeine E-Mail-Versendung

Wichtig: Es muss mindestens ein Standard-SMTP-Konto im System definiert sein.

SMTP-Kontotypen:

Das System unterstützt verschiedene SMTP-Server:

  • Standard-SMTP: Klassische SMTP-Server (z.B. eigener Mailserver, Gmail, etc.)
  • Microsoft 365 mit OAuth: Sichere Authentifizierung über OAuth für M365-Konten

SMTP-Konto erstellen:

  1. Navigieren Sie zu "SMTP Konten" in der Administrationsoberfläche
  2. Erstellen Sie ein neues SMTP-Konto
  3. Konfigurieren Sie die folgenden Einstellungen:
    • Name: Bezeichnung des Kontos
    • E-Mail-Adresse: Absender-Adresse
    • Anzeigename: Name des Absenders
    • SMTP-Server: Hostname des Servers (z.B. smtp.firma.de)
    • Port: SMTP-Port (üblicherweise 587 für STARTTLS, 465 für SSL)
    • Benutzername/Passwort: Anmeldedaten (falls erforderlich)
    • SSL/STARTTLS: Verschlüsselungsoptionen
    • Standard-Konto: Markieren Sie ein Konto als Standard

Mail-Einstellungen

Mail-Einstellungen definieren, wann und wie E-Mails für einen bestimmten Workflow versendet werden. Sie werden pro Mandant und Workflow konfiguriert.

Grundeinstellungen:

Name und Status:

  • Name: Eindeutige Bezeichnung für die Mail-Einstellung
  • Aktiv: Bestimmt, ob diese Einstellung verwendet wird

Standardanrede:

  • Wird verwendet, wenn keine spezifische Anrede ermittelt werden kann
  • Beispiel: "Sehr geehrte Damen und Herren,"

Empfängerverwaltung

Die Empfängerverwaltung bestimmt, wer die E-Mails erhält. Es gibt zwei Systeme: Klassisch und Erweitert.

Klassische Empfängerkonfiguration

Bei der klassischen Konfiguration verwenden Sie einfache Auswahloptionen (Ja/Nein): Kundenempfänger:

  • An Kunden senden: Primäre E-Mail-Adresse des Kunden
  • An Kundenkontakt senden: E-Mail-Adresse des zugewiesenen Ansprechpartners
  • Sende an E-Mail-Adresse für Rechnungsempfang: Spezielle Rechnungs-E-Mail-Adresse
  • Rückfallempfänger Kunde: Fallback auf Kunden-E-Mail wenn Kontakt nicht verfügbar
  • Rückfallempfänger Standardansprechpartner: Fallback auf Standard-Ansprechpartner

Weitere Empfänger:

  • An Vertreter senden: E-Mail an zugewiesenen Vertriebsmitarbeiter
  • Statische Empfänger: Feste E-Mail-Adressen (kommagetrennt)
  • Statische Empfänger BCC: Feste BCC-Empfänger
  • Zusatzempfänger aus Personenkonto: E-Mail-Adressen aus benutzerdefinierten Feldern

Beispiel:

☑ An Kundenkontakt senden
☑ Rückfallempfänger Standardansprechpartner
☑ An Vertreter senden
Statische Empfänger BCC: [email protected]

Ergebnis:

  • Primär: Kundenkontakt-E-Mail
  • Fallback: Standard-Ansprechpartner
  • Zusätzlich: Vertriebsmitarbeiter
  • Immer BCC: [email protected]

Erweiterte Empfängerregeln

Für komplexere Szenarien können Sie erweiterte Empfängerregeln verwenden. Diese bieten ein flexibles Prioritätssystem mit bedingter Logik.

Aktivierung: Aktivieren Sie "Erweiterte Empfängerregeln verwenden" in den Mail-Einstellungen. Die klassischen Optionen werden dann ignoriert.

Regelparameter:

  • Aktiv: Regel ein-/ausschalten
  • Hauptpriorität: Prioritätsgruppen (10=Primär, 15=Zusätzlich, 20=Sekundär, etc.)
  • Verarbeitungsreihenfolge: Feinabstimmung innerhalb derselben Hauptpriorität
  • Verarbeitung bei Treffer stoppen: Stoppt die Regelverarbeitung bei einem Treffer
  • Regeltyp: Art der Empfängerquelle
  • Zustellungsart: To/CC/BCC
  • Separate E-Mails pro Empfänger: Individuelle vs. gruppierte E-Mails
Regeltypen
CustomerContact (Kundenkontakt)
  • Quelle: Zugewiesener Ansprechpartner des Kunden
  • Fallback: Automatisch zum nächsten verfügbaren Kontakt
  • Beispiel: Hauptansprechpartner für Rechnungen
Customer (Kunde)
  • Quelle: Primäre E-Mail-Adresse der Firma
  • Verwendung: Fallback wenn kein Ansprechpartner verfügbar
  • Beispiel: [email protected]
InvoiceEmail (Rechnungs-E-Mail)
  • Quelle: Spezielle E-Mail-Adresse für Rechnungsempfang
  • Verwendung: Oft in bedingter Logik als Hauptempfänger
  • Beispiel: [email protected]
SalesRepresentative (Vertriebsmitarbeiter)
  • Quelle: Zugewiesener Vertriebsmitarbeiter
  • Verwendung: Meist als CC für Information
  • Beispiel: [email protected]

Regeltypen:

  • CustomerContact: Ansprechpartner des Kunden
  • Customer: Primäre E-Mail-Adresse der Firma
  • InvoiceEmail: Spezielle Rechnungs-E-Mail-Adresse
  • SalesRepresentative: Zugewiesener Vertriebsmitarbeiter
  • StaticRecipients: Fest konfigurierte E-Mail-Adressen (kommagetrennt)
  • CustomFieldRecipients: E-Mail-Adressen aus benutzerdefinierten Feldern

Regelbeispiel:

Regel mit Hauptpriorität 10 (primär):

Regel 1: Kundenkontakt, Priorität 10, To
Regel 2: Vertriebsmitarbeiter, Priorität 10, CC

Ergebnis:

  • Kundenkontakt erhält die E-Mail
  • Vertriebsmitarbeiter erhält eine Kopie

Fallback-Regel mit Hauptpriorität 20 (sekundär):

Regel 3: Kunde, Priorität 20, To

Falls kein Kundenkontakt gefunden wird, erhält die Firma die E-Mail.

Hinweis: Die erweiterten Regeln bieten viele weitere Optionen wie bedingte Logik und individuelle E-Mail-Zustellung. Details finden Sie in der erweiterten Dokumentation.

Mail-Vorlagen

Mail-Vorlagen bestimmen den Inhalt der versendeten E-Mails. Es gibt zwei Methoden:

Textbausteine mit Platzhaltern

Einfache Textbausteine mit dynamischen Platzhaltern für Workflow-Daten.

Verfügbare Platzhalter:

Alle Eigenschaften des Workflow-Objekts können verwendet werden:

  • {{Kurzbeschreibung}} - Workflow-Kurzbeschreibung
  • {{LangbeschreibungExtern}} - Externe Langbeschreibung
  • {{OpNummer}} - Workflow-Nummer
  • {{AktuellsterBeleg.DatumFaktura:dd.MM.yyyy}} - Rechnungsdatum formatiert
  • {{AktuellsterBeleg.Endbetrag:C2}} - Rechnungsbetrag als Währung
  • {{Kunde.Kontoname1}} - Firmenname des Kunden
  • {{Projekt.Bezeichnung1}} - Projektbezeichnung
  • {{DatumSchrittGeschrieben:dd.MM.yyyy}} - Fallerfassungsdatum

Beispiel-Template:

##Empfaenger##

im Anhang finden Sie Ihre Rechnung {{OpNummer}} vom {{AktuellsterBeleg.DatumFaktura:dd.MM.yyyy}}.
Der Gesamtbetrag beträgt {{AktuellsterBeleg.Endbetrag:C2}}.

{{LangbeschreibungExtern}}

##Anlagen##

Hinweis: Sie können auf alle Eigenschaften und verschachtelte Objekte zugreifen (z.B. {{Kunde.Adresse.Strasse1}}, {{Projekt.Bezeichnung1}}). Formatierung erfolgt über Standard-.NET-Formatstrings.

Rich-Text-Vorlagen (MailMerge)

Erweiterte Vorlagen mit Formatierung, Tabellen, Bildern und bedingter Logik.

Erstellung:

  1. Navigieren Sie zu "Mail Vorlagen" in der Administrationsoberfläche
  2. Erstellen Sie eine neue RichTextMailMergeData-Vorlage
  3. Gestalten Sie Inhalte im Rich-Text-Editor
  4. Fügen Sie Mail-Merge-Felder über das Ribbon-Menü ein
  5. Weisen Sie die Vorlage in den Mail-Einstellungen zu

Features:

  • Formatierung (Schriftarten, Farben, Tabellen)
  • Erweiterte Platzhalter mit Objektnavigation
  • Bedingte Logik (If-Then-Else)
  • Schleifen für Wiederholungen
  • Eingebettete Bilder und Logos

Anhangsverwaltung

Die Anhangsverwaltung steuert, welche Dokumente an E-Mails angehängt werden.

Quellen für Anhänge:

  • Workflow-Uploads: Dokumente, die im Workflow hochgeladen wurden
  • Beleg-Anhänge: Dokumente aus verknüpften Belegen (z.B. Rechnungen, Lieferscheine)
  • Archivformular-Filter: Nur Dokumente mit bestimmten Archivformularen

Konfigurationsoptionen:

Grundoptionen:

  • Anhänge einschließen: Aktiviert die Anhangsfunktion
  • Nur mit Anhängen: E-Mail wird nur versendet, wenn Anhänge vorhanden sind
  • Archivformular-Filter: Wählt spezifische Archivformular-Typen aus

Validierungsoptionen:

  • Überspringe bei fehlendem Archivformular-Anhang: Verhindert Versand, wenn erforderliche Archivformular-Anhänge fehlen
  • Überspringe bei fehlendem Beleg-Anhang: Verhindert Versand, wenn Beleg-Anhänge fehlen

Anwendungsbeispiele:

  • Rechnungsversand: Nur senden, wenn PDF-Rechnung vorhanden ist
  • Auftragsbestätigung: Nur mit Auftragsformular
  • Lieferbenachrichtigung: Nur mit Lieferschein

Workflow-Filter

Workflow-Filter bestimmen, welche Workflows verarbeitet werden. Sie können zeitbasierte Filter verwenden.

Zeitbasierte Filter:

Option 1: Zeitraum-Filter (Since)

  • Verarbeitet Workflows der letzten X Stunden/Tage
  • Format: TimeSpan (z.B. "1.00:00:00" für 1 Tag)
  • Beispiel: Nur Workflows der letzten 24 Stunden

Option 2: Datum-Filter (After)

  • Verarbeitet alle Workflows ab einem festen Datum
  • Format: DateTime (z.B. "01.01.2024")
  • Beispiel: Alle Workflows seit Jahresbeginn

Option 3: Logischer Zeitbereich-Filter (Time Range)

  • Verarbeitet Workflows basierend auf logischen Zeiträumen
  • Verfügbare Zeiträume:
    • Dieses Jahr
    • Dieser Monat
    • Dieses Quartal
    • Diese Woche
    • Heute
    • Seit gestern
  • Vorteil: Keine Wartung fester Datumswerte erforderlich
  • Beispiel: "Dieser Monat" verarbeitet automatisch alle Workflows seit dem 1. des aktuellen Monats

Filter-Priorität:

  1. Zeitraum-Filter (aktiv) wird zuerst geprüft
  2. Falls nicht aktiv: Datum-Filter
  3. Falls nicht aktiv: Logischer Zeitbereich-Filter
  4. Fallback: Alle Workflows seit 1970

Wichtig: Es kann immer nur ein Filter aktiv sein. Aktivieren Sie nur den Filter, der Ihren Anforderungen entspricht.

Betrieb und Wartung

Dieser Abschnitt beschreibt den laufenden Betrieb und die Wartung des MesoWorkerService.

Mail-Journal

Das Mail-Journal protokolliert alle versendeten und fehlgeschlagenen E-Mails.

Zugriff: Navigieren Sie in der Administrationsoberfläche zu "Queued Mail" oder "Mail Journal".

Informationen im Journal:

  • Zeitstempel des Versands/Fehlers
  • Empfänger (To, CC, BCC)
  • Betreff
  • Status (versendet, fehlgeschlagen, wartend)
  • Fehlermeldungen (bei fehlgeschlagenen E-Mails)
  • Verknüpfter Workflow

Verwendung:

  • Überprüfen Sie regelmäßig das Journal auf fehlgeschlagene E-Mails
  • Analysieren Sie Fehlermeldungen bei Problemen
  • Überwachen Sie die Zustellungsrate

Fehlerbenachrichtigungen

Der Service benachrichtigt Administratoren automatisch bei Problemen.

Konfiguration: Admin-E-Mail-Adressen werden in den Mail-Einstellungen (appsettings.json oder Umgebungsvariablen) konfiguriert:

"MailSettings": {
  "AdminMailRecipients": ["[email protected]", "[email protected]"]
}

Benachrichtigungsfälle:

  • E-Mail konnte nicht versendet werden
  • SMTP-Server ist nicht erreichbar
  • Authentifizierung fehlgeschlagen
  • Lizenz ist ungültig oder abgelaufen

Protokollierung

Der Service erstellt detaillierte Protokolldateien für Diagnose und Überwachung.

Protokolldateien:

  • Windows-Dienst: Logs/MesoWorkerService-[Datum].txt
  • Container: Ausgabe über Docker Logs (docker logs mesoworkerservice)

Protokollierungsstufen:

  • Information: Normale Betriebsmeldungen
  • Warning: Warnungen (z.B. fehlende Empfänger)
  • Error: Fehler (z.B. Datenbankverbindung fehlgeschlagen)
  • Debug: Detaillierte Debug-Informationen (nur für Fehlersuche)

Konfiguration: Protokollierungsstufen können in appsettings.json oder Umgebungsvariablen angepasst werden:

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.Hosting.Lifetime": "Information"
  }
}

Best Practices:

  • Überprüfen Sie Protokolle regelmäßig auf Fehler und Warnungen
  • Behalten Sie "Information" als Standard-Protokollierungsstufe
  • Verwenden Sie "Debug" nur zur Fehlersuche (erzeugt viele Einträge)
  • Archivieren Sie alte Protokolldateien regelmäßig

Wartungsaufgaben

Regelmäßige Aufgaben:

  1. Mail-Journal prüfen (täglich)

    • Überprüfen Sie fehlgeschlagene E-Mails
    • Analysieren Sie Trends bei Fehlern

  2. Stammdaten pflegen (wöchentlich)

    • Aktualisieren Sie E-Mail-Adressen von Kunden
    • Überprüfen Sie Ansprechpartner-Daten

  3. SMTP-Konten überwachen (wöchentlich)

    • Testen Sie SMTP-Verbindungen
    • Überprüfen Sie OAuth-Token (M365)

  4. Protokolldateien prüfen (wöchentlich)

    • Suchen Sie nach wiederkehrenden Fehlern
    • Überprüfen Sie Performance-Warnungen

  5. Service-Status überwachen (täglich)

    • Health-Check-Endpoint aufrufen: http://server:5000/health
    • Windows-Dienst-Status prüfen

  6. Updates einspielen (nach Bedarf)

    • Neue Container-Images deployen
    • Windows-Dienst aktualisieren
    • Konfigurationsänderungen testen

Troubleshooting:

Problem: E-Mails werden nicht versendet

  • Überprüfen Sie Mail-Journal auf Fehler
  • Prüfen Sie SMTP-Konto-Einstellungen
  • Testen Sie SMTP-Server-Erreichbarkeit
  • Überprüfen Sie Workflow-Filter-Einstellungen

Problem: Keine Empfänger gefunden

  • Überprüfen Sie Kundenstamm-Daten (E-Mail-Adressen)
  • Prüfen Sie Empfängerregeln in Mail-Einstellungen
  • Überprüfen Sie Ansprechpartner-Zuweisungen

Problem: Service startet nicht

  • Überprüfen Sie Lizenz-Einstellungen
  • Prüfen Sie Datenbankverbindungen
  • Kontrollieren Sie Protokolldateien

Überwachungsdienst - Erweiterte Konfiguration

Der Überwachungsdienst wurde bereits im Abschnitt Hauptkomponenten beschrieben. Dieser Abschnitt enthält zusätzliche Details zur Konfiguration und Fehlerbehebung.

Konfigurationsdetails

Container-Konfiguration

environment:
  # No-Rule Warning Job
  - Quartz__NoRuleWarningJob__scheduler=0 0 8 * * ?
  - Quartz__NoRuleWarningJob__enabled=true
  - Quartz__NoRuleWarningJob__startnow=false

Anwendungsfälle

Der No-Rule Warning Service hilft bei der Erkennung verschiedener Probleme:

1. Fehlende Stammdaten

Problem: Für einen Kunden ist keine E-Mail-Adresse hinterlegt.
Ergebnis: Keine Mail wird versendet.
Lösung: Warnung identifiziert fehlende Stammdaten, sodass Daten nachgepflegt werden können.

2. Fehlkonfiguration

Problem: Mail-Einstellungen sind nicht korrekt konfiguriert (z.B. falsche Empfänger-Regeln).
Ergebnis: Keine Mail wird versendet.
Lösung: Warnung zeigt Konfigurationsprobleme, sodass Einstellungen korrigiert werden können.

3. Zu restriktive Filter-Kriterien

Problem: Filter-Kriterien selektieren keine Fälle.
Ergebnis: Keine Mail wird versendet.
Lösung: Warnung macht auf Filter-Probleme aufmerksam, sodass Filter angepasst werden können.

Duplikatsverhinderung

Der Service protokolliert versendete Warnungen in der Datenbank:

  • Jeder gewarnter Fall wird mit Fall-ID, Schritt-Nummer und Workflow-Nummer gespeichert
  • Verhindert mehrfache Warnungen für denselben Fall
  • Protokollierung erfolgt nur bei erfolgreichem E-Mail-Versand
  • Ermöglicht Nachverfolgung der Warnungshistorie

Best Practices

  1. Zeitraum (LookbackPeriod):

    • Wählen Sie einen angemessenen Zeitraum (z.B. 24 Stunden)
    • Zu kurze Zeiträume: Wichtige Fälle könnten übersehen werden
    • Zu lange Zeiträume: Zu viele Warnungen für bereits bekannte Probleme

  2. Grace Period:

    • Setzen Sie auf mindestens das 2-3-fache des Mail-Dienst-Intervalls
    • Standard-Empfehlung: 15-20 Minuten
    • Bei sehr frequenten Mail-Dienst-Ausführungen: 20-30 Minuten
    • Verhindert Fehlalarme für gerade in Bearbeitung befindliche Workflows

  3. Empfänger (WarningRecipients):

    • Konfigurieren Sie administrative E-Mail-Adressen
    • Stellen Sie sicher, dass E-Mails regelmäßig geprüft werden
    • Verwenden Sie Verteiler für Team-Benachrichtigungen

  4. Ausführungshäufigkeit (Scheduler):

    • Täglich um 8:00 Uhr (Standard) für normale Überwachung
    • Mehrmals täglich für kritische Workflows
    • Passen Sie die Cron-Expression an Ihre Anforderungen an

  5. SMTP-Konto:

    • Verwenden Sie ein dediziertes SMTP-Konto für Warnungen
    • Stellt separate Nachverfolgung und Zustellung sicher
    • Fallback auf Standard-SMTP-Konto funktioniert automatisch

Troubleshooting

Problem: Warnungen werden nicht versendet

Mögliche Ursachen:

  • Enabled ist auf false gesetzt
  • Keine gültigen Empfänger konfiguriert (WarningRecipients leer oder ungültig)
  • SMTP-Konto nicht verfügbar oder falsch konfiguriert
  • Job ist in appsettings.json deaktiviert (enabled: false)
  • Cron-Expression ist fehlerhaft

Lösungsschritte:

  1. Überprüfen Sie die Logs nach Fehler-Meldungen
  2. Prüfen Sie die Konfiguration in der Administrationsoberfläche
  3. Testen Sie das SMTP-Konto mit einer Test-Mail
  4. Validieren Sie die Cron-Expression mit einem Online-Tool

Problem: Zu viele Warnungen

Mögliche Ursachen:

  • Der LookbackPeriod ist zu groß (z.B. 7 Tage statt 1 Tag)
  • Die GracePeriod ist zu klein (z.B. 2 Minuten statt 15 Minuten)
  • Viele Workflows haben tatsächliche Konfigurationsprobleme
  • Der Dienst läuft zu häufig (mehrmals stündlich)

Lösungsschritte:

  1. Reduzieren Sie den LookbackPeriod (z.B. auf 24 Stunden)
  2. Erhöhen Sie die GracePeriod (z.B. auf 20-30 Minuten)
  3. Beheben Sie die zugrunde liegenden Konfigurationsprobleme
  4. Passen Sie die Ausführungshäufigkeit an (z.B. nur 1x täglich)

Problem: Duplikate werden versendet

Mögliche Ursachen:

  • E-Mail-Versand schlägt fehl (keine Protokollierung)
  • Datenbank-Commit schlägt fehl
  • Transaktion wird zurückgerollt

Lösungsschritte:

  1. Überprüfen Sie die Logs auf Fehler beim E-Mail-Versand
  2. Prüfen Sie die Datenbank-Verbindung
  3. Kontrollieren Sie die Protokollierungstabelle auf Einträge
  4. Testen Sie mit einem einzelnen Fall

Problem: Grace Period funktioniert nicht

Mögliche Ursachen:

  • Grace Period ist auf 0 oder sehr klein gesetzt
  • Der Mail-Dienst läuft sehr selten
  • Systemzeit ist nicht synchronisiert

Lösungsschritte:

  1. Setzen Sie Grace Period auf mindestens 15 Minuten
  2. Überprüfen Sie die Mail-Dienst-Konfiguration
  3. Validieren Sie die Systemzeit auf allen Servern
  4. Prüfen Sie die SQL-Query in den Logs

Migration und Einrichtung

Bei der ersten Verwendung des Überwachungsdienstes:

  1. Automatische Datenbankerstellung: Die Tabellen werden automatisch erstellt
  2. Konfiguration erstellen: In der Admin-Oberfläche neue Überwachungseinstellungen für gewünschte Mandanten anlegen
  3. Job aktivieren: In appsettings.json oder Container-Umgebungsvariablen aktivieren
  4. Erste Ausführung: Optional startnow: true setzen für sofortigen Test
  5. Monitoring: Logs überprüfen nach erfolgreicher Ausführung

Hinweis: Es sind keine manuellen Migrationsschritte erforderlich. Alle benötigten Tabellen werden automatisch erstellt.

Versionshistorie

Version 2.4.1 (Januar 2026)

💎 Added

  • Neue Einstellung "Warte auf Beleg-Workflow" für Auftragszeilen-Workflow-Erzeugung
    • Neue Option WaitForVoucherWorkflow in OrderLineWorkflowSettings
    • Verhindert die Erzeugung von Belegzeilen-Workflows, wenn noch kein Beleg-Workflow existiert
    • Nicht verarbeitete Zeilen werden beim nächsten Job-Lauf automatisch erneut geprüft
    • Ermöglicht sequentielle Workflow-Erzeugung: zuerst Beleg-Workflow, dann Zeilen-Workflows
    • Funktioniert unabhängig von der bestehenden LinkVoucherWorkflowAsParent Option
    • Detailliertes Logging für übersprungene Belegzeilen

Version 2.4.0 (Januar 2026)

💎 Added

  • Modul-basierte Lizenzierung: WorkerService unterstützt jetzt modulare Lizenzierung
    • Drei separate Module können individuell lizenziert werden:
      • MESO-WSMAIL: Mailservice (aktiviert MailWorkerJob und NoRuleWarningJob)
      • MESO-WSBELEG: Belegzeilenworkflows (aktiviert OrderLineWorkerJob)
      • MESO-WSGRAPH: Graph API Terminabgleich (aktiviert AppointmentWorkerJob)
    • Automatische Erkennung lizenzierter Module beim Start
    • Jobs werden nur aktiviert wenn das entsprechende Modul lizenziert ist
    • Detailliertes Logging zeigt welche Module lizenziert sind und welche Jobs aktiviert werden
    • Basis-Produkt MESO-WorkerService weiterhin erforderlich

Version 2.3.0 (Januar 2026)

💎 Added

  • Terminsynchronisation über MS Graph API: Neue Funktion zur automatischen Erstellung von Kalender-Terminen aus CRM-Einträgen
    • Flexible Workflow-Selektion mit optionalen Filtern für präzise CRM-Eintrags-Auswahl
    • Konfigurierbare Datumsfeld-Zuordnung (Start-/Enddatum, Kalenderstart-/-enddatum, Eskalationsdatum, Erfassungsdatum)
    • Optional: Zeitdauer-Addition zu ermittelten Datumsfeldern
    • Ganztags-Termin-Option steuerbar über konfigurierbare CRM-Eigenschaft
    • Flexible Empfänger-Ermittlung über eMail-Adressen:
      • Verfassender Benutzer des Workflows
      • Delegiert an Benutzer
      • Delegiert an Gruppe (alle Gruppenmitglieder)
      • XRM-Einträge (CrmMehrfacheinträge mit 1:N Benutzern oder Gruppen)
      • Vertreter des zugewiesenen Benutzers
      • Kombinationen mehrerer Quellen möglich
    • Betreff und Body mit VariableReplacementService für dynamische Inhalte
    • Optionale Fall-Anhänge mit Filterung nach Archiv-Formular-ID
    • Journal zur Dokumentation erstellter Termine mit Graph Event IDs
    • Optionale Rücksynchronisation von Terminänderungen aus Exchange zurück in CRM:
      • Konfigurierbar mit Zeithorizont (z.B. 7 Tage)
      • Nur verfügbar wenn ein CRM-Eintrag zu einem einzelnen Termin führte
      • Synchronisiert Änderungen an Datum, Betreff und Body zurück in entsprechende CRM-Felder
    • Authentifizierung über Azure AD Client Credentials (App-only)
    • Termine werden in persönlichen Kalendern der Empfänger erstellt
    • Automatische Ausführung alle 10 Minuten (konfigurierbar)
    • Umfassende Fehlerbehandlung und Protokollierung

Version 2.2.4 (Januar 2026)

💎 Added

  • Workflow-Erzeugung aus Bestelldateizeilen: Neue Optionen zum Anfügen von Anhängen
    • AttachVoucherDocument: Fügt das Beleg-Dokument aus der ArchivId der Belegstufe als Anhang zum erzeugten CRM-Fall hinzu
    • AttachVoucherAttachments: Fügt alle Beleganhänge aus der DokumentenId als Anhänge zum CRM-Fall hinzu
    • AttachParentWorkflowAttachments: Kopiert Anhänge vom übergeordneten CRM-Fall (bei aktiviertem LinkVoucherWorkflowAsParent)
    • Automatische Duplikatserkennung verhindert mehrfaches Anfügen derselben Dokumente
    • Umfassende Fehlerbehandlung und Protokollierung für robuste Dokumentenverarbeitung

Version 2.2.3 (Dezember 2025)

🐛 Fixed

  • EML-Generierung bei Änderung von QueuedMail-Entwürfen: RTF-Formatierung bleibt erhalten
    • Beim Ändern des Body einer QueuedMail (Draft) wird RTF nun korrekt zu HTML konvertiert
    • Verhindert, dass RTF-Code in der EML-Datei erscheint
    • Formatierungen (Fett, Kursiv, Absätze etc.) bleiben erhalten
    • Verwendet RichEditDocumentServer für präzise RTF-zu-HTML-Konvertierung

Version 2.2.2 (Dezember 2025)

Neue Funktionen:

  • Schnellstart-Sektion in README.MD: Neue übersichtliche Schritt-für-Schritt-Anleitung zur Inbetriebnahme
    • Klare Darstellung der erforderlichen Reihenfolge: Datenbank erstellen, ConnectionStrings konfigurieren, Service starten
    • Beide Deployment-Optionen (Windows und Container) im Schnellstart abgedeckt
    • Wichtige Hinweise und Tipps zur korrekten Installation

Verbesserungen:

  • README.MD-Struktur verbessert: Installation und Ersteinrichtung umstrukturiert
    • Datenbank-Ersteinrichtung als kritischer erster Schritt deutlich hervorgehoben
    • Warnhinweise an allen relevanten Stellen hinzugefügt
    • Verweise auf Schnellstart-Sektion für schnelle Orientierung
    • Verbesserte Navigation durch aktualisiertes Inhaltsverzeichnis

Version 2.2.1 (Dezember 2025)

Neue Funktionen:

  • Deutsche Übersetzungen für die Administrationsoberfläche: Alle fehlenden Beschriftungen wurden ins Deutsche übersetzt
    • Workflow-Protokoll aus Bestelldateizeilen: Vollständige Übersetzung aller Felder
    • Workflow-Einstellungen: Vollständige Übersetzung aller Felder
    • Mail-Anhänge: Vollständige Übersetzung hinzugefügt
    • Verbesserte Benutzerfreundlichkeit der Administrationsoberfläche

Version 2.2.0 (Dezember 2025)

Neue Funktionen:

  • Workflow-Erzeugung aus Bestelldateizeilen: Neue Funktion zur automatischen CRM-Fall-Erzeugung auf Basis von Belegzeilen
    • Automatische Workflow-Generierung aus Bestelldateizeilen
    • Flexible Filterkriterien für präzise Zeilenselektion
    • Verhindert Mehrfachverarbeitung durch intelligente Protokollierung
    • Optionale Speicherung der erzeugten Fall-ID in benutzerdefinierter Spalte
    • Konfigurierbar über die Administrationsoberfläche
    • Automatische Ausführung alle 5 Minuten (konfigurierbar)
    • Umfassende Fehlerbehandlung und Protokollierung
  • Konfigurierbare Datumsfelder für Workflows aus Bestelldateizeilen
    • Wahl zwischen Standard-Datumsfeldern und Kalender-Datumsfeldern
    • Standardmäßig deaktiviert für Abwärtskompatibilität

Fehlerbehebungen:

  • Deutsche Sprachressourcen im Container-Deployment
    • Deutsche Sprachauswahl in der Administrationsoberfläche funktioniert nun korrekt im Container

Version 2.1.1 (Dezember 2025)

Fehlerbehebungen:

  • Thread-Safety-Problem im Mail-Dienst behoben

Version 2.1 (November 2025)

Neue Funktionen:

  • Automatische EML-Neuerzeugung für Entwürfe im Postausgang
    • Automatische Regenerierung bei Änderungen an Empfänger, Betreff, Text, CC und BCC
    • Erhaltung der bestehenden Anhänge beim Regenerieren
    • Funktioniert nur bei E-Mails mit aktiviertem Entwurf-Status
    • Nahtlose Integration in die Detailansicht des Postausgangs
  • Logische Zeitbereiche für Workflow-Filterung
    • Unterstützte Zeitbereiche: Dieses Jahr, Dieser Monat, Dieses Quartal, Diese Woche, Heute, Seit gestern
    • Automatische Berechnung des Startdatums basierend auf dem gewählten Zeitbereich
    • Kompatibel mit bestehenden Filter-Optionen
    • Vereinfachte Konfiguration ohne Wartung fester Datumswerte
  • Überwachungsdienst für fehlende E-Mail-Versendungen
    • Mandantenspezifische Konfiguration mit flexiblen Zeiträumen
    • Grace Period zur Vermeidung von Fehlalarmen für gerade verarbeitete Workflows
    • Automatische Duplikatsverhinderung durch Protokollierung
    • HTML-formatierte Warnungs-E-Mails mit detaillierter Fall-Auflistung
    • Konfigurierbare Empfänger und optionale SMTP-Konten
    • Zeitplanbasierte Ausführung mit konfigurierbaren Intervallen
    • Umfassende Fehlerbehandlung und Protokollierung

Version 2.0 (Oktober 2025)

Neue Funktionen:

  • Erweiterte Empfängerregeln mit Prioritätssystem
  • Bedingte Zustellungslogik
  • Individuelle E-Mail-Zustellung pro Empfänger
  • Microsoft 365 OAuth-Authentifizierung für SMTP
  • Container-Support mit Docker Images
  • Health-Checks für Monitoring

Verbesserungen:

  • Migration auf .NET 9
  • Modernisierung der Software
  • Verbesserung der Administrationsoberfläche

Fehlerbehebungen:

  • Diverse Fehlerbehebungen im Mail-Versand
  • Verbesserungen der Anhangsverwaltung

Downloads

Download dieser Dokumentation als PDF

Softwaredownloads:

Support und Kontakt

Bei Fragen oder Problemen wenden Sie sich an das CSS EDV Support Team:

CSS EDV Support GmbH
Ihr Partner für professionelle EDV-Lösungen

Website: https://css-edv-support.de
Dokumentation erstellt von CSS EDV Support Tobias Forbrich e.K. - November 2025

Version: 2.1
Erstellt: 2024
Aktualisiert: J2025

nach oben