MicrosoftBusinessCentralV2 Connector - ItemUpdate
This document details the ItemUpdate synchronization process for the Microsoft Business Central V2 connector. This function synchronizes item data, including product details, stock information, pricing, and images, from Microsoft Business Central into the App4Sales platform. The synchronization process is initiated by the App4Sales platform and retrieves data directly from the Business Central API. It supports incremental updates, ensuring that only modified data is processed since the last synchronization.
Data Source Configuration
The Microsoft Business Central V2 connector retrieves item-related data via REST API calls to the configured Business Central environment. The base URL and environment name are configured within the connector settings. The synchronization leverages timestamps to fetch only data modified since the last sync, ensuring efficient updates.
The following Business Central entities are queried during the ItemUpdate process:
Items: Main item records, filtered to include only unblocked items.
Item Variants: Specific variants of items, used for matrix items.
Item Unit of Measures: Units of measure associated with items.
Item Categories: Categorization of items.
Item Extended Text Lines: Additional descriptive text for items.
Item Attribute Value Mappings: Attributes and their values for items.
Purchase Order Lines: Used to determine incoming stock.
Item References: Cross-references or alternative item codes.
VAT Posting Setup Entries: Tax-related information for items.
Default Dimensions: Default analytical dimensions for items.
Dimension Values: Values for the analytical dimensions.
Price List Lines: Individual price entries for items and customers.
Price List Headers: Headers for price lists.
Customers: Customer records, used for customer-specific pricing.
Item Pictures: Base64 encoded image data for items.
General Ledger Setup: Used to determine the default currency.
Incremental Synchronization: Data retrieval for items, variants, unit of measures, item attributes, purchase order lines, item references, default dimensions, dimension values, item categories, price list lines, price list headers, and customers utilizes timestamps (e.g.,
ItemsTimestamp,PriceListLinesTimestamp) from the connector settings. This ensures that only data modified since the last successful synchronization is fetched from Business Central, optimizing performance.Item Filtering: Only items with
Blocked == falsein Business Central are synchronized to App4Sales.Variant Handling: For items with variants, a distinct App4Sales item is created for each variant. The
ItemCodefor a variant is composed of the parent item's code and the variant code (e.g.,ITEMCODE-VARIANTCODE). Variant-specific stock quantities (Inventory,QuantityOnPurchaseOrder,QuantityOnSalesOrder) are associated directly with the variant item.Stock Calculation: The
LastAvailableStockfor an item is calculated using a configurable stock formula applied to the item'sInventory,QuantityOnPurchaseOrder, andQuantityOnSalesOrder.Next Delivery Date: The
NextDeliverydate is determined by finding the minimumExpectedReceiptDatefrom all associated purchase order lines where the receipt date is in the future.Price List Line Duplication for Variants: If a price list line exists for a parent item (without a specific variant code) and that item has variants, the connector duplicates this price list line for each variant. This ensures that each variant explicitly inherits pricing from its parent if no variant-specific pricing is defined in Business Central.
Default Currency Fallback: If a customer in Business Central does not have a currency code explicitly set, the connector defaults their currency code to the local currency code defined in Business Central's General Ledger Setup, or to a fallback currency specified in connector settings.
VAT Percentage Calculation: The VAT percentage is dynamically determined based on the item's
VatProductPostingGroupand the configured VAT posting setup entries in Business Central. An optional connector setting,VATBusinessPostingGroupCodeForItemVATPercent, can be used to further filter the VAT posting setup entries.EAN Code Prioritization: The EAN code is first attempted to be retrieved from
GlobalTradeItemNumber. If not available, it looks for an item reference of type 'BARCODE' that matches the item's unit of measure.Error Handling: The process includes logging of essential information and errors using the
LogMeutility to assist with troubleshooting.Company Name: Configured to identify the specific Business Central company to connect to.
Environment Name: Configured to specify the Business Central environment (e.g., Production, Sandbox).
Incremental Synchronization Timestamps: The connector leverages various internal timestamps (e.g., 'Items Timestamp', 'Price List Lines Timestamp') to perform incremental updates, fetching only data modified since the last synchronization.
Use Images Only From PIM: This App4Sales PIM setting determines if item pictures should be synchronized from Business Central. If enabled, images from Business Central are ignored.
Extra Field Name For Purchase Package Size: (Connector Setting) Specifies an item attribute name or an unknown element field in Business Central from which to derive the
PurchasePackageSizefor App4Sales items.VAT Business Posting Group Code For Item VAT Percent: (Connector Setting) An optional filter used to select the correct VAT posting setup entry when calculating the item's VAT percentage.
Use Levels For Item Category Code: (Connector Setting) If enabled, item categories in App4Sales will be constructed to reflect a hierarchical structure from Business Central item categories (e.g., "Parent | Level1 | ItemCategoryCode").
Indicator Field Name To Sync Item Categories: (Connector Setting) When
Use Levels For Item Category Codeis disabled, this setting specifies a boolean indicator field within Business Central item categories. Only categories with this field set totruewill be synchronized as App4Sales item categories.MBC Base Currency Code: (Connector Setting) Fallback currency code used if Business Central's General Ledger Setup does not provide a local currency code.
The connector only synchronizes items where the 'Blocked' field in Business Central is set to
false.Image synchronization is dependent on the App4Sales PIM setting 'Use Images Only From PIM'. If this is enabled, images from Business Central will not be synced.
Price list lines for parent items are duplicated for each variant if no variant-specific price is defined. This assumes all variants inherit the parent's price unless explicitly overridden.
The
NextDeliverydate only considers purchase order lines with anExpectedReceiptDatein the future. Past or current expected receipts are ignored for this field.