Dokumentation

• 1: Überblick
• 1.1: Wie es funktioniert
• 1.2: Technische Architektur
• 2: Einrichtung
• 2.1: Voraussetzungen
• 2.2: Installation
• 2.3: Umgebungsvariablen
• 2.4: Container-Betrieb
• 3: Konfiguration
• 3.1: Verbindungen (connections)
• 3.2: Jobs (jobs)
• 3.3: Mappings (mappings)
• 3.4: Watermarks (watermark)
• 4: Konnektoren
• 4.1: D365BC — Business Central
• 4.2: D365CE — Dataverse / Customer Engagement
• 4.3: D365NAV — Microsoft Dynamics NAV
• 4.4: MSSQL — Microsoft SQL Server
• 4.5: MySQL — MySQL / MariaDB
• 4.6: Oracle — Oracle Database
• 4.7: PostgreSQL
• 4.8: OpenAPI — generischer REST-Konnektor
• 5: MCP-Server
• 5.1: Funktionsweise
• 5.2: Operationen
• 5.3: Nutzung
• 6: Betrieb & Wartung
• 6.1: Logging & Telemetrie
• 6.1.1: Metriken
• 6.1.2: Performance & Laufzeiten
• 6.2: Monitoring & Alerts
• 6.3: Grafana-Dashboard
• 6.4: Updates & Upgrades
• 7: Versionshistorie
• 7.1: Release v2.3
• 7.2: Release v2.2
• 7.3: Release v2.1
• 7.4: Release v2.0
• 7.5: Ältere Releases

1 - Überblick

Dieses Kapitel erklärt die dsyr.DataBridge auf zwei Ebenen: konzeptuell für alle, die verstehen wollen wie die Synchronisation abläuft — und technisch für diejenigen, die den genauen Aufbau der Komponenten kennen möchten.

1.1 - Wie es funktioniert

Das Grundprinzip

Die dsyr.DataBridge arbeitet wie ein kontinuierlicher Datenstrom zwischen zwei Systemen. Sie fragt regelmäßig: „Was hat sich seit dem letzten Mal geändert?" — und überträgt genau diese Änderungen ins Zielsystem. Nichts mehr, nichts weniger.

Kein manueller Export. Kein Doppelpflegen. Keine Vollsynchronisation, die alles neu schreibt. Nur die Differenz, automatisch, im Minutentakt.

Der Datenfluss in fünf Schritten

flowchart LR
    A([Quelldaten<br/>ändern sich]) -->|"alle 15 Sekunden<br/>prüfen"| B[DataBridge<br/>erkennt Änderung]
    B -->|"Datensätze<br/>puffern"| C[(Service Bus<br/>Queue)]
    C -->|"Nachricht<br/>verarbeiten"| D[Felder<br/>mappen & wandeln]
    D -->|"schreiben"| E([Zielsystem<br/>aktualisiert])
    E -->|"Stand merken"| F[(Watermark<br/>gespeichert)]
    F -.->|"nächster Lauf<br/>startet hier"| B

    style A fill:#e8f5f1,stroke:#18b28d,color:#111111
    style E fill:#e8f5f1,stroke:#18b28d,color:#111111
    style C fill:#fff3e0,stroke:#f57c00,color:#111111
    style F fill:#e3f2fd,stroke:#1565c0,color:#111111

Schritt 1 — Änderungen erkennen

Alle 15 Sekunden (konfigurierbar über GetChangesTimerExpression) startet ein Timer. Die DataBridge fragt das Quellsystem: „Gib mir alle Datensätze, die seit meinem letzten Stand geändert wurden."

Dafür nutzt sie den gespeicherten Watermark — einen Zeitstempel oder einen Änderungstoken, der beim letzten erfolgreichen Lauf hinterlegt wurde.

Schritt 2 — Änderungen puffern

Gefundene Datensätze landen nicht sofort im Zielsystem, sondern zunächst in einer Azure Service Bus Queue. Das entkoppelt Erkennung und Verarbeitung: Selbst wenn das Zielsystem kurz nicht erreichbar ist, gehen keine Daten verloren. Die Queue speichert die Nachrichten bis zur erfolgreichen Verarbeitung.

Schritt 3 — Felder mappen und wandeln

Jede Nachricht aus der Queue wird einzeln verarbeitet. Die DataBridge liest die konfigurierten Mappings und weiß: Quellfeld A geht in Zielfeld B, Wert X wird zu Wert Y übersetzt, ein fehlendes Feld bekommt einen Standardwert.

Dieser Schritt ist vollständig konfigurierbar — ohne Programmierung.

Schritt 4 — Ins Zielsystem schreiben

Der gemappte Datensatz wird ins Zielsystem geschrieben. Die DataBridge prüft dabei anhand eines konfigurierten Schlüssels, ob der Datensatz dort bereits existiert:

• Existiert: Update des vorhandenen Datensatzes
• Existiert nicht: Neuanlage

Schritt 5 — Watermark aktualisieren

Nach erfolgreichem Durchlauf speichert die DataBridge den neuen Stand als Watermark. Beim nächsten Timer-Aufruf dient dieser Wert als Startpunkt — so werden Datensätze weder doppelt übertragen noch übersprungen.

Bidirektionale Synchronisation

Die fünf Schritte gelten für eine Richtung der Synchronisation. Wenn Daten in beide Richtungen fließen sollen (z. B. BC → Dataverse und Dataverse → BC), werden zwei unabhängige Jobs konfiguriert — jeder mit eigenem Quell- und Zielsystem, eigenem Mapping und eigenem Watermark.

Prioritäten und Parallelverarbeitung

Nicht alle Datensätze sind gleich wichtig. Die DataBridge kennt drei Prioritätsstufen:

Nachrichten mit hoher Priorität werden bevorzugt verarbeitet, ohne dass niedrigere Prioritäten blockiert werden.

Was passiert bei Fehlern?

Schlägt die Verarbeitung einer Nachricht fehl, gibt es mehrere Sicherheitsnetze:

1. Automatischer Wiederholungsversuch — die Nachricht wird nach kurzer Wartezeit erneut verarbeitet (bis zu einer konfigurierten Maximalanzahl).
2. Transitive Queue — meldet das Zielsystem einen Konflikt (z. B. ein Duplikat), wird die Nachricht in eine separate Queue abgelegt, damit sie den Hauptpfad nicht blockiert. Dort wird sie nicht automatisch erneut verarbeitet, sondern bei Bedarf manuell zurückgestellt.
3. Dead-Letter Queue — dauerhaft nicht verarbeitbare Nachrichten werden dort gesammelt und können analysiert oder manuell re-queued werden.

In keinem dieser Fälle gehen Daten still verloren. Das Monitoring und die konfigurierbaren Alerts informieren aktiv, wenn die Dead-Letter Queue Einträge enthält.

1.2 - Technische Architektur

Azure-Komponenten

Die DataBridge besteht aus mehreren Azure-Diensten, die in einer gemeinsamen Ressourcengruppe betrieben werden:

Architektur nach dem C4-Modell

Die folgenden drei Diagramme folgen dem C4-Modell (Context → Container → Component) — von außen nach innen, jede Ebene zoomt weiter in die DataBridge hinein.

Ebene 1 — System Context

Wer nutzt die DataBridge, und mit welchen Systemen tauscht sie Daten aus?

flowchart TB
    admin(["👤 Administrator"])
    ki(["🤖 KI-Assistent<br/><small>z. B. Claude Code</small>"])

    databridge["dsyr.DataBridge<br/><small>Synchronisiert Datensätze zwischen<br/>Quell- und Zielsystemen</small>"]

    bc["D365 Business Central<br/><small>ERP — Quelle/Ziel</small>"]
    ce["D365 CE / Dataverse<br/><small>CRM — Quelle/Ziel</small>"]
    nav["D365 NAV<br/><small>ERP — Quelle/Ziel</small>"]
    sql[("SQL-Datenbanken<br/><small>nur Quelle</small>")]
    rest["Beliebige REST-API<br/><small>über OpenAPI-Spec</small>"]

    admin -->|"konfiguriert, überwacht"| databridge
    ki -->|"MCP über HTTPS"| databridge
    databridge <-->|"OData v4, OAuth2/API-Key"| bc
    databridge <-->|"Dataverse SDK"| ce
    databridge <-->|"OData, Basic Auth"| nav
    databridge -->|"ADO.NET"| sql
    databridge <-->|"REST, aus Spec aufgelöst"| rest

    style databridge fill:#1565c0,color:#fff,stroke:#0d47a1,stroke-width:2
    style admin fill:#08427b,color:#fff,stroke:#052e56
    style ki fill:#08427b,color:#fff,stroke:#052e56
    style bc fill:#8b8b8b,color:#fff,stroke:#666
    style ce fill:#8b8b8b,color:#fff,stroke:#666
    style nav fill:#8b8b8b,color:#fff,stroke:#666
    style sql fill:#8b8b8b,color:#fff,stroke:#666
    style rest fill:#8b8b8b,color:#fff,stroke:#666

Ebene 2 — Container

Innerhalb des eigenen Azure-Abonnements des Kunden besteht die DataBridge aus fünf Containern (im C4-Sinn: separat betreibbare/skalierbare Einheiten):

flowchart TB
    admin(["👤 Administrator"])
    ki(["🤖 KI-Assistent"])

    subgraph RG["Ressourcengruppe des Kunden"]
        func["Function App<br/><small>.NET 10, Isolated Worker</small>"]
        sb[["Service Bus<br/><small>7 Queues</small>"]]
        ts[("Table Storage<br/><small>connections/jobs/<br/>mappings/watermark</small>")]
        appins["Application Insights"]
        graf["Grafana-Dashboard"]

        func <-->|"Nachrichten"| sb
        func <-->|"Konfiguration & Watermark"| ts
        func -->|"Telemetrie"| appins
        appins --> graf
    end

    systems["Quell-/Zielsysteme<br/><small>D365 BC/CE/NAV, SQL, REST</small>"]

    admin -->|"konfiguriert (Table Storage)"| func
    ki -->|"ruft MCP-Tools auf"| func
    func <-->|"liest/schreibt Datensätze"| systems

    style func fill:#1565c0,color:#fff,stroke:#0d47a1,stroke-width:2
    style sb fill:#1565c0,color:#fff,stroke:#0d47a1
    style ts fill:#1565c0,color:#fff,stroke:#0d47a1
    style appins fill:#1565c0,color:#fff,stroke:#0d47a1
    style graf fill:#1565c0,color:#fff,stroke:#0d47a1
    style admin fill:#08427b,color:#fff,stroke:#052e56
    style ki fill:#08427b,color:#fff,stroke:#052e56
    style systems fill:#8b8b8b,color:#fff,stroke:#666
    style RG fill:#f5f5f5,stroke:#999,color:#111111,stroke-dasharray: 4 2

Ebene 3 — Component

Innerhalb des Containers Function App sind die Funktionen (Trigger-Ebene) von der Service-Schicht (Logik-Ebene) getrennt. Um das Diagramm lesbar zu halten, wird die Service-Schicht hier als ein Component dargestellt und direkt im Anschluss (Abschnitt Service-Schicht) sowie in der Connector-Hierarchie weiter aufgeschlüsselt — das C4-Modell ist für genau dieses schrittweise Hineinzoomen gedacht.

flowchart TB
    subgraph FA["Function App"]
        getchanges["GetChanges<br/><small>Timer</small>"]
        processq["Process*QueueItems<br/><small>Service-Bus-Trigger (3x)</small>"]
        executejob["ExecuteJob / ExecuteHttpRequest<br/><small>HTTP</small>"]
        diagapi["CheckList / Validate / JobApi /<br/>MappingApi<br/><small>HTTP, read-only</small>"]
        mcp["McpApi<br/><small>MCP-Server für KI-Assistenten</small>"]
        orch["Orchestrator<br/><small>Durable, alternativ zu GetChanges</small>"]

        services["Service-Schicht<br/><small>InitializationService + 8 Services<br/>— siehe Detail-Diagramm unten</small>"]
        connectors["Connector-Schicht<br/><small>IConnector-Implementierungen<br/>— siehe Connector-Hierarchie</small>"]

        getchanges --> services
        processq --> services
        executejob --> services
        diagapi --> services
        mcp --> services
        orch --> services
        services --> connectors
    end

    style services fill:#1565c0,color:#fff,stroke:#0d47a1,stroke-width:2
    style connectors fill:#1565c0,color:#fff,stroke:#0d47a1,stroke-width:2
    style FA fill:#f5f5f5,stroke:#999,color:#111111,stroke-dasharray: 4 2

Die Azure Functions

Alle Funktionen laufen in derselben Function App und teilen sich eine gemeinsame Service-Schicht:

Zusätzlich existiert eine optionale Durable-Orchestrierung als Alternative zum Timer-Pfad (StartGetChangesOrchestration, GetChangesOrchestrator, GetChangesActivity und die Durable Entity JobState). Sie wird ausschließlich per HTTP gestartet und ist im Regelbetrieb nicht aktiv.

Alle Funktionen lassen sich einzeln per App-Setting deaktivieren (AzureWebJobs.<Funktionsname>.Disabled), ohne die Function App neu zu deployen.

Queue-Struktur im Service Bus

Der Service Bus Namespace enthält sieben Queues:

flowchart TD
    GC[GetChanges] -->|Priorität: Hoch| QH[sbqhighexport]
    GC -->|Priorität: Standard| QS[sbqexport]
    GC -->|Priorität: Niedrig| QL[sbqlowexport]

    QH --> PH[ProcessHighPriorityQueueItems]
    QS --> PS[ProcessStandardQueueItems]
    QL --> PL[ProcessLowPriorityQueueItems]

    PH -->|"Konflikt im Ziel<br/>(HTTP 409)"| TH[sbqtransitivehigh]
    PS -->|"Konflikt im Ziel<br/>(HTTP 409)"| TS[sbqtransitivestandart]
    PL -->|"Konflikt im Ziel<br/>(HTTP 409)"| TL[sbqtransitivelow]

    PH -->|"SkipOutdatedMessages"| IGN[sbqignored]
    PS --> IGN
    PL --> IGN

    PH -->|"max. Zustellversuche<br/>überschritten"| DLQ[("Dead-Letter-Subqueue<br/>je Queue")]
    PS --> DLQ
    PL --> DLQ

    style QH fill:#fce4ec,stroke:#c62828,color:#111111
    style QS fill:#fff3e0,stroke:#e65100,color:#111111
    style QL fill:#e8f5e9,stroke:#2e7d32,color:#111111
    style TH fill:#fce4ec,stroke:#c62828,color:#111111,stroke-dasharray: 4 2
    style TS fill:#fff3e0,stroke:#e65100,color:#111111,stroke-dasharray: 4 2
    style TL fill:#e8f5e9,stroke:#2e7d32,color:#111111,stroke-dasharray: 4 2
    style IGN fill:#f3e5f5,stroke:#6a1b9a,color:#111111
    style DLQ fill:#b0bec5,stroke:#37474f,color:#111111

Service-Schicht

Alle Funktionen teilen eine gemeinsame Service-Schicht. Die Services selbst sind DI-Singletons; lazy und thread-sicher nachgeladen wird die Konfiguration beim ersten Aufruf. Das folgende Diagramm zoomt gegenüber dem C4-Component-Diagramm oben gezielt auf den InitializationService-Teilbaum und dessen Initialisierungsreihenfolge. InitializationService (bis v2.3 CoreService) ist reduziert auf Initialisierung und Ready/Error-Zustand — er ist kein Service-Locator: ProcessJobsForRetrievalInOrderService und ProcessQueueMessageService werden von den Functions, die sie brauchen (GetChanges/ExecuteJob bzw. Process*QueueItems), direkt injiziert, nicht über ihn geroutet:

flowchart TB
    IS["InitializationService<br/>Lazy Konfigurations-Laden<br/>thread-sicher"]

    IS --> STORE["StorageService<br/>Table-Storage-CRUD"]
    IS --> CONS["ConnectionService<br/>Verwaltet Connector-Instanzen<br/>je Connection-Name"]
    IS --> MS["MappingService<br/>Gruppiert FieldMappings<br/>je Mapping-Name"]
    IS --> JS["JobService<br/>Prüft Schedules<br/>validiert Job-Konfiguration"]
    IS --> CHK["CheckListService<br/>Diagnose"]

    PJRS["ProcessJobsForRetrievalInOrderService<br/>Erkennungs-Pfad"] --> WS["WatermarkService"]
    PJRS --> SBS["ServiceBusService"]
    PQS["ProcessQueueMessageService<br/>Verarbeitet einzelne<br/>Nachrichten End-to-End"] --> SBS
    PQS --> WS
    JS --> WS
    WS --> STORE

    style IS fill:#e8f5f1,stroke:#18b28d,color:#111111,stroke-width:2

Daneben stehen Querschnitts-Services, die nicht unter dem InitializationService-Teilbaum hängen:

• SettingsService — liest App-Settings und Connection-Strings aus der Konfiguration (nicht aus Table Storage)
• MetricsService — sendet vorab aggregierte Custom Metrics an Application Insights (z. B. ChangesDetected je Job)
• McpToolService — bündelt die Tool-Logik hinter dem MCP-Server: ruft JobService, MappingService, ServiceBusService und ConnectionService auf und stößt darüber (wie JobApi/MappingApi) selbst einmalig InitializationService.EnsureInitializedAsync an — hängt also nicht im InitializationService-Baum, sondern davor

Initialisierungsreihenfolge:

1. StorageService prüft die vier Tabellen und legt fehlende an
2. ConnectionService liest connections, deserialisiert die JSON-Verbindungsdaten und führt je System einen Verbindungstest aus
3. MappingService liest mappings und gruppiert die Einträge nach Mapping-Name
4. JobService liest jobs und validiert sie: existieren Verbindungen und Mappings? Ist die Cron-Expression gültig?

Schlägt ein Verbindungstest fehl, wird der Fehler protokolliert und der laufende Aufruf mit einer Exception beendet. Die Initialisierung wird zurückgesetzt und beim nächsten Timer-Aufruf bzw. bei der nächsten Queue-Nachricht erneut versucht (Self-Repair). Bei Queue-Nachrichten bedeutet das: die Nachricht wird abandoned und zählt gegen maxDeliveryCount.

Connector-Hierarchie

Detailansicht der Komponente Connector-Schicht aus dem C4-Component-Diagramm oben — als UML-artiges Klassendiagramm, da C4 Vererbungshierarchien nicht sauber abbilden kann. Jedes Quell- und Zielsystem wird durch einen Konnektor abstrahiert. Alle Konnektoren implementieren dasselbe Interface und sind damit gegeneinander austauschbar:

flowchart TD
    IC["«interface»<br/>IConnector"]

    CB["ConnectorBase<br/>Serialisierung, Caching,<br/>Filter-Templating,<br/>Key-Vault-Integration"]

    HCB["HttpConnectorBase<br/>OAuth2 / Basic Auth,<br/>Token-Lifecycle,<br/>HTTP-Client-Management"]

    SCB["SqlConnectorBase<br/>ADO.NET, Schema-Caching,<br/>Paging (OFFSET / FETCH)"]

    IC --> CB
    CB --> HCB
    CB --> SCB
    CB --> CE["CeConnector<br/>Dataverse SDK"]

    HCB --> BC["BcConnector<br/>OData v4 API"]
    HCB --> NAV["NavConnector<br/>OData / Basic Auth"]
    HCB --> OA["OpenApiConnector<br/>Generische REST-API,<br/>Pfade aus OpenAPI-Spec"]

    SCB --> SQL[MsSqlConnector]
    SCB --> PG[PostgreSqlConnector]
    SCB --> MY[MySqlConnector]
    SCB --> OR[OracleConnector]

    style IC fill:#e3f2fd,stroke:#1565c0,color:#111111
    style CB fill:#e8f5f1,stroke:#18b28d,color:#111111
    style HCB fill:#fff3e0,stroke:#e65100,color:#111111
    style SCB fill:#fce4ec,stroke:#c62828,color:#111111

Für die Typumwandlung greifen zwei Bausteine ineinander:

• TargetValueMapper — wählt anhand des Zielsystem-Metadatentyps (EDM bei BC/NAV, AttributeMetadata bei Dataverse) den passenden Resolver aus. Existiert je Connector.
• AttributeResolver — führt die eigentliche Typumwandlung durch (Boolean, Date, DateTime, Decimal, Guid, Integer, String; bei Dataverse zusätzlich Picklist, Lookup, Money, State/Status, MultiSelect). Liegt als Resolver-Familie je Systemtyp vor.

IConnector stellt zusätzlich GetTableMetadata(tableName, apiPath) bereit: liefert Typ, Nullable, maximale Länge und Primary-Key-Information je Spalte direkt aus dem Zielsystem — implementiert für alle Connector-Typen, seit v2.3 auch für die SQL-Familie. Dient vor allem dem MCP-Server zur Validierung von Mappings gegen das echte Schema.

Änderungserkennung pro Connector-Typ

Die Methode, mit der Änderungen erkannt werden, unterscheidet sich je nach System:

Der Watermark-Wert wird pro Job in der Tabelle watermark gespeichert und am Ende der Erkennungsphase fortgeschrieben. Ein manuelles Leeren des Watermarks erzwingt einen vollständigen Neulauf des jeweiligen Jobs.

Über CRUD hinaus: Aktions-Jobs, job-eigene Pfade, eingebettete Kinder

Drei neuere Erweiterungen des Job-/Mapping-Modells betreffen nicht nur den OpenAPI-Konnektor, sind dort aber am relevantesten:

• InvokeAction — ein Job mit einem Action-Wert, der keinem bekannten JobActionType entspricht, ruft statt eines CRUD-Vorgangs einen benannten, nicht-CRUD-Endpunkt auf (z. B. einen OpenAPI-operationId oder ein CE-OrganizationRequest). Details: Jobs → InvokeAction.
• Job-eigene Source-/Target-Pfade — ein Job kann über Source/Target die SourceTable/TargetTable seiner Mapping-Zeilen überschreiben (bzw. bei fehlendem Mapping ein synthetisches Mapping erzeugen), sodass eine Mapping-Gruppe für mehrere Ressourcen oder Aktionspfade wiederverwendet werden kann. Details: Jobs → Source und Target.
• EmbedChildren — bettet die Datensätze eines referenzierten Kind-Jobs bereits beim Lesen in die Nachricht des Elterndatensatzes ein, sodass Eltern- und Kind-Datensätze gemeinsam als eine Nachricht verarbeitet werden (derzeit nur mit D365CE als Quellsystem). Details: Mappings → EmbedChildren.

Retry- und Fehlerverhalten

2 - Einrichtung

Dieses Kapitel führt Schritt für Schritt durch die erstmalige Einrichtung einer dsyr.DataBridge-Instanz. Am Ende steht eine vollständig deployete und konfigurierte Azure Function App, die synchronisieren kann.

Empfohlene Reihenfolge:

1. Voraussetzungen — Benutzer, Berechtigungen, Azure-Provider
2. Installation — Azure-Ressourcen per Bicep anlegen, Function deployen
3. Umgebungsvariablen — Alle Einstellungen im Function-App-Kontext

Ergänzend, außerhalb des regulären Installationswegs:

• Container-Betrieb — Betrieb als Container-Image. Beta, nicht für den Kundenbetrieb vorgesehen.

2.1 - Voraussetzungen

Bevor die DataBridge installiert werden kann, müssen die folgenden Voraussetzungen in Azure, Dataverse und Business Central erfüllt sein.

Azure-Abonnement

Ein aktives Azure-Abonnement ist Pflicht. Im Abonnement müssen die folgenden Resource Provider registriert sein:

Provider können im Azure Portal unter Abonnement → Ressourcenanbieter aktiviert werden.

Empfohlene Instanzen-Struktur

Pro Umgebung wird eine eigene DataBridge-Instanz (= Ressourcengruppe) benötigt. Als Regelfall werden zwei Instanzen empfohlen:

Eine Entwicklungsinstanz ist meist nicht nötig, da die Entwicklung der DataBridge selbst bei WYSA liegt und sich eine Synchronisation im Entwicklungssystem selten lohnt.

Eine dritte Instanz für Entwicklung ist dann sinnvoll, wenn im Entwicklungssystem eigene Anpassungen an Dataverse oder Business Central entstehen, die vor dem Test gegen eine laufende Synchronisation geprüft werden sollen — etwa neue Felder, geänderte Optionssets oder umgebaute Entitäten. In diesem Fall werden drei Ressourcengruppen benötigt (Entwicklung, Test, Produktion).

Laufzeitumgebung

Die DataBridge läuft als Azure Function App. Die folgenden Eckdaten werden vom Deployment gesetzt und müssen nicht vorbereitet werden — sie sind hier als Referenz für die Abstimmung mit der IT aufgeführt:

Beim containerisierten Betrieb wird zusätzlich Zugriff auf die WYSA-Container-Registry benötigt. Das aktuelle Image ist acrwysatest.azurecr.io/containered-connector:v2.3.0.

Unterstützte Quell- und Zielsysteme

Für die vier SQL-Systeme gelten die unten beschriebenen Anforderungen an Anwendungsbenutzer und Change Tracking nicht — dort werden lediglich ein Connection String und die Netzwerkerreichbarkeit aus Azure heraus benötigt. Die Konnektoren sind als Vorabversion eingestuft und unterstützen kein Schreiben; Details auf den Konnektor-Seiten.

Benutzerkonten

Die folgenden Anforderungen gelten für die Anbindung von Dataverse und Business Central. Für SQL-Quellsysteme genügt ein Datenbankbenutzer mit Leserechten.

Administrations-/Betreuungsbenutzer (Entra-Benutzer)

Für die Einrichtung und Pflege von Dataverse und Business Central wird ein menschlicher Benutzer benötigt, der in Entra ID existiert und entsprechend lizensiert ist.

Anwendungsbenutzer (Service Principal / App Registration)

Anwendungsbenutzer ermöglichen der DataBridge den automatisierten, sicheren Zugriff auf die Systeme — ohne personengebundene Credentials.

Minimum: 1 Anwendungsbenutzer pro DataBridge-Instanz.

Empfehlung: 3 Anwendungsbenutzer für maximale Sicherheit und klare Trennung:

Alle Anwendungsbenutzer müssen als App Registration in Entra ID angelegt und in den jeweiligen Systemen als S2S-Benutzer registriert sein.

Dataverse: Change Tracking aktivieren

Für alle Dataverse-Tabellen, die als Quelle genutzt werden sollen, muss Change Tracking aktiviert sein. Ohne Change Tracking kann die DataBridge keine effizienten Differenzabfragen durchführen.

Aktivierung: Power Platform Admin Center → Umgebung → Tabellen → Tabelle auswählen → Eigenschaften → „Änderungsnachverfolgung aktivieren" ✅

Benötigte Software für die Installation

Für das Deployment per Bicep / Azure CLI muss auf dem ausführenden Rechner installiert sein:

Bicep-Extension installieren und verifizieren:

az bicep install
az bicep version   # Ausgabe sollte ≥ 0.35 zeigen

Die Installation selbst kann durch WYSA durchgeführt werden, sofern der Deployment-Anwendungsbenutzer mit Contributor-Rechten auf der Ressourcengruppe bereitgestellt wurde. Soll der Preview-Schalter enableManagedIdentity genutzt werden, benötigt der Deployment-User Owner oder User Access Administrator, da dabei Rollenzuweisungen angelegt werden.

2.2 - Installation

Für die Installation gibt es zwei Wege:

Beide Wege legen dieselben Ressourcen an und sind gleichwertig im Ergebnis.

Weg 1 — Azure Marketplace (empfohlen)

1. Ressourcengruppe anlegen

Im Azure Portal eine neue Ressourcengruppe für die DataBridge-Instanz erstellen. Pro Umgebung (Test, Produktion) wird eine eigene Ressourcengruppe verwendet.

2. DataBridge aus dem Marketplace auswählen

In der Ressourcengruppe Erstellen wählen und im Marketplace nach der WYSA DataBridge suchen.

3. Region und Kurzname festlegen

4. Produkteinstellungen

Unter Product Settings werden die fachlichen Einstellungen gruppiert:

Alle Telemetrie-Einstellungen können auf den Vorgabewerten bleiben und später jederzeit in den Umgebungsvariablen angepasst werden.

5. Service Bus

6. Storage Account

Als Speicherkonto-Typ steht ausschließlich StorageV2 zur Verfügung.

7. App Service Plan

Anschließend über Überprüfen und erstellen das Deployment starten.

Weg 2 — Bicep / Azure CLI

1. Bicep-Dateien bereitstellen

Die Bicep-Templates befinden sich im Repository unter bicep/. Klone das Repository oder lade die Dateien auf den Rechner, von dem aus die Installation durchgeführt wird.

2. Bei Azure anmelden

az login

Es öffnet sich ein Browser-Fenster. Melde dich mit dem Deployment-Anwendungsbenutzer oder dem Administrations-Benutzer an, der Contributor-Rechte auf der Ziel-Ressourcengruppe hat. Den Haken bei „Zugriffseinwilligung für alle Benutzer" nicht setzen.

3. Abonnement prüfen

az account show

Vergleiche die angezeigte Abonnement-ID mit der ID im Azure Portal. Falls mehrere Abonnements vorhanden sind, das richtige setzen:

az account set --subscription "<Abonnement-ID>"

4. Ressourcen deployen

az deployment group create --template-file ./bicep/main.bicep --resource-group <Name-der-Ressourcengruppe> --parameters name=<instanzname> -c

Das Flag -c zeigt eine Vorschau der Änderungen an. Mit Y oder J bestätigen.

Bicep-Parameter im Überblick

Infrastruktur:

Laufzeit und Telemetrie:

Alerts:

Was angelegt wird

Nach erfolgreichem Deployment existieren in der Ressourcengruppe:

Service-Bus-Queues: sbqexport · sbqhighexport · sbqlowexport · sbqignored · sbqtransitivehigh · sbqtransitivestandart · sbqtransitivelow

Table-Storage-Tabellen: connections, jobs, mappings, watermark — sie werden vom Deployment leer angelegt.

Phase 2 — Function App befüllen

Beim Marketplace-Weg entfällt dieser Schritt in der Regel; das Paket wird mit ausgeliefert. Beim Bicep-Weg wird der Anwendungscode separat eingespielt.

Option A: Container-Image

Wird die DataBridge containerisiert betrieben, verweist die Function App auf das bereitgestellte Image:

acrwysatest.azurecr.io/containered-connector:v2.3.0

Option B: Zip-Upload per Azure Portal

1. Im Azure Portal die Function App öffnen
2. Entwicklungstools → Erweiterte Tools (Kudu) öffnen
3. In Kudu: Tools → Zip Push Deploy
4. Die bereitgestellte .zip-Datei per Drag & Drop hochladen
5. Nach dem Upload startet die Function App automatisch neu

Option C: Deployment-Pipeline

Das Deployment kann über eine CI/CD-Pipeline automatisiert werden. WYSA stellt hierfür Azure-Pipeline-Definitionen zur Verfügung (cicd/-Verzeichnis). Alternativ kann eine eigene Azure-DevOps- oder GitHub-Actions-Pipeline verwendet werden.

Nach der Installation: Konfigurationstabellen befüllen

Nach dem Deployment laufen die Azure Functions — aber noch ohne Konfiguration. Die vier Table-Storage-Tabellen existieren, sind aber leer:

Die Tabellen können über den Azure Storage Explorer oder direkt im Azure Portal (Storage Account → Tables) bearbeitet werden.

Details zu den Tabellen und den erwarteten Feldern sind im Kapitel Konfiguration beschrieben.

Umgebungsvariablen prüfen

Alle Verbindungs-Strings sowie der Timer-Ausdruck und die Telemetrie-Einstellungen werden vom Deployment gesetzt. Nachträglich anzupassen sind sie nur, wenn vom Vorgabewert abgewichen werden soll.

Eine vollständige Übersicht findet sich auf der Seite Umgebungsvariablen.

Installation prüfen

Sobald Konfigurationstabellen und Umgebungsvariablen gesetzt sind, kann die Installation geprüft werden:

GET https://func-<name>.azurewebsites.net/api/GetInfo?code=<Function-Key>

Eine erfolgreiche Antwort sieht so aus:

{
  "Version": "2.1.2026.802"
}

Alternativ: Im Azure Portal → Function App → Funktionen → GetInfo → Testen/Ausführen — dort wird der Schlüssel automatisch mitgegeben.

Für eine inhaltliche Prüfung der Konfiguration stehen zusätzlich die Diagnose-Funktionen Validate (prüft die hinterlegte Konfiguration) und CheckList (gleicht Mappings gegen die Attribute der beteiligten Systeme ab) zur Verfügung.

2.3 - Umgebungsvariablen

Die DataBridge Function App wird über Anwendungseinstellungen (Application Settings) konfiguriert. Diese sind im Azure Portal unter Function App → Einstellungen → Umgebungsvariablen zu finden und zu bearbeiten.

Infrastruktur-Verbindungen

Diese Variablen verbinden die Function App mit den zugehörigen Azure-Diensten. Sie werden durch das Deployment automatisch befüllt.

¹ Schlüssel- oder identitätsbasiert. Standardmäßig werden die beiden Connection Strings gesetzt. Zusätzlich setzt das Deployment in diesem Modus TARGET_BASED_SCALING_ENABLED=0: Target-based Scaling ist damit abgeschaltet, der Host skaliert direkt über den Metrics Monitor und die entsprechende Warnung im Log entfällt. Ist der Preview-Schalter enableManagedIdentity (Bicep) aktiv, entfallen sie und werden durch die identitätsbasierten Varianten ersetzt — die Function nutzt dann die Managed Identity:

Lokal (local.settings.json) bleiben die schlüsselbasierten Connection Strings maßgeblich.

Laufzeit-Einstellungen

CRON-Ausdruck — Format

Der CRON-Ausdruck nutzt das 6-stellige NCrontab-Format (inkl. Sekunden):

┌─────────── Sekunde  (0–59)
│ ┌───────── Minute   (0–59)
│ │ ┌─────── Stunde   (0–23)
│ │ │ ┌───── Tag      (1–31)
│ │ │ │ ┌─── Monat    (1–12)
│ │ │ │ │ ┌─ Wochentag (0–6, Sonntag=0)
│ │ │ │ │ │
*/15 * * * * *  →  alle 15 Sekunden (Vorgabe)
0 */2 * * * *   →  alle 2 Minuten
0 */5 * * * *   →  alle 5 Minuten
0 0 */1 * * *   →  stündlich

Einzelne Jobs können über das Feld Schedule einen eigenen, seltener greifenden Zeitplan bekommen — siehe Jobs.

Logging & Telemetrie

Die DataBridge steuert ihr Telemetrie-Volumen über zwei Mechanismen: gepuffertes Logging für Log-Einträge und Sampling für ausgehende Aufrufe. Ausführlich beschrieben unter Betrieb → Logging.

Telemetrie-Verhalten im Überblick

Trace-Einträge erreichen Application Insights grundsätzlich nie — auch nicht bei Fehler-Läufen. Sie sind ausschließlich live im Log Stream der Function App bzw. im Container-Log sichtbar.

Abhängigkeiten

Die Entscheidung fällt hier pro Aufruf und nicht pro Funktionsausführung — ein fehlgeschlagener Lauf enthält deshalb nicht zwangsläufig die erfolgreichen Aufrufe davor.

Funktionen gezielt deaktivieren

Einzelne Azure Functions können ohne Redeployment deaktiviert werden. Das ist nützlich, um z. B. die Quellabruf-Funktion zu stoppen, ohne die Queue-Verarbeitung zu unterbrechen.

Das Namensschema AzureWebJobs.<Funktionsname>.Disabled gilt für jede Function der App. Neben den vier betrieblich relevanten oben sind das:

ExecuteJob · ExecuteHttpRequest · GetInfo · Validate · CheckList · StartGetChangesOrchestration · GetChangesOrchestrator · GetChangesActivity · JobState

Die letzten vier gehören zur optionalen Durable-Orchestrierung, die im Regelbetrieb ohnehin nicht aktiv ist.

Plattform-Einstellungen — nicht verändern

Diese Werte setzt das Deployment. Sie steuern die Azure-Functions-Laufzeit selbst und haben keinen fachlichen Bezug zur DataBridge:

Nur im Container-Betrieb

Key Vault (optional)

Statt Connection Strings direkt in den Anwendungseinstellungen zu speichern, können diese in einem Azure Key Vault hinterlegt werden. Die Function App referenziert das Secret dann per Key Vault Reference:

@Microsoft.KeyVault(SecretUri=https://<vault>.vault.azure.net/secrets/<name>/)

Diese Referenz wird direkt als Wert der jeweiligen Umgebungsvariable eingetragen. Azure löst sie zur Laufzeit automatisch auf — ohne Änderungen am Code.

Für die Zugangsdaten zu Quell- und Zielsystemen gibt es einen zweiten, davon unabhängigen Weg über den Parameter keyVaultUrl im Verbindungs-JSON — siehe Verbindungen.

2.4 - Container-Betrieb

Die DataBridge lässt sich als Container-Image bauen und betreiben. Das Image basiert auf der Azure-Functions-Laufzeit und enthält dieselbe Anwendung wie das reguläre Deployment.

Sinnvoll ist der Container-Betrieb derzeit vor allem für lokale Tests und Entwicklung: Die HTTP-Trigger lassen sich damit ohne Azure-Deployment aufrufen.

Voraussetzungen

Alle Befehle auf dieser Seite werden aus dem Ordner src/ ausgeführt — dort liegen Dockerfile, compose.yml und die Start-Scripts.

Image bauen

Das Dockerfile liegt in src/. Bei Bedarf lässt sich dort das Basis-Image anpassen.

• Docker
• Podman

docker build --tag acrwysatest.azurecr.io/containered-connector:v2.3.0 .

podman build --tag acrwysatest.azurecr.io/containered-connector:v2.3.0 .

Allgemein aufgebaut ist der Tag so:

{acr-name}.azurecr.io/{image-name}:{version}

In die Azure Container Registry veröffentlichen

Zunächst an Azure und anschließend an der Registry anmelden:

az login

az acr login --name acrwysatest

Danach das gebaute Image veröffentlichen:

docker push acrwysatest.azurecr.io/containered-connector:v2.3.0

Damit steht das Image unter der angegebenen Versionsnummer in der Registry bereit.

az acr update -n acrwysatest --admin-enabled true

Lokal betreiben

Umgebungsdatei anlegen

In src/.podman/ liegt die Vorlage podman.env.sample. Diese kopieren und unter dem Namen podman.<Umgebung>.env ablegen, zum Beispiel podman.wysatest.env:

cp .podman/podman.env.sample .podman/podman.wysatest.env

Anschließend die Datei mit den Verbindungsdaten der Zielumgebung füllen. Sie enthält unter anderem AzureWebJobsStorage, ConnectionStrings__ExportQueueServiceBus, APPLICATIONINSIGHTS_CONNECTION_STRING, den Timer-Ausdruck GetChangesTimerExpression sowie die Funktions-Toggles.

Danach in src/compose.yml prüfen, dass env_file auf die richtige Datei verweist:

    env_file:
      - .podman/podman.wysatest.env

Der Container veröffentlicht seinen Port unter 7071 und setzt AzureWebJobsSecretStorageType=files, damit die Function-Keys im Container abgelegt werden können.

Start-Script (empfohlen)

Der einfachste Weg sind die mitgelieferten Start-Scripts in src/. Sie bauen das Image, starten den Container und geben anschließend alle HTTP-Trigger-URLs inklusive Authentication-Key aus.

• Linux / macOS
• Windows (PowerShell)

bash start-local.sh

.\start-local.ps1

Die Ausgabe sieht dann ungefähr so aus:

============================================
 DataBridge lokal gestartet
============================================
 Master Key: abc123...

 HTTP-Trigger URLs:

 [GET]  http://127.0.0.1:7071/api/GetInfo?code=abc123...
 [GET]  http://127.0.0.1:7071/api/CheckList?code=abc123...
 [POST] http://127.0.0.1:7071/api/ExecuteJob?code=abc123...
 [POST] http://127.0.0.1:7071/api/ExecuteHttpRequest?code=abc123...
============================================

Die URLs lassen sich direkt im Browser öffnen oder in Bruno beziehungsweise curl verwenden.

Manueller Start

Wer den Container selbst steuern möchte, startet ihn aus dem Ordner src/:

podman compose up --build -d

Logs anzeigen:

podman compose logs -f

Container beenden:

podman compose down

Installation prüfen

Ob der Container korrekt läuft, lässt sich über die HTTP-Trigger prüfen — GetInfo liefert die Version, CheckList und Validate prüfen Mappings und Konfiguration. Die Details dazu stehen unter Installation.

3 - Konfiguration

Die dsyr.DataBridge hat keine Konfigurationsdateien. Alle Laufzeit-Einstellungen — Verbindungen zu Quell- und Zielsystemen, Synchronisations-Jobs, Feld-Mappings und Änderungsstände — leben in vier Azure Tables innerhalb der zugehörigen Ressourcengruppe.

Das hat einen entscheidenden Vorteil: Anpassungen werden ohne Redeployment wirksam. Die Tabellen werden beim nächsten Funktionsaufruf automatisch neu eingelesen.

3.1 - Verbindungen (connections)

Die Tabelle connections ist die Grundlage jeder DataBridge-Konfiguration. Sie enthält die Zugangsdaten zu allen Systemen, mit denen die DataBridge kommuniziert — sowohl Quell- als auch Zielsysteme.

Tabellenstruktur

Unterstützte Connector-Typen

Universelle JSON-Parameter

Diese Parameter sind für alle Connector-Typen gültig und werden in das Json-Feld eingetragen. Alle sind optional:

Zusätzliche Parameter für HTTP-Konnektoren (D365BC, D365NAV, OpenAPI)

Diese Parameter stehen allen HTTP-basierten Konnektoren zur Verfügung, auch wenn sie bislang vor allem für den OpenAPI-Konnektor relevant sind:

JSON-Parameter je Connector-Typ

D365BC — Business Central

Für Cloud-Umgebungen (OAuth2 Client Credentials):

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<BC-Umgebungsname, z. B. production>",
  "companyId": "<BC Company ID (GUID)>"
}

Für OnPremise-Umgebungen (Basic Auth):

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>"
}

Zusätzlicher optionaler Parameter:

Die Auswahl des Authentifizierungsverfahrens erfolgt automatisch: Sind userName und password gesetzt, verwendet die DataBridge Basic Auth, andernfalls OAuth2 Client Credentials aus clientId, clientSecret und tenantId.

D365CE — Dataverse / Customer Engagement

{
  "connectionstring": "<XRM-Connection-String>"
}

Alternativ über Managed Identity (ohne Secret):

{
  "url": "https://<org>.crm4.dynamics.com",
  "clientid": "<Client-ID der user-assigned Identity, optional>"
}

Ohne clientid wird die system-zugewiesene Identity verwendet. Ist connectionstring gesetzt, hat er immer Vorrang. Details siehe D365CE.

Das Format des XRM-Connection-Strings beschreibt die Microsoft-Dokumentation.

Beispiel:

AuthType=ClientSecret;Url=https://<org>.crm4.dynamics.com;ClientId=<id>;ClientSecret=<secret>

D365NAV — Microsoft Dynamics NAV

Für Cloud-Umgebungen (OAuth2 Client Credentials):

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<NAV-Umgebungsname>",
  "companyId": "<Company ID (GUID)>"
}

Für OnPremise-Umgebungen:

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>/",
  "baseAddress": "https://<server>:<port>/",
  "authenticationMethod": "NTLM"
}

Zusätzliche NAV-Parameter:

OPENAPI — generischer REST-Konnektor

{
  "baseUrl": "https://api.example.com",
  "openApiSpecUrl": "https://api.example.com/openapi.yaml",
  "clientId": "<Client-ID>",
  "clientSecret": "<Client-Secret>",
  "tenantId": "<Entra Tenant ID>",
  "tokenUrl": "https://api.example.com/oauth/token",
  "apiKeyHeader": "X-API-Key",
  "apiKeyValue": "<API-Key>",
  "customHeaders": { "X-Custom-Header": "wert" }
}

Vollständige Parameterliste, Authentifizierungsauswahl, Paginierung und Besonderheiten: Konnektoren → OpenAPI.

SQL-Datenbanken (MSSQL, MYSQL, ORACLE, PGSQL)

Alle SQL-Konnektoren verwenden einen einzelnen Connection String:

{
  "connectionstring": "<datenbankspezifischer Connection String>"
}

Zusätzlicher optionaler Parameter:

Diagnose-Schalter (D365BC und D365NAV)

Für die Fehlersuche lassen sich zusätzliche Protokollierungen einschalten. Alle drei Schalter stehen standardmäßig auf false:

Key Vault — Verbindungsdaten sicher speichern

Statt Credentials direkt in Table Storage zu speichern, kann ein Azure-Key-Vault-Secret referenziert werden. Das Json-Feld enthält dann nur die Referenz:

{
  "keyVaultUrl": "https://<vault>.vault.azure.net/secrets/<secret-name>/"
}

Das Secret selbst enthält das vollständige JSON-Objekt der Verbindung — also alle Parameter, die sonst direkt im Json-Feld stünden. Beim Verbindungsaufbau lädt die DataBridge das Secret und ersetzt damit die gesamte Verbindungskonfiguration.

Optional lässt sich eine bestimmte Secret-Version adressieren, indem die Versions-ID an den Pfad angehängt wird.

Hinweise

• Der RowKey ist der Bezeichner, der in der jobs-Tabelle unter SourceConnection bzw. TargetConnection eingetragen wird. Sprechende Namen wählen (z. B. bc-produktion, dataverse-test).
• Eine Verbindung kann von mehreren Jobs gleichzeitig genutzt werden.
• Beim Start prüft die DataBridge jede Verbindung mit einem Verbindungstest. Schlägt er fehl, bricht der laufende Aufruf ab und die Initialisierung wird beim nächsten Aufruf erneut versucht.
• Änderungen in der connections-Tabelle werden bei der nächsten Initialisierung eingelesen — kein Redeployment nötig.

3.2 - Jobs (jobs)

Ein Job beschreibt genau eine Synchronisationsrichtung zwischen zwei Systemen: er verbindet eine Quelltabelle mit einer Zieltabelle, legt den Zeitplan fest und verweist auf das zugehörige Mapping.

Tabellenstruktur

Ausführungsreihenfolge

Das Feld Order bestimmt, in welcher Reihenfolge die fälligen Jobs bei jedem Timer-Aufruf abgearbeitet werden. Empfehlung: BC-Jobs vor CE-Jobs ausführen, um sicherzustellen, dass IDs aus BC schon in Dataverse existieren, bevor sie referenziert werden.

Order 10: BC → CE (Stammdaten, z. B. Kunden)
Order 20: BC → CE (Bewegungsdaten, z. B. Angebote)
Order 30: CE → BC (Rückmeldungen)

Der Order-Wert muss über alle Jobs eindeutig sein — auch über inaktive ResponseJobs hinweg. Ein doppelter Wert führt dazu, dass die betroffenen Jobs als unvollständig markiert und nicht ausgeführt werden.

Filter-Syntax

Der Filter bestimmt, welche Datensätze aus der Quelle abgerufen werden.

D365BC, D365NAV und SQL — Filter mit Watermark-Platzhalter

Der Filterausdruck wird als Bedingung in die Quellanfrage eingesetzt. Zwei Elemente steuern das Verhalten:

• %watermark% wird zur Laufzeit durch den gespeicherten Watermark-Wert ersetzt
• {{ … }} klammert einen Block, der komplett entfällt, wenn die Watermark leer ist

{{lastModifiedDateTime gt %watermark%}}

Ist die Watermark leer (Erstlauf oder manuell geleert), verschwindet der gesamte Block und der Job liest den vollständigen Bestand. Genau dafür ist die Klammerung gedacht.

{{lastModifiedDateTime gt %watermark%}} and {{blocked eq false}}

Richtig kombiniert wird, indem die Zusatzbedingung außerhalb der Klammer steht und das and mit in den Watermark-Block wandert:

blocked eq false {{and lastModifiedDateTime gt %watermark%}}

Beide Varianten sind gültig — der Erstlauf liest den vollen Bestand, gefiltert auf blocked eq false.

D365CE / Dataverse — JSON-Operationen

Dataverse nutzt die Change Tracking API; ein OData-Filter kommt dort nicht zum Einsatz. Stattdessen erwartet das Filter-Feld ein JSON-Objekt, das nach dem Abruf clientseitig ausgewertet wird — passende Datensätze werden verarbeitet, alle anderen verworfen.

{ "Operations": [ { "Name": "NotNull", "Parameters": { "SourceField": "wysa_number" } } ] }

{ "Operations": [ { "Name": "StatusCode", "Parameters": { "Value": 3 } } ] }

Ein nicht aufgeführter Operationsname führt zu einem Fehler (Undefined FilterOperation). Die unter SourceField genannten Felder werden automatisch mit abgefragt — sie müssen nicht zusätzlich im Mapping stehen.

Schedule — jobbezogener CRON-Ausdruck

Wenn ein Job seltener als der globale Timer laufen soll, kann ein eigener CRON-Ausdruck eingetragen werden. Die DataBridge prüft anhand von LastCronRun im Watermark, ob das Intervall bereits abgelaufen ist.

Beispiele:

Der globale Timer (GetChangesTimerExpression) steht bei einer Neuinstallation auf */15 * * * * * — also alle 15 Sekunden. Ein Job ohne eigenen Schedule wird damit bei jedem dieser Läufe geprüft.

Priorität

Jede der drei Queues hat einen eigenen, gleichrangigen Verarbeiter. Sie laufen unabhängig und parallel — dadurch bleibt eine hochpriore Nachricht nicht hinter einem Rückstau niedrigerer Priorität stehen. Eine echte Vorrang-Reihenfolge zwischen den Queues gibt es nicht.

Action — welche Änderungsarten gelesen werden

InvokeAction — Aktions-Jobs

(neu) Enthält Action weder einen leeren Wert noch den Namen eines bekannten JobActionType (NewUpdate, Delete, TimeStamp, DeleteOnUpdate), wird der Job zu einem Aktions-Job: Statt eines CRUD-Zyklus ruft er einen benannten, nicht-CRUD-Endpunkt auf. Der Wert von Action wird dabei unverändert als Aktionsname übernommen — z. B. ein OpenAPI-operationId oder der Name eines CE-OrganizationRequest.

Action = SendByEInvoice

Aktuell implementiert der OpenAPI-Konnektor InvokeAction (ResourcePath aus Source/Target bzw. TargetPath + TargetTable der Mapping-Zeilen). Details und Konfigurationsbeispiel: Konnektoren → OpenAPI → InvokeAction.

Source und Target — job-eigene Ressourcenpfade

(neu) Bislang bestimmten ausschließlich die Mapping-Zeilen (SourceTable/TargetTable), welche Ressource ein Job liest bzw. beschreibt. Ein Job kann jetzt zusätzlich eigene Felder Source und Target tragen, die diese Werte überschreiben:

• Sind Source/Target am Job leer, gilt weiterhin das bisherige Verhalten — die Mapping-Zeilen bestimmen die Ressource (mit einer einmaligen Warnung im Log, die auf die ältere Konfigurationsform hinweist).
• Ist mindestens eines der beiden Felder gesetzt, wird nur dieses überschrieben; das jeweils andere fällt weiterhin auf den Mapping-Wert zurück.
• Fehlt sogar das Mapping-Feld am Job komplett, wird aus Source/Target ein synthetisches Mapping ohne TargetKey erzeugt (JOB-<Jobname>) — nützlich für reine Aktions-Jobs ohne Feld-Mapping.
• Enthält Source/Target einen Schrägstrich (pfad/ressource), wird der Teil vor dem letzten Schrägstrich als Pfad (SourcePath/TargetPath), der Teil danach als Ressourcenname (SourceTable/TargetTable) interpretiert.

Source = v2/clients
Target = v2/client_invoices/{id}/send_by_einvoice

Damit lässt sich ein und dieselbe Mapping-Definition für mehrere Ressourcen bzw. Aktionspfade wiederverwenden, statt für jede Kombination eine eigene Mapping-Gruppe anzulegen.

ResponseJob — Rückschreiben von IDs

Ein ResponseJob löst das Problem, dass Business Central beim Anlegen eines Datensatzes eine neue interne ID vergibt, die anschließend in Dataverse gespeichert werden soll.

Ablauf:

1. Job A schreibt einen Datensatz von CE nach BC
2. BC antwortet mit dem neu erzeugten Datensatz inkl. der neuen BC-ID
3. Die DataBridge führt automatisch Job B (den ResponseJob) aus
4. Job B liest die BC-ID aus der Antwort (ReadFromMessage-Operation) und schreibt sie zurück nach CE

Konfiguration:

Job A:  IsActive = true
        ResponseJob = "JobB-RowKey"

Job B:  IsActive = false   ← wird nur durch Job A ausgelöst, nie direkt
        SourceConnection = BC-Verbindung
        TargetConnection = CE-Verbindung

Felder, die aus der BC-Antwort gelesen werden, werden im Mapping mit einem Unterstrich-Präfix im SourceField markiert und die Operation ReadFromMessage eingetragen (Details: Mappings → ReadFromMessage).

3.3 - Mappings (mappings)

Die mappings-Tabelle ist die mächtigste Konfigurationsebene der DataBridge. Sie legt für jedes Feld fest: woher kommt der Wert, wohin geht er, und wie wird er unterwegs transformiert.

Ein Mapping ist eine Gruppe von Zeilen in der Tabelle — alle mit demselben PartitionKey. Jede Zeile beschreibt genau eine Feld-Zuordnung.

Tabellenstruktur

RowKey-Namenskonvention

Die empfohlene Konvention für den RowKey: _quellfeld__zielfeld_

Beispiele:

_systemid__wysa_bcsystemid_
_lastModifiedDateTime__wysa_lastmodified_
_no__wysa_bcnumber_

Doppelter Unterstrich trennt Quell- vom Zielfeld. Die umgebenden Unterstriche kennzeichnen es als Mapping-RowKey. Diese Konvention ist optional, aber empfohlen für Lesbarkeit und Filterbarkeit.

TargetKey — Upsert-Schlüssel

Der TargetKey bestimmt, wie die DataBridge entscheidet, ob ein Datensatz im Zielsystem angelegt (Insert) oder aktualisiert (Update) wird.

Es gibt vier Typen:

PrimaryKey

Nutzt den systemnativen Primärschlüssel des Zielsystems. Der Schlüsselname wird automatisch aus dem SourceField der Mapping-Zeile übernommen.

{ "KeyType": "PrimaryKey" }

Id

Ähnlich wie PrimaryKey, nutzt jedoch die systemspezifische ID-Eigenschaft des Connectors.

{ "KeyType": "Id" }

CustomKey

Benutzerdefinierter Schlüssel aus einem oder mehreren Feldern. Wird eingesetzt, wenn der Datensatz im Zielsystem nicht über den Primärschlüssel, sondern über eine Geschäftsfeld-Kombination identifiziert wird.

{
  "KeyType": "CustomKey",
  "KeyName": "wysa_number",
  "KeyValues": [
    { "keyName": "wysa_segmentno", "attributeName": "segmentNo", "rank": 1 },
    { "keyName": "wysa_lineno",    "attributeName": "lineNo",    "rank": 2 }
  ]
}

Filter

Sucht im Zielsystem nach einem Datensatz, der alle angegebenen Feld-Wert-Kombinationen erfüllt. Im Gegensatz zu CustomKey wird kein explizites Schlüsselfeld benötigt.

{
  "KeyType": "Filter",
  "KeyValues": [
    { "keyName": "mailingGroupCode", "attributeName": "listid",   "rank": 1 },
    { "keyName": "contactNo",        "attributeName": "entityid", "rank": 2 }
  ]
}

Statische Schlüsselwerte

(ab v2.1 — verfügbar für D365CE und D365BC)

Ein Schlüsselteil kann gegen einen fest hinterlegten Wert aufgelöst werden, ohne dass dafür ein Quellfeld existieren muss. Dazu wird statt attributeName das Feld StaticValue gesetzt:

{
  "KeyType": "CustomKey",
  "KeyName": "wysa_category",
  "KeyValues": [
    { "keyName": "wysa_category", "StaticValue": "STANDARD", "rank": 1 }
  ]
}

StaticValue greift nur, wenn attributeName leer ist. Ist beides gesetzt, gewinnt der Quellwert.

Bei Business Central werden statische Werte für die Metadaten-Typen string, guid und int32 unterstützt; andere Typen führen zu einem Fehler.

Mehrere Ziel-Schlüssel mit Rangfolge

(ab v2.1)

Ein Mapping kann mehrere Ziel-Schlüssel besitzen. Sie werden anhand des Feldes KeyRank in aufsteigender Reihenfolge geprüft — sobald ein Schlüssel im Zielsystem einen Datensatz findet, wird dieser verwendet und die übrigen werden übersprungen.

Typischer Einsatz: zuerst über eine externe ID suchen, ersatzweise über eine Nummer.

Die Konfiguration unterscheidet sich je nach Ebene:

{
  "KeyType": "CustomKey",
  "KeyRank": 1,
  "KeyName": "wysa_externalid",
  "KeyValues": [
    { "keyName": "wysa_externalid", "attributeName": "externalId", "rank": 1 }
  ]
}

Bestehende Mappings mit einem einzelnen TargetKey funktionieren unverändert — intern wird ein einzelner Schlüssel wie eine Liste mit einem Eintrag behandelt.

KeyAttributeFromExisting

Optionales Feld am TargetKey, ausgewertet bei KeyType: Filter von den Konnektoren für Business Central, NAV und OpenAPI. Der Filter findet nur den bestehenden Zieldatensatz. Für die Item-URL beim Aktualisieren (bei OpenAPI auch beim Löschen) wird der Schlüssel aus dem hier angegebenen Feld dieses Datensatzes übernommen.

• BC/NAV: Pflicht bei Filter. Guid- und Zahl-Schlüssel werden ohne, alle anderen mit Hochkommas in die URL geschrieben, der Typ kommt aus den Metadaten. Fehlt das Feld im bestehenden Datensatz, bricht die Verarbeitung mit einem Fehler ab.
• OpenAPI: Optional. Ohne Angabe wird der Primärschlüssel der Spezifikation verwendet (id, Id, ID, uuid oder key).

Der Feldname ist case-sensitiv (id ≠ Id).

IgnoreEmptySourceKey

(ab v2.2, nur D365CE)

Optionales Boolesches Feld am TargetKey. Standard ist false.

{
  "KeyType": "CustomKey",
  "KeyRank": 2,
  "KeyName": "wysa_externalid",
  "IgnoreEmptySourceKey": true,
  "KeyValues": [
    { "keyName": "wysa_externalid", "attributeName": "externalId", "rank": 1 }
  ]
}

Zwei verschiedene Arten von „kein Treffer"

Um das Feld einordnen zu können, muss man zwei Situationen auseinanderhalten, die beide danach aussehen, als wäre ein Schlüssel erfolglos geblieben:

Die zweite Zeile ist der Normalfall für jeden neuen Datensatz: Beim ersten Übertragen findet kein Schlüssel etwas, und genau deshalb wird angelegt. IgnoreEmptySourceKey ändert daran nichts.

Das Feld wirkt ausschliesslich auf die erste Zeile: Es erklärt einen leeren Quellwert für diesen einen Schlüssel zum Normalfall statt zum Fehler.

Wann das Feld überhaupt zum Tragen kommt

Die Schlüssel werden nach KeyRank der Reihe nach geprüft. Sobald ein Schlüssel einen Datensatz findet, bricht die Suche ab und der Datensatz wird aktualisiert — unabhängig davon, was bei den vorherigen Schlüsseln passiert ist und wie sie konfiguriert sind.

Beispiel mit drei Schlüsseln, bei dem Schlüssel 1 leer und nicht markiert ist:

Das Feld greift also nur dann, wenn die Liste vollständig durchlaufen wurde und kein einziger Schlüssel einen Datensatz gefunden hat. Erst dann steht die Frage „Fehler oder anlegen?" überhaupt im Raum.

Die Entscheidung am Ende

Hat kein Schlüssel etwas gefunden, entscheidet sich Folgendes:

• Waren alle leer gebliebenen Schlüssel mit IgnoreEmptySourceKey: true markiert (oder blieb gar keiner leer), wird ein neuer Datensatz angelegt.
• War auch nur einer der leer gebliebenen Schlüssel nicht markiert, bleibt es beim Fehler.

Das Feld gilt also je Schlüssel: Es hebt die Fehlerbehandlung der übrigen Schlüssel nicht auf. Lassen Sie es bei einem Schlüssel bewusst weg, bleibt ein leerer Wert dort ein Fehler — auch wenn ein anderer Schlüssel des Mappings markiert ist.

Typischer Einsatz

Ein optionales Feld wie eine externe ID ist nicht in jedem Quelldatensatz gefüllt, die Belegnummer dagegen immer. Mit IgnoreEmptySourceKey: true am ID-Schlüssel laufen auch die Datensätze ohne externe ID sauber durch und werden über die Belegnummer gefunden.

Das Feld wird derzeit ausschliesslich vom D365CE-Konnektor ausgewertet. Bei Business Central und NAV bleibt es wirkungslos.

Virtuelle Felder

Beginnt das SourceField mit einem Unterstrich, handelt es sich um ein virtuelles Feld: Es wird nicht aus der Quelltabelle gelesen, sondern zur Laufzeit über eine SourceOperation erzeugt.

Der ResponseJob ist dabei nur einer von mehreren Anwendungsfällen:

SourceOperation — Transformation beim Lesen

SourceOperations werden angewendet, bevor der Wert in die Service Bus Queue geschrieben wird. Sie sind connector-spezifisch — nicht jede Operation steht in jedem Connector zur Verfügung.

LookupValue

(verfügbar: D365BC, D365CE, D365NAV)

Liest einen Wert aus einer anderen Tabelle im Quellsystem nach. Beispiel: Aus einem Land-Code soll der ausgeschriebene Ländername übertragen werden.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "countryRegionCode",
        "LookupTable": "publisher/product/v1.0/countriesRegions",
        "LookupField": "name",
        "UseCache": true
      }
    }
  ]
}

ReadFromMessage

(verfügbar: D365BC, D365NAV, D365CE)

Liest einen Wert aus der ursprünglichen Queue-Nachricht — wird typischerweise in ResponseJobs verwendet, um Felder aus der Antwort des Zielsystems (z. B. eine neu vergebene ID) zurückzuschreiben.

{
  "Operations": [
    { "Name": "ReadFromMessage" }
  ]
}

Zugehörige Zeile in der Tabelle:

ActivityParty

(verfügbar: nur D365CE)

Liest ein Feld über eine ActivityParty-Beziehung aus. Wird für CE-Aktivitäten (E-Mails, Aufgaben) verwendet, bei denen Teilnehmer über den activityparty-Datensatz verknüpft sind.

{
  "Operations": [
    {
      "Name": "ActivityParty",
      "Parameters": {
        "PartyParams": {
          "TypeMask": 2,
          "SourceField": "activityid",
          "TargetField": "wysa_number",
          "TargetTable": "contact"
        }
      }
    }
  ]
}

Werden mehrere Teilnehmer gefunden, werden ihre Werte komma-separiert zusammengefügt.

LinkToRecord

(verfügbar: nur D365CE)

Erzeugt eine anklickbare URL zu einem Datensatz in Dataverse. Nützlich, um in BC oder SQL einen direkten Link auf den zugehörigen CE-Datensatz zu speichern.

{
  "Operations": [
    {
      "Name": "LinkToRecord",
      "Parameters": {
        "BaseUrl": "https://<org>.crm4.dynamics.com/main.aspx?appid=<AppId>&pagetype=entityrecord"
      }
    }
  ]
}

An die angegebene Basis-URL werden automatisch &etn=<entity> und &id=<guid> angehängt.

EmbedChildren

(neu, verfügbar: nur D365CE als Quellsystem)

Bettet die Zeilen eines referenzierten Kind-Jobs in die Nachricht des Elterndatensatzes ein, sodass Eltern- und Kind-Datensätze gemeinsam als eine Nachricht durch den Service Bus laufen und gemeinsam ins Ziel geschrieben werden — z. B. eine Rechnung mit ihren Rechnungspositionen.

{
  "Operations": [
    {
      "Name": "EmbedChildren",
      "Parameters": { "JobName": "invoice-lines" }
    }
  ]
}

Zugehörige Zeile in der Tabelle:

Der referenzierte Kind-Job liefert SourceConnection, Quellressource und Mapping; sein Filter kann {{...%parent.feld%...}}-Platzhalter enthalten, die zur Abrufzeit gegen den Eltern-Quelldatensatz aufgelöst werden. Beim Schreiben in eine OpenAPI-Zielressource wird daraus ein verschachteltes JSON-Array gebaut und unverändert — ohne Feld-für-Feld-Abgleich gegen ein eventuell vorhandenes Zielarray — mit der Elternanfrage übertragen.

TargetOperation — Transformationen beim Schreiben

TargetOperations werden angewendet, bevor der Wert ins Zielsystem geschrieben wird.

DefaultValue

(alle Konnektoren)

Schreibt immer einen festen Wert ins Zielfeld — unabhängig vom Quellwert. Das SourceField kann in diesem Fall leer gelassen werden.

{
  "Operations": [
    { "Name": "DefaultValue", "Parameters": { "DefaultValue": "2" } }
  ]
}

DefaultValueIfNullOrEmpty

(alle Konnektoren)

Schreibt einen festen Wert nur dann, wenn das Quellfeld leer oder null ist. Ist ein Quellwert vorhanden, wird dieser unverändert verwendet.

{
  "Operations": [
    { "Name": "DefaultValueIfNullOrEmpty", "Parameters": { "DefaultValue": "unbekannt" } }
  ]
}

DefaultValueMap

(alle Konnektoren)

Übersetzt den ermittelten Wert anhand einer Zuordnungsliste. Der Schlüsselvergleich erfolgt ohne Beachtung der Groß-/Kleinschreibung.

{
  "Operations": [
    {
      "Name": "DefaultValueMap",
      "Parameters": {
        "Mapping": [
          { "Key": "DE", "Value": "Deutschland" },
          { "Key": "AT", "Value": "Österreich" }
        ]
      }
    }
  ]
}

Findet sich kein passender Schlüssel, bleibt der Wert unverändert — im Unterschied zu OptionMapping, das in diesem Fall einen Fehler wirft.

Lookup

(nur D365CE)

Befüllt ein Lookup-Feld in Dataverse, indem der verknüpfte Datensatz über einen Schlüssel gesucht wird.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "contact",
        "TargetKey": {
          "KeyType": "CustomKey",
          "KeyName": "wysa_number",
          "KeyValues": [
            { "keyName": "wysa_number", "attributeName": "contactNo", "rank": 1 }
          ]
        }
      }
    }
  ]
}

TargetTable ist zwingend — ohne diesen Parameter bricht die Auflösung ab.

OptionMapping

(verfügbar: D365CE; bei D365BC und D365NAV für String-Felder)

Übersetzt Textwerte aus dem Quellsystem in numerische Optionset-Werte von Dataverse (und umgekehrt). Die Mapping-Liste enthält alle bekannten Schlüssel-Wert-Paare.

{
  "Operations": [
    {
      "Name": "OptionMapping",
      "Parameters": {
        "Mapping": [
          { "Key": "Blank",                       "Value": "" },
          { "Key": "Prospect",                    "Value": "383380000" },
          { "Key": "First_x002D_time_x0020_Donor","Value": "383380001" },
          { "Key": "Recurring_x0020_Donor",       "Value": "383380002" }
        ]
      }
    }
  ]
}

Für MultiSelect-Optionsets ist zusätzlich der Parameter OptionDelimiter anzugeben — er trennt die Einzelwerte im Quellstring. Ohne ihn schlägt die Aufteilung fehl.

Datentyp-Umwandlung

Welche Quelltypen ein Zielfeld akzeptiert, hängt vom Connector und vom Zielfeld-Typ ab. Die vollständigen Matrizen stehen auf den Konnektor-Seiten.

Zwei Punkte, die häufig zu Rückfragen führen:

String zu Dezimalzahl (ab v2.1) — Dezimalfelder akzeptieren jetzt auch Quellwerte vom Typ string. Diese werden immer im Format en-US interpretiert, also mit Punkt als Dezimaltrennzeichen. Ein leerer String wird zu null, ein nicht konvertierbarer Wert erzeugt einen Fehler.

Culture bei echten Zahlentypen — kommt der Wert dagegen bereits als decimal oder money, gilt die im Verbindungs-JSON eingestellte language (Vorgabe de-DE).

Spezialfälle

Feld ohne Quellwert (reiner Standardwert)

Soll ein Zielfeld immer mit einem festen Wert befüllt werden, ohne dass ein Quellfeld existiert:

Wert aus der Antwortnachricht lesen (ResponseJob)

Siehe auch Virtuelle Felder und Jobs → ResponseJob.

Mehrere Operationen in einer Zeile

Ob mehrere Einträge im Operations-Array wirken, hängt davon ab, um welche Art von Operation es sich handelt:

Eine Verkettung im Sinne von „erst A, dann B auf das Ergebnis von A" gibt es bei SourceOperations damit nicht.

3.4 - Watermarks (watermark)

Die Tabelle watermark ist die Gedächtnisfunktion der DataBridge. Nach jedem Job-Lauf wird hier gespeichert, bis zu welchem Stand die Daten gelesen wurden. Beim nächsten Lauf startet der Quellabruf genau an diesem Punkt.

Diese Tabelle wird vom Deployment angelegt und zur Laufzeit automatisch befüllt — manuelle Einträge sind normalerweise nicht nötig. Es gibt jedoch Situationen, in denen ein gezielter Eingriff sinnvoll ist.

Tabellenstruktur

Watermark-Typen

Der Typ wird im Job über das Feld WatermarkType festgelegt und bestimmt, wie der gespeicherte Wert interpretiert wird.

datetime — Vollständiger Zeitstempel

Für Quellsysteme, die Änderungen über ein Datum-/Uhrzeit-Feld tracken. Typisch für Business Central (lastModifiedDateTime).

Format: yyyy-MM-ddTHH:mm:ss.fffZ

Beispielwert: 2026-05-31T08:15:00.000Z

Der Filter im Job sieht dann so aus:

{{lastModifiedDateTime gt %watermark%}}

date — Nur Datum

Für Quellsysteme, bei denen nur das Datum (ohne Uhrzeit) relevant ist. Typisch für NAV-Systeme mit datumbasiertem Tracking.

Format: yyyy-MM-dd

Beispielwert: 2026-05-31

string — Change Tracking Token

Für Dataverse / D365CE: Die Change Tracking API gibt bei jedem Abruf einen opaken Token zurück, der den aktuellen Änderungsstand repräsentiert. Dieser Token wird als string gespeichert und beim nächsten Lauf direkt an die API übergeben — kein Datumsvergleich, kein Risiko fehlender Änderungen.

Format: opake Zeichenkette (von Dataverse vergeben)

Beispielwert: 892290!08/10/2026 10:00:00

Schreibweise und unbekannte Typen

Der Typ wird ohne Beachtung von Groß-/Kleinschreibung und ohne umgebende Leerzeichen erkannt — datetime, DateTime und DATETIME sind gleichwertig.

Wann wird der Watermark aktualisiert?

Der Watermark wird am Ende der Erkennungsphase fortgeschrieben — also sobald alle gefundenen Änderungen in die Queue geschrieben sind, und bevor das Zielsystem beschrieben wurde. Für die Zustellung ins Ziel sorgen danach die Queue-Mechanismen (Wiederholung, Dead-Letter).

Im Einzelnen:

1. Beim Lesen führt die DataBridge den Änderungsmarker (ChangeTracker) der verarbeiteten Datensätze mit
2. Bei date und datetime wird jeweils der höhere der beiden Werte behalten, bei string gewinnt immer der zuletzt gelesene Token — ein opaker Token hat keine Ordnung
3. Nach dem Leeren des letzten Batches wird der Endstand in die Tabelle geschrieben
4. LastCronRun wird auf den Zeitpunkt gesetzt, zu dem der Job begonnen hat

Bricht ein Job mit einem Fehler ab, bleibt der Watermark auf dem zuletzt geschriebenen Stand. Beim nächsten Lauf wird ab diesem Punkt erneut gelesen.

Zeitzonen

Zeitstempel werden zeitzonenunabhängig verglichen. Bis v2.0 wurde die Zeitangabe in die lokale Zeit des Servers umgerechnet — beim Typ date konnte das über eine Tagesgrenze springen und das Vergleichsergebnis je nach Betriebsstandort verändern.

Erster Lauf — kein Eintrag vorhanden

Existiert für einen Job noch kein Watermark-Eintrag, legt die DataBridge ihn beim ersten Lauf automatisch an. Als Startpunkt wird ein möglichst früher Wert verwendet:

Das bedeutet: der erste Lauf lädt alle vorhandenen Datensätze aus dem Quellsystem. Bei großen Datenmengen sollte dies zu einem Zeitpunkt mit geringer Last geschehen.

Manueller Eingriff — Wann und warum

Vollständigen Neulauf erzwingen

Den Wert in der Watermark-Spalte leeren oder auf den Initialwert zurücksetzen. Beim nächsten Lauf werden alle Datensätze erneut übertragen.

Typische Anwendungsfälle:

• Mapping wurde grundlegend geändert und alle Datensätze sollen neu gemappt werden
• Zielsystem wurde zurückgesetzt oder neu aufgebaut
• Datenverlust im Zielsystem

Partiellen Neulauf ab bestimmtem Datum

Den Watermark-Wert manuell auf ein Datum setzen, ab dem neu gelesen werden soll:

2026-01-01T00:00:00.000Z

Damit werden nur Datensätze übertragen, die seit diesem Datum geändert wurden.

Bei WatermarkType = string ist das nicht möglich — der Token stammt aus Dataverse und lässt sich nicht sinnvoll von Hand konstruieren. Dort bleibt nur das vollständige Leeren.

LastCronRun zurücksetzen

Wenn ein Job mit eigenem Schedule nicht zum erwarteten Zeitpunkt ausgeführt wurde, kann LastCronRun manuell auf einen früheren Wert gesetzt werden. Die DataBridge erkennt dann, dass das Intervall abgelaufen ist, und führt den Job beim nächsten Timer-Aufruf aus.

4 - Konnektoren

Jedes Quell- oder Zielsystem wird über einen Konnektor angebunden. Ein Konnektor übernimmt die systemspezifische Kommunikation: Authentifizierung, Datenabfrage, Änderungserkennung und das Schreiben von Datensätzen.

Unterstützte Konnektoren

Die Konnektoren D365BC, D365CE und D365NAV kommunizieren über HTTP/OData-APIs. MSSQL, MySQL, Oracle und PostgreSQL verwenden direkte Datenbankverbindungen (ADO.NET). Der OpenAPI-Konnektor kommuniziert ebenfalls über HTTP, leitet Pfade, Wrapper-Schlüssel und Feldtypen jedoch aus einer OpenAPI-Spezifikation ab, statt sie fest zu verdrahten.

Schreiben in SQL-Systeme

Keiner der vier SQL-Konnektoren unterstützt das Schreiben. Ein SQL-System als TargetConnection führt zur Laufzeit zu einem Abbruch. Die SQL-Konnektoren sind derzeit ausschließlich als Quellsystem einsetzbar.

Der OpenAPI-Konnektor

Der OpenAPI-Konnektor unterscheidet sich grundlegend von den übrigen HTTP- Konnektoren: Er ist nicht auf ein bestimmtes System zugeschnitten, sondern bindet beliebige REST-APIs an, für die eine OpenAPI-Spezifikation vorliegt. Pfade, Wrapper-Schlüssel und Feldtypen werden zur Laufzeit aus der Spezifikation aufgelöst, statt je System hartcodiert zu sein. Er befindet sich aktuell noch in Entwicklung.

Versionsangaben

Die auf den Konnektor-Seiten genannten Mindestversionen sind getestete Versionsstände. Die DataBridge prüft die Version des angebundenen Systems nicht — ältere Stände können funktionieren, sind aber nicht abgesichert. Bei Fragen zu einer konkreten Version bitte WYSA kontaktieren.

4.1 - D365BC — Business Central

Der D365BC-Konnektor verbindet die DataBridge mit Microsoft Dynamics 365 Business Central über die OData-v4-REST-API (API-Version 2.0). Er unterstützt sowohl Cloud-Umgebungen (OAuth2) als auch OnPremise-Installationen (Basic Auth).

Verbindungsparameter

Cloud-Umgebung (empfohlen)

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<BC-Umgebungsname, z. B. production>",
  "companyId": "<Company ID (GUID)>"
}

Cloud-Umgebung mit Managed Identity (ab v2.3)

Ohne Client Secret, über die Managed Identity der Function App:

{
  "authmethod": "ManagedIdentity",
  "clientId": "<Client-ID der user-assigned Identity, optional>",
  "environment": "<BC-Umgebungsname, z. B. production>",
  "companyId": "<Company ID (GUID)>"
}

• Ohne clientId wird die system-zugewiesene Identity der Function App verwendet, mit clientId die benutzer-zugewiesene.
• clientSecret und tenantId sind nicht nötig. Der Token wird mit dem scope der Connection angefordert und rechtzeitig vor Ablauf erneuert.
• Managed Identity wird nur über authmethod aktiviert, nie automatisch.
• Voraussetzung: Die Identity ist in Business Central unter Microsoft-Entra-Anwendungen angelegt, aktiviert und mit Berechtigungssätzen versehen.

OnPremise-Umgebung

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>",
  "companyId": "<Company ID (GUID)>"
}

Ist url gesetzt, wird daraus die Basisadresse gebildet (<url>/api/) und environment nicht ausgewertet. Ist url leer, verwendet der Konnektor den Cloud-Endpunkt und bildet die Adresse aus environment.

Die Auswahl des Authentifizierungsverfahrens erfolgt automatisch: Sind userName und password gesetzt, wird Basic Auth verwendet, andernfalls OAuth2 Client Credentials aus clientId, clientSecret und tenantId. Mit authmethod lässt sich die Methode ausdrücklich festlegen.

Optionale Parameter

Gelten für Cloud und OnPremise:

Die drei Diagnose-Schalter erzeugen erhebliche Datenmengen und können Geschäftsdaten im Klartext protokollieren — nur gezielt für die Dauer einer Analyse aktivieren. Vollständige Beschreibung unter Verbindungen.

Tabellen- und Feldnamen

SourceTable / TargetTable

Der Tabellenname leitet sich aus dem API-Pfad der Business-Central-API v2.0 ab — ohne den Company-Teil der URL.

SourceField / TargetField

Exakter Feldname aus der BC-API-Seite (case-sensitive). Zu finden in der BC-API-Dokumentation oder über den API-Explorer in Business Central.

Unterstützte TargetKey-Typen

Statische Schlüsselwerte (ab v2.1)

In einem KeyValue kann statt attributeName ein StaticValue angegeben werden. Der Schlüsselteil wird dann nicht aus dem Quelldatensatz gelesen, sondern fest gesetzt.

{
  "KeyType": "CustomKey",
  "KeyName": "wysa_number",
  "KeyValues": [
    { "keyName": "sourceSystem", "StaticValue": "DataBridge",   "rank": 1 },
    { "keyName": "customerNo",   "attributeName": "bcCustomerNo", "rank": 2 }
  ]
}

Statische Werte werden für die BC-Metadatentypen string, guid und int32 unterstützt. Bei jedem anderen Typ des Schlüsselfeldes bricht die Verarbeitung mit einem Fehler ab (Metadata type … not yet implemented for CreateKeyString).

SourceOperations

LookupValue

Liest einen Wert aus einer anderen BC-API-Tabelle nach.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "countryRegionCode",
        "LookupTable": "publisher/product/v1.0/countriesRegions",
        "LookupField": "name",
        "UseCache": true
      }
    }
  ]
}

LookupType kennt die beiden Werte Attribute und Name. Business Central unterstützt ausschließlich Attribute; der Wert Name führt zu einem Abbruch (SourceOperation for Lookups). Name ist dem D365CE-Konnektor vorbehalten.

ReadFromMessage

Liest einen Wert aus der BC-Antwort — nur in ResponseJobs. Das SourceField muss einen _-Prefix haben.

{
  "Operations": [
    {
      "Name": "ReadFromMessage"
    }
  ]
}

Datentypen — Zieltyp und akzeptierte Quelltypen

Beim Schreiben bestimmt der Datentyp des Zielfeldes in den BC-Metadaten, welche Umwandlung angewendet wird. Der Quelltyp stammt aus dem Feldtyp des Quellsystems und entscheidet, ob die Umwandlung gelingt.

Jeder in der Tabelle nicht genannte BC-Zieltyp führt beim Schreiben zu einem Abbruch (No Resolver defined for edmPrimitiveTypeKind …).

Schreibvorgang und Fehlerverhalten

Vor jedem Schreibvorgang sucht der Konnektor den bestehenden Zieldatensatz — je nach TargetKey-Typ über den Schlüssel oder über einen Filter. Wird ein Datensatz gefunden, erfolgt ein Update, andernfalls eine Neuanlage.

ResponseJob — BC-IDs zurückschreiben

Wenn BC beim Anlegen eines Datensatzes eine neue ID vergibt (z. B. die Kundennummer), kann diese über einen ResponseJob automatisch ins Quellsystem zurückgeschrieben werden.

Beispiel: CE-Kontakt nach BC anlegen und BC-ID zurück nach CE schreiben

Job A (Hauptjob):

SourceConnection: ce-produktion
TargetConnection: bc-produktion
Mapping:          ce-contact-to-bc-customer
ResponseJob:      bc-id-back-to-ce
IsActive:         true

Job B (ResponseJob):

SourceConnection: bc-produktion
TargetConnection: ce-produktion
Mapping:          bc-response-to-ce-contact
IsActive:         false

Mapping für Job B — das BC-ID-Feld:

Änderungserkennung (Watermark)

Business Central liefert für jede Entität ein lastModifiedDateTime-Feld, das beim Speichern automatisch aktualisiert wird.

Der Filterausdruck aus dem Job wird als OData-$filter an die BC-Anfrage angehängt. Die Regeln zur Klammerung und zum Platzhalter %watermark% sind unter Jobs → Filter-Syntax beschrieben.

4.2 - D365CE — Dataverse / Customer Engagement

Der D365CE-Konnektor verbindet die DataBridge mit Microsoft Dataverse und Dynamics 365 Customer Engagement über das offizielle Dataverse SDK. Er nutzt die Change Tracking API für eine lückenlose Erkennung aller Änderungen.

Die Mindestversion beschreibt den getesteten Stand; eine Versionsprüfung findet im Code nicht statt.

Voraussetzung: Change Tracking aktivieren

Für alle Dataverse-Tabellen, die als Quelle genutzt werden, muss Change Tracking aktiviert sein. Ohne Change Tracking kann der Konnektor keine Differenzabfragen durchführen.

Aktivierung: Power Platform Admin Center → Umgebung → Tabellen → Tabelle auswählen → Eigenschaften → Änderungsnachverfolgung aktivieren ✅

Verbindungsparameter

{
  "connectionstring": "<XRM-Connection-String>"
}

Beispiel (Client Secret Authentication):

AuthType=ClientSecret;Url=https://<org>.crm4.dynamics.com;ClientId=<id>;ClientSecret=<secret>

Alternative: Managed Identity (ab v2.3)

Statt eines Connection-Strings mit Secret kann die Verbindung über eine Managed Identity aufgebaut werden:

{
  "url": "https://<org>.crm4.dynamics.com",
  "clientid": "<Client-ID der user-assigned Identity, optional>"
}

• Ohne clientid wird die system-zugewiesene Identity der Function App verwendet, mit clientid die benutzer-zugewiesene.
• Ist connectionstring gesetzt, hat er immer Vorrang; url wird dann ignoriert.
• Sind weder connectionstring noch url gesetzt, bricht der Verbindungsaufbau mit einem Fehler ab.
• Voraussetzung: Die Identity ist in der Dataverse-Umgebung als Application User angelegt und hat eine passende Sicherheitsrolle (Power Platform Admin Center → Umgebung → Einstellungen → Benutzer + Berechtigungen → Anwendungsbenutzer).

Die vollständige XRM-Connection-String-Referenz findet sich in der Microsoft-Dokumentation.

Zusätzlich stehen die universellen Parameter keyVaultUrl, maxPageSize, language und httpClientTimeoutSeconds zur Verfügung — siehe Verbindungen.

Tabellen- und Feldnamen

SourceTable / TargetTable

Logischer Entitätsname in Kleinbuchstaben — so wie er in den Dataverse-Metadaten steht.

SourceField / TargetField

Logischer Attributname in Kleinbuchstaben.

Unterstützte TargetKey-Typen

Bei CustomKey werden Schlüsselteile vom Typ int32, guid und string unterstützt; jeder andere Typ führt zum Abbruch (keytype … not yet supported for key …). Leere Schlüsselteile werden übersprungen — bleibt danach kein Teil übrig, gilt der Schlüssel als nicht auflösbar.

Ist der Alternativschlüssel in Dataverse nicht angelegt oder nicht aktiv, bricht die Suche mit einem Fehler ab (ab v2.3). Die Nachricht landet nach den Wiederholungen in der Dead-Letter-Queue und wird nicht als neuer Datensatz angelegt. Bis v2.2 wurde dieser Fall wie „Datensatz nicht gefunden“ behandelt, was zu Dubletten führen konnte.

Ein KeyValue kann statt attributeName ein StaticValue enthalten; der Schlüsselteil wird dann fest gesetzt und als Typ string behandelt.

Mehrere Ziel-Schlüssel mit Rangfolge (ab v2.1)

Statt eines einzelnen TargetKey lässt sich eine Liste TargetKeys angeben. Die Schlüssel werden nach KeyRank aufsteigend geprüft; der erste Schlüssel, der im Zielsystem einen Datensatz findet, gewinnt — alle weiteren werden übersprungen.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "TargetKeys": [
          {
            "KeyType": "CustomKey",
            "KeyRank": 1,
            "KeyName": "wysa_externalid",
            "KeyValues": [
              { "keyName": "wysa_externalid", "attributeName": "externalId", "rank": 1 }
            ]
          },
          {
            "KeyType": "CustomKey",
            "KeyRank": 2,
            "KeyName": "wysa_code",
            "KeyValues": [
              { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
            ]
          }
        ]
      }
    }
  ]
}

Bestehende Mappings mit einem einzelnen TargetKey funktionieren unverändert weiter.

SourceOperations

LookupValue

Liest einen Wert aus einem verknüpften Dataverse-Datensatz nach.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "wysa_countrycode",
        "LookupTable": "wysa_country",
        "LookupField": "wysa_name",
        "UseCache": true
      }
    }
  ]
}

LookupType kennt zwei Werte. Nur der CE-Konnektor unterstützt beide:

ReadFromMessage

Liest Werte aus einer vorherigen Quellanfrage — nur in ResponseJobs. Verhalten wie beim D365BC-Konnektor.

ActivityParty

Liest ein Feld über eine ActivityParty-Beziehung. Wird für CE-Aktivitäten (E-Mails, Aufgaben, Anrufe) verwendet, bei denen Teilnehmer über den activityparty-Datensatz verknüpft sind.

{
  "Operations": [
    {
      "Name": "ActivityParty",
      "Parameters": {
        "PartyParams": {
          "TypeMask": 2,
          "SourceField": "activityid",
          "TargetField": "wysa_number",
          "TargetTable": "contact"
        }
      }
    }
  ]
}

TypeMask entspricht dem Dataverse-Feld participationtypemask und wird von der DataBridge unverändert an die Abfrage durchgereicht. Die gültigen Werte gibt die Dataverse-Plattform vor; die gebräuchlichsten sind:

Diese Tabelle ist eine Plattform-Referenz, keine Festlegung der DataBridge. Die verbindliche und vollständige Liste steht in der Microsoft-Dokumentation zur Entität activityparty.

LinkToRecord

Erzeugt eine anklickbare URL zu einem Datensatz in Dataverse.

{
  "Operations": [
    {
      "Name": "LinkToRecord",
      "Parameters": {
        "BaseUrl": "https://<org>.crm4.dynamics.com/main.aspx?appid=<AppId>&pagetype=entityrecord"
      }
    }
  ]
}

TargetOperations

Lookup

Befüllt ein Lookup-Feld in Dataverse, indem der verknüpfte Datensatz über eine Feldwert-Kombination gesucht wird. Die Operation gehört in die Spalte TargetOperation des Mappings und benötigt zwingend den Operations-Rahmen, den Namen Lookup sowie TargetTable.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "TargetKey": {
          "KeyType": "CustomKey",
          "KeyName": "wysa_code",
          "KeyValues": [
            { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
          ]
        }
      }
    }
  ]
}

Wird kein passender Datensatz gefunden, legt die DataBridge standardmäßig einen neuen an.

Weitere Parameter der TargetOperation

DoNotCreate (ab v2.1)

Ist DoNotCreate auf true gesetzt, wird der Zieldatensatz eines Lookups nur dann verknüpft, wenn er bereits existiert. Wird er nicht gefunden, bleibt das Feld leer — es entsteht kein neuer Datensatz.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "DoNotCreate": true,
        "TargetKey": {
          "KeyType": "CustomKey",
          "KeyName": "wysa_code",
          "KeyValues": [
            { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
          ]
        }
      }
    }
  ]
}

OptionMapping

Übersetzt Quellwerte in numerische Dataverse-Optionset-Werte.

{
  "Operations": [
    {
      "Name": "OptionMapping",
      "Parameters": {
        "Mapping": [
          { "Key": "Blank",                        "Value": "" },
          { "Key": "Prospect",                     "Value": "383380000" },
          { "Key": "First_x002D_time_x0020_Donor", "Value": "383380001" },
          { "Key": "Recurring_x0020_Donor",        "Value": "383380002" }
        ]
      }
    }
  ]
}

Ein leerer Value setzt das Zielfeld auf null. Ein Quellwert, der in der Liste nicht vorkommt, führt zum Abbruch (Could not find TableMapping for …).

Datentypen — Zieltyp und akzeptierte Quelltypen

Beim Schreiben bestimmt der Attributtyp des Zielfeldes aus den Dataverse-Metadaten, welche Umwandlung angewendet wird.

Sonderfälle jenseits der Tabelle:

• UniqueIdentifierAttributeMetadata sowie Primärschlüssel- und logische Attribute (z. B. statuscodename) werden beim Schreiben stillschweigend übersprungen
• FileAttributeMetadata und ImageAttributeMetadata werden nicht unterstützt (type not supported)
• Jeder sonstige, nicht aufgeführte Attributtyp führt zum Abbruch (Type … not yet implemented)

Sonderentitäten

Einige Dataverse-Entitäten werden nicht über den generischen Weg verarbeitet.

listmember — Marketinglisten

Datensätze der Entität listmember werden nicht über den generischen Schreibpfad angelegt oder gelöscht, sondern über die Dataverse-Nachrichten AddMemberList bzw. RemoveMemberList. Das Mapping muss daher die Felder listid und entityid befüllen — sie liefern die Kennungen für die beiden Nachrichten.

Entitäten ohne statuscode

Für die folgenden Entitäten wird das Attribut statuscode beim Lesen automatisch aus der Spaltenliste entfernt, weil sie es nicht besitzen:

Ein Job-Filter mit der Operation StatusCode ist für diese Entitäten folglich nicht verwendbar.

Job-Filter

Der CE-Konnektor wertet das Feld Filter des Jobs clientseitig aus: Die Datensätze werden über die Change Tracking API abgerufen und anschließend geprüft; nicht passende Datensätze werden verworfen.

Unterstützt werden die Operationen Equals, Boolean, OptionSetValue, NotNull, IsNull und StatusCode. Ein anderer Operationsname führt zum Abbruch (Undefined FilterOperation).

Syntax, Parameter und Beispiele sind unter Jobs → Filter-Syntax beschrieben.

Änderungserkennung (Watermark)

Der CE-Konnektor nutzt die Dataverse Change Tracking API. Diese liefert bei jedem Abruf einen opaken Token, der beim nächsten Aufruf übergeben wird. So werden alle Änderungen erfasst — auch wenn der Timer genau während einer Änderung ausgeführt wird.

4.3 - D365NAV — Microsoft Dynamics NAV

Der D365NAV-Konnektor verbindet die DataBridge mit Microsoft Dynamics NAV über OData. Er ist auf die ältere NAV-API-Struktur ausgelegt und unterstützt auch OnPremise-Installationen mit NTLM-Authentifizierung.

Verbindungsparameter

Cloud-Umgebung (OAuth2)

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<NAV-Umgebungsname>",
  "companyId": "<Company ID (GUID)>",
  "url": "https://<server>/<pfad>/"
}

OnPremise-Umgebung (NTLM)

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>/",
  "baseAddress": "https://<server>:<port>/",
  "authenticationMethod": "NTLM"
}

Optionale Parameter

Die drei Diagnose-Schalter erzeugen erhebliche Datenmengen und können Geschäftsdaten im Klartext protokollieren — nur gezielt für die Dauer einer Analyse aktivieren. Vollständige Beschreibung unter Verbindungen.

Tabellen- und Feldnamen

• SourceTable / TargetTable: Name des OData-EntitySets, so wie er in $metadata steht
• SourceField / TargetField: Exakter Feldname aus der NAV-OData-API (case-sensitive)

Unterstützte TargetKey-Typen

Bei CustomKey werden die Metadatentypen int32 und string unterstützt, bei Filter die Typen string und guid. Jeder andere Typ des Schlüsselfeldes führt zum Abbruch (Metadata type … not yet implemented for CreateKeyString).

SourceOperations

LookupValue

Liest einen Wert aus einer anderen NAV-Tabelle nach — Aufbau und Parameter wie beim D365BC-Konnektor.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "countryRegionCode",
        "LookupTable": "CountryRegions",
        "LookupField": "Name",
        "UseCache": true
      }
    }
  ]
}

Unterstützt wird ausschließlich LookupType: Attribute. Der Wert Name führt zu einem Abbruch (SourceOperation for Lookups).

ReadFromMessage

Liest einen Wert aus der NAV-Antwort — nur in ResponseJobs. Das SourceField muss einen _-Prefix haben. Verhalten wie bei D365BC.

Datentypen — Zieltyp und akzeptierte Quelltypen

Beim Schreiben bestimmt der Datentyp des Zielfeldes aus den NAV-Metadaten, welche Umwandlung angewendet wird.

Jeder in der Tabelle nicht genannte NAV-Zieltyp führt beim Schreiben zu einem Abbruch (No Resolver defined for edmPrimitiveTypeKind …).

ResponseJob

Der NAV-Konnektor unterstützt das ResponseJob-Muster wie D365BC: Nach erfolgreichem Schreiben in NAV kann ein ResponseJob ausgelöst werden, der Felder aus der NAV-Antwort (z. B. neu vergebene Nummern) zurück ins Quellsystem schreibt. Aufbau und Konfiguration sind unter D365BC → ResponseJob beschrieben.

Änderungserkennung (Watermark)

Im Gegensatz zu Business Central gibt es kein einheitliches lastModifiedDateTime-Feld. Das korrekte Watermark-Feld hängt von der NAV-Version und der verwendeten Seite bzw. Codeunit ab. Im Zweifelsfall mit dem NAV-Administrator klären.

Der Filterausdruck aus dem Job wird als OData-$filter an die NAV-Anfrage angehängt. Die Regeln zur Klammerung und zum Platzhalter %watermark% sind unter Jobs → Filter-Syntax beschrieben.

Fehlersuche

Fehler beim Schreiben werden mit dem Text Error in NAV-Communication protokolliert, zusammen mit der verwendeten relativen Adresse sowie dem neuen und dem bestehenden Datensatz. Bis einschließlich v2.0 lautete derselbe Text irreführend Error in BC-Communication — ältere Logeinträge einer NAV-Verbindung sind also trotz BC-Nennung dem NAV-Konnektor zuzuordnen.

4.4 - MSSQL — Microsoft SQL Server

Der MSSQL-Konnektor ermöglicht das Lesen von Daten aus Microsoft SQL Server-Datenbanken (OnPremise und Azure SQL) und deren Übertragung in andere Systeme.

Wie die übrigen drei SQL-Konnektoren wertet MSSQL den Filter des Jobs aus und erzeugt gültiges Paging für sein Datenbanksystem.

Verbindungsparameter

{
  "connectionstring": "<ADO.NET Connection String>"
}

Beispiel (SQL Server Authentication):

Server=<server>;Database=<db>;User Id=<user>;Password=<password>;TrustServerCertificate=True;

Beispiel (Windows Authentication / Integrated Security):

Server=<server>;Database=<db>;Integrated Security=True;TrustServerCertificate=True;

Optionale Parameter

Tabellen- und Feldnamen

Der Wert aus SourceTable wird unverändert hinter FROM eingesetzt.

Änderungserkennung (Watermark)

Die Erkennung basiert auf einer Zeitstempel-Spalte in der SQL-Tabelle. Diese Spalte muss beim Einfügen oder Ändern eines Datensatzes automatisch aktualisiert werden.

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung (ORDER BY … ASC) verwendet.

Filter — die WHERE-Klausel kommt aus dem Job

Ein typischer Filter für eine MSSQL-Quelle:

{{ModifiedAt > '%watermark%'}}

Die Klammerung {{ … }} sorgt dafür, dass der Block bei leerer Watermark vollständig entfällt — der Erstlauf liest dann den gesamten Bestand. Die vollständigen Regeln stehen unter Jobs → Filter-Syntax.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist beim MSSQL-Konnektor allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

4.5 - MySQL — MySQL / MariaDB

Der MySQL-Konnektor ist für das Lesen von Daten aus MySQL- und MariaDB-Datenbanken vorgesehen.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges MySQL-SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<MySQL Connection String>"
}

Beispiel:

Server=<server>;Database=<db>;User=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

4.6 - Oracle — Oracle Database

Der Oracle-Konnektor ist für das Lesen von Daten aus Oracle-Database-Instanzen vorgesehen.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges PL/SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<Oracle Connection String>"
}

Beispiel (TNS):

Data Source=<tns-alias>;User Id=<user>;Password=<password>;

Beispiel (Easy Connect):

Data Source=<server>:<port>/<service>;User Id=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

4.7 - PostgreSQL

Der PostgreSQL-Konnektor ermöglicht das Lesen von Daten aus PostgreSQL-Datenbanken und deren Übertragung in andere Systeme.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges PostgreSQL-SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<PostgreSQL Connection String>"
}

Beispiel (Npgsql-Format):

Host=<server>;Database=<db>;Username=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Der Wert aus SourceTable wird unverändert hinter FROM eingesetzt.

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung (ORDER BY … ASC) verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Zahlen werden in der Kultur der Quellverbindung formatiert. Steht dort der Vorgabewert de-DE, wird ein Komma als Dezimaltrennzeichen ausgegeben — für Zielumwandlungen, die einen Textwert zwingend als en-US lesen, ist language entsprechend anzupassen.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

4.8 - OpenAPI — generischer REST-Konnektor

Der OpenAPI-Konnektor verbindet die DataBridge mit einer beliebigen REST-API, für die eine OpenAPI-Spezifikation (JSON oder YAML) existiert. Anders als bei den übrigen HTTP- Konnektoren werden Pfade, Wrapper-Schlüssel ({"clients": [...]} vs. {"client": {...}}) und Feldtypen nicht pro Ressource fest verdrahtet, sondern zur Laufzeit aus der Spezifikation aufgelöst. Ein Mapping muss dafür lediglich SourceTable/TargetTable auf den Ressourcennamen setzen (z. B. clients).

Verbindungsparameter

{
  "baseUrl": "https://api.example.com",
  "openApiSpecUrl": "https://api.example.com/openapi.yaml",
  "clientId": "<Client-ID>",
  "clientSecret": "<Client-Secret>",
  "tenantId": "<Entra Tenant ID>",
  "scope": "<OAuth2-Scope>",
  "tokenUrl": "https://api.example.com/oauth/token",
  "apiKeyHeader": "X-API-Key",
  "apiKeyValue": "<API-Key>",
  "customHeaders": { "X-Custom-Header": "wert" },
  "nextLinkPath": "@odata.nextLink",
  "nextPagePath": "meta.next_page",
  "pageQueryParam": "page",
  "pageSizeQueryParam": "per_page",
  "updateMethod": "PATCH",
  "authenticateSpecRequest": false
}

Zusätzlich stehen die universellen Parameter maxPageSize, language, httpClientTimeoutSeconds, keyVaultUrl, logCreateRequests, logUpdateRequests und logReceivedData zur Verfügung — siehe Verbindungen.

Authentifizierung

Der OpenAPI-Konnektor nutzt dieselbe Auswahllogik wie die übrigen HTTP-Konnektoren, erweitert um API-Key-Authentifizierung:

{
  "apiKeyHeader": "X-Qonto-Staging-Token",
  "apiKeyValue": "<Token>"
}

Zusätzliche statische Header (z. B. mandantenspezifische Tokens, die parallel zu OAuth2 oder API-Key benötigt werden) lassen sich unabhängig von der Authentifizierungsmethode über customHeaders mitgeben.

Tabellen- und Feldnamen

• SourceTable / TargetTable: kurzer Ressourcenname, wie er in der OpenAPI-Spezifikation als letztes Pfadsegment vorkommt (z. B. clients für /v2/clients). Der Konnektor sucht in der Spezifikation nach einem Pfad, der auf /<Ressourcenname> endet und keine Parameter enthält; ein zugehöriger Einzeldatensatz-Pfad (/v2/clients/{id}) wird automatisch mitaufgelöst.
• Alternativ kann auch der vollständige Pfad aus der Spezifikation eingetragen werden (Rückwärtskompatibilität).
• SourceField / TargetField: Feldname aus dem JSON-Schema der Ressource. Verschachtelte Felder werden mit Punktnotation adressiert (z. B. phone.country_code).

Liste- und Einzeldatensatz-Antworten müssen nicht manuell konfiguriert werden: Wrapper- Schlüssel wie {"clients": [...]} oder {"client": {...}} werden aus der Spezifikation erkannt. Fehlen entsprechende Hinweise in der Spezifikation, erkennt der Konnektor ersatzweise die gebräuchlichen Muster value, data und results als Array-Wrapper.

Unterstützte TargetKey-Typen

Wird bei CustomKey/Filter mehr als ein Datensatz gefunden, bricht die Verarbeitung mit einem Fehler ab (Found more than 1 record).

Schreiben (Upsert)

Der Konnektor prüft vor jedem Schreibvorgang, ob bereits ein Zieldatensatz existiert (GetSingleRequest bei PrimaryKey/Id/CustomKey, ein gefilterter Liste-Abruf bei Filter). Existiert er, wird nur bei tatsächlicher Werteänderung ein Update ausgelöst — identische Werte führen zu keiner Anfrage.

• Anlegen: POST auf den Collection-Pfad

• Aktualisieren: PATCH (Vorgabe) oder PUT (updateMethod) auf den Item-Pfad

• Anfrage-Body wird bei Bedarf automatisch in einen aus der Spezifikation abgeleiteten Wrapper-Schlüssel eingebettet (z. B. {"client": {...}}). Ein Job kann das über SpecialSettings gezielt abschalten:

  { "DoNotWrapRequestBody": true }
  

• Ein 409 Conflict bei Anlegen oder Aktualisieren wird als transiente Ausnahme behandelt und über die Transitive-Queue erneut verarbeitet (siehe Architektur → Retry- und Fehlerverhalten).

Löschen

Anders als die SQL-Konnektoren unterstützt der OpenAPI-Konnektor Löschungen: Der Schlüssel wird wie beim Lookup aufgelöst, anschließend folgt ein DELETE auf den Item-Pfad. Bei TargetKey vom Typ Filter wird der Datensatz zuerst gesucht. Wird keiner gefunden, schreibt der Konnektor eine Warnung ins Log und sendet kein DELETE.

InvokeAction — generische Aktionsaufrufe

Neben dem klassischen CRUD-Zyklus unterstützt die DataBridge seit dieser Version Aktions-Jobs: Ein Job mit Action = InvokeAction (technisch: jeder Wert, der nicht auf einen bekannten JobActionType passt) ruft einen benannten, nicht-CRUD-Endpunkt auf, statt einen Datensatz anzulegen oder zu ändern — z. B. POST /v2/client_invoices/{id}/send_by_einvoice.

Konfiguration: