Direkt zum Hauptinhalt

MESO-WorkerService

CSS EDV Support Logo

Automatisierungsdienst für Mesonic WinLine Hintergrunddienst zur Automatisierung von E-Mail-Versand, Workflow-Verwaltung und Überwachung in WinLine-Umgebungen.

Ü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 drei 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. Ü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-  │  │ Überwachungs-  │
    │              │  │  Erzeugung  │  │    dienst      │
    └──────────────┘  └─────────────┘  └────────────────┘
            │               │               │
            └───────────────┼───────────────┘
                            ▼
            ┌───────────────────────────────┐
            │   WinLine Datenbanken         │
            │   • CWLSYSTEM                 │
            │   • Mandanten-DB              │
            └───────────────────────────────┘
                            │
                            ▼
            ┌───────────────────────────────┐
            │   Anwendungsdatenbank         │
            │   (MesoWorkerDb)              │
            │   • Konfiguration             │
            │   • Mail-Journal              │
            │   • Protokollierung           │
            └───────────────────────────────┘

Administrationsoberflächen:

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

Eine detaillierte Architekturübersicht finden Sie in Systemarchitektur

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

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.

Voraussetzungen:

  • Windows Server 2016 oder neuer
  • .NET 9 Runtime installiert
  • Netzwerkzugriff zur WinLine-Datenbank

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. 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
    • Die Konfigurationsdatei appsettings.json muss vor der Installation konfiguriert sein
    • Für weitere Unterstützung kontaktieren Sie den Support: [email protected]

  3. Konfigurationsdatei anpassen

    Öffnen Sie die Datei appsettings.json im Installationsverzeichnis und passen Sie die Einstellungen an (siehe Windows-Dienst Konfiguration).

  4. Datenbank bei Erstinstallation erstellen

    Bei der Erstinstallation muss die Datenbank initialisiert werden. Siehe Datenbank-Ersteinrichtung (Windows) für detaillierte Anweisungen.

  5. Dienst starten

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

    Start-Service MesoWorkerService

Vorteile:

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

Nachteile:

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

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. Stack-Datei erstellen

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

  3. Umgebungsvariablen konfigurieren

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

  4. Datenbank bei Erstinstallation erstellen

    Bei der Erstinstallation muss die Datenbank initialisiert werden. Siehe Datenbank-Ersteinrichtung (Container) für detaillierte Anweisungen.

  5. Container starten

    Mit Docker Compose:

    docker-compose up -d

    Mit Portainer:

    • Stack in Portainer importieren
    • Umgebungsvariablen anpassen
    • Stack deployen

Vorteile:

  • 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:

  • 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
    }
  },
  "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 mit 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
      
      # 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 0 8 * * ? = Täglich um 8:00 Uhr (Überwachungsdienst)

Ersteinrichtung

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.

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
    • Erweiterte Entwicklertools (falls benötigt)

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 drei 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

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 unter "Order Line Workflow Settings" konfiguriert.

Ü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 (No-Rule Warning Service)

Der Überwachungsdienst wurde bereits im Abschnitt Hauptkomponenten beschrieben. Dieser Abschnitt enthält zusätzliche technische 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 → Daten können nachgepflegt werden.

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 → Einstellungen können korrigiert werden.

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 → Filter können angepasst werden.

Duplikatsverhinderung

Der Service protokolliert versendete Warnungen in der NoRuleWarningJournal-Tabelle:

  • 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 MailWorkerJob-Intervalls
    • Standard-Empfehlung: 15-20 Minuten
    • Bei sehr frequenten MailWorkerJob-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:

  • ✗ LookbackPeriod ist zu groß (z.B. 7 Tage statt 1 Tag)
  • ✗ GracePeriod ist zu klein (z.B. 2 Minuten statt 15 Minuten)
  • ✗ Viele Workflows haben tatsächliche Konfigurationsprobleme
  • ✗ Job 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 Job-Häufigkeit an (z.B. nur 1x täglich)

Problem: Duplikate werden versendet

Mögliche Ursachen:

  • ✗ E-Mail-Versand schlägt fehl (keine Journal-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 NoRuleWarningJournal-Tabelle 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
  • ✗ MailWorkerJob läuft sehr selten
  • ✗ Systemzeit ist nicht synchronisiert

Lösungsschritte:

  1. Setzen Sie Grace Period auf mindestens 15 Minuten
  2. Überprüfen Sie die MailWorkerJob-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 No-Rule Warning Service:

  1. Automatische Datenbankerstellung: Die Tabellen NoRuleWarningSettings und NoRuleWarningJournal werden automatisch erstellt
  2. Konfiguration erstellen: In der Admin-Oberfläche neue NoRuleWarningSettings 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. Das DevExpress XAF Framework erstellt alle benötigten Tabellen automatisch.

Versionshistorie

Version 2.2.1 (Dezember 2025)

Added:

  • Deutsche Übersetzungen für XAF Model: Alle fehlenden BusinessObject-Beschriftungen wurden ins Deutsche übersetzt
    • OrderLineWorkflowJournal: Vollständige Übersetzung aller Eigenschaften
    • OrderLineWorkflowSettings: Vollständige Übersetzung aller Eigenschaften
    • MailAttachment: Vollständige Übersetzung hinzugefügt
    • Verbesserte Benutzerfreundlichkeit der Administrationsoberfläche

Version 2.2.0 (Dezember 2025)

Added:

  • 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
    • Journal-basierte Mehrfachverarbeitungs-Prävention
    • Optionale Speicherung der erzeugten Fall-ID in benutzerdefinierter Spalte
    • Konfigurierbar über bestehende WorkflowSettings-Infrastruktur
    • Neuer OrderLineWorkerJob mit Standard-Schedule alle 5 Minuten
    • Umfassende Fehlerbehandlung und Logging
    • Wiederverwendung bestehender Workflow-Business-Logik
  • Konfigurierbare Datumsfelder für OrderLine-Workflows
    • Neue Eigenschaft UseDatevarianteKalender in OrderLineWorkflowSettings
    • Wahl zwischen Standard-Datumsfeldern und Kalender-Datumsfeldern
    • Standardmäßig deaktiviert für Abwärtskompatibilität

Fixed:

  • Deutsche Sprachressourcen im Blazor Docker Container
    • Hinzufügen von SatelliteResourceLanguages=de zu allen relevanten Projekten
    • Sicherstellen, dass DevExpress .de NuGet-Pakete korrekt als Satellite Assemblies publiziert werden
    • Deutsche Sprachauswahl in XAF Anwendungen funktioniert nun korrekt im Container

Version 2.1.1 (Dezember 2025)

Fixed:

  • Thread-Safety-Problem im MailWorkerJob behoben

Version 2.1 (November 2025)

Added:

  • 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 Draft-Status
    • Nahtlose Integration in die Detailansicht von QueuedMail
  • 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
  • No-Rule Warning Service
    • Mandantenspezifische Konfiguration mit flexiblen Zeiträumen
    • Grace Period zur Vermeidung von Race Conditions mit MailWorkerJob
    • Automatische Duplikatsverhinderung durch Journal-Protokollierung
    • HTML-formatierte Warnungs-E-Mails mit detaillierter Fall-Auflistung
    • Konfigurierbare Empfänger und optionale SMTP-Konten
    • Quartz-basierte Job-Planung mit Cron-Expressions
    • Umfassende Fehlerbehandlung und Logging

Version 2.0 (Oktober 2025)

Added:

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

Refactoring:

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

Fixed:

  • Diverse Bugfixes 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: November 2025

nach oben