Business Central stellt mit Hilfe der API Pages bereits im Standard zahlreiche APIs zur Verfügung. Darüber hinaus lassen sich eigene API Pages erstellen. Für die Anbindung von Business Central an externe Systeme und die Integration in die eigene Systemlandschaft ist dies ein wichtiger Baustein.
Wie lässt sich mit API Pages der Datenaustausch mit einem Webservice realisieren? Wie aufwändig ist das und was muss man dazu wissen? In diesem Beitrag möchten wir dies mit Hilfe eines Beispiels aus der Praxis anschaulich darstellen.
Die Anforderung in unserem Beispiel
In einer Shopanwendung können B2B Kunden Bestellungen erfassen. Die Shopanwendung übermittelt neue Bestellungen per Webservice an Business Central. Neue Bestellungen aus der Shopanwendung sollen als Verkaufsauftrag in Business Central angelegt werden.
Vorüberlegungen
Zunächst ist zu entscheiden, ob eine Business Central Standard API Page verwendet wird oder ob eine eigene API Page erstellt wird. Die in Business Central enthaltenen API Pages basieren auf den Standard Tabellen. Ein Webservice mit Verbindung zur API Page „Sales Order Entity“ würde direkt auf die Tabelle „Sales Header“ der Verkaufsaufträge zugreifen.
In dem hier beschriebenen Beispiel fiel die Entscheidung aus zwei Gründen gegen die Standard API Pages aus:
- Das Anlegen neuer Aufträge erfordert einen schreibenden Zugriff in Business Central
- Neue Verkaufsaufträge sollen vor der Übernahme aber erst validiert werden. Dazu werden sie zunächst in eigenen, kundenspezifischen Tabellen abgelegt, und nicht direkt in die Standard-Tabelle geschrieben.
Insbesondere um das Validieren der eingelesenen Aufträge zu ermöglichen, haben wir also kundenspezifische Tabellen für „Shop Import Header“ und „Shop Import Lines“ erstellt. Diese beiden Tabellen werden mit eigens dafür erstellten API Pages veröffentlicht. Dadurch können die vom Webservice gesendeten Daten zunächst ungeprüft in den Tabellen abgelegt werden.
Dies „erledigt“ die API Page wenn der Webservice Daten mit einem POST-Request sendet. Neue Datensätze werden anschließend validiert und von dort in die Business Central Tabellen „Sales Header“ und „Sales Line“ übernommen.
Das Validieren und Übernehmen in die Zieltabellen sind natürlich Teil der Kundenanpassung und nicht der API Pages, weshalb wir in diesem Beitrag nicht näher darauf eingehen.
Umsetzung
Die in unserem Beispiel erforderlichen Tabellen und API Pages haben wir als Erweiterung in AL erstellt. Anschließend muss dafür gesorgt werden, dass die API Endpunkte erreichbar sind.
Schauen wir uns diese beiden Schritte im Einzelnen an. Zum besseren Verständnis haben wir die hier beschriebenen Felder reduziert auf die für das Beispiel wesentlichen Felder.
Tabellen und API Pages erstellen:
Bei der Frage, welche Tabellen und Felder in den Import-Tabellen erforderlich sind, ist ein Blick auf den Webservice erforderlich.
In unserem Beispiel sendet der Webservice der Shopanwendung im POST-Request ein JSON-Array, das neben anderen die folgenden Felder enthält:
Daraus lassen sich die beiden Tabellen „Shop Import Header“ und „Shop Import Line“ ableiten, in denen diese Daten abgelegt werden. Beide müssen mindestens die vom Webservice gesendeten Felder enthalten.
Wir haben in der Tabelle „Shop Import Header“ ein Feld „No.“ erstellt und als Schlüsselfeld verwendet, welches unabhängig ist von der „Shop Order No.“, die die Shopanwendung liefert. Über dieses Feld sind die Zeilen („Shop Import Line“) mit dem Header („Shop Import Header“) verknüpft. (siehe Abb. 1 und Abb. 2).
Abb. 1: Tabelle „Shop Import Header“:
Abb. 2: Tabelle „Shop Import Line”:
Die API Pages „API Shop Import Header“ und „API Shop Import Line“ zu diesen beiden Tabellen enthalten die Felder dieser Tabellen. Zu beachten ist, dass in API Pages die folgenden Properties gesetzt werden müssen:
- PageType: API
- APIPublisher: <IhrFirmenname> (wird Teil der Webservice Adresse)
- APIGroup: <GruppenName> (wird Teil der Webservice Adresse)
- APIVersion: <API-Version vX.Y> (z.B. ‚v1.0‘ oder ‚v2.0‘, wird Teil der Webservice Adresse)
- EntityName: z.B. 'shopOrder' und EntitySetName: z.B. 'shopOrders'
In den Tabellennamen sowie den o.g. Properties sind lediglich Alphanumerische Zeichen (A-Z, a-z, 0-9) zugelassen, CamelCase Schreibweise ist üblich.
In unserem Beispiel sehen die Pages wie in Abb. 3 und 4 gezeigt aus. Die API Page der Zeilen ist als PagePart eingebunden, dabei werden ihr EntitySetName und ihr Objekt Name verwendet.
Abb. 3: Page „API Shop Import Header“:
Abb. 4: Page “API Shop Import Lines”:
API Endpunkte veröffentlichen:
Die API Endpunkte müssen auch veröffentlich werden. Dazu muss in der Business Central Administration das Kennzeichen „Enable API Services“ gesetzt werden sowie die OData Base-URL und der Port hinterlegt werden; Standard Port ist 7048.
Zu beachten ist, dass im Service-Tier, in dem die Einstellung vorgenommen wird, die entsprechende Authentifizierung eingerichtet ist, mit der sich der Webservice authentifizieren wird. Es kommt durchaus in Betracht, dazu eine neue Service-Tier einzurichten.
Für diese Aufgaben ist entsprechendes Know How erforderlich. Dies ist umso mehr gefordert, wenn der Webservice-Endpunkt auch von außerhalb des eigenen Netzwerkes für den Webservice erreichbar gemacht werden soll, um dabei das nötige Maß an Sicherungsmaßnahmen beizubehalten.
Im Business Central Client öffnen Sie anschließend die Page „API Einrichtung“ und starten mit dem Button „APIs integrieren“ den Prozess zum Veröffentlichen der APIs.
Weitere Informationen finden Sie z.B. auf dieser Microsoft-Seite.
Weitere Informationen über Business Central API Pages
In NAV2018 erstmals als Beta Version verfügbar, wurden die API Pages bis zur aktuellen Business Central Version weiterentwickelt, aktuell als Version 2.0.
Eine Übersicht, welche API Pages der Standard der aktuell eingesetzten Version bietet lässt sich leicht erhalten, indem in der Base App nach Pages mit „Entity“ im Namen gesucht wird.
Microsofts Dokumentation bietet einige Beiträge für den Einstieg in das Thema. Eine Übersicht der verfügbaren Endpunkte finden Sie über diesen Link.
Eine kurze Zusammenfassung, worauf beim Erstellen eigener API Pages zu achten ist, finden Sie unter diesem Link:
Auch einige Blogs liefern hilfreiche Informationen, z.B. hat sich Arend-Jan Kauffmann hier ausgiebig mit API Pages in Business Central beschäftigt.
Mein Fazit
Dass API Pages das Erstellen und Veröffentlichen von REST Webservices für Business Central praktisch mit Bordmitteln ermöglichen, konnte hoffentlich anschaulich beschrieben werden.
Zur Konfiguration des Service-Tiers und zum erstmaligen Einrichten der Authentifizierung ist jedoch ein gutes Maß an Wissen und Erfahrung notwendig, umso mehr wenn der Webservice von außerhalb des eigenen Netzwerkes erreichbar sein soll.
Unserer Erfahrung nach sollten daher an der Umsetzung beteiligt sein:
- Knowhow in der Administration von Business Central und Kenntnis der Systemumgebung/ Netzwerk, um Service-Tier und Authentifizierung einzurichten.
- Grundkenntnisse in einem Tool wie Postman, um den Webservice in der Entwicklung und dem Support testen zu können.
- Ansprechpartner auf Seiten des Kunden oder Dienstleisters, der den Webservice aufrufen möchte für die notwendigen Absprachen.
Ist die erste Einrichtung geschafft und steht die erste Testverbindung zum Webservice, dann sind die größten Hürden genommen. Das Erstellen und Anpassen erfordern auf Seiten Business Central keinerlei Kenntnisse in Webservice-Programmierung.
Sollen mehr oder weniger Felder ausgetauscht werden, entspricht die Anpassung im Prinzip dem Anpassen von Tabellen und Pages in AL. Der Programmieraufwand verringert sich dadurch drastisch.
API Pages sind daher eine gute Möglichkeit, Business Central ohne Programmierung von Schnittstellen in Geschäftsprozesse einzubinden und mit anderen Anwendungen zu vernetzen. Und die dafür notwendige Anpassung in Business Central kann standardkonform erfolgen.
Übrigens:
In unserem Beispiel hat der Hersteller der Shopanwendung signalisiert, dass der Webservice auf Seiten der Shopanwendung leicht zu modifizieren sei.
Daher konnten zunächst die Tabellen und API Pages in Business Central erstellt werden. Anschließend konnten wir manuell Beispiel-Daten erfassen und mit Postmann abrufen. So konnten wir dem Hersteller der Shopanwendung aussagekräftige Musterdaten an die Hand geben, wie der Webservice idealerweise Daten senden sollte. Das hat natürlich dazu beigetragen, Anpassungen auf Seiten des ERP-Systems weitestgehend zu vermeiden, um Standardnähe zu wahren.
Denkt man das vorgestellte Beispiel weiter in diese Richtung, dann können API Pages durchaus auch beim Übertragen von Stammdaten wie z.B. Artikel in Richtung der Shopanwendung eine Rolle spielen, indem die Daten von der Shopanwendung per GET-Request geholt werden. Dies geht natürlich nur unter gewissen Voraussetzungen. Aber wenn der anzubindende Webservice ohnehin erstellt oder angepasst werden muss, lohnt es sich, darüber nachzudenken, um Anpassungen des ERP-Systems möglichst zu vermeiden.
Haben Sie API Pages in ihrem Unternehmen bereits eingesetzt? Welche Erfahrungen haben Sie damit gemacht? Schildern Sie uns gerne ihre Erfahrungen! Planen Sie den Einsatz von API Pages? Sprechen Sie uns gerne an.
Für weitere hilfreiche Tipps & Tricks in Dynamics NAV / Business Central klicken Sie auf den Namen des Autors und Sie sehen alle Beiträge im Überblick.
Möchten Sie keinen Beitrag mehr verpassen? Dann abonnieren Sie einfach den Blog und Sie werden automatisch per E-Mail benachrichtigt.
