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

Caution: By installing the Perk connector as an extension, you must be aware that they will not receive automatic updates with any new features. You will be responsible for installing and managing any updates of the Perk connector.

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

To set up the connector for Business Central On Premises:

1. Install the extension.
2. Set up Business Central for Microsoft Entra.
3. Configure the connector in Business Central.
4. Set up export in Perk:
   1. expense export
   2. invoice export
5. Synchronize master and transactional data.

Caution: The on-premises edition of Business Central may be hosted on private web servers with restricted access to and from unsecured networks. Make sure that the security policies do not prevent traffic exchanges between Perk and the Business Central tenant’s services. 
In other words, firewall rules, port forwarding rules, and secure network gateways must set up to allow traffic passthrough to and from Business Central On premises and Perk before proceeding to synchronize data or trigger export.

Architectural overview

To exchange data between Perk 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 Perk. After a user authenticates (i.e. signs in), the authorization server issues security tokens that the client application (i.e. the Perk 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 Perk 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, Perk can then post expenses or invoices.

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

Install the Perk connector as an extension

To install the Perk 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:

Note: ID ranges are dynamic and may be influenced by your license. 
If you are using these ID ranges, you may have to assign another one for the extension package’s objects. Otherwise, you’ll encounter conflicts.

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

Set up Business Central for Microsoft Entra

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

Caution: It is highly important that you follow the steps outlined in the Microsoft official documentation, particularly the sections Configure Business Central Server and Configure Business Central Web Server Component

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

• Application (Client) ID: Also referred to as the application ID or client ID, this unique identifier is assigned to your app by the identity platform. The client ID helps identify your application within the platform and is included in the security tokens issued by the platform.
• Redirect URI: The redirect URI specifies where the authorization server should send the user-agent (e.g., a web browser or mobile app) after completing the authentication process. For example, after the user signs in, the authorization server redirects them to the specified URI. Note that not all client types require a redirect URI.

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

Register an application on the MS Azure portal

First you need to register an app on the MS Azure portal for the Perk 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:

• Name of the app: Perk Business Central connector
• Application (client ID): Copy this ID, you’ll need it later.

Authentication tab:

Click + Add a platform.

1. Select Web.
2. Enter Redirect URIs:
   • https://<servername_or_ipaddress>/BC230/SignIn
   • https://<servername_or_ipaddress>/BC230/auth-response
   • https://<servername_or_ipaddress>/BC230/OAuthLanding.htm
   • https://test.yokoy.ai/oauth2/callback (test) or https://app.yokoy.ai/oauth2/callback (prod)
3. Click Save.

Tip: To add several redirect URIs, you need to add one and click Save. Then you can add the second one in the main screen.

API permissions section:

1. Click + Add a permission.
2. Select Dynamics 365 Business Central.
3. In Delegated permissions, select and add permissions:
   • user_impersonation
   • Financials.ReadWrite.All
4. In Application permissions, select and add permissions:
   • app_access
   • AdminCenter.ReadWrite.All
   • API.ReadWrite.All
5. Click Grant admin consent for…

Certificates & Secrets section:

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

Publish the web service in Business Central

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

Create the application

You need to create a new application in Business Central:

1. Create a new application card.
2. Enter the Application ID (created in the Overview section in the Azure portal) in Client ID.
3. Enter Perk for Business Central in the Description.
4. Under “State”, select Enabled

Assign user permissions 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 Perk 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.

Configure web services

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

To do this:

1. Go to Web Services.
2. Click + New to create a new object.
3. Select the Codeunit object type.
4. Search for the object IDs depending on the module you want to implement:
   • Expense processing: Import Expencies YKY (63807)
   • Invoice processing: Webhooks YKY (63806)
5. Enter a unique service name (i.e. Invoice processing or Expense processing). Make sure that the Published checkbox is selected.

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

Set up the expense export in Perk

Perk 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.

Caution: You can’t use the Perk connector to export per diems/mileage separately.

To do this:

1. Go to Settings > Integrations.
2. Select the Expense export card.
3. Choose Business Central [API] as the ERP system.
4. Enter the authentication credentials:
   • Azure Directory ID: Business Central tenant ID
   • Client ID: MS Azure portal client ID created previously
   • Client secret: MS Azure portal client secret created previously
5. Click Sign in with Business Central.

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.

Caution: Make sure to select the correct ERP system! Ms Dynamics Cloud & MS Dynamic OnPrem are the export facilities for another MS Dynamics Business Central connector, not the Perk-developed connector.

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

Warning: The expense export setting Exclude cost objects from export is not compatible with this integration.  The Perk integration for MS Dynamics 365 Business Central always expects a cost object when exporting expenses.

Set up the invoice export in Perk

To process invoices with Business Central, Perk uses webhooks to notify Business Central about changes in the document status. There is a specific invoice export facility in Perk 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 Perk, you need to set up the integration in Perk:

1. Go to Settings > Integrations.
2. Select the Invoice exports card.
3. Enter these details:
   • Export name: Business Central Invoices
   • Document type: Supplier invoices
4. In System tab, select Business Central Integration.
5. In Configuration tab, enter the data used to form the URL to access the Business Central API. You need to enter this data:

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

Warning: If you try to set up multiple export facilities (i.e. the Perk connector together with existing integrations), you may encounter the error Validation: Multiple export facilities applicable when you try to export an invoice. You can only have one export facility active at a time.

Tip: Next step: Set up and synchronize master and transactional data.