Microsoft Business Central anbinden: Drei-Tage-Abonnements, ein maesn-Payload

Business Central ist Microsofts ERP für kleine und mittlere Unternehmen, und für einen Integrator ist die Adresse die bestimmende Eigenschaft. Ein Datensatz liegt in einer Firma innerhalb einer Umgebung, und eine Anfrage, die keine von beiden nennt, hat keine Adresse, an der sie ankommen kann.

Das zeigt sich in der URL. Jeder Ressourcenpfad führt die Umgebung und die Firma mit, vor Ihrem ersten nützlichen Aufruf brauchen Sie also zwei Ermittlungsaufrufe, um herauszufinden, welche ein bestimmter Kunde hat. Das Entra-Verzeichnis steht hinter beiden, es ist aber kein Wert, den Sie senden.

Über maesn geschieht die Ermittlung beim Verbinden. Ihr Code tut dafür nichts. Business Central gehört zu den Systemen auf dem interaktiven Fluss, Ihr Kunde wählt also Umgebung und Firma auf einer Auswahlseite, und beide werden mit der Verbindung gespeichert.

Wo der Fluss nicht verwendet wird, werden sie als Query-Parameter environmentName und companyId übertragen. Wie sich das über Systeme hinweg verallgemeinern lässt, ist Unified Authentication.

Wenn Sie die Objektabdeckung, die Entra-App-Registrierung und den AppSource-Eintrag an einer Stelle brauchen, ist das die Microsoft Dynamics 365 Business Central Schnittstelle. Was folgt, ist das, was die Plattform tut, nachdem Sie verbunden sind.

Das ist der Teil, den Business Central wirklich gut kann. Es sendet native Ereignisse, und das ist ungewöhnlich: Bei den meisten Buchhaltungsplattformen lesen Sie nach Zeitplan und vergleichen das Ergebnis mit dem, was Sie schon hatten.

Ein Abonnement gilt der Ressource, der Ereignistyp gehört nicht dazu. Eine Registrierung liefert also alle vier Arten dafür. Diese Objekte sind heute über maesn für Ereignisse freigeschaltet, und weitere lassen sich für einen Anwendungsfall zuschalten, der sie braucht.

Hier steht der Satz, der ändert, wie Sie bauen. Microsoft wörtlich: Abonnements laufen nach drei Tagen ab, wenn sie nicht vorher erneuert werden. Abonnements werden erneuert, indem eine PATCH-Anfrage an das Abonnement gesendet wird. Die Frist ist am Abonnement selbst ablesbar, als expirationDateTime.

Ein Abonnement ist damit ein wiederkehrender Auftrag mit einer 72-Stunden-Frist, und er muss für jede Ressource laufen, für jede Firma, für jeden Kunden, dauerhaft.

Die Erneuerung ist außerdem kein stiller PATCH. Microsoft verlangt den Validierungs-Handshake beim Anlegen und bei der Erneuerung: Business Central ruft Ihre Benachrichtigungs-URL mit einem validationToken im Query-String auf, und Sie müssen dieses Token im Body mit einem 200 zurückgeben.

Ein Endpunkt, der während eines Deployment-Fensters nicht erreichbar ist, kostet Sie deshalb die Erneuerung. Und eine fehlgeschlagene Erneuerung erzeugt nirgends einen Fehler, weil nichts fehlgeschlagen ist. Die Ereignisse kommen einfach nicht mehr an.

Über maesn ist dieser Auftrag nicht Ihrer. Die bei Business Central registrierte URL ist unsere, Ihr Endpunkt ist bei uns registriert, und die Erneuerung samt dem Handshake, der dazugehört, läuft auf unserer Seite. Bei Ihrem Endpunkt kommt das Ereignis an.

Business Central hat einen vierten Ereignistyp, den die anderen Systeme nicht haben, und auf ihn sollten Sie Ihren Entwurf auslegen. Ändern sich mehrere Datensätze einer Ressource kurz hintereinander, hält es sie zurück und sendet ein einzelnes COLLECTION-Ereignis, das einen Zeitraum trägt.

Das Ereignis sagt Ihnen also, wann sich etwas geändert hat, und nicht was. Das ist die eine Stelle im einheitlichen Payload, an der filterDate gefüllt ist, und die Dokumentation sagt es in einem Kommentar am Feld: nur für Sammelereignistypen unterstützt.

Dieser Lesevorgang ist Ihrer. maesn registriert das Abonnement, normalisiert den Payload und übergibt Ihnen den Zeitraum. Die Dokumentation ist eindeutig, dass der Listen-Endpunkt mit dem gelieferten filterDate aufgerufen werden muss, und es ist ein gefilterter Aufruf gegen dieselbe Schnittstelle, die Sie ohnehin nutzen, und nicht gegen Business Centrals eigene Filtersyntax.

Zwei kleinere Dinge im selben Payload. Ereignisse kommen als Array an, auch wenn es nur eines ist, ein Handler für ein einzelnes Objekt bricht also in der ersten Minute unter Last. Und resourceId ist bei einem Sammelereignis per Definition leer, was sich im Code zu prüfen lohnt. Die Abonnement-Mechanik selbst ist auf jedem System derselbe Aufruf, und das sind Unified Webhooks.

Was Business Central veröffentlicht, ist ein Warteschlangenmodell, und der Unterschied zählt, weil dieselbe Ursache verschiedene Statuscodes erzeugt, je nachdem, wo Ihre Anfrage stand, als sie abgebrochen wurde.

Zwei davon ändern, wie Sie blättern. Eine Antwort darf bis zu 20.000 Entitäten tragen, bevor Business Central sie mit 413 ablehnt, was großzügig ist, und eine einzelne Anfrage darf acht Minuten laufen, bevor sie mit 408 abgebrochen wird, was es nicht ist.

Ein breiter ungefilterter Lesevorgang scheitert also eher an der Zeit als an der Größe, und die Abhilfe ist ein engerer Filter. Eine kleinere Seite ändert daran nichts. Wie dieselbe Frage über Systeme hinweg aussieht, ist Unified Pagination and Filtering.

Der 429 erreicht Sie. Nur die asynchronen Endpunkte von maesn fangen Lastspitzen ab, das Backoff gegen Business Central bleibt also in Ihrem Code. Diese vier Codes richtig einzuordnen ist der größte Teil dieser Arbeit, und es ist auf jedem System dasselbe Problem, weshalb es im Unified Error Handling sitzt.

Business Central stellt Rechnungszeilen als eigenständige Datensätze bereit, lesbar, anlegbar und änderbar. Auf den meisten Buchhaltungssystemen ist eine Rechnung ein Dokument, das Sie in einem Stück zusammensetzen und buchen, und die Zeile hat keine eigene Adresse.

Das ist eine echte Fähigkeit und eine echte Portabilitätsfalle. Code, der einer bestehenden Rechnung eine Zeile hinzufügt, funktioniert hier und hat auf einem System, das nur ganze Dokumente annimmt, läuft er ins Leere, er gehört also hinter eine Fähigkeitsprüfung und aus Ihrem gemeinsamen Schreibpfad heraus.

In die andere Richtung müssen ein Kopf und seine Zeilen nicht zwei Aufrufe sein. Business Central unterstützt OData $expand, auch verschachtelt, die Zeilen kommen also mit dem Dokument zurück.

Das ist der Fehler, der beim Kunden auftritt und nicht im eigenen Mandanten, und der Grund dafür ist, dass der Aufruf identisch ist, der Mandant nicht.

Wenn Sie einen Kunden, einen Lieferanten oder eine Rechnung anlegen, füllt Business Central Pflichtfelder aus Vorlagen, die innerhalb des Mandanten auf der Seite API Setup konfiguriert sind. Buchungsgruppen, Steuerkonfiguration und Dokumentvorgaben kommen von dort. Die maesn-Dokumentation sagt es unumwunden: Einige Pflichtfelder werden von diesen Vorlagen befüllt und lassen sich über die Schnittstelle überhaupt nicht setzen.

Ein Anlegen, das in Ihrer Testumgebung funktioniert, kann also bei einem Kunden fehlschlagen, weil dessen Vorlagen fehlen oder anders konfiguriert sind, und Microsofts Vorgaben sind über Lokalisierungen hinweg nicht identisch. Lokalisierte Fassungen ergänzen je Markt eigene Felder, Steuerregeln und Anforderungen an die elektronische Rechnung.

Für das Onboarding folgen daraus zwei Dinge. Prüfen Sie vor dem ersten Live-Aufruf die Vorlagen für jedes Objekt, das Sie anlegen wollen, und behandeln Sie einen Fehlschlag beim Anlegen als Konfigurationsfrage, bevor Sie ihn als Fehler in Ihrem Payload behandeln.

maesn normalisiert die Form der Integration. Die Regeln der Plattform bleiben, wie sie sind, und drei Dinge wandern in dem Moment auf unsere Seite, in dem Sie verbinden:

• Das Abonnement, je Kunde. Ein Aufruf legt es an, mit dem Endpunkt, auf dem Sie Ereignisse wollen, und der Ressource, die Sie beobachten wollen, und ein Aufruf entfernt es. Sie schreiben nicht gegen die Abonnement-Ressource von Business Central.
• Der Payload, in einer Form. Jedes Ereignis kommt im selben Umschlag an wie der Rest Ihrer Integrationen, und ein Feld, das dieses System nicht unterstützt, kommt als ausdrückliches null zurück und verschwindet nicht.
• Die Umgebung und die Firma. Auf dem interaktiven Fluss wählt Ihr Kunde beide, und sie werden mit der Verbindung gespeichert, Ihr Code muss sie also nie ermitteln.
• Die Erneuerung nach drei Tagen. Unsere URL ist die, die bei Business Central registriert ist, der PATCH vor jedem Ablauf und der Validierungs-Handshake, den er auslöst, laufen also hier. Ein Deployment-Fenster auf Ihrer Seite kostet Sie kein Abonnement.

Fünf Dinge bleiben bei Ihnen, und es ist günstiger, das jetzt zu wissen als nach dem ersten Kundengespräch.

• Der Lesevorgang nach einem Sammelereignis. Wir übergeben Ihnen den Zeitraum im normalen Umschlag. Ihn in Datensätze zu verwandeln ist ein gefilterter Aufruf, und der ist Ihrer.
• Die Ratenbegrenzung erreicht Sie weiterhin. Nur die asynchronen Endpunkte von maesn fangen Lastspitzen ab, der 429 von Business Central kommt also in Ihrem Code an. Was der asynchrone Weg abdeckt und was nicht, ist Asynchronous Processing.
• Die Entra-App-Registrierung braucht den Administrator Ihres Kunden. Anwendungsberechtigungen, delegierte Berechtigungen und eine Administratorzustimmung sind Schritte, die nur jemand mit den Rechten in diesem Verzeichnis abschließen kann. Wir gehen sie mit Ihnen durch, erteilen können wir sie aber nicht.
• API Setup liegt in Business Central. Wir können Ihnen sagen, welche Vorlagen ein Anlegen braucht. Konfiguriert werden sie im Mandanten des Kunden.
• Löschungen gibt es hier nicht. Kein Objekt auf diesem System unterstützt eine, Korrekturen werden also als neue Dokumente gebucht. Bauen Sie diesen Weg von Anfang an.