Skip to main content

MESO Archivimport

Windows-Service zum automatisierten Import von Dokumenten in das MESONIC-Archiv.

Download aktuelle Version (ZIP)

Funktionsweise

Der Service importiert Dateien aus einem konfigurierbaren Importverzeichnis in das MESONIC-Archiv. Die erlaubten Dateitypen sind über FileFilter konfigurierbar (Standard: *.pdf). Es werden zwei Verzeichnistypen unterstützt:

  • Reguläre Verzeichnisse: Direkte Unterverzeichnisse von ImportPath. Der Verzeichnisname muss exakt der Bezeichnung eines Archiv-Formulars in MESONIC entsprechen.
  • Erkennungsverzeichnisse: Unterverzeichnisse, die einem Objekttyp zugeordnet sind (Belege, Artikel, Personenkonten). Diese enthalten Formular-Unterverzeichnisse, deren Name dem Archiv-Formular entspricht.

Betriebsmodi

  • Batch-Modus (Watch: false): Verarbeitet alle vorhandenen Dateien einmalig und beendet sich danach.
  • Watch-Modus (Watch: true): Verarbeitet vorhandene Dateien und überwacht das Importverzeichnis dauerhaft auf neue Dateien. Neue Dateien werden automatisch erkannt. Falls eine Datei noch gesperrt ist (z.B. laufender Kopiervorgang), werden bis zu 10 Versuche im Abstand von 500ms unternommen.

Objekterkennung

Der Service unterstützt drei Objekttypen. Die Zuordnung erfolgt über konfigurierbare Erkennungsverzeichnisse:

Objekttyp Standard-Verzeichnis MesoXPO-Klasse Suchfeld
Belege Belege BestelldateiKopf Belegkey (Kontonummer-Laufnummer) oder Belegnummer
Artikel Artikel ArtikelStammdatei Artikelnummer
Personenkonten Personenkonten ViewKontenstamm Kontonummer

Dateien in regulären Verzeichnissen (die keinem Objekttyp zugeordnet sind) werden ohne Objekterkennung importiert - Schlagwortdateien funktionieren weiterhin.

Wichtig: Dateien dürfen nicht direkt in einem Erkennungsverzeichnis liegen, sondern müssen sich in einem Formular-Unterverzeichnis befinden. Dateien direkt in z.B. Belege\ werden mit einer Warnung übersprungen.

Verzeichnis-Erkennung (optional)

Alternativ zur Identifier-Extraktion aus dem Dateinamen (per Regex) kann der Identifier auch über den Verzeichnisnamen ermittelt werden. Dazu werden Dateien in ein Unterverzeichnis des Formular-Verzeichnisses gelegt, dessen Name dem Objekt-Identifier entspricht:

Belege\Laborbericht\12000-156A\scan.pdf

Hier wird 12000-156A als Identifier aus dem Verzeichnisnamen übernommen - unabhängig vom Dateinamen. Das ist nützlich wenn:

  • Dateinamen keine auswertbare Struktur haben (z.B. scan001.pdf)
  • Mehrere Dateien demselben Objekt zugeordnet werden sollen
  • Die Zuordnung manuell über die Ablagestruktur gesteuert werden soll

Die Verzeichnis-Erkennung hat Vorrang vor der Regex-Extraktion. Sie funktioniert in allen Modi (Batch, Watch, Mandantenverzeichnisse).

Verzeichnisstruktur

C:\Archivimport\
  Belege\                          <-- Erkennungsverzeichnis (Objekttyp: Beleg)
    Laborbericht\                  <-- Formular-Unterverzeichnis -> Archiv-Formular "Laborbericht"
      12000-156A.pdf               <-- Identifier aus Dateiname (per Regex)
      12000-156A.ini               <-- optionale Schlagwortdatei
      20100-42B\                   <-- Verzeichnis-Erkennung: Identifier = "20100-42B"
        scan001.pdf                <-- Dateiname beliebig
        scan002.pdf
    Probebegleitschein\            <-- Formular-Unterverzeichnis -> Archiv-Formular "Probebegleitschein"
      20100-42B.pdf
  Artikel\                         <-- Erkennungsverzeichnis (Objekttyp: Artikel)
    Artikelbilder\                 <-- Formular-Unterverzeichnis -> Archiv-Formular "Artikelbilder"
      Artikel_ART-001.pdf
  Personenkonten\                  <-- Erkennungsverzeichnis (Objekttyp: Personenkonto)
    Kundenstamm\                   <-- Formular-Unterverzeichnis -> Archiv-Formular "Kundenstamm"
      Konto_12000.pdf
  Rechnungen\                      <-- Reguläres Verzeichnis -> Archiv-Formular "Rechnungen"
    dokument.pdf

Mandantenverzeichnisse

Mit MandantenVerzeichnisse: true wird die erste Verzeichnisebene unter ImportPath als Mandantennummer interpretiert. So können mehrere Mandanten mit einer einzigen Service-Instanz bedient werden. Der Parameter Company entfällt in diesem Modus. Ist Company dennoch in der Konfiguration gesetzt, wird der Wert ignoriert und eine Warnung geloggt.

Systemverzeichnisse (Erfolgreich/Fehler bzw. die konfigurierten Namen) auf Mandantenebene werden automatisch übersprungen und nicht als Mandant interpretiert.

Die Datenbankverbindung wird beim Start nur auf Systemebene hergestellt. Mandanten-spezifische Verbindungen werden erst bei Bedarf erstellt und anschließend für die Dauer der Sitzung zwischengespeichert.

C:\Archivimport\
  500M\                            <-- Mandant 500M
    Belege\                        <-- Erkennungsverzeichnis (Objekttyp: Beleg)
      Laborbericht\
        12000-156A.pdf             <-- Identifier aus Dateiname
        20100-42B\                 <-- Verzeichnis-Erkennung
          scan.pdf
    Rechnungen\                    <-- Reguläres Verzeichnis -> Archiv-Formular "Rechnungen"
      dokument.pdf
  600M\                            <-- Mandant 600M
    Belege\
      Probebegleitschein\
        20100-42B.pdf
    Artikel\
      Artikelbilder\
        Artikel_ART-001.pdf

Innerhalb jedes Mandantenverzeichnisses gilt die gleiche Struktur wie im Einzelmandant-Modus (Erkennungsverzeichnisse, Formular-Unterverzeichnisse, Schlagwortdateien etc.).

Dateiverschiebung nach Verarbeitung

Nach der Verarbeitung werden Dateien (inkl. begleitender Schlagwortdateien) automatisch verschoben:

  • Erfolgreicher Import: Unterverzeichnis Erfolgreich (konfigurierbar via SuccessFolder)
  • Fehler beim Import: Unterverzeichnis Fehler (konfigurierbar via ErrorFolder)

Das Zielverzeichnis wird relativ zum Verzeichnis der Datei erstellt:

  • Regulär: Rechnungen\Erfolgreich\dokument.pdf
  • Erkennung: Belege\Laborbericht\Erfolgreich\12000-156A.pdf
  • Verzeichnis-Erkennung: Belege\Laborbericht\12000-156A\Erfolgreich\scan.pdf

Bei Namenskonflikten wird automatisch ein Zeitstempel angefügt (z.B. 12000-156A_20240115_143022.pdf).

Konfiguration

Die Konfiguration erfolgt über die Datei appsettings.json. Änderungen an der Konfiguration werden zur Laufzeit automatisch übernommen (Hot-Reload via IOptionsMonitor).

Beim Start werden die Pflichtparameter validiert. Fehlende oder ungültige Werte führen zu einem sofortigen Abbruch mit Fehlermeldung.

{
  "License": {
    "LicenseNr": "",
    "CustomerNr": ""
  },
  "Company": "500M",
  "ConnectionString": "XpoProvider=MSSqlServer;data source=WS01;integrated security=SSPI;initial catalog=CWLSYSTEM;TrustServerCertificate=True;",
  "ImportPath": "C:\\Archivimport",
  "FileFilter": "*.pdf",
  "Belege": {
    "Folder": "Belege",
    "Regex": "^(?<nummer>[^-]+-[^.]+)\\.[^.]+$",
    "KeywordMapping": "1=Kontonummer,43=Auftragsnummer,49=DatumLieferschein:dd-MM-yyyy",
    "FileFilter": "*.pdf;*.tif"
  },
  "Artikel": {
    "Folder": "Artikel",
    "Regex": "^Artikel_(?<nummer>.+)\\.[^.]+$",
    "KeywordMapping": "41=Artikelnummer"
  },
  "Personenkonten": {
    "Folder": "Personenkonten",
    "Regex": "^Konto_(?<nummer>.+)\\.[^.]+$",
    "KeywordMapping": "1=Kontonummer"
  },
  "MandantenVerzeichnisse": false,
  "EnableBelegKeyFallback": true,
  "Watch": true,
  "SuccessFolder": "Erfolgreich",
  "ErrorFolder": "Fehler"
}

Lizenz

Parameter Beschreibung
License:LicenseNr Lizenznummer
License:CustomerNr Kundennummer

Die Lizenzprüfung erfolgt beim Start gegen https://license.css-edv-support.de (Produkt: MESO-ARCHIVEIMP). Ohne gültige Lizenz startet der Service im Demomodus (siehe unten).

In Container-Umgebungen können die Werte alternativ über Umgebungsvariablen gesetzt werden:

  • LICENSE_LICENSE_NR
  • LICENSE_CUSTOMER_NR

Demomodus

Wenn keine gültige Lizenz vorhanden ist (fehlende Konfiguration, ungültige Daten oder Server nicht erreichbar), startet der Service automatisch im Demomodus. In diesem Modus:

  • Dateien werden erkannt, Identifier extrahiert und Objekte zugeordnet
  • Schlagworte werden ermittelt (aus Mapping und Schlagwortdateien)
  • Die Ergebnisse werden als [DEMO]-Warnung geloggt
  • Die Archivierung wird übersprungen - es werden keine Dokumente im MESONIC-Archiv abgelegt
  • Dateien werden nicht in Erfolgs-/Fehlerverzeichnisse verschoben

Pflichtparameter

Parameter Beschreibung Beispiel
Company MESONIC-Mandantennummer (entfällt bei MandantenVerzeichnisse: true) "500M"
ConnectionString XPO-ConnectionString zur MESONIC-Systemdatenbank "XpoProvider=MSSqlServer;data source=WS01;..."
ImportPath Pfad zum Importverzeichnis "C:\\Archivimport"

Optionale Parameter

Parameter Standard Beschreibung
FileFilter "*.pdf" Erlaubte Dateitypen als Wildcard-Muster. Mehrere Muster mit Semikolon trennen: "*.pdf;*.tif;*.jpg"
MandantenVerzeichnisse false Erste Verzeichnisebene als Mandantennummer interpretieren (siehe Mandantenverzeichnisse). Company wird dann aus den Verzeichnisnamen ermittelt
Watch false Dauerüberwachung des Importverzeichnisses aktivieren
EnableBelegKeyFallback false Bei Belegkey-Format auch über LadeBeleg suchen, wenn die direkte Suche fehlschlägt
SuccessFolder "Erfolgreich" Name des Unterverzeichnisses für erfolgreich importierte Dateien
ErrorFolder "Fehler" Name des Unterverzeichnisses für fehlgeschlagene Importe
TestSentry false Löst eine Test-Exception aus, um die Sentry-Integration zu prüfen

Objekttyp-Konfiguration (Belege, Artikel, Personenkonten)

Jeder Objekttyp wird als eigene Sektion konfiguriert:

Parameter Beschreibung
Folder Name des Erkennungsverzeichnisses (Unterverzeichnis von ImportPath), das diesem Objekttyp zugeordnet ist. Dieses Verzeichnis enthält Formular-Unterverzeichnisse
Regex RegEx-Muster zur Extraktion der Objektnummer aus dem Dateinamen. Wenn leer, wird der Dateiname ohne Erweiterung als Nummer verwendet. Unterstützte benannte Gruppen: nummer, belegkey, belegnummer
KeywordMapping Zuordnung von Schlagwortnummern zu Properties der MesoXPO-Klasse. Format: SchlagwortNr=PropertyName, kommagetrennt. Optional mit Datumsformat: 49=DatumLieferschein:dd-MM-yyyy
FileFilter Optional: Überschreibt den globalen FileFilter für diesen Objekttyp. Z.B. "*.pdf;*.tif" um zusätzlich TIFF-Dateien zu akzeptieren

Identifier-Extraktion

Der Identifier wird in folgender Reihenfolge ermittelt:

  1. Verzeichnisname (wenn die Datei in einem Identifier-Unterverzeichnis liegt): Der Verzeichnisname wird direkt als Identifier verwendet.
  2. RegEx aus Dateiname: Die konfigurierte Regex wird auf den Dateinamen angewendet.
  3. Dateiname ohne Erweiterung (wenn keine Regex konfiguriert ist): Der vollständige Dateiname ohne Erweiterung gilt als Identifier.

Beispiele je Objekttyp

Belege - Regex: ^(?<nummer>[^-]+-[^.]+)\.[^.]+$

Dateiname Extrahierter Identifier
12000-156A.pdf 12000-156A
20100-42B.tif 20100-42B

Artikel - Regex: ^Artikel_(?<nummer>.+)\.[^.]+$

Dateiname Extrahierter Identifier
Artikel_ART-001.pdf ART-001
Artikel_12345.png 12345

Personenkonten - Regex: ^Konto_(?<nummer>.+)\.[^.]+$

Dateiname Extrahierter Identifier
Konto_12000.pdf 12000
Konto_20100.tif 20100

Ohne Regex (Default-Verhalten):

Dateiname Extrahierter Identifier
ART-001.pdf ART-001
12000.tif 12000

Beleg-Sonderlogik

Für Belege wird der Identifier zusätzlich auf das Belegkey-Format Kontonummer-Laufnummer geprüft:

  • 12000-156A → Suche nach Kontonummer 12000, Laufnummer 156A
  • Falls nicht gefunden und EnableBelegKeyFallback aktiv → Fallback via LadeBeleg

Bei Belegen wird nach erfolgreichem Import automatisch die Archiv-DokID mit dem Beleg verknüpft.

Schlagwort-Mapping

Über KeywordMapping werden Objekt-Properties auf Archiv-Schlagworte gemappt:

1=Kontonummer,43=Auftragsnummer,49=DatumLieferschein:dd-MM-yyyy
  • Schlagwort 001 = Wert der Property Kontonummer
  • Schlagwort 043 = Wert der Property Auftragsnummer
  • Schlagwort 049 = Wert der Property DatumLieferschein, formatiert als dd-MM-yyyy

Die Properties werden per Reflection aus der jeweiligen MesoXPO-Klasse ausgelesen.

Schlagwortdateien

Schlagworte können auch über eine Begleitdatei (.ini oder .txt) mit gleichem Dateinamen angegeben werden. Diese haben Vorrang vor den automatisch ermittelten Schlagworten.

Format (eine Zeile pro Schlagwort):

# Kommentare mit # oder ;
1=12000
43=AUF-2024-001
49=15-01-2024

Installation als Windows-Service

Voraussetzungen

  • Windows 10/11 oder Windows Server 2016+
  • Administratorrechte für die Service-Installation

Die Anwendung wird als Self-Contained publiziert und benötigt keine separate .NET-Installation.

Schritt für Schritt

  1. Dateien bereitstellen: Das Publish-Artefakt (ZIP) in ein Zielverzeichnis entpacken, z.B. C:\Programme\MesoArchivImport\

  2. Konfiguration anpassen: Die Datei appsettings.json im Installationsverzeichnis bearbeiten und die Pflichtparameter (Company, ConnectionString, ImportPath) sowie die Lizenzdaten setzen.

  3. Importverzeichnis anlegen: Das konfigurierte Importverzeichnis (z.B. C:\Archivimport) mit den gewünschten Unterverzeichnissen erstellen (siehe Verzeichnisstruktur).

  4. Service registrieren (als Administrator):

sc create "MESO Archivimport" binPath="C:\Programme\MesoArchivImport\MesoArchivImport.exe" start=auto
  1. Service starten:
sc start "MESO Archivimport"

Service verwalten

sc stop "MESO Archivimport"        &:: Service stoppen
sc delete "MESO Archivimport"      &:: Service deinstallieren
sc query "MESO Archivimport"       &:: Status abfragen

Kommandozeilenausführung

Zum Testen kann die Anwendung auch direkt ohne Service-Installation ausgeführt werden. Alle Parameter können als Kommandozeilenargumente übergeben werden:

MesoArchivImport.exe --Company "500M" --ConnectionString "XpoProvider=MSSqlServer;data source=WS01;integrated security=SSPI;initial catalog=CWLSYSTEM" --ImportPath "C:\Archivimport" --Watch true

Update

  1. Service stoppen: sc stop "MESO Archivimport"
  2. Dateien im Installationsverzeichnis durch die neue Version ersetzen (die appsettings.json beibehalten)
  3. Service starten: sc start "MESO Archivimport"

Logging

Der Service nutzt Serilog mit drei konfigurierbaren Sinks:

  • Console: Farbige Ausgabe im Kompaktformat (HH:mm:ss [INF] Message)
  • File: Tägliches Rolling in Logs/archivimport-YYYYMMDD.log (relativ zum Installationsverzeichnis)
  • Sentry: Fehler ab Error werden automatisch an Sentry gemeldet

Die gesamte Logging-Konfiguration erfolgt über die Serilog-Sektion in appsettings.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "outputTemplate": "{Timestamp:HH:mm:ss} [{Level:u3}]  {Message:lj}{NewLine}{Exception}"
        }
      },
      {
        "Name": "File",
        "Args": {
          "path": "Logs/archivimport-.log",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 30,
          "fileSizeLimitBytes": 10485760,
          "rollOnFileSizeLimit": true,
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level:u3}] {Message:lj}{NewLine}{Exception}"
        }
      },
      {
        "Name": "Sentry",
        "Args": {
          "dsn": "https://...",
          "minimumBreadcrumbLevel": "Information",
          "minimumEventLevel": "Error"
        }
      }
    ]
  }
}

File-Logging

Parameter Standard Beschreibung
path Logs/archivimport-.log Pfad und Dateinamenmuster. Das Datum wird automatisch eingefügt (archivimport-20260220.log)
rollingInterval Day Rotationsintervall (Day, Hour, Month)
retainedFileCountLimit 30 Maximale Anzahl aufbewahrter Log-Dateien
fileSizeLimitBytes 10485760 (10 MB) Maximale Dateigrösse pro Log-Datei
rollOnFileSizeLimit true Bei Überschreitung der Dateigrösse eine neue Datei beginnen

Log-Level anpassen

Über MinimumLevel.Default wird das globale Minimum gesteuert. Mit Override können einzelne Namespaces gezielt lauter oder leiser geschaltet werden:

"MinimumLevel": {
  "Default": "Debug",
  "Override": {
    "Microsoft": "Warning",
    "System": "Warning"
  }
}

Verfügbare Level: Verbose, Debug, Information, Warning, Error, Fatal

No comments to display

Back to top