OAuth 2.0 Applications and Storage Setup

This page describes how to let ExFlow store incoming document attachments in SharePoint (or an Azure Blob Container) instead of in the Business Central database.

For support regarding below, please contact the internal IT department or trusted Business Central partner.

Overview of the setup

1. Register an application in Microsoft Entra and give it access to SharePoint.
2. Create an OAuth 2.0 Application in ExFlow that uses the Entra application to get an access token.
3. Prepare a SharePoint folder and create a Storage Setup in ExFlow that points to it.
4. Activate Blob Storage so ExFlow starts moving documents.

For an Azure Blob Container, steps 1 and 2 are not needed. See Blob Storage Setup for Azure Container.

Values to copy from Microsoft Entra

Keep these at hand, they are needed in step 2:

Value	Used in ExFlow field
Application (client) ID	Application / Client ID
Client secret (value)	Client Secret
OAuth 2.0 token endpoint (v2)	Access Token URL
OAuth 2.0 authorization endpoint (v2)	Authorization URL
Microsoft Graph API endpoint	Scope (as https://graph.microsoft.com/.default)

Create Application or Service Principal in MS Entra (or Azure)

In the Microsoft Entra admin center, go to App registrations and select New registration. Enter a name of choice, select Accounts in any organizational directory and then select Register.

After registration, copy the Application (client) ID.

Go to API permissions and select Add a permission.

Select Microsoft Graph and Application permissions.
Search for "site" and add the permission Sites.ReadWrite.All.

Select Add a permission again, then SharePoint and Application permissions.
Select and add both permissions: Sites.ReadWrite.All and Sites.Manage.All.

Select Grant admin consent for these permissions:

The permissions should look like this:

Go to Certificates & secrets.

Create a new client secret:

Copy the secret Value right away and store it safely. It is only shown once. If the secret is lost or expires, create a new secret and enter it in the OAuth 2.0 Application in ExFlow.

Go back to the list of App registrations and select Endpoints. Copy the OAuth 2.0 authorization endpoint (v2), the OAuth 2.0 token endpoint (v2) and the Microsoft Graph API endpoint.

The setup in Microsoft Entra is now complete.

Configure an OAuth2 Application in ExFlow

Go to: ExFlow Setup --> Actions --> Functions --> OAuth2 Applications

Select New to create a new OAuth 2.0 Application.

Fill in the fields as follows:

General
Code	A short code of choice that identifies this application, for example SHAREPOINT.
Description	A description of the application.
Application / Client ID	Paste the Application (client) ID from Microsoft Entra.
Client Secret	Paste the client secret value from Microsoft Entra. The value is stored securely and shown as asterisks.
Grant Type	Select Client Credentials. This is the grant type to use for SharePoint storage. (Authorization Code and Password Credentials are also available. Password Credentials shows extra User Name and Password fields.)
Redirect URL	Leave empty. Only used with the Authorization Code grant type.
Scope	Enter https://graph.microsoft.com/.default (the Microsoft Graph API endpoint followed by .default).

Endpoints
Authorization URL	Paste the OAuth 2.0 authorization endpoint (v2). Only used with the Authorization Code grant type, but can be filled in anyway.
Access Token URL	Paste the OAuth 2.0 token endpoint (v2). Required.
Auth. URL Parms	Leave empty. Only used with the Authorization Code grant type.

Both URLs must start with https://.

Test the setup by selecting Request Access Token. With Client Credentials, no login is prompted. If everything is correct, the message "Access Token updated successfully." is shown and Status on the OAuth 2.0 Applications list is set to Connected. If something is wrong, the error from Microsoft is shown and Status is set to Error.

Actions
Request Access Token	Gets a new access token using the settings on the card. Use this to test the setup.
Refresh Access Token	Refreshes the access token using a refresh token. Not used with Client Credentials, since no refresh token is issued. ExFlow requests a new token automatically when the old one expires.

SharePoint Setup

In SharePoint, go to Site contents and create a new Document library. Then create a folder in the new document library. ExFlow stores the documents in this folder.

Open the newly created folder and copy the complete URL from the browser's address field. The URL is needed in the Storage Setup below.

Note: Make sure the URL is copied after opening the folder. The folder name is read from the ?id=... part of that URL. If only the URL of the document library is copied, the folder must be entered manually.

Storage Setup

Go to: ExFlow Setup --> Actions --> Functions --> Blob Storage Mgmt (the page ExFlow Storage Management Setup).

Select Storage Setup and then New.

Enter a Code and Description. For Blob Source, select SharePoint.

Then select Setup Storage to open the SharePoint Setup.

Paste the URL copied from SharePoint into the field SharePoint Url. When leaving the field, the values for Host, Site, Document Library and Folder are filled in automatically. If a value is missing (most often Folder), enter it manually.

Note: If the SharePoint Url is changed later, a confirmation is required. All SharePoint values are then cleared and read again from the new URL, and the connection must be tested again.

In OAuth2 Application Code, select the OAuth 2.0 Application created earlier, and select Connect to test the connection.

If all is OK, SharePoint Connection Status is set to Connected, and Site Id, Drive Id and List Id are filled in.

If the connection fails, the error from SharePoint is shown, for example:

Message	Most likely cause
Not Found	The site or document library name is wrong.
Unauthorized or Forbidden	The API permissions are missing or admin consent has not been granted in Microsoft Entra.

SharePoint Connection Status
Disconnected	The connection has not been tested yet.
Revalidate	A setting has changed since the last test. Select Connect again.
Connected	The connection has been tested successfully.

Close the SharePoint Setup page. On the ExFlow Storage Setup page, select Enable / Disable so that Enabled is turned on. This is only possible when SharePoint Connection Status is Connected.

Close ExFlow Storage Setup and return to ExFlow Storage Management Setup.

Activate Blob Storage

On ExFlow Storage Management Setup, select the new storage setup in Incoming Doc. Storage Code.

Check Blob Name Structure before continuing. The default, Split String 2 Char 3 Levels, is recommended. Blob Name Structure and Incoming Doc. Storage Code cannot be changed while Blob Storage is active.

Turn on Active, or select Enable/Disable Blob Storage.

If there are posted invoices or credit memos in ExFlow, ExFlow asks to add them to blob storage. Select Yes to continue. Selecting No cancels the activation.

When Blob Storage is activated, ExFlow creates the job queue entry ExFlow Blob Storage Job - Recurring (category EXFLOW). It runs every 60 minutes between 08:00 and 17:00 and moves documents to storage. Read more under Job Queues.

To check the status of posted invoices in blob storage, select Actions --> Storage Details.

To move documents to storage right away instead of waiting for the job queue, select Sync Storage.

Refresh the SharePoint folder in the browser. The new folders created by ExFlow should now be visible.

Deactivating Blob Storage: If Active is turned off again, a confirmation is required. All documents stored in blob storage are then restored to the Business Central database, and the storage cache and cross references are cleared. This can take some time if there are many documents.

Blob Storage Setup for Azure Container

The setup for an Azure Blob Container is similar to SharePoint, but does not use an OAuth 2.0 Application.

Go to: ExFlow Setup --> Actions --> Functions --> Blob Storage Mgmt, select Storage Setup and create a new setup with Blob Source set to Azure Container. Then select Setup Storage to configure the Azure Blob Container settings.

Azure Container Setup
Storage Account	Name of the Azure Storage Account. Must be between 3 and 24 characters.
Container Name	Name of the container in the Storage Account. Must be between 3 and 63 characters.
Shared Access Key	The access key found under the Azure Storage Account's Access keys in the Azure portal. The key is kept in isolated storage and is shown as ********** once saved. Clear the field to delete the key.
Test	Checks that the settings are valid and that the container exists. The message "Azure Blob Container settings OK" is shown if all is OK.

If the test fails, one of these messages is shown:

Message	Most likely cause
Azure Shared Account Key missing	Shared Access Key is empty.
Unable to fetch list of containers, please review settings	Storage Account or Shared Access Key is wrong.
Container does not exist, please review settings	Container Name is wrong, or the container has not been created in Azure.

When the test is OK, go back to ExFlow Storage Setup, select Enable / Disable so that Enabled is turned on, and continue in the same way as for SharePoint: select the setup in Incoming Doc. Storage Code and activate Blob Storage.

For details on working with Azure Blob Containers, please go to Microsoft Learn Introduction to Azure Blob Storage.

Reference: ExFlow Storage Management Setup

Actions
Storage Setup	Configure one or more storage setups (SharePoint or Azure Container).
Enable/Disable Blob Storage	Activate or deactivate blob storage. Same as the Active field.
Storage Details	Shows cached entries and cross reference entries.
Sync Storage	Runs the same transfer as the job queue, right away.
Manually Add All Posted Documents to Cache	Adds all incoming documents linked to ExFlow posted documents to the storage cache.
Manually Restore All Posted Incoming From Cache	Restores all incoming documents linked to ExFlow posted documents from storage back to the database.

General
Cache in Days	Specifies how many days cached content remains in Business Central. After the specified number of days, the content is removed from local storage. Recommended to set 60 days.
Batch Size	Set to 0 to transfer all documents in one batch during sync. Set to a value above 0 to transfer only that many documents per sync. Applies both to the job queue and to Sync Storage.
Blob Name Structure	Specifies the naming convention used for the path to blobs. Split String 2 Char 3 Levels (default and recommended) splits the name into a path like ab/cd/ef/abcdefgh. As-Is uses the name without splitting. Cannot be changed while Blob Storage is active.
Active	Enables Blob Storage. Requires Incoming Doc. Storage Code to be filled in.

Storage Codes
Incoming Doc. Storage Code	The storage setup used for incoming document attachments of ExFlow posted documents. File names, folder structure and retrieval are handled by ExFlow. Cannot be changed while Blob Storage is active.
General Blob Storage Code	The storage setup used by the general Blob Storage API. Only needed for partner/developer extensions, see below.

For partners and developers: When General Blob Storage Code is set to a storage setup (this can be the same as for Incoming Doc. Storage Code), the file API in codeunit BSApi (Blob Storage API) can be used. It works like a file system where files can be written and read, and the developer controls names and structure. The Blob Storage for incoming document attachments uses the same BSApi internally.