Install the Yokoy connector in Business Central On Premises

For Microsoft Dynamics 365 Business Central On-Premise implementations, you install the Yokoy Spend Management Connector as an extension.

The extension needs to be registered and configured with Microsoft Entra to allow Yokoy access to the Business Central API endpoints.

To set up the connector for Business Central On Premises:

To exchange data between Yokoy and Microsoft Dynamics 365 Business Central, the application uses OAuth 2.0 authentication and authorization to secure data transfer.

The Microsoft Entra is used as the identity provider (IdP). It securely manages user information, access rights, and the trust relationships between Business Central and Yokoy. After a user authenticates (i.e. signs in), the authorization server issues security tokens that the client application (i.e. the Yokoy web app) uses to grant, deny, or revoke access to the Business Central API (authorization). Once the client application has valid bearer tokens (access, ID and refresh), it can access the data in Business Central and perform operations such as create, update, or delete. In other words, when the Yokoy app makes API calls to Business Central, the extension verifies the access tokens provided and determines whether to allow or deny access to the requested resources. If allowed access, Yokoy can then post expenses or invoices.

Therefore, you need to set up Microsoft Entra to recognize the client app (Yokoy) and issue security tokens.

To install the Yokoy connector as an extension, you need to have access to the connector package (.app). You must open a service request to obtain access to the connector package.

Once you have access to this file, you can proceed to install the app using the Extension Management page.

The extension package uses these ID ranges for the objects listed below:

Extensions may be uninstalled automatically after a Business Central update without data loss. See Uninstalling the extension.

Once you have installed the extension, you need to register and configure it in Microsoft Entra to allow Yokoy access to the Business Central API endpoints. You also need to configure the app permissions.

To trust the security tokens issued by Microsoft Entra, you must register your app. During registration, the platform assigns key values, such as:

App registration also provides the authentication and authorization endpoints needed to obtain ID and access tokens.

First you need to register an app on the MS Azure portal for the Yokoy connector.
See Register an app in the Microsoft identity platform for guidance.

Create the basic definition of the application by configuring the Overview, Authentication, Certificates & secrets, and API permission sections.

Overview section:

Authentication tab:

Click + Add a platform.

API permissions section:

Certificates & Secrets section:

Create a new client secret. We recommend you set the expiry as 24 months. Copy the Value and Secret ID.

Enter “Microsoft Entra Applications” in the Business Central global search tool (top right corner) to access the application setup.

You need to create a new application in Business Central:

You need to set up the application so it has super admin permissions.

More specifically, you need to add these permission sets in the User Groups section in the Microsoft Entra Application card you’ve just created.

Once the initial installation has been completed, standard users need the Yokoy BC permission set (PERMISSIONSET YKY) to make any subsequent changes to the integration and synchronize data.

In addition, you need to determine the ID range on which new objects can be created (e.g. 50000 to 55000).

Since the ID range used for custom developments may vary, it is important to specify this range as the installation package will overwrite any existing objects that are assigned the same ID range. See Install the connector as an extension for a list of the ID ranges used in the extension by default.

You need to add the web services in the Business Central for each module you plan to integrate (i.e. one web service for Yokoy Invoice and another for Yokoy Expense).

To do this:

Once you have done this, you should configure the Yokoy Integrations Setup page in Business Central before continuing to set up the expense or invoice export in Yokoy.

Yokoy is responsible for exporting the expense data to the general ledger in Business Central. Expense receipts and attachments can be attached to journal entries as required.

If the company plans to process credit notes, you need to have enabled credit notes for the legal entity.

You need to set up the Expense export tab (Admin > Integrations, Expense export) to send expense data (expense, card transaction, travel expenses) to Business Central.

To do this:

Make sure to disable any popup blockers in your browser window. MS Dynamics authentication uses a popup window to make the authentication request to MS Entra.

Once connection has been established, you can configure the export settings:

To process invoices with Business Central, Yokoy uses webhooks to notify Business Central about changes in the document status. There is a specific invoice export facility in Yokoy to handle the webhook response. Currently, the webhooks are synchronous. This means that the provider must wait until the webhook has finished processing to get a response.

To allow Business Central to connect to Yokoy, you need to set up the integration in Yokoy:

You need to do this for each legal entity that you want to link to a Business Central company.