For Microsoft Dynamics 365 Business Central Cloud implementations, you can choose to install the Perk Spend Management Connector from the AppSource or 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 Cloud:

1. Install the extension either from the AppSource or as an extension.
2. Set up the web service in Business Central Cloud.
3. Configure the connector in Business Central.
4. Set up export in Perk:
   • expense export
   • invoice export
5. Synchronize master and transactional data.

Install the Perk connector from Microsoft 365 Dynamics App Source

To install the Perk connector, search for the extension in the AppSource by typing Perk and click Get it now.

This installs the extension in your Microsoft 365 Dynamics Business Central tenant.

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 the customer’s license. 
If the customer is 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 the web service in Business Central for Cloud

Since Business Central is responsible for retrieving data from Perk, you need to create the web service in Business Central to handle this process.

1. Register an application on the MS Azure portal.
2. Publish the web service on the Web service page in Business Central.
3. Assign the appropriate permissions in Business Central.

Caution: Make sure to disable sandbox refresh if you are installing the extension on a test environment. Otherwise, you will need to re-configure the extension after every refresh.

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://businesscentral.dynamics.com/OAuthLanding.htm
   • https://businesscentral.dynamics.com/
   • https://test.yokoy.ai/oauth2/callback (Perk test) or https://app.yokoy.ai/oauth2/callback (Perk 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.

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

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 (3110567)
   • Invoice processing: Webhooks YKY (3110566)
5. Enter a unique service name (i.e. Invoice processing or Expense processing). Make sure that the Published checkbox is selected.

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. 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 integration 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:

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 export card.
3. In the Invoice exports tab, click Start Wizard.
4. Enter these details:
   • Export name: Business Central Invoices
   • Document type: Supplier invoices
5. In System tab, select Business Central Integration.
6. 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.