Web Services - EXFID

Introduction

ExFlow can import documents from several sources, such as Local File System, Azure Storage or Web Services.

This page describes the ExFlow Web Service EXFID: what it does, how to set it up and which methods it offers. EXFID is a SOAP web service, so the integration can be written in any language that can send SOAP requests, for example C# or VB.NET.

Using EXFID, third-party integrators or Business Central partners can send electronic invoices to ExFlow using a standardized protocol.

General

An invoice imported into ExFlow normally consists of two files:

• An XML file with the invoice in a known structure.
• A PDF file with a presentation of the invoice.

Only one of the two files is required in some cases:

• XML only: If the Data Exchange Definition has a stylesheet (XSL), ExFlow generates the PDF from the XML.
• PDF only: If the PDF is a PDF/A-3 file with an embedded XML, for example ZUGFeRD or Factur-X, ExFlow extracts the XML and any embedded attachments from the PDF.

The import through EXFID is started by the external system, not by ExFlow or a Job Queue Entry. The external system calls EXFID in Business Central, and each call creates an Incoming Document with the files as Incoming Document Attachments. The documents are then processed when the import is run in the ExFlow Import Journal.

Business Central / ExFlow

Install ExFlow and run the Wizard to get a setup.

Import a suitable Data Exchange Definition (DED), either one from ExFlow or an existing DED in Business Central.

Web Service EXFID

Go to: ExFlow Setup --> Create / Update Default Web Services

Make sure the web services EXFID and EXFWEB exist in Web Services in Business Central. If they are missing, run Create / Update Default Web Services in ExFlow Setup.

The SOAP address of EXFID is shown in Web Services in Business Central. For Business Central online it has this format:

https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<environment>/WS/<company name>/Codeunit/EXFID

ExFlow Setup

Go to: ExFlow Setup --> OCR Import

Field	Description
Web Def. Data Exchange Type	Select the Data Exchange Type used for documents imported through EXFID. If the list is empty, run Import Data Exchange Definitions in ExFlow Setup and import one or more Data Exchange Definitions.
Web Optional Doc. XPath	Optional. The XPath in the invoice XML that points to optional attachments. Read more under Optional Attachments below.

Import Journal

Go to: ExFlow Import Journals

Create or configure an ExFlow Import Journal to process documents imported through EXFID.

To create a new ExFlow Import Journal, edit the list and set a Name and Description for the new journal. Then set Source Type to Web Service.

Process the imported documents by running Import Documents in the Import Journal, or by running Batch Import Documents.

Methods

All files are sent as Base64 encoded text. The content may also be compressed with gzip before it is Base64 encoded. ExFlow detects this and decompresses it automatically.

Method	Description
AddDocument	Sends one document. Parameters: XML file name, XML file, PDF file name, PDF file.
AddDocumentByDocumentId	Same as AddDocument, but with a Document Id. Used to connect attachments that were sent before with AddAttachment.
AddAttachment	Sends one optional attachment before the document. Returns a Document Id, which is then used in AddDocumentByDocumentId.
AddAttachmentChunk	Same as AddAttachment, but for large files sent in several parts.
AddDocumentChunk	Sends a large document in several parts.
CreateDocumentFromChunks	Creates the document from all parts sent with AddDocumentChunk.

Large Documents – Chunks

Large files can be split into several parts (chunks) and sent one at a time.

1. Call AddDocumentChunk with Chunk Id 1 and an empty Document Id. ExFlow returns a Document Id.
2. Call AddDocumentChunk for the next parts with the same Document Id and Chunk Id 2, 3, and so on. The file names (XML and PDF) are only sent with the last part.
3. Call CreateDocumentFromChunks with the Document Id. ExFlow joins the parts in Chunk Id order and creates the document.

The Base64 text is split into parts, and the parts are joined again in the same order. Parts that have not been used within one hour are deleted.

Optional Attachments

Optional attachments can be added to include more documents than the XML and PDF. There are two ways:

Embedded Attachments
Some XML formats, such as Peppol and OIOUBL, include attachments in the XML as Base64 encoded data, optionally compressed with gzip. To see how this is set up, import the Peppol or OIOUBL Data Exchange Definition. The same setup can be used for any XML format.

Pre-Sent Attachments
If the XML format does not support embedded attachments, or if embedding is technically difficult, the attachments can be sent before the document:

1. Call AddAttachment (or AddAttachmentChunk for large files) for each attachment. The first call returns a Document Id. Use the same Document Id for the next attachments.
2. Call AddDocumentByDocumentId with the same Document Id to send the XML and PDF.

All attachments sent with that Document Id are added to the Incoming Document. If Web Optional Doc. XPath is set in ExFlow Setup, only the attachments whose file name is found at that XPath in the invoice XML are added. If the value at the XPath is a URL, ExFlow downloads the file from that URL instead.

Attachments that have not been used within one hour are deleted.

Authentication

OAuth

From ExFlow 19.2, EXFID supports OAuth authentication (service-to-service). This is required for Business Central online.

1. Register an application in Azure
Go to: Azure Portal --> Microsoft Entra ID --> App registrations

1. Register a new application, give it a name and select the relevant account type.
2. Copy the Application (client) ID. It is needed in Business Central and in the integration.
3. Create a client secret (or certificate) for the integration.
4. Under API permissions, add Dynamics 365 Business Central --> Application permissions --> API.ReadWrite.All.
5. Click Grant admin consent. This requires a Global Administrator, or a user with permission to grant admin consent.

2. Create the Microsoft Entra Application in Business Central
Go to: Microsoft Entra Applications

1. Create a new card and enter the Client ID from the App Registration.
2. Add a relevant description and set State to Enabled.
3. Under User Permission Sets, add the permission set EX WEB SERVICE. Leave the Company field blank so that it applies to all companies.
4. Click Grant Consent.

The integration can now get an access token from Microsoft Entra ID (client credentials flow, scope https://api.businesscentral.dynamics.com/.default) and call EXFID with it.

Web Service Access Key

A Web Service Access Key can only be used with Business Central on-premises or a local container. Business Central online does not support Web Service Access Keys.

Open the user card in Business Central and create a Web Service Access Key. Use the user name and the key as credentials in the integration.