OAuth 2.0-Anwendungen und Speichereinrichtung

Diese Seite beschreibt, wie ExFlow Anhänge eingehender Dokumente in SharePoint (oder in einem Azure Blob Container) statt in der Business Central-Datenbank speichern kann.

Für Unterstützung zu den folgenden Punkten wenden Sie sich bitte an die interne IT-Abteilung oder einen vertrauenswürdigen Business Central-Partner.

Übersicht über die Einrichtung

1. Registrieren Sie eine Anwendung in Microsoft Entra und gewähren Sie ihr Zugriff auf SharePoint.
2. Erstellen Sie eine OAuth 2.0-Anwendung in ExFlow, die die Entra-Anwendung verwendet, um ein Zugriffstoken abzurufen.
3. Bereiten Sie einen SharePoint-Ordner vor und erstellen Sie eine Speichereinrichtung in ExFlow, die auf diesen Ordner verweist.
4. Aktivieren Sie den Blob-Speicher, damit ExFlow mit dem Verschieben der Dokumente beginnt.

Für einen Azure Blob Container sind die Schritte 1 und 2 nicht erforderlich. Siehe Blob-Speichereinrichtung für Azure Container.

Aus Microsoft Entra zu kopierende Werte

Halten Sie diese Werte bereit, sie werden in Schritt 2 benötigt:

Wert	Verwendet im ExFlow-Feld
Anwendungs-ID (Client)	Anwendungs-/Client-ID
Geheimer Clientschlüssel (Wert)	Client-Geheimnis
OAuth 2.0-Tokenendpunkt (v2)	Zugriffstoken-URL
OAuth 2.0-Autorisierungsendpunkt (v2)	Autorisierungs-URL
Microsoft Graph-API-Endpunkt	Bereich (als https://graph.microsoft.com/.default)

Anwendung oder Dienstprinzipal in MS Entra (oder Azure) erstellen

Gehen Sie im Microsoft Entra Admin Center zu App-Registrierungen und wählen Sie Neue Registrierung. Geben Sie einen Namen Ihrer Wahl ein, wählen Sie Konten in einem beliebigen Organisationsverzeichnis und wählen Sie dann Registrieren.

Kopieren Sie nach der Registrierung die Anwendungs-ID (Client).

Gehen Sie zu API-Berechtigungen und wählen Sie Berechtigung hinzufügen.

Wählen Sie Microsoft Graph und Anwendungsberechtigungen.
Suchen Sie nach "site" und fügen Sie die Berechtigung Sites.ReadWrite.All hinzu.

Wählen Sie erneut Berechtigung hinzufügen, dann SharePoint und Anwendungsberechtigungen.
Wählen Sie beide Berechtigungen aus und fügen Sie sie hinzu: Sites.ReadWrite.All und Sites.Manage.All.

Wählen Sie Administratorzustimmung erteilen für diese Berechtigungen:

Die Berechtigungen sollten wie folgt aussehen:

Gehen Sie zu Zertifikate und Geheimnisse.

Erstellen Sie einen neuen geheimen Clientschlüssel:

Kopieren Sie den Wert des geheimen Schlüssels sofort und bewahren Sie ihn sicher auf. Er wird nur einmal angezeigt. Wenn der geheime Schlüssel verloren geht oder abläuft, erstellen Sie einen neuen geheimen Schlüssel und tragen Sie ihn in der OAuth 2.0-Anwendung in ExFlow ein.

Gehen Sie zurück zur Liste der App-Registrierungen und wählen Sie Endpunkte. Kopieren Sie den OAuth 2.0-Autorisierungsendpunkt (v2), den OAuth 2.0-Tokenendpunkt (v2) und den Microsoft Graph-API-Endpunkt.

Die Einrichtung in Microsoft Entra ist damit abgeschlossen.

Konfigurieren einer OAuth2-Anwendung in ExFlow

Gehen Sie zu: ExFlow Setup --> Aktionen --> Funktionen --> OAuth2-Anwendungen

Wählen Sie Neu, um eine neue OAuth 2.0-Anwendung zu erstellen.

Füllen Sie die Felder wie folgt aus:

Allgemein
Code	Ein frei wählbarer kurzer Code, der diese Anwendung identifiziert, zum Beispiel SHAREPOINT.
Beschreibung	Eine Beschreibung der Anwendung.
Anwendungs-/Client-ID	Fügen Sie die Anwendungs-ID (Client) aus Microsoft Entra ein.
Client-Geheimnis	Fügen Sie den Wert des geheimen Clientschlüssels aus Microsoft Entra ein. Der Wert wird sicher gespeichert und als Sternchen angezeigt.
Berechtigungstyp	Wählen Sie Clientanmeldeinformationen. Dies ist der Berechtigungstyp, der für die SharePoint-Speicherung zu verwenden ist. (Autorisierungscode und Passwortanmeldeinformationen sind ebenfalls verfügbar. Bei Passwortanmeldeinformationen werden zusätzlich die Felder Benutzername und Kennwort angezeigt.)
Umleitungs-URL	Leer lassen. Wird nur mit dem Berechtigungstyp Autorisierungscode verwendet.
Bereich	Geben Sie https://graph.microsoft.com/.default ein (der Microsoft Graph-API-Endpunkt gefolgt von .default).

Endpunkte
Autorisierungs-URL	Fügen Sie den OAuth 2.0-Autorisierungsendpunkt (v2) ein. Wird nur mit dem Berechtigungstyp Autorisierungscode verwendet, kann aber trotzdem ausgefüllt werden.
Zugriffstoken-URL	Fügen Sie den OAuth 2.0-Tokenendpunkt (v2) ein. Erforderlich.
Auth. URL Parms	Leer lassen. Wird nur mit dem Berechtigungstyp Autorisierungscode verwendet.

Beide URLs müssen mit https:// beginnen.

Testen Sie die Einrichtung, indem Sie Zugriffstoken anfordern wählen. Bei Clientanmeldeinformationen wird keine Anmeldung abgefragt. Wenn alles korrekt ist, wird die Meldung "Zugriffstoken erfolgreich aktualisiert." angezeigt und der Status in der Liste der OAuth 2.0-Anwendungen wird auf Verbunden gesetzt. Wenn etwas falsch ist, wird der Fehler von Microsoft angezeigt und der Status wird auf Fehler gesetzt.

Aktionen
Zugriffstoken anfordern	Ruft mit den Einstellungen auf der Karte ein neues Zugriffstoken ab. Verwenden Sie diese Aktion, um die Einrichtung zu testen.
Zugriffstoken aktualisieren	Aktualisiert das Zugriffstoken mithilfe eines Aktualisierungstokens. Wird bei Clientanmeldeinformationen nicht verwendet, da kein Aktualisierungstoken ausgestellt wird. ExFlow fordert automatisch ein neues Token an, wenn das alte abläuft.

SharePoint-Einrichtung

Gehen Sie in SharePoint zu Websiteinhalte und erstellen Sie eine neue Dokumentbibliothek. Erstellen Sie dann einen Ordner in der neuen Dokumentbibliothek. ExFlow speichert die Dokumente in diesem Ordner.

Öffnen Sie den neu erstellten Ordner und kopieren Sie die vollständige URL aus dem Adressfeld des Browsers. Die URL wird in der nachfolgenden Speichereinrichtung benötigt.

Hinweis: Achten Sie darauf, die URL nach dem Öffnen des Ordners zu kopieren. Der Ordnername wird aus dem Teil ?id=... dieser URL gelesen. Wenn nur die URL der Dokumentbibliothek kopiert wird, muss der Ordner manuell eingegeben werden.

Speichereinrichtung

Gehen Sie zu: ExFlow Setup --> Aktionen --> Funktionen --> Blob Storage Mgmt (die Seite ExFlow Storage Management Setup).

Wählen Sie Speichereinrichtung und dann Neu.

Geben Sie einen Code und eine Beschreibung ein. Wählen Sie für Blob-Quelle die Option SharePoint aus.

Wählen Sie dann Speicher einrichten, um die SharePoint-Einrichtung zu öffnen.

Fügen Sie die aus SharePoint kopierte URL in das Feld SharePoint-URL ein. Beim Verlassen des Feldes werden die Werte für Host, Site, Dokumentbibliothek und Ordner automatisch ausgefüllt. Wenn ein Wert fehlt (meistens Ordner), geben Sie ihn manuell ein.

Hinweis: Wenn die SharePoint-URL später geändert wird, ist eine Bestätigung erforderlich. Alle SharePoint-Werte werden dann gelöscht und aus der neuen URL neu gelesen, und die Verbindung muss erneut getestet werden.

Wählen Sie unter OAuth2-Anwendungscode die zuvor erstellte OAuth 2.0-Anwendung aus und wählen Sie Verbinden, um die Verbindung zu testen.

Wenn alles in Ordnung ist, wird der SharePoint-Verbindungsstatus auf Verbunden gesetzt, und Site-ID, Drive-ID und List-ID werden ausgefüllt.

Wenn die Verbindung fehlschlägt, wird der Fehler von SharePoint angezeigt, zum Beispiel:

Meldung	Wahrscheinlichste Ursache
Not Found	Der Name der Site oder der Dokumentbibliothek ist falsch.
Unauthorized oder Forbidden	Die API-Berechtigungen fehlen oder die Administratorzustimmung wurde in Microsoft Entra nicht erteilt.

SharePoint-Verbindungsstatus
Getrennt	Die Verbindung wurde noch nicht getestet.
Erneut validieren	Seit dem letzten Test wurde eine Einstellung geändert. Wählen Sie erneut Verbinden.
Verbunden	Die Verbindung wurde erfolgreich getestet.

Schließen Sie die Seite SharePoint-Einrichtung. Wählen Sie auf der Seite ExFlow Storage Setup die Option Aktivieren / Deaktivieren, sodass Aktiviert eingeschaltet ist. Dies ist nur möglich, wenn der SharePoint-Verbindungsstatus Verbunden ist.

Schließen Sie ExFlow Storage Setup und kehren Sie zu ExFlow Storage Management Setup zurück.

Blob-Speicher aktivieren

Wählen Sie auf ExFlow Storage Management Setup die neue Speichereinrichtung im Feld Speichercode für eingehende Dokumente aus.

Prüfen Sie die Blob-Name-Struktur, bevor Sie fortfahren. Der Standardwert Split String 2 Char 3 Levels wird empfohlen. Blob-Name-Struktur und Speichercode für eingehende Dokumente können nicht geändert werden, solange der Blob-Speicher aktiv ist.

Schalten Sie Aktiv ein oder wählen Sie Blob-Speicher aktivieren/deaktivieren.

Wenn es gebuchte Rechnungen oder Gutschriften in ExFlow gibt, fragt ExFlow, ob diese dem Blob-Speicher hinzugefügt werden sollen. Wählen Sie Ja, um fortzufahren. Mit Nein wird die Aktivierung abgebrochen.

Wenn der Blob-Speicher aktiviert wird, erstellt ExFlow den Aufgabenwarteschlangeneintrag ExFlow Blob Storage Job - Recurring (Kategorie EXFLOW). Er wird zwischen 08:00 und 17:00 Uhr alle 60 Minuten ausgeführt und verschiebt Dokumente in den Speicher. Lesen Sie mehr unter Job Queues.

Um den Status gebuchter Rechnungen im Blob-Speicher zu prüfen, wählen Sie Aktionen --> Speicherdetails.

Um Dokumente sofort in den Speicher zu verschieben, statt auf die Aufgabenwarteschlange zu warten, wählen Sie Speicher synchronisieren.

Aktualisieren Sie den SharePoint-Ordner im Browser. Die von ExFlow erstellten neuen Ordner sollten jetzt sichtbar sein.

Blob-Speicher deaktivieren: Wenn Aktiv wieder ausgeschaltet wird, ist eine Bestätigung erforderlich. Alle im Blob-Speicher gespeicherten Dokumente werden dann in die Business Central-Datenbank zurückgespielt, und der Speicher-Cache sowie die Querverweise werden gelöscht. Bei vielen Dokumenten kann dies einige Zeit dauern.

Blob-Speichereinrichtung für Azure Container

Die Einrichtung für einen Azure Blob Container ähnelt der für SharePoint, verwendet jedoch keine OAuth 2.0-Anwendung.

Gehen Sie zu: ExFlow Setup --> Aktionen --> Funktionen --> Blob Storage Mgmt, wählen Sie Speichereinrichtung und erstellen Sie eine neue Einrichtung, bei der Blob-Quelle auf Azure Container gesetzt ist. Wählen Sie dann Speicher einrichten, um die Azure Blob Container-Einstellungen zu konfigurieren.

Azure Container-Einrichtung
Speicherkonto	Name des Azure-Speicherkontos. Muss zwischen 3 und 24 Zeichen lang sein.
Containername	Name des Containers im Speicherkonto. Muss zwischen 3 und 63 Zeichen lang sein.
Gemeinsamer Zugriffsschlüssel	Der Zugriffsschlüssel, der im Azure-Portal unter Zugriffsschlüssel des Azure-Speicherkontos zu finden ist. Der Schlüssel wird im isolierten Speicher abgelegt und nach dem Speichern als ********** angezeigt. Leeren Sie das Feld, um den Schlüssel zu löschen.
Testen	Prüft, ob die Einstellungen gültig sind und der Container vorhanden ist. Wenn alles in Ordnung ist, wird die Meldung "Azure Blob Container settings OK" angezeigt.

Wenn der Test fehlschlägt, wird eine dieser Meldungen angezeigt:

Meldung	Wahrscheinlichste Ursache
Azure Shared Account Key missing	Gemeinsamer Zugriffsschlüssel ist leer.
Unable to fetch list of containers, please review settings	Speicherkonto oder Gemeinsamer Zugriffsschlüssel ist falsch.
Container does not exist, please review settings	Containername ist falsch, oder der Container wurde in Azure nicht erstellt.

Wenn der Test erfolgreich ist, gehen Sie zurück zu ExFlow Storage Setup, wählen Sie Aktivieren / Deaktivieren, sodass Aktiviert eingeschaltet ist, und fahren Sie wie bei SharePoint fort: Wählen Sie die Einrichtung im Feld Speichercode für eingehende Dokumente aus und aktivieren Sie den Blob-Speicher.

Weitere Details zur Arbeit mit Azure Blob Containern finden Sie in Microsoft Learn Einführung in Azure Blob Storage.

Referenz: ExFlow Storage Management Setup

Aktionen
Speichereinrichtung	Konfigurieren Sie eine oder mehrere Speichereinrichtungen (SharePoint oder Azure Container).
Blob-Speicher aktivieren/deaktivieren	Aktivieren oder deaktivieren Sie den Blob-Speicher. Entspricht dem Feld Aktiv.
Speicherdetails	Zeigt zwischengespeicherte Einträge und Querverweiseinträge an.
Speicher synchronisieren	Führt sofort dieselbe Übertragung wie die Aufgabenwarteschlange aus.
Alle gebuchten Dokumente manuell zum Cache hinzufügen	Fügt alle eingehenden Dokumente, die mit gebuchten ExFlow-Dokumenten verknüpft sind, dem Speicher-Cache hinzu.
Alle gebuchten eingehenden Dokumente manuell aus dem Cache wiederherstellen	Stellt alle eingehenden Dokumente, die mit gebuchten ExFlow-Dokumenten verknüpft sind, aus dem Speicher in der Datenbank wieder her.

Allgemein
Cache in Tagen	Gibt an, wie viele Tage zwischengespeicherte Inhalte in Business Central verbleiben. Nach der angegebenen Anzahl von Tagen werden die Inhalte aus dem lokalen Speicher entfernt. Empfohlen werden 60 Tage.
Batchgröße	Stellen Sie 0 ein, um alle Dokumente während der Synchronisierung in einem Batch zu übertragen. Stellen Sie einen Wert über 0 ein, um pro Synchronisierung nur so viele Dokumente zu übertragen. Gilt sowohl für die Aufgabenwarteschlange als auch für Speicher synchronisieren.
Blob-Name-Struktur	Gibt die Namenskonvention für den Pfad zu Blobs an. Split String 2 Char 3 Levels (Standard und empfohlen) unterteilt den Namen in einen Pfad wie ab/cd/ef/abcdefgh. As-Is verwendet den Namen ohne Unterteilung. Kann nicht geändert werden, solange der Blob-Speicher aktiv ist.
Aktiv	Aktiviert den Blob-Speicher. Erfordert, dass Speichercode für eingehende Dokumente ausgefüllt ist.

Speicher-Codes
Speichercode für eingehende Dokumente	Die Speichereinrichtung, die für Anhänge eingehender Dokumente von gebuchten ExFlow-Dokumenten verwendet wird. Dateinamen, Ordnerstruktur und Abruf werden von ExFlow gesteuert. Kann nicht geändert werden, solange der Blob-Speicher aktiv ist.
Allgemeiner Blob-Speichercode	Die Speichereinrichtung, die von der allgemeinen Blob Storage API verwendet wird. Nur für Partner-/Entwicklererweiterungen erforderlich, siehe unten.

Für Partner und Entwickler: Wenn Allgemeiner Blob-Speichercode auf eine Speichereinrichtung gesetzt ist (diese kann dieselbe wie für Speichercode für eingehende Dokumente sein), kann die Datei-API in der Codeunit BSApi (Blob Storage API) verwendet werden. Sie funktioniert wie ein Dateisystem, in das Dateien geschrieben und aus dem Dateien gelesen werden können, wobei der Entwickler Namen und Struktur steuert. Der Blob-Speicher für Anhänge eingehender Dokumente verwendet intern dieselbe BSApi.