🌐 Web | 👤 Yokoy Admin
Für Microsoft Dynamics 365 Business Central On-Premises-Implementierungen installierst Du den Yokoy Spend Management Connector als Erweiterung.
🚧 Vorsicht
Wenn Du den Yokoy-Connector als Erweiterung installierst, musst Du Dir darüber im Klaren sein, dass Du keine automatischen Updates mit neuen Funktionen erhältst. Du bist für die Installation und Verwaltung aller Updates des Yokoy-Connectors verantwortlich.
Die Erweiterung muss bei Microsoft Entra registriert und konfiguriert werden, um Yokoy Zugriff auf die Business Central API-Endpunkte zu gewähren.
So wird der Connector für Business Central On-Premises eingerichtet:
Richte den Export in Yokoy ein:
🚧 Vorsicht
Die On-Premises-Edition von Business Central kann auf privaten Webservern mit eingeschränktem Zugriff auf und von ungesicherten Netzwerken gehostet werden. Stelle sicher, dass die Sicherheitsreglements den Datenverkehr zwischen Yokoy und den Diensten des Business-Central-Mandanten nicht behindern. Mit anderen Worten: Firewall-Regeln, Port-Weiterleitungsregeln und sichere Netzwerk-Gateways müssen so eingerichtet werden, dass sie den Datenverkehr zu und von Business Central On-Premises und Yokoy durchlassen, bevor Daten synchronisiert oder Exporte ausgelöst werden.
Architektur-Überblick
Um Daten zwischen Yokoy und Microsoft Dynamics 365 Business Central auszutauschen, verwendet die Anwendung die OAuth 2.0-Authentifizierung und -Autorisierung, um die Datenübertragung zu sichern.
Microsoft Entra wird als Identitätsanbieter (IdP) verwendet. Es verwaltet sicher Benutzerinformationen, Zugriffsrechte und die Vertrauensbeziehungen zwischen Business Central und Yokoy. Nach der Authentifizierung eines Benutzers (d. h. der Anmeldung) stellt der Autorisierungsserver Sicherheitstoken aus, die die Client-Anwendung (d. h. die Yokoy-Webanwendung) verwendet, um den Zugriff auf die Business Central-API zu gewähren, zu verweigern oder zu widerrufen (Autorisierung). Sobald die Client-Anwendung über gültige Inhaber-Token (Zugriff, ID und Aktualisierung) verfügt, kann sie auf die Daten in Business Central zugreifen und Vorgänge wie Erstellen, Aktualisieren oder Löschen ausführen. Mit anderen Worten: Wenn die Yokoy-App API-Aufrufe an Business Central sendet, überprüft die Erweiterung die bereitgestellten Zugriffstoken und entscheidet, ob der Zugriff auf die angeforderten Ressourcen gewährt oder verweigert wird. Wenn der Zugriff gewährt wird, kann Yokoy dann Spesen oder Rechnungen buchen.
Daher musst Du Microsoft Entra einrichten, damit die Client-App (Yokoy) erkannt und Sicherheitstoken ausgestellt werden können.
Installiere den Yokoy-Connector als Erweiterung
Um den Yokoy-Connector als Erweiterung zu installieren, benötigst Du Zugriff auf das Connector-Paket (.app). Du musst eine Serviceanfrage stellen, um Zugriff auf das Connector-Paket zu erhalten.
Sobald Du Zugriff auf diese Datei hast, kannst Du mit der Installation der App über die Seite Erweiterungsverwaltung fortfahren.
Das Erweiterungspaket verwendet diese ID-Bereiche für die unten aufgeführten Objekte:
Objekttyp | Number of objects | ID range |
Codeunits | 8 | 63800–63807 |
Enums | 2 | 63800, 63802 |
Seiten | 1 | 63800 |
Seitenerweiterungen | 13 | 63800–63812 |
Berichte | 8 | 63800–63807 |
Tabellen | 1 | 63800 |
Tabellenerweiterungen | 15 | 63800–63814 |
✏️ Hinweis
ID-Bereiche sind dynamisch und können durch die Lizenz des Kunden beeinflusst werden.
Wenn der Kunde diese ID-Bereiche verwendet, musst Du möglicherweise einen anderen für die Objekte des Erweiterungspakets zuweisen. Andernfalls kommt es zu Konflikten.
Erweiterungen können nach einem Update von Business Central automatisch und ohne Datenverlust deinstalliert werden. Siehe Deinstallation der Erweiterung.
Business Central für Microsoft Entra einrichten
Nachdem Du die Erweiterung installiert hast, musst Du sie in Microsoft Entra registrieren und konfigurieren, um Yokoy Zugriff auf die Business Central API-Endpunkte zu gewähren. Außerdem musst Du die App-Berechtigungen konfigurieren.
🚧 Vorsicht
Es ist sehr wichtig, dass Du die in der offiziellen Microsoft-Dokumentation beschriebenen Schritte befolgst, insbesondere die Abschnitte Business Central Server konfigurieren (Task 4) und Business Central Web Server-Komponente konfigurieren (Task 5).
Um den von Microsoft Entra ausgestellten Sicherheitstoken zu vertrauen, musst Du Deine App registrieren. Während der Registrierung weist die Plattform Schlüsselwerte zu, wie z.B.:
Anwendungs- (Client-)ID: Diese eindeutige Kennung, auch als Anwendungs- oder Client-ID bezeichnet, wird Deiner App von der Identitätsplattform zugewiesen. Die Client-ID hilft dabei, Deine Anwendung innerhalb der Plattform zu identifizieren, und ist in den von der Plattform ausgegebenen Sicherheitstoken enthalten.
Umleitungs-URL: Die Umleitungs-URL gibt an, wohin der Autorisierungsserver den Benutzeragenten (z. B. einen Webbrowser oder eine Mobile-App) nach Abschluss des Authentifizierungsprozesses senden soll. Beispielsweise leitet der Autorisierungsserver den Benutzer nach der Anmeldung an die angegebene URI weiter. Beachte, dass nicht alle Client-Typen eine Umleitungs-URL erfordern.
Die App-Registrierung bietet auch die Authentifizierungs- und Autorisierungsendpunkte, die zum Erhalt von ID- und Zugriffstoken erforderlich sind.
Registriere eine Anwendung im Microsoft Azure-Portal
Zuerst musst Du eine App auf dem Microsoft Azure-Portal für den Yokoy-Connector registrieren.
Siehe Registrieren einer Anwendung bei Microsoft Identity Platform für eine Anleitung.
Erstelle die grundlegende Definition der Anwendung, indem Du die Abschnitte Übersicht, Authentifizierung, Zertifikate und Geheimnisse und API-Berechtigung konfigurierst.
Abschnitt Übersicht:
Name der App: Yokoy Business Central-Connector
Anwendung (Client-ID): Kopiere diese ID, Du wirst sie später brauchen.
Abschnitt Authentifizierung:
Klicke auf + Plattform hinzufügen.
Wähle Web aus.
Gib die Umleitungs-URLs ein:
Klicke auf Speichern.
💡 Tipp
Um zwei Umleitungs-URLs hinzuzufügen, musst Du eine hinzufügen und auf Speichern klicken. Anschließend kannst Du die zweite im Hauptbildschirm hinzufügen.
Abschnitt API-Berechtigung:
Klicke auf + Berechtigung hinzufügen.
Wähle Dynamics 365 Business Central aus.
Wähle unter Stellvertretende Berechtigungen Berechtigungen aus und füge sie hinzu:
user_impersonationFinancials.ReadWrite.All
Wähle unter Anwendungsberechtigungen Berechtigungen aus und füge sie hinzu:
app_accessAdminCenter.ReadWrite.AllAPI.ReadWrite.All
Klicke auf Admin-Zustimmung erteilen für…
Abschnitt Zertifikate und Geheimnisse:
Erstelle ein neues Kundengeheimnis. Es wird empfohlen, die Gültigkeitsdauer auf 24 Monate festzulegen. Kopiere den Wert und die Geheim-ID.
Veröffentliche den Webdienst in Business Central
Gib „Microsoft Entra Application“ in das globale Suchwerkzeug von Business Central (oben rechts) ein, um auf die Anwendungseinrichtung zuzugreifen.
Erstelle die Anwendung
Du musst eine neue Anwendung in Business Central erstellen:
Erstelle eine neue Anwendungskarte.
Gib die Anwendungs-ID (erstellt im Abschnitt Übersicht im Azure-Portal) in Client-ID ein.
Gib Yokoy for Business Central in die Beschreibung ein.
Klicke auf Aktivieren.
Vergabe von Benutzerberechtigungen in Business Central
Du musst die Anwendung so einrichten, dass sie über Super-Admin-Berechtigungen verfügt.
Genauer gesagt musst Du diese Berechtigungssätze im Abschnitt Benutzergruppen auf der Microsoft Entra-Anwendungskarte hinzufügen, die Du gerade erstellt hast.
Berechtigungssatz | Beschreibung |
Dynamics 365 Basic access | |
Dynamics 365 Full access | |
Dyn. 365 Einrichtung von Firmendaten | |
D365 Webhook-Abonnement | |
Dyn. 365 Setup Kostenrechnung | |
Dyn. 365 Anlagevermögen einrichten | |
Dynamics 365 Basic HR-Einrichtung | |
Dyn. 365 Intercompany Setup | |
Dynamics 365 Projekte erstellen | |
Dynamics 365 Rlshp. Mgt. Setup | |
Duplikate zusammenführen | |
Reten. Pol. Setup - BaseApp | |
Outlook-Synchronisierungsadministrator | |
Erweiterungsverwaltung – Admin | |
Test Tool | |
PERMISSIONSET YKY | Benutzerdefinierte Berechtigungen für die Yokoy-Erweiterung |
Nach Abschluss der Erstinstallation benötigen Standardbenutzer den Yokoy BC-Berechtigungssatz (PERMISSIONSET YKY), um anschließend Änderungen an der Integration vorzunehmen und Daten zu synchronisieren.
Außerdem musst Du den ID-Bereich festlegen, in dem neue Objekte erstellt werden können (z. B. 50000 bis 55000).
Da der für benutzerdefinierte Entwicklungen verwendete ID-Bereich variieren kann, ist es wichtig, diesen Bereich anzugeben, da das Installationspaket alle vorhandenen Objekte überschreibt, denen derselbe ID-Bereich zugewiesen ist. Eine Liste der in der Erweiterung standardmäßig verwendeten ID-Bereiche findet sich unter Installieren den Yokoy-Connector als Erweiterung.
Webdienst konfigurieren
Du musst den Webdienst in Business Central hinzufügen.
Um dies zu tun:
Gehe zu Web Services.
Klicke auf + Neu, um ein neues Objekt zu erstellen.
Wähle den Codeunit Objekttyp aus.
Suche nach der Objekt-ID entsprechend dem Modul, das du implementieren möchtest:
Yokoy Expense: Import Expencies YKY (63807)
Yokoy Invoice: Webhooks YKY (63806)
Gib den Servicenamen Yokoy Expense / Yokoy Invoice ein. Stelle sicher, dass das Kontrollkästchen Veröffentlicht aktiviert ist.
💡 Zugehörige Dokumentation
Sobald Du dies getan hast, solltest Du die Einrichtungsseite für die Yokoy-Integration in Business Central konfigurieren, bevor Du mit der Einrichtung des Spesen- oder Rechnungsimports in Yokoy fortfährst.
Spesenexport in Yokoy einrichten
Yokoy ist für den Export der Spesen in das Hauptbuch in Business Central verantwortlich. Belege und Anhänge können bei Bedarf an Journalbuchungen angehängt werden.
Wenn die Firma plant, Gutschriften zu verarbeiten, musst Du Gutschriften für die Firma aktiviert haben.
Du musst die Spesenexport Registerkarte (Admin > Integrationen, Spesenexport) einrichten, um Spesendaten (Spesen, Kartentransaktionen, Reisekosten) an Business Central zu senden.
Du kannst den Yokoy-Connector nicht verwenden, um Tagespauschalen/ Fahrtpauschalen separat zu exportieren.
Um dies zu tun:
Gehe zu Admin > Integrationen.
Wähle die Registerkarte Spesenexport.
Wähle
Business Central [API]als das ERP-System aus.Gib die Authentifizierungsdaten ein:
Verzeichnis-D: Business Central-Mandanten-ID
Client secret: MS Azure-Portal-Client-Geheimschlüssel, der zuvor erstellt wurde.
Klicke Anmeldung bei Business Central.
Stelle sicher, dass alle Popup-Blocker in Deinem Browserfenster deaktiviert sind. Die MS Dynamics-Authentifizierung verwendet ein Popup-Fenster, um die Authentifizierungsanfrage an MS Entra zu senden.
🚧 Vorsicht
Achte darauf, das richtige ERP-System auszuwählen! Ms Dynamics Cloud & MS Dynamic OnPrem sind die Exportmöglichkeiten für einen anderen MS Dynamics Business Central-Connector, nicht für den von Yokoy entwickelten Connector.
Sobald die Verbindung hergestellt wurde, kannst Du die Exporteinstellungen konfigurieren:
Feld | Beschreibung |
Name des Webdienstes | Name des im Business Central erstellten Webdienstes. |
Base URL | Externe IP-Adresse des Webservers, einschließlich des offenen Ports. Zum Beispiel https://191.255.255.255:80 |
Mandant | Für Business Central On-Premises ist dies nicht erforderlich. |
Instanz | ID der Business-Central-Umgebung. |
Name der Firma | Name der Firma in Business Central. |
Konto-Typ | Dieses Feld gilt nur für den Spesenexport (Spesen aktuelles System) Business Central-Konto des Kreditorpostens. Legt fest, ob die Informationen von der Kreditorenkarte oder der Mitarbeiterkarte übernommen werden (d. h. es wird der ERP-Code im Yokoy-Benutzerprofil verwendet).
Bekannte Einschränkung Derzeit wird nur Mitarbeiter unterstützt, da Yokoy-Benutzer mit der Mitarbeiterkarte verknüpft sind. |
Art des Firmenkartenkontos | Gilt nur für den Export von Kartentransaktionen (Aktuelles System für Kartentransaktionen) Business Central-Konto des Kreditorenpostens. Legt fest, ob die Informationen aus der Kreditorenkarte oder dem Sachkonto übernommen werden (d. h. verwendet den ERP-Code im Lieferanten oder die Kategorie Spesen, je nachdem, ob Du Kreditor oder Sachkonto ausgewählt hast). |
❗️ Kostenobjekte vom Export ausschließen
Die Einstellung Kostenobjekte vom Export ausschließen für den Spesenexport ist mit dieser Integration nicht kompatibel. Die Yokoy-Integration für MS Dynamics 365 Business Central erwartet beim Export von Spesen immer ein Kostenobjekt.
Rechnungsexport in Yokoy einrichten
Um Rechnungen mit Business Central zu bearbeiten, verwendet Yokoy Webhooks, um Business Central über Änderungen des Dokumentstatus zu informieren. Yokoy verfügt über eine spezielle Rechnungs-Exportfunktion, um die Webhook-Antwort zu verarbeiten. Derzeit sind die Webhooks synchron. Das bedeutet, dass der Anbieter warten muss, bis der Webhook die Verarbeitung abgeschlossen hat, um eine Antwort zu erhalten.
Damit Business Central eine Verbindung zu Yokoy herstellen kann, musst Du die Integration in Yokoy einrichten:
Gehe zu Admin > Integrationen.
Wähle die Registerkarte Rechnungsexport aus.
Klicke in der Registerkarte Rechnungsexport auf Assistent starten.
Gib die folgenden Details ein:
Export Name: Business Central Rechnungen
Dokumenttyp auswählen: Alle Lieferantenrechnungen
Wähle auf der Registerkarte System die Option
Business Central Integration.Gib auf der Registerkarte Konfiguration die Daten ein, die zur Bildung der URL für den Zugriff auf die Business Central API verwendet werden. Du musst die folgenden Daten eingeben:
Feld | Beschreibung |
Base URL | Externe IP-Adresse des Webservers, einschließlich des offenen Ports. Zum Beispiel |
Token URL | Gib die URL des Umleitungs-URI für die Authentifizierung ein, die Du zuvor in Anwendung registrieren im MS Azure-Portal konfiguriert hast, d. h. diese URL enthält normalerweise die Zeichenfolge |
Scope | Dieser sollte sein: https://api.businesscentral.dynamics.com/.default |
Mandant | Für Business Central On-Premises ist dies nicht erforderlich. |
Umgebung | ID der Business Central-Umgebung. |
Name des Webdienstes | Name des Webservice, den Du zuvor in Business Central veröffentlicht hast. |
Name der Firma | Name des Unternehmens. Diese Information kann in der URL für den Zugriff auf Business Central identifiziert werden, identifiziert mit dem |
Du musst dies für jede Firma tun, die Du mit einer Firma in Business Central verknüpfen möchtest.
❗️Warnung
Wenn Du versuchst, mehrere Exportfunktionen einzurichten (d. h. den Yokoy-Connector zusammen mit vorhandenen Integrationen), kann beim Versuch, eine Rechnung zu exportieren, die Fehlermeldung Validierung: Mehrere Exportmöglichkeiten anwendbar angezeigt werden. Es kann jeweils nur eine Exportfunktion aktiv sein.
💡 Tipp
Nächster Schritt: Einrichten und Synchronisieren von Stamm- und Transaktionsdaten.