Table of Contents

Business Central OData default API blueprint

Order of imports and exports

This blueprint includes activities for importing the following list of Business Central object types:

  1. Countries/Regions
  2. Currencies
  3. Employees
  4. Customers
  5. Contacts
  6. Vendors
  7. Locations
  8. Item categories
  9. Items
  10. Item variants
  11. Units of measure

The blueprint also includes a separate activity group for exporting the following list of entities:

  1. Countries/Regions
  2. Currencies
  3. Employees
  4. Customers
  5. Contacts
  6. Manufacturers
  7. Stock locations
  8. Product categories (EcomGroups)
  9. Products
  10. Product variants
  11. Product variant options (unitsOfMeasure)
  12. Orders

The activities are designed to be run in the order mentioned above - at least when they are run for the first time. This is to ensure that data is added to the database in accordance with all parent/child relations.

Language and shop mappings have been intentionally removed from all blueprints, as these configurations vary between projects depending on which IDs are created and used. Therefore, these mappings must be added manually to the relevant jobs.

Endpoint

The Business Central OData default API blueprint is configured to request a single predefined endpoint - the Business Central API endpoint, which generally looks like this:

https://api.businesscentral.dynamics.com/v2.0/[TENANT_ID]/[ENVIROMENT_NAME]/api/v2.0/companies([COMPANY_ID])

The Microsoft documentation on API endpoints provides a detailed overview of how to access this endpoint.

To start querying the default API you will need to set up an endpoint collection with a valid authentication. The recommended method authentication to use is OAuth Service-to-service (S2S) - check out our comprehensive guide, to learn how to configure an S2S authentication between DynamicWeb and Business Central.

Mappings

The following sections contain tables of all predefined mappings of the activities included in the Business Central Default API blueprint. Each section also contains the list of required manual configurations for each object type.

Imports

Description

All import jobs are configured to run using Delta replication (the Mode setting in the OData Provider).
This means that each job checks when it was last executed and uses that timestamp in the next request.
If the job is running for the first time, no date or time is applied — meaning all available data will be imported.

Countries/Regions

Description

We map the code field from Business Central to CountryCode2 in DynamicWeb and the CountryCultureInfo field is explicitly set to an empty string to accommodate a nullable column in the database and prevent data validation issues. This is the most suitable and consistent field available for creating country records.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for countriesRegions → EcomCountries

countriesRegions EcomCountries Script
code CountryCode2
CountryCultureInfo Constant=’’

Currencies

Description

We map the code field from Business Central to CurrencyCode and the displayName field to CurrencyName, as these provide the essential information needed to create currency records in DynamicWeb.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for currencies → EcomCurrencies

currencies EcomCurrencies Script
code CurrencyCode
displayName CurrencyName

Employees

Description

This import contains many mappings based on commonly used employee fields.
Note that no mappings to user groups are included — if you wish to categorize your users, you will need to either create a mapping manually or specify the group directly in the destination provider settings.
No predefined groups have been created in this blueprint, as the relevant IDs vary between projects and are therefore unknown to us.

Manual configuration

Source settings: Select Predefined endpoint Destination settings: Select Destination group (ie. the user group you wish to import to)

Predefined mappings for employees → AccessUser

employees AccessUser Script
addressLine1 AccessUserAddress
addressLine2 AccessUserAddress2
city AccessUserCity
country AccessUserCountryCode
displayName AccessUserName
employmentDate AccessUserValidFrom
givenName AccessUserFirstName
jobTitle AccessUserJobTitle
middleName AccessUserMiddleName
mobilePhone AccessUserMobile
personalEmail AccessUserEmail
phoneNumber AccessUserPhone
postalCode AccessUserZip
state AccessUserState
surname AccessUserLastName
terminationDate AccessUserValidTo
personalEmail AccessUserUserName
number AccessUserExternalId

Customers

Description

Customers → AccessUser
No mappings to user groups have been defined in this import, following the same approach as in the Employees import.
If grouping of users is required, this must be handled manually or configured in the destination provider settings.

Customers → AccessUserAddress
We have set AccessUserAddressIsDefault to False by default.
A conditional is applied so that only records containing a value in salesPersonCode are imported — this ensures that the data being processed corresponds to users already imported (based on their external ID).

Customers → AccessUserSecondaryRelation
This mapping creates impersonations using the same conditional logic as the Customers → AccessUserAddress mapping.
This ensures that only data with valid relationships is imported into DynamicWeb.

Manual configuration

Source settings: Select Predefined endpoint Destination settings: Select Destination group (ie. the user group you wish to import to)

Predefined mappings for customers → AccessUser

customers AccessUser Script
email AccessUserUserName
email AccessUserEmail
number AccessUserExternalId
displayName AccessUserName
addressLine1 AccessUserAddress
addressLine2 AccessUserAddress2
country AccessUserCountryCode
postalCode AccessUserZip
city AccessUserCity
phoneNumber AccessUserPhone
number AccessUserCustomerNumber

Predefined mappings for customers → AccessUserAddress

Conditionals:

  • salesPersonCode DifferentFrom ''
customers AccessUserAddress Script
addressLine1 AccessUserAddressAddress
addressLine2 AccessUserAddressAddress2
city AccessUserAddressCity
country AccessUserAddressCountryCode
displayName AccessUserAddressName
email AccessUserAddressEmail
number AccessUserAddressCustomerNumber
phoneNumber AccessUserAddressPhone
postalCode AccessUserAddressZip
salespersonCode AccessUserAddressUserId
state AccessUserAddressState
AccessUserAddressIsDefault Constant=False
AccessUserAddressType Constant=False
displayName AccessUserAddressCompany

Predefined mappings for customers → AccessUserSecondaryRelation

Conditionals:

  • salesPersonCode DifferentFrom ''
customers AccessUserSecondaryRelation Script
number AccessUserSecondaryRelationSecondaryUserId
salesPersonCode AccessUserSecondaryRelationUserId

Contacts

Description

Contacts → AccessUser
A conditional has been added where type = 'Person', since we are only interested in personal data — this entity also contains company information.
As with other user-related imports, no mappings to user groups have been created. If grouping is required, it must be configured manually or in the destination provider settings.

Contacts → AccessUserAddress
Here, the conditional is set to type = 'Company', as we assume that the addresses being imported represent the default company addresses for the associated users.

Contacts → AccessUserSecondaryRelation
Additional conditionals have been added to ensure cleaner data.
We exclude records where displayName and companyName are empty, and only include records where type = 'Person'.
This ensures that only valid and complete relationships are created in DynamicWeb.

Manual configuration

Source settings: Select Predefined endpoint Destination settings: Select Destination group (ie. the user group you wish to import to)

Predefined mappings for contacts → AccessUser

Conditionals:

  • type EqualTo 'Person'
contacts AccessUser Script
email AccessUserUserName
email AccessUserEmail
number AccessUserExternalId
companyNumber AccessUserCustomerNumber
companyName AccessUserCompany
displayName AccessUserName
addressLine1 AccessUserAddress
addressLine2 AccessUserAddress2
country AccessUserCountryCode
postalCode AccessUserZip
city AccessUserCity
phoneNumber AccessUserPhone
mobilePhoneNumber AccessUserMobile

Predefined mappings for contacts → AccessUserAddress

Conditionals:

  • type EqualTo 'Company'
contacts AccessUserAddress Script
addressLine1 AccessUserAddressAddress
addressLine2 AccessUserAddressAddress2
city AccessUserAddressCity
companyName AccessUserAddressCompany
country AccessUserAddressCountryCode
displayName AccessUserAddressName
email AccessUserAddressEmail
mobilePhoneNumber AccessUserAddressCell
number AccessUserAddressUserId
phoneNumber AccessUserAddressPhone
postalCode AccessUserAddressZip
state AccessUserAddressState
AccessUserAddressIsDefault Constant=True
AccessUserAddressType Constant=False

Predefined mappings for contacts → AccessUserSecondaryRelation

Conditionals:

  • type EqualTo 'Person'
  • displayName DifferentFrom ''
  • companyName DifferentFrom ''
contacts AccessUserSecondaryRelation Script
companyNumber AccessUserSecondaryRelationSecondaryUserId
number AccessUserSecondaryRelationUserId

Vendors

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for vendors → EcomManufacturers

vendors EcomManufacturers Script
number ManufacturerId
displayName ManufacturerName
addressLine1 ManufacturerAddress
postalCode ManufacturerZipCode
city ManufacturerCity
country ManufacturerCountry
phoneNumber ManufacturerPhone
email ManufacturerEmail
website ManufacturerWeb

Locations

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for locations → EcomStockLocation

locations EcomStockLocation Script
code StockLocationName
displayName StockLocationDescription

Item Categories

Description

The GroupDescription field is set as a constant with the value “BC IMPORT”.
This is done solely to help distinguish between groups that have been manually created in DynamicWeb and those imported from Business Central.
Apart from that, standard mappings have been applied based on relevant fields.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for itemCategories → EcomGroups

itemCategories EcomGroups Script
code GroupId
displayName GroupName
GroupDescription Constant=’BC IMPORT’
GroupLanguageId Constant=’LANG1’

Items

Description

In this import, both ProductVariantId and ProductExternalVariantId are added as empty constants, since this job only handles master products.
The group coming from Business Central is treated as the product’s primary group, representing the main category the product belongs to.
Furthermore, the ProductId field is only set when new products are created — this approach prevents issues with duplicate or conflicting product IDs that could occur when products are combined in DynamicWeb.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for Items → EcomProducts

Items EcomProducts Script
number ProductId
number ProductNumber
displayName ProductName
gtin ProductEAN
unitPrice ProductPrice
unitCost ProductCost
baseUnitOfMeasureCode ProductDefaultUnitId
itemCategoryCode Groups
itemCategoryCode PrimaryGroup
id ProductExternalId
blocked ProductActive Invert
ProductType Constant=0
ProductVariantId Constant=’’
ProductExternalVariantId Constant=’’
inventory ProductStock

Item variants

Description

itemVariants → EcomVariantGroups
This mapping creates the variant groups, which are structured as families in DynamicWeb.

itemVariants → EcomVariantOptions
This mapping creates the variant options associated with each variant group.

itemVariants → EcomProducts
This mapping follows the same logic as the Items import but includes the ProductVariantId and ProductExternalVariantId fields.
We have chosen to map code to ProductExternalId because id in Business Central is a GUID.
However, it’s also possible to swap these two fields — if you do, make sure to apply the same change consistently across all related mappings.

itemVariants → EcomVariantOptionsProductRelation
This mapping creates the relations between the master product and its variants, ensuring all variant structures are linked correctly in DynamicWeb.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for itemVariants → EcomVariantGroups

itemVariants EcomVariantGroups Script
itemNumber VariantGroupId
VariantGroupFamily Constant=True
description VariantGroupName
VariantGroupLabel Constant=’ERP Variant’

Predefined mappings for itemVariants → EcomVariantsOptions

itemVariants EcomVariantsOptions Script
id VariantOptionId
itemNumber VariantOptionGroupId
code VariantOptionName

Predefined mappings for itemVariants → EcomProducts

itemVariants EcomProducts Script
id ProductVariantId
itemNumber VariantGroups
id VariantOptions
itemNumber ProductNumber
itemNumber ProductId
description ProductName
itemNumber ProductExternalId
code ProductExternalVariantId

Predefined mappings for itemVariants → EcomVariantOptionsProductRelation

itemVariants EcomVariantOptionsProductRelation Script
itemNumber VariantOptionsProductRelationProductId
id VariantOptionsProductRelationVariantId

Units of measure

Description

unitsOfMeasure → EcomUnits
No special logic is applied here — standard and relevant mappings have been added as they make sense for importing unit data.

unitsOfMeasure → EcomUnitTranslations
Since DynamicWeb 10 introduced translations for units, this mapping has been included to handle multilingual unit names.
The UnitTranslationLanguageId field is currently scripted as "LANG1", but this should be updated to match the default language used in your specific solution.

Manual configuration

Source settings: Select Predefined endpoint

Predefined mappings for unitsOfMeasure → EcomUnits

unitsOfMeasure EcomUnits Script
code UnitId
id UnitExternalId

Predefined mappings for unitsOfMeasure → EcomUnitTranslations

unitsOfMeasure EcomUnitTranslations Script
code UnitTranslationUnitId
displayName UnitTranslationName
UnitTranslationLanguageId Constant=’LANG1’

Exports

Export countries

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomCountries → countriesRegions

EcomCountries countriesRegions Script
CountryCode2 code

Export currencies

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomCurrencies → currencies

EcomCurrencies currencies Script
CurrencyCode code
CurrencyName displayName

Export AccessUsers (employees)

Description

This export contains two almost identical mappings.
The first mapping includes a conditional where AccessUserExternalId is empty — this ensures that only users created directly in DynamicWeb are exported.
Additionally, a Response mapping is set up to map the returned id from Business Central back into AccessUserExternalId, maintaining a proper link between systems.
Beyond that, the mappings cover the standard employee fields required for synchronization.

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for AccessUser → employees

Conditionals:

  • AccessUserExternalId EqualTo ''
AccessUser employees Script
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCountryCode country
AccessUserEmail personalEmail
AccessUserId number
AccessUserFirstName givenName
AccessUserJobTitle jobTitle
AccessUserLastName surname
AccessUserMiddleName middleName
AccessUserMobile mobilePhone
AccessUserPhone phoneNumber
AccessUserState state
AccessUserValidFrom employmentDate
AccessUserValidTo terminationDate
AccessUserZip postalCode

Predefined mappings for AccessUser → employees

Conditionals:

  • AccessUserExternalId DifferentFrom ''
AccessUser employees Script
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCountryCode country
AccessUserEmail personalEmail
AccessUserExternalId id
AccessUserFirstName givenName
AccessUserJobTitle jobTitle
AccessUserLastName surname
AccessUserMiddleName middleName
AccessUserMobile mobilePhone
AccessUserPhone phoneNumber
AccessUserState state
AccessUserValidFrom employmentDate
AccessUserValidTo terminationDate
AccessUserZip postalCode

Export AccessUsers (contacts)

Description

The same principle applies here as in the Employees export.

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for AccessUser → contacts

Conditionals:

  • AccessUserExternalId EqualTo ''
AccessUser contacts Script
type Constant=’Person’
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCompany companyName
AccessUserCountryCode country
AccessUserCustomerNumber companyNumber
AccessUserEmail email
AccessUserId number
AccessUserMobile mobilePhoneNumber
AccessUserName displayName
AccessUserPhone phoneNumber
AccessUserZip postalCode

Predefined mappings for AccessUser → contacts

Conditionals:

  • AccessUserExternalId DifferentFrom ''
AccessUser contacts Script
type Constant=’Person’
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCompany companyName
AccessUserCountryCode country
AccessUserCustomerNumber companyNumber
AccessUserEmail email
AccessUserExternalId id
AccessUserMobile mobilePhoneNumber
AccessUserName displayName
AccessUserPhone phoneNumber
AccessUserZip postalCode

Export AccessUsers (customers)

Description

The same principle applies here as in the Employees export.
A conditional is used where AccessUserExternalId is empty — ensuring that only customers created directly in DynamicWeb are exported to Business Central.
Additionally, an extra conditional has been added to ensure that AccessUserName is not empty, since it maps to displayName, which is a required field in Business Central when using the Default API.
A Response mapping also updates AccessUserExternalId with the returned id from Business Central to maintain synchronization between systems.

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for AccessUser → customers

Conditionals:

  • AccessUserName DifferentFrom ''
  • AccessUserExternalId EqualTo ''
AccessUser customers Script
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCountryCode country
AccessUserEmail email
AccessUserId number
AccessUserName displayName
AccessUserPhone phoneNumber
AccessUserZip postalCode

Predefined mappings for AccessUser → customers

Conditionals:

  • AccessUserName DifferentFrom ''
  • AccessUserExternalId DifferentFrom ''
AccessUser customers Script
AccessUserAddress addressLine1
AccessUserAddress2 addressLine2
AccessUserCity city
AccessUserCountryCode country
AccessUserEmail email
AccessUserExternalId id
AccessUserName displayName
AccessUserPhone phoneNumber
AccessUserZip postalCode

Export manufacturers

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomManufacturers → vendors

EcomManufacturers vendors Script
ManufacturerAddress addressLine1
ManufacturerCity city
ManufacturerCountry country
ManufacturerEmail email
ManufacturerId number
ManufacturerName displayName
ManufacturerPhone phoneNumber
ManufacturerWeb website
ManufacturerZipCode postalCode

Export Stock locations

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomStockLocation → locations

EcomStockLocation locations Script
StockLocationName code
StockLocationDescription displayName

Export Product Categories (EcomGroups)

Predefined mappings for EcomGroups → itemCategories

EcomGroups itemCategories Script
GroupId code
GroupName displayName

Export Products

Description

When exporting products via the Default API, it’s important to note that translations are not supported.
Therefore, a conditional has been added to filter by ProductLanguageId, ensuring only products in the default language are exported.
Additionally, ProductVariantId and ProductExternalVariantId are left empty, as this export only handles master products, not variants.

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomProducts → items

Conditionals:

  • ProductType In '0,2'
  • ProductExternalVariantId EqualTo ''
  • ProductLanguageId EqualTo 'LANG1'
  • ProductVariantId EqualTo ''
EcomProducts items Script
PrimaryGroup itemCategoryCode
ProductCost unitCost
ProductDefaultUnitId baseUnitOfMeasureCode
ProductEAN gtin
ProductNumber number
ProductName displayName
ProductPrice unitPrice
ProductActive blocked Invert

Export product variants

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomProducts → itemVariants

Conditionals:

  • ProductExternalVariantId DifferentFrom ''
EcomProducts itemVariants Script
ProductId itemNumber
ProductExternalId code
ProductName description

Predefined mappings for EcomProducts → itemVariants

Conditionals:

  • ProductVariantId DifferentFrom ''
  • ProductExternalVariantId EqualTo ''
EcomProducts itemVariants Script
ProductId itemNumber
ProductVariantId code
ProductName description

Export units of measure

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomUnitTranslations → unitsOfMeasure

Conditionals:

  • UnitTranslationLanguageId EqualTo 'LANG1'
EcomUnitTranslations unitsOfMeasure Script
UnitTranslationName displayName
UnitTranslationUnitId code

Export Orders

Description

This export is more complex, as it contains multiple table mappings, each serving a specific purpose.

  • The first mapping exports the main order data.
    Make sure to update the Conditionals so that only orders with the appropriate status are exported — by default, it includes all Completed orders.

  • The second mapping creates an order line for the payment fee, where a Constant value is set on lineObjectNumber.
    This value must match what is defined in your Business Central environment (or the mapping can be removed if not used).

  • The third mapping works the same way as the second but covers the shipping fee.

  • The last three mappings handle the actual order lines, split by lineType:

    • Item (products)
    • Resource (fixed-price lines)
    • Charge (taxes or fees)

Ensure the Conditionals match the logic and requirements of your own Business Central setup before running the export.

Manual configuration

Destination settings: Select Destination endpoint

Predefined mappings for EcomOrders → salesOrders

Conditionals:

  • OrderComplete EqualTo True
EcomOrders salesOrders Script
OrderCurrencyCode currencyCode
OrderId externalDocumentNumber
OrderDeliveryAddress sellToAddressLine1
OrderDeliveryAddress2 sellToAddressLine2
OrderDeliveryCity sellToCity
OrderDeliveryCountryCode sellToCountry
OrderDeliveryZip sellToPostCode
OrderTotalDiscountWithoutVAT discountAmount

Predefined mappings for EcomOrders → salesOrderLines (Payment fee)

Conditionals:

  • OrderPaymentFeeWithoutVAT GreatherThan 0
  • OrderComplete EqualTo True
EcomOrders salesOrderLines Script
OrderIntegrationOrderId documentId
quantity Constant=1
lineObjectNumber Constant=’DW-PAY’
OrderPaymentFeeWithoutVAT unitPrice
lineType Constant=’Charge’

Predefined mappings for EcomOrders → salesOrderLines (Shipping fee)

Conditionals:

  • OrderShippingFeeWithoutVAT GreatherThan 0
  • OrderComplete EqualTo True
EcomOrders salesOrderLines Script
OrderIntegrationOrderId documentId
quantity Constant=1
lineObjectNumber Constant=’DW-SHIP’
OrderShippingFeeWithoutVAT unitPrice
lineType Constant=’Charge’

Predefined mappings for EcomOrderLines → salesOrderLines (Item)

Conditionals:

  • OrderLineType In '0,5,6'
EcomOrderLines salesOrderLines Script
OrderIntegrationOrderId documentId
OrderLineCalculatedDiscountPercentage discountPercent
OrderLineQuantity quantity
lineType Constant=’Item’
OrderLineUnitId unitOfMeasureCode
OrderLineProductVariantId itemVariantId
OrderLineUnitPriceWithoutVAT unitPrice
OrderLineProductNumber lineObjectNumber

Predefined mappings for EcomOrderLines → salesOrderLines (Fixed price)

Conditionals:

  • OrderLineType In '2'
EcomOrderLines salesOrderLines Script
OrderIntegrationOrderId documentId
OrderLineCalculatedDiscountPercentage discountPercent
OrderLineQuantity quantity
lineType Constant=’Resource’
OrderLineUnitId unitOfMeasureCode
OrderLineProductVariantId itemVariantId
OrderLineUnitPriceWithoutVAT unitPrice
OrderLineProductNumber lineObjectNumber

Predefined mappings for EcomOrderLines → salesOrderLines (Tax)

Conditionals:

  • OrderLineType In '4'
EcomOrderLines salesOrderLines Script
OrderIntegrationOrderId documentId
OrderLineQuantity quantity
lineType Constant=’Charge’
OrderLineUnitId unitOfMeasureCode
OrderLineProductVariantId itemVariantId
OrderLineUnitPriceWithoutVAT unitPrice
OrderLineProductNumber lineObjectNumber
To top