MicrosoftBusinessCentralV2 - CustomerUpdate
This document details the Customer Update pipeline for the Microsoft Business Central V2 connector. This process synchronizes customer data, including core customer information, addresses, and contact persons, from Microsoft Business Central into the App4Sales platform. It also handles price list linking, payment conditions, and dynamic free fields.
Data Source Configuration
Customer, Address, and Contact data are retrieved from the Microsoft Business Central V2 API. The connector queries various endpoints to collect comprehensive customer-related information.
Customer Core Fields
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerCode | MbcCustomer.number | Direct mapping. |
CustomerName | MbcCustomer.displayName | Direct mapping. |
VatLiable | MbcCustomer.taxLiable | Direct mapping. |
VatCode | MbcCustomer.vatNo | Direct mapping. |
Phone | MbcCustomer.phoneNumber | Direct mapping. |
MbcCustomer.email | Direct mapping. | |
PaymentConditionCode | MbcCustomer.paymentTermsCode / MbcCustomer.paymentMethodCode | If the setting "Use payment terms as payment conditions" is enabled, maps from |
LanguageCode | MbcCustomer.languageCode | Mapped via |
InternalCode | MbcCustomer.SystemId | Maps to the unique system ID of the customer in Business Central. |
Fax | MbcCustomer.faxNo | Direct mapping. |
Currency | MbcCustomer.currencyCode | If |
Website | MbcCustomer.homePage | Direct mapping. |
CustomerNote | MbcCustomer.comment | Direct mapping. |
CustomerManager | MbcCustomer.salesPersonCode | Direct mapping. |
DiscountGroup | MbcCustomer.customerDiscGroup | Direct mapping. |
UsesPriceField | Derived (PriceGroup, DiscountGroupCode, CustomerCode) | Determined by an existing linked price list ID for the customer. If no existing link, it's generated based on |
Addresses
Customer addresses are synchronized from two sources:
A primary "Visit" address derived directly from the main customer record.
Additional "Delivery" addresses retrieved from specific address entities in Business Central.
Visit Address Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
AddressLine1 | MbcCustomer.addressFirst | Direct mapping. |
AddressLine2 | MbcCustomer.addressSecond | Direct mapping. |
Country | MbcCustomer.regionCode | Resolved from ISO2 country code using culture provider. |
City | MbcCustomer.addressCity | Direct mapping. |
PostCode | MbcCustomer.postCode | Direct mapping. |
State | MbcCustomer.addressCounty | Direct mapping. |
IsMainAddress | Hardcoded | Always |
AddressType | Hardcoded | Always |
Iso2 | MbcCustomer.regionCode | Direct mapping. |
AddressId | MbcCustomer.customerCode | Uses the customer code as the address ID. |
Delivery Address Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
AddressLine1 | MbcAddress.addressLineFirst | Direct mapping. |
AddressLine2 | MbcAddress.addressLineSecond | Direct mapping. |
AddressLine3 | MbcAddress.Code | Uses the address code as AddressLine3. |
AddressType | Hardcoded | Always |
PostCode | MbcAddress.postCode | Direct mapping. |
City | MbcAddress.city | Direct mapping. |
State | MbcAddress.county | Direct mapping. |
Country | MbcAddress.countryRegionCode | Resolved from ISO2 country code using culture provider. |
Phone | MbcAddress.phoneNo | Direct mapping. |
Fax | MbcAddress.fax | Direct mapping. |
MbcAddress.email | Direct mapping. | |
Iso2 | MbcAddress.countryRegionCode | Direct mapping. |
AddressId | MbcAddress.Code | Direct mapping. |
ExternalId | MbcAddress.Code | Direct mapping. |
IsMainAddress | MbcAddress.Code, MbcCustomer.ShipToCode |
|
Contacts
Contact persons associated with a customer are synchronized. The primary contact person for a customer is identified based on MbcCustomer.primaryContactNo.
Contact Person Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
ContactId | MbcContact.no | Direct mapping. |
FirstName | MbcContact.firstName / MbcContact.fullName | If |
LastName | MbcContact.lastName / MbcContact.fullName | If |
MiddleName | MbcContact.middleName / MbcContact.fullName | If |
FullName | MbcContact.fullName | Direct mapping. |
MobileNumber | MbcContact.mobilePhoneNo | Direct mapping. |
MbcContact.email | Direct mapping. | |
Phonenumber | MbcContact.phoneNo | Direct mapping. |
IsMainContactPerson | MbcCustomer.primaryContactNo, MbcContact.no |
|
Dynamic Free Fields
The connector captures specific extra data from Business Central and stores it as dynamic free fields in App4Sales.
App4Sales Field (Key) | Source Field (API/Excel/DB) | Logic/Notes |
VATBusPostingGroup | MbcCustomer.vatBusPostingGroup | Stored as a key-value pair within the serialized DynamicFreeFields XML. |
Special Logic & Filters
Price List Generation and Linking
The system generates price lists and links them to customers based on their currency, price group, and discount group.
Price List ID Generation: A unique ID and code for a price list are generated by hashing a combination of the customer's currency code, price group, and discount group code (e.g., "EUR - RETAIL - GOLD"). For customer-specific price lists, the customer code is used (e.g., "Customer - CUST001").
Price Collection: Prices are collected from various sources within Business Central:
Default prices (for all customers).
Customer-specific prices.
Prices based on the customer's price group.
Prices based on the customer's discount group.
Price Calculation: For each item, the system considers all applicable price list lines (price and discount) based on quantity and selects the combination that results in the minimum price. If only discounts are present, the maximum discount is applied to the item's unit price.
Tier Prices: For quantities greater than one, tier prices (
StafflePrice) are created if specific quantity-based prices or discounts are found.Price Normalization: Prices from Business Central are filtered for active dates and valid items. Item discount groups are "exploded" into individual item prices. Minimum quantities are ensured to be at least 1. Specific adjustments are made for price group and discount group price types.
Language Synchronization
The connector synchronizes languages from Business Central to ensure correct language mapping within App4Sales. If no languages are found in Business Central, existing mapped languages in App4Sales are used.
Payment Condition Updates
Payment conditions are updated based on customer data. The choice between using Business Central's "Payment Terms" or "Payment Methods" as App4Sales payment conditions depends on the Use payment terms as payment conditions connector setting.
Domain Specifics
Customer Core Fields
This section details the primary fields that define a customer in App4Sales, their origin in Business Central, and any transformations. It includes identity fields, financial attributes like VAT liability, and communication details. Price list selection is dynamically determined, and the currency can fallback to a base currency if not explicitly defined for the customer.
Addresses
The connector handles both a main "Visit" address, directly from the customer's primary record, and potentially multiple "Delivery" addresses from dedicated address entities in Business Central. Country codes are normalized, and the "main" delivery address is identified by matching the address code with the customer's configured ShipToCode.
Contacts
Contact persons are linked to customers. The system attempts to derive names (first, middle, last) from a full name if individual fields are not populated. A single contact is designated as the primary contact based on the primaryContactNo field from the Business Central customer record.
Extra Data & Free Fields
Beyond standard fields, the VATBusPostingGroup from Business Central is explicitly stored as a dynamic free field, allowing for flexible storage of additional ERP-specific attributes.
Discounts & Dashboards
Price list generation logic implicitly handles discounts by incorporating discount group prices. Customer dashboards, when present, are decoded and stored via the internal CustomerDataManager within the CustomerUpdateHandler. (Note: The provided code snippets do not explicitly detail notes handling within the CustomersSyncManager. Further investigation may be required if these are critical to the CustomerUpdate pipeline as per the task scope).
Known Limitations
This connector does not explicitly implement functionality for "fixed item filters" or "customer-specific item class discounts." These features are not directly synchronized from Microsoft Business Central V2 by this connector.
Related Settings & Prerequisites
The following connector settings influence the customer synchronization behavior:
Setting Name | Description |
Customers Timestamp | Used for incremental synchronization of customer data. |
Contacts Timestamp | Used for incremental synchronization of contact data. |
Order Addresses Timestamp | Used for incremental synchronization of order addresses. |
Alternative Addresses Timestamp | Used for incremental synchronization of alternative addresses. |
Standard Addresses Timestamp | Used for incremental synchronization of standard addresses. |
Ship To Addresses Timestamp | Used for incremental synchronization of ship-to addresses. |
Use payment terms as payment conditions | If enabled, payment conditions are mapped from payment terms; otherwise, from payment methods. |
Microsoft Business Central base currency code | Default currency code used if a customer's currency is not specified. |
Value of the type for companies for during the contact synchronization | Used to filter contact types when retrieving contacts from Business Central. Default value is 'Company'. |
NL customer default Gen. Bus. Posting Group | Default General Business Posting Group for customers in the Netherlands. |
EU customer default Gen. Bus. Posting Group | Default General Business Posting Group for customers in the European Union (excluding NL). |
NL customer default Customer Posting Group | Default Customer Posting Group for customers in the Netherlands. |
EU customer default Customer Posting Group | Default Customer Posting Group for customers in the European Union (excluding NL). |