¶ fd.docuBridge
¶ Kurzbeschreibung
docuBridge ist ein modulares Integrations- und Import-Framework zur strukturierten Übertragung externer Daten und Dokumente in docuvita (docuvita Sidebar).
Das System dient als Brücke zwischen Dateisystemen, Fremdanwendungen und docuvita-Importmechanismen (AutoProfiler, dvImport).
Ziel: reproduzierbare, konfigurierbare und automatisierte Datenübernahme ohne direkte Manipulation der Quelldaten.
¶ Systemübersicht
docuBridge besteht aus mehreren logisch getrennten Komponenten:
- docuBridge Server
- docuBridge Client
- docuBridge Server Configurator
| AppName | Technologie | Beschreibung |
|---|---|---|
docuBridge Client |
.NET 4.8 | Client auf Clientrechnern |
docuBridge Server |
ASP.NET | Serveranwendung |
docuBridge Server.Configurator |
.NET 4.8 | Konfigurationsanwendung für den Server |
Die Architektur folgt einem serverzentrierten Modell mit externer Konfiguration und optionaler Client-Kommunikation über TCP bzw. HTTP.
¶ Architektur
¶ Überblick
Externe Datenquelle (ERP, Dateisystem, Anwendung)
→ docuBridge Client
→ strukturierte Metadaten (JSON)
→ docuBridge Server
→ docuvita (Import API / AutoProfiler)
Der docuBridge Client ist für Benutzerinteraktion und Kontextbildung verantwortlich,
während der docuBridge Server die zentrale Verarbeitung, Validierung und Weiterleitung der Metadaten übernimmt.
¶ Anwendungsfall: ERP-Integration und Sidebar
¶ Auslöser (Trigger)
Bei Interaktion mit einem Objekt im ERP-System wird ein HTTP-Request an docuBridge gesendet.
Beispiel GET Request an localhost:
curl -G "http://hg-blp:25024/api/client/sidebar/selectObject" \
--data-urlencode "user=hkheun\\raphael" \
--data-urlencode "objectName=SALES QUOTE" \
--data-urlencode "objectValue=A250184" \
--data-urlencode "dataSource=HEU"
Auf Basis dieser Daten wird die docuvita Sidebar im docuBridge Client aktualisiert.
¶ Aktualisierung der Sidebar
Nach Eingang des Requests zeigt der docuBridge Client in der Sidebar:
- den Namen des aktuellen Dokuments bzw. Objekts
- den zugehörigen Kunden oder Lieferanten
Diese Informationen bilden den fachlichen Kontext für alle weiteren Aktionen innerhalb der Sidebar.
¶ Suche in docuvita
Basierend auf den empfangenen Objektinformationen kann eine Suche in docuvita ausgelöst werden.
Die Suche erfolgt anhand der im Server Configurator definierten Objekttypen und kann u. a. folgende Kriterien nutzen:
- Kundennummer
- Lieferantennummer
- Vorgangs-ID
Die Suche kann flexibel umgeschaltet werden zwischen:
- Vorgangsebene
- Kundenebene
- Lieferantenebene
Das Suchergebnis wird außerdem nach der ausgewählten DataSource gefiltert. Diese kann im Konfigurator eingestellt werden.
¶ Suche nach Vorgangsnummer oder Name (Vorgangsebene)
Im Feld Vorgangsnummer im Haupt-Tab kann neben der Vorgangsnummer auch ein Name bzw. ein Teil eines Namens eingegeben werden.
- Vorgangsnummer oder Name (bzw. Namensteil) eingeben und mit Enter bestätigen.
- Der docuBridge Server führt die für den ausgewählten Objekttyp und die DataSource konfigurierten ODBC-Abfragen als Listenabfrage aus. Als angezeigter Text dient die Spalte, die in der Abfrage mit
@@objectValue@@verglichen wird. - Ergebnis:
- ein Treffer: wird automatisch übernommen, Kunden- bzw. Lieferantendaten werden geladen;
- mehrere Treffer: werden als Auswahlliste unter dem Feld angezeigt; nach Auswahl eines Eintrags werden die zugehörigen Daten geladen;
- kein Treffer: der eingegebene Wert bleibt im Feld erhalten.
- Wurde über einen Namen gesucht, wird im Feld nach der Auswahl die zugehörige Vorgangsnummer (ID) angezeigt.
- Mit Suche wird anschließend die Suche in docuvita auf Vorgangsebene gestartet.
Damit die Namenssuche funktioniert, muss die ODBC-Abfrage des Objekttyps einen Vergleich mit @@objectValue@@ enthalten (z. B. ... WHERE [description] LIKE '%@@objectValue@@%') und eine ID-Spalte liefern (z. B. ID, KUNDEN_ID, LIEFERANTEN_ID). Ist für den Objekttyp keine Abfrage konfiguriert, bleibt die Liste leer.
¶ Filter der Suchergebnisse
Über das Auswahlfeld Filter im Such-Tab werden die gefundenen Dokumente in der Baumansicht gruppiert. Ein Wechsel des Filters wendet die Gruppierung sofort auf das letzte Suchergebnis an, ohne neue Suche.
| Filter | Gruppierung nach | Herkunft des Feldes |
|---|---|---|
| Objekttyp | docuvita-Objekttyp | Objekttyp des Dokuments |
| Vorgangsnummer | Wert des Vorgangsfeldes | dvObjecttypeFieldIdProcess im Objekttyp (Configurator) |
| Belegnummer | Wert des Belegnummer-Feldes | dvObjecttypeFieldIdBelegNumber im Objekttyp (Configurator) |
| Belegtyp | Belegtyp des Dokuments | docuvita-Systemfeld Belegtyp (obj.vouchertype) |
Bei den Filtern Vorgangsnummer, Belegnummer und Belegtyp werden Dokumente, bei denen das jeweilige Feld leer ist, nicht angezeigt. Ist für einen Objekttyp das Vorgangs- bzw. Belegnummer-Feld nicht konfiguriert, erscheinen dessen Dokumente bei diesem Filter nicht.
¶ Drag-and-Drop und Importvorbereitung
Über eine Drag-and-Drop-Funktion im Client kann ein Dokument für den Import nach docuvita ausgewählt werden.
¶ Dateiauswahl im Haupt-Tab („Home“-Tab mit Haus-Icon)
Im Haupt-Tab (Haus-Icon) steht ein spezielles Eingabefeld für die Dokumentauswahl zur Verfügung.
Beim Klick auf dieses Feld öffnet sich ein Windows-Dateidialog (Explorer), über den der Benutzer eine Datei auswählen kann. Alternativ kann eine Datei per Drag-and-Drop auf dieses Feld gezogen werden.
Vor dem Hochladen bzw. Übertragen eines Dokuments muss im docuBridge Server Configurator ein gültiges Importtemplate für den jeweiligen Objekttyp konfiguriert sein.
Ohne eine definierte Template-Konfiguration ist kein Import nach docuvita möglich.
¶ Direkte Pfadwahl im Struktur-Tab
Im Tab „Struktur“ kann der Zielpfad für die Ablage in docuvita direkt über die Struktur ausgewählt werden.
Damit wird die Zielposition des Dokuments unmittelbar festgelegt, ohne den Umweg über die Pfadkonfiguration im Haupt-Tab.
Nach dem Ablegen des Dokuments öffnet sich eine Maske zur Importvorbereitung.
Abhängig von den empfangenen Kontextdaten werden automatisch vorbelegt:
- Kunden- bzw. Lieferantenname und -nummer
- Vorgangs-ID
- Ersteller
- Bezug zum Vorgang
¶ Konfigurierbares Dateinamens-Template
Der Dateiname des zu importierenden Dokuments kann im docuBridge Server Configurator über das Feld dvTemplateFileName innerhalb des jeweiligen Objekttyps definiert werden.
Das Template legt fest, wie der finale Dateiname in docuvita gebildet wird.
Beispiel:
@@objecttype@@ (@@vorgangsnummer@@)
¶ Platzhalter (Dateinamens-Template und Belegtyp-Vorlage)
Im Dateinamens-Template (dvTemplateFileName) und in der Vorlage des Belegtyps (dvBelegtypePattern, Modus „Auto“) können folgende Platzhalter verwendet werden. Sie werden im docuBridge Client beim Import ersetzt; Groß-/Kleinschreibung spielt keine Rolle.
| Platzhalter | Ersetzt durch | Beispiel |
|---|---|---|
@@objecttype@@ |
Name des Objekttyps | SALES QUOTE |
@@vorgangsnummer@@ |
aktuelle Vorgangsnummer | A250184 |
@@ts@@ |
Uhrzeit (lokal), Format HHmmss |
141321 |
@@dt@@ |
Datum und Uhrzeit (lokal), Format yyMMddHHmmss |
261002141321 |
@@uts@@ |
Unix-Zeitstempel in Sekunden (UTC) | 1790943201 |
@@rnd@@ |
zufällige 6-stellige Ziffernfolge | 048213 |
@@obj.vouchertype@@ |
ausgewählter Belegtyp (nur in der Belegtyp-Vorlage) | Angebot |
Die Platzhalter müssen exakt in dieser Schreibweise (mit @@ am Anfang und Ende) angegeben werden; geänderte Variablennamen werden nicht ersetzt. Im Configurator fügen die Buttons im Dialog „Template-Dateiname“ @@objecttype@@ bzw. @@vorgangsnummer@@ direkt ein.
Beispiel Belegtyp-Vorlage:
@@objecttype@@_@@vorgangsnummer@@_@@dt@@
Das Template kann Platzhalter enthalten, die zur Laufzeit durch Kontextdaten (Objekttyp, Vorgangs-ID) ersetzt werden.
Verhalten ohne Dateinamens-Template
Ist kein dvTemplateFileName definiert oder leer, wird das Originaldateiname des hochgeladenen Dokuments unverändert verwendet.
Die Entscheidung über den finalen Dateinamen erfolgt serverseitig auf Basis der Konfiguration.
Die vorbelegten Daten können vor dem Import geprüft und bei Bedarf angepasst werden.
Diese Maske dient der fachlichen und technischen Validierung vor der Übergabe an docuvita.
¶ Import nach docuvita
Der eigentliche Import des Dokuments erfolgt:
- entweder direkt über die docuvita Import API
- oder über einen dvImportParser im AutoProfiler
Für jeden Objekttyp kann ein oder mehrere Importtemplates definiert werden.
Ein Importtemplate legt fest:
- an welcher Stelle das Dokument in docuvita abgelegt wird
- mit welchen Akten oder Vorgängen es verknüpft wird
- welche Metadaten automatisch ergänzt oder gesetzt werden
Durch den Einsatz von Importtemplates kann flexibel auf Änderungen an Objekttypen oder fachlichen Anforderungen reagiert werden, ohne Anpassungen am Client-Code vorzunehmen.
¶ Bedingung zur Ausführung
In der Bedingung zur Ausführung können beliebige Variablen verwendet werden, die vom Client als Parameter übergeben werden.
Variablen müssen mithilfe der Platzhaltersyntax @@...@@ angegeben werden.
Unterstützte Operatoren:
- Vergleichsoperatoren:
==, !=, >, <, >=, <= - Text- und Mengenoperatoren:
contains, in - Null-Prüfungen:
isnull, notnull, == null, != null
Logische Verknüpfungen:
- && (AND)
- || (OR)
- ! (NOT)
Beispiel:
@@Kundennummer@@ != null && @@Kundenname@@ notnull
¶ Verwendung von Variablen im Importtemplate
Die in der Bedingung zur Ausführung verwendeten Variablen können ebenfalls direkt im Importtemplate genutzt werden.
Platzhalter werden zur Laufzeit durch die vom Client übergebenen Werte ersetzt.
Die Verwendung erfolgt über die Platzhalter-Syntax @@...@@.
Ein spezieller Platzhalter ist @@doc@@.
Dieser steht für das vollständige Dokumentobjekt, das vom Client übergeben wird, einschließlich aller zugehörigen Metadatenfelder.
@@doc@@ darf ausschließlich als eigenständiges XML-Element innerhalb der Struktur verwendet werden und nicht innerhalb von Attributen.
Beispiel:
<?xml version="1.0" encoding="utf-8"?>
<import>
<data>
<object type="Kundenakte" obj.name="@@kundenname@@ (@@kundennummer@@)">
<object type="Ordner" obj.name="Belege" kundennummer="@@kundennummer@@">
@@doc@@
</object>
</object>
</data>
</import>
¶ Klassenstruktur
¶ Root
- Einstiegspunkt der JSON-Struktur.
- Enthält ein Docuvita-Objekt.
¶ Docuvita
- Enthält:
systemconfig: Liste von Systemeinstellungen.mandanten: Mandanteninformationen.objecttypes: Objekttypdefinitionen.belegtypes: Belegtypfinitionen.users: Benutzerinformationen.abfragen: Konfiguration der ODBC-Abfragen (inkl. ConnectionString).
¶ SystemConfig, Mandant, ObjectType, Belegtype, Abfrage
- Gemeinsame Felder:
FieldName: Name des Feldes.FieldType: FieldType beschreibt den logischen Datentyp, nicht den JSON-Typ.FieldValue: FieldValue wird immer als string serialisiert.FieldDescription: Beschreibung des Feldes.
¶ Kommunikation und Protokolle
¶ Client–Server-Kommunikation
Die Kommunikation zwischen docuBridge Client und docuBridge Server erfolgt wahlweise über:
- ein Socket-basiertes Protokoll (TCP)
- HTTP-basierte Requests
HTTP wird primär für synchrone Such- und Abfrageoperationen genutzt, während TCP für zustandsbehaftete oder ereignisbasierte Kommunikation vorgesehen ist.
¶ docuBridge Server
¶ Funktion
Der docuBridge Server ist die zentrale Laufzeitkomponente des Systems zur:
- Annahme strukturierter Metadaten (JSON)
- Verarbeitung mehrerer Objektarten
- Weiterleitung an docuvita-konforme Importmechanismen
¶ Server-Konfiguration (docuBridge Server.Configurator JSON)
JSON-Datei wird durch docuBridge Server beim Start (oder Reload) eingelesen. Wird über docuBridge Server.Configurator erstellt/editiert (GUI) und als JSON serialisiert.
{
"docuvita": {
"systemconfig": [
{
"FieldName": "dvUrl",
"FieldType": "S",
"FieldValue": "https://localhost:443/server/services/web",
"FieldDescription": ""
},
{
"FieldName": "dvApiKey",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvImportUser",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvImportPassword",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "clientDataSource",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": null
}
],
"mandanten": {
"mandant": [
{
"FieldName": "dvMandantName",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvMandantId",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
}
]
},
"objecttypes": [
{
"objecttypefields": [
{
"FieldName": "dvObjecttypeName",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvObjecttypeId",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
},
{
"FieldName": "dvObjecttypeFieldIdCustomerNumber",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
},
{
"FieldName": "dvObjecttypeFieldIdVendorNumber",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
},
{
"FieldName": "dvObjecttypeFieldIdProcess",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
},
{
"FieldName": "dvObjecttypeDvImportPath",
"FieldType": "S",
"FieldValue": "C:\\pfad\\zur\\Config\\dvImport\\dvImport_1",
"FieldDescription": ""
},
{
"FieldName": "dvTemplateFileName",
"FieldType": "S",
"FieldValue": "ObjectName (Vorgangsnummer)",
"FieldDescription": ""
},
{
"FieldName": "dvLinkedDocumentType",
"FieldType": "S",
"FieldValue": "offer,invoice,order,delivery_note,reminder",
"FieldDescription": ""
}
]
}
],
"belegtyps": [
{
"belegtypen": [
{
"FieldName": "dvObjecttypeId",
"FieldType": "N",
"FieldValue": "8",
"FieldDescription": ""
},
{
"FieldName": "dvBelegtypeName",
"FieldType": "S",
"FieldValue": "Document",
"FieldDescription": ""
},
{
"FieldName": "dvBelegtypeModus",
"FieldType": "S",
"FieldValue": "Auto",
"FieldDescription": ""
},
{
"FieldName": "dvBelegtypePattern",
"FieldType": "S",
"FieldValue": "@@objtype@@_@@vorgangsnummer@@",
"FieldDescription": ""
}
]
}
],
"users": {
"user": [
{
"FieldName": "benutzerName",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvBenutzerName",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvPassword",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvMandant",
"FieldType": "N",
"FieldValue": "1",
"FieldDescription": ""
}
]
},
"abfragen": {
"abfrage": [
{
"FieldName": "ConnectionString",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvLieferant",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "dvKunde",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "SALES+QUOTE",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
},
{
"FieldName": "ARTICLE",
"FieldType": "S",
"FieldValue": "",
"FieldDescription": ""
}
]
}
}
}
¶ JSON Server.Configurator Konfiguration
Die Konfiguration erfolgt über eine JSON Datei, diese kann in gängigen Editoren angepasst und erweitert werden, eine Anpassung über eine Benutzeroberfläche ist ebenfalls geplant.
Die Typkonvertierung erfolgt serverseitig anhand von FieldType.
| DvUrl | string | URL zum docuvita System |
| dvApiKey | string | API Key für das docuvita System |
| dvImportUser | string | Benutzername für das docuvita System |
| dvImportPassword | string | Passwort zum Benutzernamen |
| clientDataSource | string | Datenquellenbeschreibung, die auf dem Client angezeigt wird |
| mandanten | object | Konfiguration der docuvita-Mandanten |
| mandant | Array | Liste der Mandanten-Felder |
| dvMandantName | string | Name des Mandanten |
| dvMandantId | string | In docuvita vergeben ID des Mandanten |
| objecttypes | Array | Konfiguration der Objekttypen |
| objecttypefields | Array | Felder des Objekttyps |
| dvObjecttypeName | string | Name des Objekttypes (muss identisch zur docuvita Konfiguration sein) |
| dvObjecttypeId | string (numerisch, serverseitig konvertiert) | In docuvita vergebene ID des Objekttyps |
| dvObjecttypeFieldIdCustomerNumber | string (numerisch, serverseitig konvertiert) | docuvita Field-Id für zugehörige Kundennummer bzw. eindeutige Kundenidentifikation aus dem ERP-System |
| dvObjecttypeFieldIdVendorNumber | string (numerisch, serverseitig konvertiert) | docuvita Field-Id für die zugehörige Lieferantennummer bzw. eindeutige Lieferantenidentifikation aus dem ERP-System |
| dvObjecttypeFieldIdProcess | string (numerisch, serverseitig konvertiert) | docuvita Field-Id für die Projektnummer bzw. eindeutige Vorgangs- oder Projektidentifikation aus dem ERP System |
| dvObjecttypeDvImportPath | string | Pfad zum dvImport Template |
| dvTemplateFileName | string | Template für FileName |
| dvLinkedDocumentType | string | Verknüpfte Dokumenttypen zu diesem Objekttyp, dient zum Vorausfüllen von Eigenschaften beim Import von Begleitdokumenten, kommasepariert |
| dvObjecttypeId | string (numerisch, serverseitig konvertiert) | In docuvita vergebene ID des Objekttyps |
| dvBelegtypeName | string | Name des Belegtypes (muss identisch zur docuvita Konfiguration sein) |
| dvBelegtypeModus | string | ein Modus, der der Vorgangsnummer beeinflusst. Es gibt drei Typen: automatisch, manuell und Vorgangsnummer |
| dvBelegtypePattern | string | Vorlage zum Ausfüllen der Vorgangsnummer basierend auf ihrem Modus |
| users | object | Konfiguration der Benutzer |
| user | Array | Liste der User-Felder |
| benutzerName | string | Benutzername im docuBridge System |
| dvBenutzerName | string | Benutzername im docuvita System |
| dvPassword | string | Passwort zum Benutzernamen im docuvita System |
| dvMandant | string | docuvita Mandant des Benutzers |
| abfragen | object | Konfiguration der ODBC Abfragen |
| abfrage | Array | Liste der ODBC-Abfragefelder |
| ConnectionString | string | ODBC-Connection-String und Name der Datenquelle (DataSource) |
| dvLieferant | string | ODBC Abfrage zur Ermittlung der Lieferantennummer |
| dvKunde | string | ODBC Abfrage zur Ermittlung der Kundennummer |
| SALES+QUOTE | string | ODBC Abfrage zur Ermittlung von Objektdaten für den Objekttyp SALES QUOTE |
| ARTICLE | string | ODBC Abfrage zur Ermittlung von Objektdaten für den Objekttyp ARTICLE |
¶ Mehrere ConnectionStrings
Für die ODBC-Konfiguration können mehrere ConnectionStrings angelegt werden.
Die Konfiguration erfolgt in folgender Reihenfolge:
- Zuerst wird ein neuer ConnectionString erstellt.
- Anschließend wird der DataSource-Name vergeben.
- Danach werden die zugehörigen ODBC-Abfragen (z. B. dvKunde, dvLieferant oder objekttypspezifische Abfragen) diesem ConnectionString hinzugefügt.
Jede DataSource besitzt ihren eigenen ConnectionString und ihre eigenen ODBC-Abfragen.
Dadurch können mehrere Datenbanksysteme parallel konfiguriert werden.
¶ docuBridge Client
¶ Rolle
Der docuBridge Client stellt die Benutzerschnittstelle dar und ermöglicht:
- Suche nach Dokumenten anhand von Objektkennungen (
objectNameNr,objectName,DataSource) - Anzeige von Dokumentmetadaten
- Öffnen und Anzeigen referenzierter Dokumente
- Vorbereitung von Importen per Drag-and-Drop
¶ Client-Konfiguration (docuBridge Client JSON)
{
"serverUrl": "http://localhost:5000/",
"portTcp": "9010",
"logsPfad": "C:\\ProgramData\\docuBridge",
"tabControls":
[
"tabHome",
"tabTree",
"tabSearch",
"tabUpload"
],
"FormWidth": 506,
"FormTop": 0,
"IsAppBarAttached": false,
"AppBarEdge": "Left"
}
¶ Konfiguration des docuBridge Clients
Die Konfiguration des docuBridge Clients erfolgt über eine JSON Datei, diese kann in gängigen Editoren angepasst und erweitert werden.
| serverUrl | string | URL zum docuBridge Server |
| portTcp | string | Port für TCP requests |
| logsPfad | string | Pfad für Logdateien des Clients |
| tabControls | Array | Liste der angezeigten Tabs in der Sidebar, Reihenfolge entspricht der Anzeige |
| FormWidth | integer | Breite der Sidebar in Pixeln |
| FormTop | integer | Vertikale Position der Sidebar auf dem Bildschirm |
| IsAppBarAttached | boolean | Gibt an, ob die Sidebar als AppBar am Bildschirmrand angedockt ist |
| AppBarEdge | string | Bildschirmrand, an dem die Sidebar angedockt wird. Mögliche Werte: Left, Right |
¶ docuBridge Server Configurator
¶ Zweck
Der docuBridge Server Configurator ist eine WinForms-Anwendung zur Erstellung, Pflege und Serialisierung der docuBridge-Serverkonfiguration.
Der docuBridge Server Configurator stellt eine grafische Benutzeroberfläche zur Erstellung und Pflege der JSON-Konfiguration bereit. Alle Änderungen werden visuell vorgenommen und anschließend als JSON serialisiert und vom Server eingelesen.
¶ Funktionen
- Verwaltung mehrerer Mandanten
- Definition von Benutzern
- Konfiguration von ODBC-Verbindungen
- Definition von Objekttypen
- Definition von Vorgangsnummer durch Belegtypen
- Serialisierung der Konfiguration als JSON
¶ Reihenfolge der Einträge ändern (Drag & Drop)
Innerhalb der folgenden Bereiche werden die Einträge als Blöcke untereinander angezeigt. Die Reihenfolge dieser Blöcke kann per Drag & Drop geändert werden:
| Bereich | Block (UserControl) | Abschnitt in der JSON-Konfiguration |
|---|---|---|
| Mandanten | MandantenControl |
mandanten |
| Tab „Benutzer“ | BenutzerControl |
users |
| Tab „Objekttyp“ | ObjectTypeControl |
objecttypes |
| Tab „ODBC“ | OdbcControl1 |
abfragen (objekttypspezifische Abfragen der ausgewählten DataSource) |
Vorgehen:
- Mit der linken Maustaste auf eine freie Fläche des Blocks klicken (nicht in ein Eingabefeld oder auf einen Button).
- Bei gedrückter Maustaste den Block über einen anderen Block desselben Bereichs ziehen; der Mauszeiger zeigt das Verschieben-Symbol.
- Maustaste loslassen: Der gezogene Block wird an die Position des Zielblocks gesetzt.
- Mit Speichern wird die neue Reihenfolge in die JSON-Konfiguration übernommen und die Ansicht neu geladen.
Einschränkungen:
- Blöcke können nur innerhalb desselben Bereichs verschoben werden, nicht zwischen Tabs (z. B. kein Verschieben eines Benutzers in den Tab „Objekttyp“).
- Es ändert sich ausschließlich die Reihenfolge; Inhalte der Blöcke bleiben unverändert.
- Im Tab „ODBC“ betrifft die Reihenfolge nur die objekttypspezifischen Abfragen der aktuell ausgewählten DataSource. Die Einträge ConnectionString,
dvLieferantunddvKundestehen immer am Anfang. - Ohne Speichern geht die geänderte Reihenfolge beim Schließen oder Neuladen verloren.
¶ Interne Struktur
Der Configurator basiert auf einem TabControl mit spezialisierten UserControls:
- MandantenControl
- BenutzerControl
- ObjectTypeControl
- OdbcControl
¶ Konfigurationsformat
- Format: JSON
- Serialisierung: Newtonsoft.Json
- Strukturierte Objektlisten
Die Konfiguration ist versionskontrollfähig und deploymentfähig.
¶ Verfügbare Variablen (ODBC / SQL-Abfragen)
Im Rahmen der Server-Konfiguration können in ODBC-Abfragen Variablen verwendet werden, die zur Laufzeit durch den docuBridge Server gesetzt und weiterverarbeitet werden.
1. Ausführungsreihenfolge der SQL-Abfragen
Die Verarbeitung erfolgt in einer definierten Reihenfolge:
Primäre Abfrage (Objektermittlung)
Zunächst wird eine SQL-Abfrage basierend auf objectName und objectValue ausgeführt.
Beispiel:
SELECT [ID],[address] as LIEFERANTEN_ID,[comment],[doctype],[dateprinted],[datearchived]
FROM [ERPDEMOtk2].[dbo].[document] where doctype='@@objectName@@' and id='@@objectValue@@'
Ergebnis:
Ermittlung von LIEFERANTEN_ID oder KUNDEN_ID (abhängig vom Kontext).
Die erste Abfrage definiert die Basis für alle weiteren Variablen.
2. Sekundäre Abfragen (Detailermittlung)
Basierend auf den ermittelten IDs werden weitere Abfragen ausgeführt.
Beispiel (Kunde):
SELECT [id] as CUSTOMER_ID,[description] as CUSTOMER_NAME,[type]
FROM [ERPDEMOtk2].[dbo].[address] where type ='CUSTOMER' and id='@@kunden_id@@'
Ergebnis:
Ermittlung von Kundenname und Validierung/Ergänzung von Kundennummer.
3. Verfügbare Variablen (Tokens)
Folgende Variablen können in SQL-Templates verwendet werden:
- @@objectName@@
- @@objectValue@@
- alle Variablen, die in zwei @-Zeichen eingeschlossen sind und aus der ersten Abfrage berechnet werden
Token-Namen sind case-insensitive implementiert.
4. Alias-Regeln
Damit Werte korrekt erkannt werden, müssen Alias-Namen in der zweiten Anfrage gesetzt werden:
AS CUSTOMER_ID
AS CUSTOMER_NAME
AS VENDOR_ID
AS VENDOR_NAME
Unterstützte Alias-Namen
Für Kunden: CUSTOMER_ID, KUNDEN_ID, Kundennummer, Name, CUSTOMER_NAME.
Für Lieferanten: VENDOR_ID, LIEFERANTEN_ID, Lieferantennummer, Name, VENDOR_NAME.
Die zweite Abfrage ist abhängig vom Ergebnis der ersten Abfrage und wird nur ausgeführt, wenn entsprechende IDs ermittelt wurden.
Es wird jeweils nur ein Datensatz pro Abfrage verarbeitet.
Ist für einen Objekttyp keine Listenabfrage konfiguriert, ist das ein erwarteter Zustand und kein Fehler: Der Server protokolliert den Fall als [INF] und liefert eine leere Liste zurück.
¶ Objektmodell (Konfiguration)
Die Konfiguration umfasst u. a.:
- Mandanten
- Objekttypen
- Belegtypen
- Dokumentreferenzen
- dv-Imports
- Benutzer
- ODBC-Abfragen
¶ Installation
Dieses Kapitel beschreibt die Installation von docuBridge auf einem Zielsystem sowie die grundlegenden vorbereitenden Schritte.
¶ Voraussetzungen
Für die Installation und den Betrieb von docuBridge müssen folgende Voraussetzungen erfüllt sein:
- Betriebssystem: Windows (Server oder Client, abhängig von der Komponente)
- Installationsrechte: Administratorrechte erforderlich
- .NET Framework:
- docuBridge Client: .NET Framework 4.8
- docuBridge Server Configurator: .NET Framework 4.8
- Netzwerkzugriff:
- Zugriff auf den docuBridge Server (TCP / HTTP)
- Zugriff auf docuvita-Dienste
- Microsoft SQL Server (z. B. SQL Server Express) – erforderlich für docuBridge Server
Für produktive Umgebungen wird eine stabile Netzwerkverbindung zwischen Client, Server, Datenbank und docuvita vorausgesetzt.
¶ Datenbankzugriff (SQL Server)
Für den Betrieb des docuBridge Servers ist ein SQL-Server-Zugriff erforderlich.
Für die Verbindung benötigte Daten:
User Id=docubridge_app;
Password=********;
Die Zugangsdaten werden kundenspezifisch vergeben
¶ Installationspaket
Das Installationspaket enthält abhängig von der Auswahl:
- docuBridge Client
- docuBridge Server
- docuBridge Server Configurator
Unabhängig von der Auswahl werden immer die Lizenzhinweise (THIRD-PARTY-NOTICES.txt, LICENSES\) installiert.
¶ Installationsschritte
-
Start der Installation
Führen Sie die MSI-Datei mit Administratorrechten aus. -
Willkommensdialog
Klicken Sie auf Weiter, um die Installation zu starten.
-
Lizenzvereinbarung
Lesen Sie die Lizenzvereinbarung sorgfältig durch und bestätigen Sie diese, um fortzufahren.
-
Auswahl des Installationsverzeichnisses
Wählen Sie den Zielordner für die Installation. -
Komponentenauswahl
Wählen Sie die zu installierenden Komponenten:- docuBridge Client
- docuBridge Server
- docuBridge Server Configurator
-
Konfiguration des Log-Verzeichnisses
Definieren Sie den Ablageort für Log-Dateien.
-
Start der Installation
Klicken Sie auf Installieren, um den Installationsvorgang zu starten.
-
Abschluss
Nach erfolgreicher Installation wird ein Abschlussdialog angezeigt.
-
Fertigstellen
Für einen erfolgreichen Start müssen Sie die Lizenzdatei im Serverordner (docubridge_poc) unter dem unten angegebenen Pfad hinzufügen: C:\Program Files (x86)\docuBridge\docuBridgeServer\docubridge_poc.
¶ Nach der Installation
Nach Abschluss der Installation sind folgende Schritte erforderlich:
- Serverkonfiguration
- Starten Sie den docuBridge Server Configurator
- Erstellen oder laden Sie eine Serverkonfiguration
- Definieren Sie Mandanten, Objekttypen, Benutzer und ODBC-Verbindungen
- Speichern Sie die Konfiguration als JSON-Datei
-
Konfiguration einlesen
Der docuBridge Server liest die Konfiguration beim Start oder Neustart ein. -
Funktionstest
- Starten Sie den docuBridge Client
- Prüfen Sie die Server- und Datenbankverbindung
- Testen Sie die Sidebar-Aktualisierung
¶ Deinstallation
Die Deinstallation erfolgt über die Windows-Systemsteuerung:
- Programme und Features → docuBridge → Deinstallieren
Konfigurations- und Log-Dateien können ggf. manuell entfernt werden.
¶ Logging
- Einsatz von Serilog
- Protokollierung von Import- und Serverereignissen
- Log-Ausgaben von Komponenten, die log4net verwenden, werden im docuBridge Server über
Log4NetToSerilogAppenderan Serilog weitergeleitet; Ereignisse ohne Level werden alsInformationprotokolliert.
¶ Log-Pfade
docuBridge Client
- Standardmäßig werden Client-Logs unter
C:\ProgramData\docuBridgegespeichert. - Der Log-Pfad kann in der Client-Konfiguration geändert werden.
- Nach Auswahl eines Log-Pfades wird automatisch ein Unterordner
Logserstellt. - Innerhalb des Ordners
Logswird zusätzlich ein projektbezogener Unterordner angelegt (docuBridge Client).
docuBridge Server / docuBridge Server Configurator
- Der initiale Log-Pfad kann während der Installation (MSI) festgelegt werden.
- Zusätzlich kann der Log-Pfad nachträglich im docuBridge Server Configurator über die Benutzeroberfläche angepasst werden.
- Nach Auswahl eines Log-Pfades wird automatisch ein Unterordner
Logserstellt. - Innerhalb des Ordners
Logswird jeweils ein separater Unterordner pro Projekt bzw. Komponente angelegt (docuBridge Server, docuBridge Server Configurator).
¶ Konfiguration der Log-Pfade
¶ docuBridge Client
Der Log-Pfad des docuBridge Clients wird in der Client-Konfigurationsdatei gespeichert:
C:\ProgramData\docuBridge\urlConfig\serverUrl.json
Änderungen am Log-Pfad erfolgen über die Client-Konfiguration und werden beim nächsten Start des Clients wirksam.
¶ docuBridge Server / docuBridge Server Configurator
Der Log-Pfad für den docuBridge Server sowie den docuBridge Server Configurator wird in einer separaten Konfigurationsdatei gespeichert:
..docuBridge\docuBridgeServer\Config\logConfig.json
Diese Konfiguration wird zentral über den docuBridge Server Configurator gepflegt.
Änderungen am Log-Pfad werden persistent gespeichert und gelten für alle nachfolgenden Starts des Servers bzw. des Configurators.
¶ Lizenzhinweise für Drittanbieter-Komponenten
Die Lizenzhinweise für alle ausgelieferten Fremdkomponenten (NuGet-Pakete, eingebettete swagger-ui, self-contained .NET-8-Laufzeit, native SQLite-Bibliotheken) liegen unter docubridge_poc\:
THIRD-PARTY-NOTICES.txt– generiertes Verzeichnis aller Komponenten mit Version, Lizenz und CopyrightLICENSES\– gemeinsame Lizenztexte (u. a.Apache-2.0.txt,MIT.txt,Microsoft.Data.SqlClient.SNI.txt, .NET-Lizenz und THIRD-PARTY-NOTICES der .NET- und ASP.NET-Core-Laufzeit)
Die Dateien werden mit Tools\Generate-ThirdPartyNotices.ps1 aus project.assets.json und den packages.config-Dateien erzeugt:
# Hinweise neu erzeugen
powershell -NoProfile -ExecutionPolicy Bypass -File "D:\git\fd.docuBridge\docubridge_poc\Tools\Generate-ThirdPartyNotices.ps1"
# Nur prüfen, ob die Hinweise aktuell sind
powershell -NoProfile -ExecutionPolicy Bypass -File "D:\git\fd.docuBridge\docubridge_poc\Tools\Generate-ThirdPartyNotices.ps1" -Check
- Beim Bau des Installers läuft das Skript automatisch und erzeugt die Hinweise neu.
- Beim Bau von
docubridge_pocläuft es nur mit-Checkund gibt eine Warnung aus, wennTHIRD-PARTY-NOTICES.txtveraltet ist. - Nach dem Hinzufügen, Entfernen oder Aktualisieren von Paketen müssen die neu erzeugten Dateien mit committet werden.
Der Installer liefert die Dateien über das nicht abwählbare Feature LicenseNoticesFeature in das Installationsverzeichnis aus (THIRD-PARTY-NOTICES.txt und Unterordner LICENSES).
¶ Build- und Installer-Skripte (MSI-Erstellung)
Dieses Kapitel beschreibt den Build- und Packaging-Prozess für docuBridge Client, docuBridge Server und docuBridge Server Configurator inklusive MSI-Erstellung mittels WiX Toolset v3.11.
¶ Voraussetzungen
- Visual Studio 2022 bzw. MSBuild
- .NET 8 SDK (für
dotnet publishdes Servers) - WiX Toolset v3.11
¶ MSI bauen
Der komplette Build erfolgt mit einem einzigen Aufruf des WiX-Projekts (alternativ: Build des Projekts Installer in Visual Studio):
& "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" `
"D:\git\fd.docuBridge\docubridge_poc\Installer\Installer.wixproj" `
/t:Rebuild /p:Configuration=Release /m
Ergebnis: docubridge_poc\Installer\bin\Release\docuBridge.msi
¶ Automatische Schritte beim Build
Vor dem Kompilieren des MSI führt das Target PrepareInstallerContent in Installer.wixproj folgende Schritte aus:
- Laufende Prozesse
docubridge_poc,WindowsFormsApp1unddocuBridge.Server.Configuratorwerden beendet, damit keine Dateisperren entstehen. - Die Publish-Ordner unter
Installer\publish\und der Harvest-OrdnerInstaller\obj\<Configuration>\Harvest\werden geleert und neu angelegt. - docuBridge Client und docuBridge Server Configurator werden per
ProjectReferencegebaut und ausbin\<Configuration>in die Publish-Ordner kopiert (ohne*.pdb,*.xml,*.vshost.*). - Der docuBridge Server wird als self-contained Single-File (
win-x86) veröffentlicht. heaterzeugtApp1_Harvest.wxs,App2_Harvest.wxsundApp3_Harvest.wxsaus den Publish-Ordnern (RunAsSeparateProcess, damit Visual Studio nicht abstürzt).HarvestFilter.xsltentfernt dabeidocubridge_poc.exeaus dem Server-Harvest, da diese Datei inService.wxsdefiniert ist.- Anschließend erzeugt das Target
GenerateThirdPartyNoticesdie Lizenzhinweise neu (siehe Lizenzhinweise für Drittanbieter-Komponenten).
Die Harvest-Dateien sind reine Build-Artefakte, werden nicht eingecheckt und dürfen nicht manuell bearbeitet werden.
InstallerPlatform ist auf x86 gesetzt (bei „Any CPU“ schlägt die Validierung mit ICE80 fehl).
¶ WiX-Quelldateien
| Datei | Inhalt |
|---|---|
Product.wxs |
Produkt, Verzeichnisstruktur, Features, Lizenzhinweise |
Service.wxs |
docubridge_poc.exe inkl. ServiceInstall/ServiceControl (Windows-Dienst docubridge_poc, Anzeigename „docuBridge Server“, Start manuell) |
Shortcuts.wxs |
Desktop- und Startmenü-Verknüpfung für den docuBridge Client, Startmenü-Verknüpfung für den docuBridge Configurator |
DocuBridge.UI.wxs, DocuBridge.LogFolderBrowseDlg.wxs |
Installationsdialoge inkl. Auswahl des Log-Verzeichnisses |
HarvestFilter.xslt |
Filter für den Server-Harvest |
WixUI_de-de.wxl |
Deutsche Lokalisierung |
¶ Features
| Feature | Inhalt |
|---|---|
docuBridgeFeature |
docuBridge Client (App1Group) + Verknüpfungen (ClientShortcuts) |
docubridge_pocFeature |
docuBridge Server (App2Group) + Windows-Dienst (ServerService) |
ConfiguratorFeature |
docuBridge Server Configurator (App3Group) + Verknüpfung (ConfiguratorShortcuts) |
LoggingFeature |
Log-Konfiguration (immer installiert, nicht abwählbar) |
LicenseNoticesFeature |
THIRD-PARTY-NOTICES.txt und LICENSES\ (immer installiert, nicht abwählbar) |
¶ Download
| Version | Anmerkung |
|---|---|
| 26.10.2 | initial |