MicrosoftBusinessCentral Connector - Item Update

This document details the Item Update process for the App4Sales platform using the Microsoft Business Central connector. The connector synchronizes item data, including variants, pricing, stock, images, and various attributes, from Microsoft Business Central to the App4Sales internal database. This process ensures that App4Sales has up-to-date product information for sales representatives. The update typically runs on a scheduled basis.

Data Source Configuration

Item data is retrieved from various endpoints within the Microsoft Business Central API. The specific endpoints and filters applied are influenced by connector settings. Authentication against the Business Central API is required. Data is pulled from Business Central.

Base Item Data: Retrieved from an item endpoint configured via UseItSuitsFashionData setting. Additional properties can be expanded using ExtraItemExpandProperties. Items marked as 'Blocked' in Business Central are excluded. If the ItemBooleanCustomFieldForSyncFlag setting is specified, only items with this custom boolean field set to true are synchronized.
Item Variants: If EnableItemVariantSupport is enabled, variant information is fetched for each item from the items({itemId})/ItemVariants endpoint.
Units of Measure: Retrieved from the ItemUnitsOfMeasure endpoint.
Extended Texts: Retrieved from the ExtendedTextLines endpoint.
Item Attribute Values: Retrieved from the ItemsAttributeValues endpoint. Blocked attributes are excluded.
Purchase Order Lines: If ShowDateOfNextPurchaseOrderArrivalForItem is true, future purchase order lines are retrieved from the PurchaseOrderLines endpoint.
Default Dimensions: Retrieved from the DefaultDimension endpoint, filtered by ParentType 'Item'. If UseDimensionValues is enabled, dimension values are also retrieved from the DimensionValues endpoint to provide full dimension names.
Stock Information: Retrieved through internal stock repositories and builders, which aggregate data based on configured locations and Stock Keeping Units (SKUs).
Workflow Document Statuses: If ItemWorkflowStatusesForSync is configured, statuses are retrieved from the GACWorkflowDocStatusOview endpoint. Items are then filtered based on these statuses.
Item References: If ItemReferenceTypeForEanCode and ItemReferenceUnitOfMeasureForEanCode are configured, item references are retrieved from the ItemsReferences endpoint, primarily for EAN code determination.
Additional Item Information: If UseItemInformationTableForAdditionalItemInfo is true, extra item details are retrieved from the ItemInformation endpoint.
Item Categories: Retrieved from the ItemCategories endpoint.
VAT Posting Setup Entries: Retrieved from the VatPostingSetupEntry endpoint for VAT percentage calculation.
Item Pictures: If not handled by an FTP directory (FtpPictureDirectory) or PIM system (UseImagesOnlyFromPIM), pictures are downloaded directly from Business Central via an ItemPictureRepository.

Data Mapping Table - App4Sales Item

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`MBCItem.ItemCode`	Base item code from Business Central. For variants, it's derived as `ParentItemCode_VariantCode`.
`InternalItemCode`	`MBCItem.Id`	Internal GUID of the item from Business Central.
`Description`	`MBCItem.Description`	Item description.
`VatIncluded`	`MBCItem.PriceIncludesTax`	'I' if Business Central's `PriceIncludesTax` is true, 'E' otherwise.
`ItemType`	`MBCItem.Type`	Item type from Business Central.
`Unit`	`MBCItem.BaseUnitOfMeasure`, `MBCSalesPrice.UnitOfMeasureCode`	Defaults to `MBCItem.BaseUnitOfMeasure`. Overridden if `CustomerPriceGroupCodeForItemUOM` is configured, taking the Unit of Measure from the first matching sales price in that price group.
`NextDelivery`	`MBCPurchaseOrderLine.ExpectedReceiptDate`	The earliest `ExpectedReceiptDate` from the item's associated purchase order lines. Null if no future purchase orders.
`StockIndicator`	Derived from `MBCItemStockInformation`	Stock indicator, reflecting overall stock status. Defaults to -1 if no stock information is available.
`SalesPrice`	`MBCItem.UnitPrice`, `MBCSalesPrice.UnitPrice`	Determined by the `GetSalesPrice` logic: prioritizes price from the `PriceListCodeForStandardPrice` setting (first for variant if applicable, then for parent item), falls back to `MBCItem.UnitPrice` if no specific price list price is found or if it's zero.
`Sysmodified`	`MBCItem.ModifiedOn`	Timestamp of the last modification in Business Central.
`PicturesBytes`	`MBCItem.Images`	Raw byte content of item images.
`ItemStatus`	`MBCItem.ItemStatus`	Mapped from Business Central's `ItemStatus` using the `ItemStatusMapping` configuration.
`EanCode`	`MBCItem.GlobalTradeItemNumber`, `MBCItemReference.ReferenceNo`	Defaults to `MBCItem.GlobalTradeItemNumber`. Overridden if `ItemReferenceTypeForEanCode` and `ItemReferenceUnitOfMeasureForEanCode` are configured, by finding a matching item reference (with optional `ItemReferenceBarcodeTypeFOrEanCode` and `VariantCode`) and using its `ReferenceNo`.
`LastAvailableStock`	`MBCItemInformation.AvailableInventory`, Custom field from `MBCItem` (UnknownElements), `MBCItemStockInformation.LastAvailableStock`	Prioritized logic: 1. If `UseItemInformationTableForAdditionalItemInfo` is true, uses `MBCItemInformation.AvailableInventory`. 2. If `FreeFieldNameForLastAvailableStock` is set, uses the decimal value from the corresponding custom field in Business Central. 3. Falls back to `MBCItemStockInformation.LastAvailableStock`.
`PurchasePackageSize`	`MBCItemUnitOfMeasure.QuantityPerUnit`, `MBCItem.OrderMultiple`, Custom field from `MBCItem` (UnknownElements), `MBCItemAttributeValue.AttributeValue`	Prioritized logic: 1. If `UnitOfMeasureForPurchasePackageSize` is set and other specific settings are not used, uses `QuantityPerUnit` from the matching Unit of Measure. 2. If `UseOrderMultiplyFieldForItemPurchasePackageSize` is true, uses `MBCItem.OrderMultiple`. 3. If `ExtraFieldNameForPurchasePackageSize` is set, attempts to parse a decimal from the corresponding custom field (first from UnknownElements, then from AttributeValues).
`VatPercentage`	`MBCVatPostingSetupEntry.VatPercent`	Calculated based on `MBCItem.VatProductPostingGroup` and optionally `VATBusinessPostingGroupCodeForItemVATPercent`. Matches against `MBCVatPostingSetupEntry` to find the corresponding VAT percentage.
`ExtraData`	Derived from `MBCItem` and `MBCItemVariant`	For variant items, a JSON object containing `ItemCode` (parent) and `VariantId` (variant) is stored.
`ItemCategories`	Various fields from `MBCItem` and related entities	A collection of categories derived from multiple sources: unknown elements, price list codes (if `AddPriceListsToItemCategories` is set), item type, VAT product posting group, item attributes, units of measure, item references, extended texts, dimensions, item information (if `UseItemInformationTableForAdditionalItemInfo` is true), next purchase order arrival date (if `ShowDateOfNextPurchaseOrderArrivalForItem` is true), workflow status (if `ItemWorkflowStatusesForSync` is set), quantity on purchase order, reserved quantity, quantity on order, and description 2. Item categories can be hierarchical based on `UseLevelsForItemCategoryCode`.

Data Mapping Table - App4Sales Item Stock

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`MBCItemStockInformation.ItemCode`	Item code for which the stock information applies.
`StockValues["AvailableStock"]`	`MBCItemStockInformation.LastAvailableStock`	Available stock quantity.
`StockValues["ShelfStock"]`	`MBCItemStockInformation.ShelfStock`	Stock quantity currently on the shelf.
`StockValues["ToBeDelivered"]`	`MBCItemStockInformation.OnSalesOrder`	Quantity committed to sales orders.
`StockValues["ToBeReceived"]`	`MBCItemStockInformation.OnPurchOrder`	Quantity expected from purchase orders.

Special Logic & Filters

Item Filtering: Items are filtered based on their 'Blocked' status in Business Central. Further filtering occurs if ItemBooleanCustomFieldForSyncFlag is set, only syncing items where this custom flag is true. After initial processing, items can also be filtered by ItemWorkflowStatusesForSync to include only those matching specified workflow statuses.
Variant Handling: If EnableItemVariantSupport is active, each item variant from Business Central is treated as a separate App4Sales item, with its ItemCode constructed by appending the variant code to the parent item code.
Price Calculation: Sales prices are dynamically determined, prioritizing price list configurations over the item's base unit price.
Purchase Package Size: This field is populated based on a cascading logic involving specific Unit of Measure, Order Multiple, or a custom field/attribute.
VAT Percentage: Calculated by matching the item's VAT product posting group (and optionally business posting group) against VAT posting setup entries.
Last Available Stock: Determined by a priority system, checking specific item information, custom fields, or general stock information.
Item Categories (Dynamic): Many properties, attributes, and related data points are dynamically converted into App4Sales Item Categories, providing rich classification for non-technical users. This includes extended texts, dimensions, and specific stock quantities.
Image Download: Item pictures are downloaded from Business Central only if not already managed by an FTP server or a PIM system, preventing redundant downloads.

Domain Specifics (Expanded)

Price Logic

The connector supports flexible price retrieval and calculation, considering both base unit prices and configured price lists.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`SalesPrice`	`MBCItem.UnitPrice`, `MBCSalesPrice.UnitPrice`	Determined by the following hierarchy: Attempt to retrieve price for the variant item code from `itemPrices` using the price list specified in `PriceListCodeForStandardPrice`. If variant price is not found or is zero, attempt to retrieve price for the parent item code from `itemPrices` using the price list specified in `PriceListCodeForStandardPrice`. If no price is found from the configured price lists, fallback to `MBCItem.UnitPrice`. The `itemPrices` dictionary is keyed by `(ItemCode, PriceListCode.ToLowerInvariant())`.
`ItemCategories (Price List)`	`MBCSalesPrice.UnitPrice`	If `AddPriceListsToItemCategories` is configured, the Unit Price of matching sales prices for specified price list codes is added as an item category, e.g., "PriceList: [code]".

Image Handling

Item images are handled based on existing configurations for efficiency.

Source: Images can originate directly from Microsoft Business Central.
Conditional Download: Images are only downloaded from Business Central if the FtpPictureDirectory connector setting is empty (meaning no FTP server is used for images) AND the UseImagesOnlyFromPIM setting is false (meaning no PIM system is exclusively managing images). This prevents unnecessary data transfer if images are managed externally.
Mapping: Downloaded images are stored as raw bytes in Item.PicturesBytes.

Stock & Availability

Stock information is a composite of various Business Central data points, reflecting different aspects of availability.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`StockIndicator`	Derived from `MBCItemStockInformation`	A general indicator of stock availability, derived from the collected stock information. Defaults to -1 if not available.
`LastAvailableStock`	`MBCItemInformation.AvailableInventory`, Custom field, `MBCItemStockInformation.LastAvailableStock`	Determined by the following prioritized logic: If `UseItemInformationTableForAdditionalItemInfo` is true, uses the value from `MBCItemInformation.AvailableInventory`. If `FreeFieldNameForLastAvailableStock` is set, attempts to retrieve and parse the decimal value from the custom field (unknown element) with that name in Business Central. Otherwise, uses the value from `MBCItemStockInformation.LastAvailableStock`.
`ItemCategories (QtyOnPurchaseOrder)`	`MBCItem.QuantityOnPurchOrder`	Quantity of items on purchase orders.
`ItemCategories (QtyReserved)`	`MBCItem.ReservedQtyOnPurchOrders`	Quantity of items reserved on purchase orders.
`ItemCategories (QtyOnOrder)`	`MBCItem.QuantityOnPurchOrder` - `MBCItem.ReservedQtyOnPurchOrders`	Calculated quantity of items remaining on order (Total on PO - Reserved on PO).
`ItemCategories (Next purchase order arrival date)`	`MBCPurchaseOrderLine.ExpectedReceiptDate`	If `ShowDateOfNextPurchaseOrderArrivalForItem` is true, the earliest expected receipt date of pending purchase orders is added as a category.

Matrix & Attributes

The connector supports mapping Business Central attributes, dimensions, and categories to App4Sales ItemClasses and Free Fields. Variants are also managed as distinct items with linked parentage.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode (Variants)`	`MBCItem.ItemCode`, `MBCItemVariant.Code`	For variants, the `ItemCode` is constructed by concatenating the parent item's `ItemCode` and the variant's `Code` (e.g., `PARENT_VARIANT`).
`ExtraData (Variants)`	`MBCItem.ItemCode`, `MBCItemVariant.Id`	For variant items, a JSON object is stored in `ExtraData` containing the parent `ItemCode` and the variant's `Id`.
`ItemClasses (Variants)`	`MBCItemVariant.Code`	For each variant, an `ItemClass` named "Variants" is created, with an `ItemClassValue` set to the variant's `Code`.
`ItemCategories (Attributes)`	`MBCItemAttributeValue.AttributeName`, `MBCItemAttributeValue.AttributeValue`, `MBCItemAttributeValue.UnitOfMeasure`	Mapped from Business Central item attributes. If `UsePSTItemAttributeValueTableForItemAttributes` is true, the category value includes the `UnitOfMeasure` (e.g., "AttributeValueUnitOfMeasure"). Otherwise, it's just the `AttributeValue`.
`ItemCategories (Dimensions)`	`MBCDefaultDimension.DimensionCode`, `MBCDefaultDimension.DimensionValue`	Each default dimension from Business Central is added as an item category (e.g., "DimensionCode" -> "DimensionValue"). If `UseDimensionValues` is true, `DimensionValue` contains the actual name of the dimension value.
`ItemCategories (ItemCategoryCode)`	`MBCItemCategory.Code`, `MBCItemCategory.ParentCategoryCode`, Custom field from `MBCItemCategory`	If `UseLevelsForItemCategoryCode` is true, a hierarchical category path is constructed (e.g., "Parent \| Level1 \| ItemCategoryCode"). Otherwise, if `IndicatorFieldNameToSyncItemCategories` is set, only categories where this indicator is true are included. Falls back to directly using the `ItemCategoryCode`.
`ItemCategories (Extended text)`	`MBCItemExtendedTextLine.Text`	Extended text lines are grouped by language and extended text number, then concatenated and added as an item category (e.g., "Extended text [LanguageCode-ExtendedTextNo]").
`ItemCategories (Unknown Elements)`	`MBCItem` (dynamically discovered properties)	Any unknown elements (custom fields) found directly on the `MBCItem` are added as item categories. Similarly, unknown elements within `MBCItemUnitOfMeasure` and properties from `MBCItemInformation` are added if relevant settings are enabled.

Related Settings & Prerequisites

The following connector settings significantly influence the Item Update process:

FtpPictureDirectory: If empty, pictures may be downloaded directly from Business Central.
UseImagesOnlyFromPIM: If false (and FtpPictureDirectory is empty), pictures may be downloaded directly from Business Central.
UseItSuitsFashionData: Influences the item endpoint used for retrieving base item data.
ExtraItemExpandProperties: Specifies additional properties to expand when fetching item data.
ItemBooleanCustomFieldForSyncFlag: A custom boolean field in Business Central used to filter which items are synchronized.
EnableItemVariantSupport: Enables the retrieval and mapping of item variants as distinct App4Sales items.
ShowDateOfNextPurchaseOrderArrivalForItem: If true, the earliest expected receipt date from purchase orders is calculated and added to item categories.
UseDimensionValues: If true, full dimension values (names) are retrieved and used when mapping default dimensions.
ItemWorkflowStatusesForSync: A comma-separated list of workflow statuses; items will be filtered to include only those matching these statuses.
ItemReferenceTypeForEanCode, ItemReferenceUnitOfMeasureForEanCode, ItemReferenceBarcodeTypeFOrEanCode: Settings used to determine EAN code from item references.
UseItemInformationTableForAdditionalItemInfo: If true, additional item information from a dedicated table is used for LastAvailableStock and populating item categories.
PriceListCodeForStandardPrice: The code of the price list to use for determining the standard sales price.
CustomerPriceGroupCodeForItemUOM: If set, uses the Unit of Measure from the sales price associated with this customer price group.
UnitOfMeasureForPurchasePackageSize: If set, uses the quantity per unit from a matching Unit of Measure for PurchasePackageSize.
UseOrderMultiplyFieldForItemPurchasePackageSize: If true, uses the item's Order Multiple for PurchasePackageSize.
ExtraFieldNameForPurchasePackageSize: A custom field name to retrieve PurchasePackageSize from unknown elements or attributes.
VATBusinessPostingGroupCodeForItemVATPercent: Used in conjunction with VatProductPostingGroup to find the correct VAT percentage.
FreeFieldNameForLastAvailableStock: A custom field name to retrieve LastAvailableStock from unknown elements.
AddPriceListsToItemCategories: A comma-separated list of price list codes; prices from these lists will be added as item categories.
UseLevelsForItemCategoryCode: If true, item category codes are generated hierarchically (e.g., "Parent | Child").
IndicatorFieldNameToSyncItemCategories: A custom boolean field in Business Central used to determine if an item category should be synchronized.

Known Limitations

The system assumes the correctness of configured custom field names and references. Incorrect settings may lead to missing data or unexpected behavior.
Price lists are applied based on a single PriceListCodeForStandardPrice. More complex pricing rules (e.g., customer-specific pricing, quantity breaks beyond basic sales price logic) might require custom logic or additional development.
Image handling prioritizes external sources (FTP, PIM) over Business Central download. If external sources are misconfigured, images may not sync correctly even if available in Business Central.
Stock calculations are aggregated from Business Central's stock information; advanced multi-warehouse logic or real-time stock checks beyond the provided data points are not inherently supported by this connector.

MicrosoftBusinessCentral - Item sync