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:
- Countries/Regions
- Currencies
- Employees
- Customers
- Contacts
- Vendors
- Locations
- Item Categories
- Items
- Item variants
- Units of measure
The blueprint also includes a separate activity group for exporting the following list of entities:
- Countries/Regions
- Currencies
- Employees
- Customers
- Contacts
- Manufacturers
- Stock Locations
- Products
- Product variants
- Product variant options (unitsOfMeasure)
- 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.
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:
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
Countries/Regions
Manual configuration:
- Select predefined source endpoint
- Select destination language
| countriesRegions | EcomCountries | Script |
|---|---|---|
| Code | CountryCode2 |
Currencies
Manual configuration:
- Select predefined source endpoint
- Select destination language
| currencies | EcomCurrencies | Script |
|---|---|---|
| Code | CurrencyCode | |
| displayName | CurrencyName |
Employees
Manual configuration:
- Select predefined source endpoint
- Select destination user group
| employees | AccessUser |
|---|---|
| addressLine1 | AccessUserAddress |
| addressLine2 | AccessUserAddress2 |
| City | AccessUserCity |
| Country | AccessUserCountryCode |
| displayName | AccessUserName |
| employmentDate | AccessUserValidFrom |
| givenName | AccessUserFirstName |
| jobTitle | AccessUserJobTitle |
| middleName | AccessUserMiddleName |
| mobilePhone | AccessUserMobile |
| Number | AccessUserExternalId |
| personalEmail | AccessUserEmail |
| phoneNumber | AccessUserPhone |
| postalCode | AccessUserZip |
| State | AccessUserState |
| Surname | AccessUserLastName |
| personalEmail | AccessUserUserName |
| terminationDate | AccessUserValidTo |
Customers
Manual configuration:
- Select predefined source endpoint
- Select destination user group
| Customers | AccessUser |
|---|---|
| AccessUserUserName | |
| AccessUserEmail | |
| number | AccessUserExternalId |
| displayName | AccessUserName |
| addressLine1 | AccessUserAddress |
| addressLine2 | AccessUserAddress2 |
| country | AccessUserCountryCode |
| postalCode | AccessUserZip |
| city | AccessUserCity |
| phoneNumber | AccessUserPhone |
| number | AccessUserCustomerNumber |
Conditional: salesPersonCode DifferentFrom ''
| Customers | AccessUserAddress | Script |
|---|---|---|
| addressLine1 | AccessUserAddressAddress | |
| addressLine2 | AccessUserAddressAddress2 | |
| City | AccessUserAddressCity | |
| Country | AccessUserAddressCountryCode | |
| displayName | AccessUserAddressName | |
| AccessUserAddressEmail | ||
| Id | AccessUserAddressUId | |
| Number | AccessUserAddressCustomerNumber | |
| phoneNumber | AccessUserAddressPhone | |
| postalCode | AccessUserAddressZip | |
| salesPersonCode | AccessUserAddressUserId | |
| State | AccessUserAddressState | |
| displayName | AccessUserAddressCallName | |
| AccessUserAddressIsDefault | Constant=False | |
| AccessUserAddressType | Constant=False | |
| displayName | AccessUserAddressCompany |
Conditional: salesPersonCode DifferentFrom ''
| Customers | AccessUserSecondaryRelation |
|---|---|
| salesPersonCode | AccessUserSecondaryRelationUserId |
| Number | AccessUserSecondaryRelationSecondaryUserId |
Contacts
Manual configuration:
- Select predefined source endpoint
- Select destination user group
Conditional: type EqualTo 'Person'
| Contacts | AccessUser |
|---|---|
| AccessUserUserName | |
| AccessUserEmail | |
| Number | AccessUserExternalId |
| companyNumber | AccessUserCustomerNumber |
| companyName | AccessUserCompany |
| displayName | AccessUserName |
| addressLine1 | AccessUserAddress |
| addressLine2 | AccessUserAddress2 |
| Country | AccessUserCountryCode |
| postalCode | AccessUserZip |
| City | AccessUserCity |
| phoneNumber | AccessUserPhone |
| mobilePhoneNumber | AccessUserMobile |
Conditional: type EqualTo 'Company'
| Contacts | AccessUserAddress | Script |
|---|---|---|
| addressLine1 | AccessUserAddressAddress | |
| addressLine2 | AccessUserAddressAddress2 | |
| City | AccessUserAddressCity | |
| companyName | AccessUserAddressCompany | |
| Country | AccessUserAddressCountryCode | |
| displayName | AccessUserAddressName | |
| AccessUserAddressEmail | ||
| mobilePhoneNumber | AccessUserAddressCell | |
| Number | AccessUserAddressUserId | |
| phoneNumber | AccessUserAddressPhone | |
| postalCode | AccessUserAddressZip | |
| state | AccessUserAddressState | |
| AccessUserAddressIsDefault | Constant=True | |
| AccessUserAddressType | Constant=False |
Conditionals:
- type EqualTo 'Person'
- displayName DifferentFrom ''
- companyName DifferentFrom ''
| Contacts | AccessUserSecondaryRelation |
|---|---|
| companyNumber | AccessUserSecondaryRelationSecondaryUserId |
| number | AccessUserSecondaryRelationUserId |
Vendors
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| Vendors | EcomManufacturers |
|---|---|
| Number | ManufacturerId |
| displayName | ManufacturerName |
| addressLine1 | ManufacturerAddress |
| postalCode | ManufacturerZipCode |
| City | ManufacturerCity |
| Country | ManufacturerCountry |
| phoneNumber | ManufacturerPhone |
| ManufacturerEmail | |
| Website | ManufacturerWeb |
Locations
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| Locations | EcomStockLocation |
|---|---|
| Code | StockLocationName |
| displayName | StockLocationDescription |
Item Categories
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| itemCategories | EcomGroups | Script |
|---|---|---|
| Code | GroupId | |
| displayName | GroupName | |
| GroupDescription | Constant=’BC IMPORT’ |
Items
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| Items | EcomProducts |
|---|---|
| Number | ProductId |
| Number | ProductNumber |
| displayName | ProductName |
| gtin | ProductEAN |
| unitPrice | ProductPrice |
| unitCost | ProductCost |
| baseUnitOfMeasureCode | ProductDefaultUnitId |
| itemCategoryCode | Groups |
Item variants
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| itemVariants | EcomVariantGroups |
|---|---|
| itemNumber | VariantGroupId |
| Constant: "True" | VariantGroupFamily |
| itemNumber | VariantGroupName |
| Constant: "ERP Variant" | VariantGroupLabel |
| itemVariants | EcomVariantsOptions |
|---|---|
| id | VariantOptionId |
| itemNumber | VariantOptionGroupId |
| code | VariantOptionName |
| itemVariants | EcomVariantOptionsProductRelation |
|---|---|
| itemNumber | VariantOptionsProductRelationProductId |
| id | VariantOptionsProductRelationVariantId |
| itemVariants | EcomProducts |
|---|---|
| id | ProductVariantId |
| itemNumber | VariantGroups |
| id | VariantOptions |
| ItemNumber | ProductNumber |
| itemNumber | ProductId |
| Code | ProductName |
| description | ProductShortDescription |
Units of measure
Manual configuration:
- Select predefined source endpoint
- Select destination language
- Select destination shop
| unitsOfMeasure | EcomVariantOptions |
|---|---|
| code | VariantOptionId |
| displayName | VariantOptionName |
Exports
Export countries
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
| EcomCountries | countriesRegions |
|---|---|
| CountryCode2 | code |
Export currencies
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
| EcomCurrencies | currencies |
|---|---|
| CurrencyCode | code |
| CurrencyName | displayName |
Export AccessUsers (employees)
Manual configuration
Source settings: Select user group to export from Destination settings: Select predefined destination endpoint
Predefined mappings
| AccessUser | employees |
|---|---|
| AccessUserAddress | addressLine1 |
| AccessUserAddress2 | addressLine2 |
| AccessUserCity | city |
| AccessUserCountryCode | country |
| AccessUserEmail | personalEmail |
| AccessUserExternalId | number |
| AccessUserFirstName | givenName |
| AccessUserJobTitle | jobTitle |
| AccessUserLastName | surname |
| AccessUserMiddleName | middleName |
| AccessUserMobile | mobilePhone |
| AccessUserPhone | phoneNumber |
| AccessUserState | state |
| AccessUserZip | postalCode |
Export AccessUsers (contacts)
Manual configuration
Source settings: Select user group to export from Destination settings: Select predefined destination endpoint
Predefined mappings
| AccessUser | contacts | Notes |
|---|---|---|
| Type | Constant: 'Person' | |
| AccessUserAddress | addressLine1 | |
| AccessUserAddress2 | addressLine2 | |
| AccessUserCity | city | |
| AccessUserCompany | companyName | |
| AccessUserCountryCode | country | |
| AccessUserCustomerNumber | companyNumber | |
| AccessUserEmail | ||
| AccessUserExternalId | number | |
| AccessUserMobile | mobilePhoneNumber | |
| AccessUserName | displayName | |
| AccessUserPhone | phoneNumber | |
| AccessUserZip | postalCode |
Export AccessUsers (customers)
Manual configuration
Source settings: Select user group to export from Destination settings: Select predefined destination endpoint
Predefined mappings
Conditional: AccessUserName DifferentFrom ''
| AccessUser | customers |
|---|---|
| AccessUserAddress | addressLine1 |
| AccessUserAddress2 | addressLine2 |
| AccessUserCity | city |
| AccessUserCountryCode | country |
| AccessUserEmail | |
| AccessUserExternalId | number |
| AccessUserName | displayName |
| AccessUserPhone | phoneNumber |
| AccessUserZip | postalCode |
Export manufacturers
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
| EcomManufacturers | vendors |
|---|---|
| ManufacturerAddress | addressLine1 |
| ManufacturerCity | city |
| ManufacturerCountry | country |
| ManufacturerEmail | |
| ManufacturerId | number |
| ManufacturerName | displayName |
| ManufacturerPhone | phoneNumber |
| ManufacturerWeb | website |
| ManufacturerZipCode | postalCode |
Export Stock locations
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
| EcomStockLocation | locations |
|---|---|
| StockLocationName | code |
| StockLocationDescription | displayName |
Export Product Categories (EcomGroups)
Export Products
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
Conditional: ProductVariantId DifferentFrom ''
| EcomProducts | items | Notes |
|---|---|---|
| PrimaryGroup | itemCategoryCode | |
| ProductCost | unitCost | Format culture: Default |
| ProductDefaultUnitId | baseUnitOfMeasureCode | |
| ProductEAN | gtin | |
| ProductId | number | |
| ProductName | displayName | |
| ProductPrice | unitPrice | Format culture: Default |
Export product variants
TBD
Export units of measure
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings
| EcomVariantsOptions | unitsOfMeasure |
|---|---|
| VariantOptionId | code |
| VariantOptionName | displayName |
Export Orders
Manual configuration
Destination settings: Select predefined destination endpoint
Predefined mappings - Sales Orders + Sales Order Lines
| EcomOrders | salesOrders |
|---|---|
| OrderCurrencyCode | currencyCode |
| OrderCustomerNumber | billToCustomerNumber |
| OrderDeliveryAddress | sellToAddressLine1 |
| OrderDeliveryAddress2 | sellToAddressLine2 |
| OrderDeliveryCity | sellToCity |
| OrderDeliveryCountryCode | sellToCountry |
| OrderDeliveryZip | sellToPostCode |
| OrderDiscountAmount | discountAmount |
| OrderIntegrationOrderId | id |
| EcomOrderLines | salesOrderLines |
|---|---|
| OrderIntegrationOrderId | documentId |
| OrderLineDiscountPercentage | discountPercent |
| OrderLineProductName | description |
| OrderLineQuantity | quantity |
| OrderLineUnitId | unitOfMeasureCode |
| OrderLineProductVariantId | itemVariantId |
| OrderLineUnitPrice | unitPrice |
| OrderLineUnitId | unitOfMeasureId |
| OrderLineProductNumber | lineObjectNumber |