Nachfolgend wird beschrieben, wie die collana pay App in Business Central installiert wird.
Wir unterstützen regelmäßig die aktuelle BC-Version und zusätzlich die beiden Vorgängerversionen zur aktuellen Version.
Voraussetzung für die Installation sind Admin-Berechtigungen sowohl in Business Central, als auch im Azure (Azure Active Directory).
1. Über die Suchfunktion in Business Central die Seite Marketplace für Erweiterungen öffnen.
2. Im Suchfeld collana pay eingeben und Installationsvorgang durchführen.
3. Abschließend müssen die Nutzungsbedingungen akzeptiert werden und auf Installieren geklickt werden.
Die Installation kann einige Minuten dauern. Nachdem die Installation abgeschlossen ist, kann über die drei Punkte überprüft werden, ob die Installation erfolgreich war. Wenn die Option Installieren ausgegraut ist, war die Installation erfolgreich.
Webservices
Für die Integration von collana pay mit Business Central müssen bestimmte Endpunkte für Benachrichtigungen eingerichtet werden, die von Business Central empfangen werden sollen und zur Kommunikation mit der collana pay API dienen. Um sicherzustellen, dass diese Benachrichtigungen erfolgreich verarbeitet werden können, ist es wichtig, dass die collana pay-Webdienste über das Internet erreichbar sind.
Im Rahmen der Installation der collana pay App werden automatisch zwei Codeunits bzw. Webservices erstellt und veröffentlicht. Falls der Webservice noch nicht veröffentlicht wurde, kann dies im Bereich Webdienste vorgenommen werden. Um den Webdienst PAY Receive Notification HVE zu veröffentlichen kann der Haken in der Spalte Veröffentlicht gesetzt werden.
Ein weiterer Webservice Pay Receive SOAP Notification HVE steht zur Verfügung. Für die Installation von collana pay für Business Central SaaS ist er nicht erforderlich. Dieser Webservice wird stattdessen in der On-Premise-Version verwendet. Der Webservice erfüllt dieselbe Funktion und nimmt ebenfalls Benachrichtigungen von collana pay entgegen. Der Unterschied besteht darin, dass er dabei ein älteres Format verwendet, das noch mit Business Central OnPrem kompatibel ist.
Microsoft Entra ID - App Registrierung
Microsoft Entra ID ermöglicht die Verwaltung des Netzwerkzugriffs und schützt vor unautorisierten Zugriffen. Um die Sicherheit der Zugriffe zu gewährleisten, sind Konfigurationen innerhalb der Microsoft Entra ID erforderlich. Hierfür ist es erforderlich, eine App Registrierung durchzuführen.
Um den Zugriff über das Internet zu ermöglichen, muss die collana pay Business Central-App im Microsoft Entra ID (www.portal.azure.com) registriert werden.
Mit der Registrierung der App werden folgende IDs angelegt, die zu einem späteren Zeitpunkt zur Konfiguration wichtig sind.
In dem Menüpunkt Endpoints können die URLS für die Endpunkte aufgerufen werden.
Im nächsten Schritt müssen Konfigurationen für die Plattform vorgenommen werden.
Der kopierte Link wird im markierten Bereich eingefügt und die Konfiguration wird vorgenommen. Für die Authentifizierung muss folgende URL eingetragen werden:
https://businesscentral.dynamics.com/OAuthLanding.htm
Diese Redirect-URLs dienen als Kommunikationswege für die Authentifizierung.
Im folgenden Fall wird eine OAuth2-Authentifizierung eingerichtet. Die Authentifizierung erfolgt in folgenden Schritten:
- Wenn eine bestimmte URL aufgerufen wird, ist eine Anmeldung erforderlich.
- Nach erfolgreicher Anmeldung erfolgt die Weiterleitung zu einem autorisierten Bereich, der in diesem Fall Business Central ist.
Client Secret
Im nächsten Schritt ist die Erstellung eines Client Secrets erforderlich. Dieses wird benötigt, um auf die Business Central App zuzugreifen. Während der Erstellung wird ein Wert generiert, der anschließend in im collana pay Admin Portal (COPAL) eingetragen werden muss.
Sobald das Client Secret erstellt wurde, wird dies in der Übersicht sichtbar. Im Feld Expires ist ein Datum hinterlegt, welches das Ablaufdatum repräsentiert. Dieses Ablaufdatum kann nicht verlängert werden. Stattdessen muss das Client Secret regelmäßig erneuert werden. Zu dem Zeitpunkt, wo das Secret abläuft, wird collana pay nicht mehr in der Lage sein, Nachrichten zuzustellen. In Microsoft-Systemen ist es üblich, dass Passwörter regelmäßig geändert werden müssen, und es besteht keine Möglichkeit, diese Anforderung zu deaktivieren. Daher sollten Sie das Ablaufdatum im Blick behalten und ihr Passwort in COPAL aktualisieren, sobald es abgelaufen ist.
Das Feld Value enthält ein generiertes Passwort. Dieses Passwort ist von entscheidender Bedeutung, um auf die Business Central App zuzugreifen.
Achtung! Nachdem der Wert generiert wurde, muss das Passwort kopiert werden, um es im collana pay Admin Portal zu hinterlegen. Es ist zu einem späteren Zeitpunkt nicht mehr möglich, das Passwort zu kopieren, weil es nicht mehr angezeigt wird.
API Permissions
In diesem Schritt erfolgt die API-Berechtigung, bei der der Zugriff der Business Central-App ausgewählt wird. Hier wird festgelegt, welche Informationen collana pay durch die Registrierung im jeweiligen Tenant abrufen darf.
Es ist wichtig sicherzustellen, dass bei der Auswahl der Berechtigung Application permissions ausgewählt werden, da die Kommunikation ausschließlich über die API erfolgen soll und keine anderen Zugriffsrechte gewährt werden sollen.
Nach der Konfiguration wird im Statusfeld eine Hinweismeldung angezeigt, die darauf hinweist, dass der Administrator zustimmen muss, um den Zugriff zu gewähren.
Die Zustimmung kann über Grant admin consent erteilt werden. Falls die Erteilung der Berechtigung nicht funktioniert, liegt das an der Berechtigung des aktuellen Nutzers.
Die App-Registrierung wurde erfolgreich konfiguriert, um auf bestimmte Einrichtungen zuzugreifen. Die erfolgreiche Registrierung ist anhand des grünen Häkchens erkennen, und die Hinweismeldung wurde entfernt.
Der nächste Schritt ist die Einrichtung, um collana pay für den Zugriff auf den Business Central Callback Web Service zu autorisieren.
Hier ist die Anleitung für das Setup zu finden.