How to: Business Central & OData v4

Dynamicweb allows for data integration with Dynamics365 Business Central through dedicated OData V4 endpoints.

The following guide explains how to set up OData V4 integration between Business Central and Dynamicweb.

An OData V4 integration utilizes Business Central web services that expose singular Business Central pages (i.e. items, contacts etc.)

This means that unlike the API where multiple entities are exposed in a single web service, the OData V4-way of working revolves around having a web service for each object type (or page in Business Central).

This practice is considered anti-pattern by Microsoft though, and pulling data from the API is much faster in terms of perfomance, so why use it?

The short answer is that the Business Central API has some gaps in terms of missing entities and custom fields, and that it is currently not possible to make up for these gaps for instance with custom extensions af the API. Having each page exposed as an OData v4 web service makes up for this by allowing exposure of custom fields.

Another aspect of the OData v4 approach is that it allows Dynamicweb users to configure an ERP integration that requires no logic on the external system. Essentially, the OData v4 concept of Dynamicweb is designed to have zero footprint on the ERP and require no AL-developer expertise.

First and foremost, an OData v4 import to Dynamicweb requires that the relevant data is exposed through a Business Central web service. To so, follow these steps:

• Open the Web Services list in Business Central and click New
• Set the object type field to Page
• Select the relevant Object ID to expose - please refer to the Order of imports table below for the full list of supported Object IDs.
• Give the web service a suitable name 
• Check the published checkbox

The first step required in OData integration is setting up the relevant endpoints in Settings > Integration > Endpoint Management > Add endpoint.

Specific endpoints for each object type must be set up, but for the sake of simplicity, this guide continues with the endpoint for importing products as an example.

For a more detailed guide on importing each specific object type, click here.

To add an endpoint, follow these steps:

• Provide the endpoint with a Name and an optional Description
• Insert OData v4 URL from Business Central Web Services
• Set Type to GET
• Choose Endpoint Authentication at the bottom of the page (see next section)
• Save and close

Figure 4.1 Adding an endpoint in Endpoint management

Scroll to the bottom of the page to choose the endpoint authentication.

Figure 4.2 Choosing endpoint authentication at the bottom of the "Add endpoint" page.

Please notice that cloud instances of Business Central requires the use of OAuth 2.0 to authenticate endpoint interactions. 

If you are establishing an integration activity between a locally hosted Business Central environment or a sandbox environment you can make do with a simpler authentication such as a WebServiceAccesKey.

Endpoint authentications can be managed in Settings > Integration > Endpoint Management.

When using OData integration, you might not be interested in importing every record of a given object type.

To filter in the imported data, you can add one or more query parameters to the endpoint.

A query parameter consists of a key and a value such as the examples in the table below.

Once a query parameter has been added to the endpoint and the endpoint itself has been saved, the full URL (including the added query parameter) will be visible in the endpoint editor.

There are many more ways to filter the OData provided by the endpoint.  A complete documentation for OData filter expressions can be found here:

When the endpoint has been set up, the next step is to add an integration activity in Settings > Integration > Data Integration > New Activity.

• For the Source setting choose Type: “Endpoint provider”.
• Select the "OData v4 - Business Central" as the Endpoint Type.
• Select the predefined endpoint from the dropdown menu.
• Select the desired Mode under Advanced activity settings. Please refer to the endpoint provider article for an elaboration on the modes.
• Click next.

• For the Target setting choose Type: “OData provider”.
• Select the desired Object Type from the dropdown menu in Parameters > destination > object type.
• Depending on the chosen object type more specific Object type settings may be available. For a more detailed documentation on the required settings for the specific object type imports. Click here.
• Click next.
• Select the source table to import from. The mapping to the target table will be auto selected by Dynamicweb.
• Click finish.
• Finally, provide the activity with a name and an optional description and click OK.

When the activity has been added, the settings menu for the activity depicted below will be visible. This menu can be accessed at any time by clicking the activity in Settings > Integration > Data Integration.

In this view the table mappings of the activity can be managed. The mappings are auto selected for all non-custom activities in Dynamicweb.

For a detailed overview of the many features of integration activities please refer to the documentation of the data integration module.

To finish the activity setup, press save and close or save and run to perform the import job immediately.

To make sure all imported data is stored with the correct relations in the Dynamicweb database, the import activities should be run in the following order:

You can click each object type to acces specific documentation on each of them.

Please note that while the object types of country and currency do appear first in the order list, it might not be necesarry to run them as actual OData import jobs. Simply adding them manually in Dynamicweb may suffice while also preventing unnecessary country records of the ERP from being imported.

The first step in exporting data with the OData provider is setting up the endpoint in:

Settings > Integration > Endpoint management > Add Endpoint.

Specific endpoints for each object type must be set up, but for the sake of simplicity, this guide continues with the endpoint for exporting customers as an example.

For a more detailed guide on importing each specific object type, click here.

• Provide the endpoint with a Name and an optional Description.
• Insert OData v4 URL from Business Central Web Services
• Set Type to POST
• Choose Endpoint Authentication at the bottom of the page.*
• Save and close

*An endpoint authentication can either be a WebServiceAccesKey or OAuth. Endpoint authentications can be managed in Settings > Integration > Endpoint Management.

To make sure all exported data is stored with the correct relations in Business Central, the export activities should be run in the following order:

When the endpoint has been set up, the next step is to add an integration activity in Settings > Integration > Data Integration > New Activity.

• For the Source setting choose Type: “OData provider”.
• Select the relevant object type under parameters > source object type.
• Depending on the chosen object type more specific Object type settings may be available. For a more detailed documentation on the required settings for the specific object type imports. Click here.
• For the Target setting choose Type: “Endpoint provider”.
• Select the destination endpoint from the dropdown menu.
• Click next.
• Select the source table to export. The mapping to the target table will be auto selected by Dynamicweb.
• Click finish.
• Finally, provide the activity with an optional description and click OK.

When the activity has been added, the settings menu for the activity depicted below will be visible. This menu can be accessed at any time by clicking the activity in Settings > Integration > Data Integration.

In this view the table mappings of the activity can be managed. The mappings are auto selected for all non-custom activities in Dynamicweb.

To finish the activity setup, press save and close or save and run to perform the import job immediately.