ExactOnlinePremium - ItemUpdate

The ItemUpdate method synchronizes item data from Exact Online to the App4Sales platform. This comprehensive synchronization process involves fetching item basic information, sales prices, stock levels, multi-language descriptions, classifications (item categories), and associated custom fields. The retrieved data is then mapped, transformed, and updated in the internal App4Sales database, ensuring items, their pricing, stock, and descriptive attributes are current. This process is designed to handle incremental updates based on timestamps for efficiency.

Data Source Configuration

The connector primarily pulls data from the Exact Online REST API. All API calls are authenticated using the configured Exact Online credentials. Data retrieval often utilizes skip tokens for pagination to handle large datasets.

VAT Codes: Retrieved from the Exact Online API endpoint for VAT codes (VatCode.GetRoute).
Price Lists: Fetched from the Exact Online API endpoint for price lists (ExactOnlinePriceList.GetRoute). Price lists can be excluded based on connector settings.
Exchange Rates: Retrieved from the Exact Online API (ExchangeRate.GetRoute) if currency price list generation is enabled. Only the most recent exchange rates are considered, and inverse/self-rates are generated.
Item Free Fields: Custom extra fields associated with items are fetched from the Exact Online API (ExactOnlineItemExtraField.GetRoute).
Warehouses: Specific warehouse information for package size determination is fetched from the Exact Online API (ExactOnlineWarehouse.GetRoute) if configured.
Item Sync Entities: Basic item information and metadata are retrieved from the Exact Online API (ExactOnlineItem.GetRoute). Incremental updates are supported using the ItemTimestamp setting.
Assortments: Item assortments are retrieved from the Exact Online API (ExactOnlineItemAssortment.GetRoute).
Assortment Properties: Properties for active assortments are fetched from the Exact Online API (ExactOnlineItemAssortmentProperty.GetRoutes).
Item Group Entities: Descriptions for item groups are retrieved from the Exact Online API (ExactOnlineItemGroup.GetRoutes).
Sales Channels: Sales channel data is retrieved from the Exact Online API (ExactOnlineSalesChannel.GetRoute) if the SalesChannelCodeToUseForOrders setting is set. Requires a Professional or Premium Exact Online version.
Default Sales Prices: Retrieved from the Exact Online API (ExactOnlineSalesPrice.GetRoute). Expired prices are filtered out, and only active prices not linked to specific accounts are considered. Incremental updates are supported using the ItemSalesPriceTimestamp setting.
Purchase Order Lines: Used for determining next delivery dates, retrieved from the Exact Online Purchase Order API if SyncNextDeliveryDate or GetDeliveryDatesOffline settings are enabled.
Stock Information: Item stock levels are fetched from the Exact Online Stock API.
Assembly Materials: Information about assembled items' components is fetched from the Exact Online API (ExactOnlineAssemblyBillOfMaterialMaterials.GetAssembledItemsRoutes).
Assembly Orders: Details of assembly orders are fetched from the Exact Online API (ExactOnlineAssemblyOrder.GetRoute).
Custom Fields for Items: Additional custom fields for individual items are retrieved via a specific REST API route provided within the ExactOnlineItemSync entity (newItem.CustomField).

Data Mapping Table (App4Sales Item)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`entity.Code`	Direct mapping, value is trimmed.
`InternalItemCode`	`entity.ID`	Mapped from the Exact Online unique identifier for the item, converted to string.
`SalesPrice`	`priceInfo.Price`	Direct mapping from the main sales price identified.
`VatPercentage`	`entity.SalesVatCode`, `settings.VatLiableCode`	Calculated using the `SalesVatCode` from Exact Online and the connector's `VatLiableCode` setting.
`VatIncluded`	(Output from VAT calculation)	Indicates whether VAT is included in the sales price.
`Currency`	`priceInfo.Currency`	Direct mapping from the main sales price currency.
`Description`	`entity.Description`, `entity.ExtraDescription`	If `settings.ExtraDescriptionOnDescription` is enabled and `entity.ExtraDescription` is not empty, `ExtraDescription` is used; otherwise, `entity.Description` is used.
`LastAvailableStock`	`entity.Stock` (initial), Stock API (final)	Initially set from `entity.Stock` if `settings.WarehouseForStock` is empty. Otherwise, initialized to 0 and later updated based on detailed stock information, potentially including assembled items and formula-based calculations.
`Unit`	`entity.UnitDescription`	Direct mapping.
`ExtraData`	`entity.Unit`	Stores the Exact Online unit code (e.g., 'pcs', 'kg') for internal price lookups.
`ExtraText1`	`entity.Notes`	Direct mapping.
`ItemClasses`	`entity.ItemGroupCode`, `itemGroups.Description`	An "Assortiment" item class is created, taking its value from the description of the corresponding Exact Online Item Group. Additional item classes are generated from notes, extra descriptions, search codes, statistical codes, Exact Online item assortments (Class_01 to Class_10), KeyRename settings, and custom item extra fields.
`CreatedDate`	`entity.Created`	Direct mapping.
`FreeSortField`	`settings.FreeSortField`, `ExactOnlineItem` properties, `extraFields`	Derived from an `ExactOnlineItem` property specified by `settings.FreeSortField`, or from a matching custom extra field. Integer values are used directly; otherwise, a hash code is used. Defaults to 0 if not configured or convertible.
`SearchDescription`	`entity.SearchCode`	Direct mapping.
`EanCode`	`entity.Barcode`, `entity.SearchCode`, `entity.ExtraDescription`, `entity.Notes`	Determined by connector settings: can be sourced from `SearchCode`, `ExtraDescription`, `Notes`, or defaults to `Barcode`.
`PurchasePackageSize`	`item.SearchCode`, `item.ExtraDescription`, `extraFields`	Determined by connector settings: can be sourced from `SearchCode`, parsed from `ExtraDescription` (potentially using a split character and index), or from a specific custom extra field. Defaults to 1 if no valid value is found or conversion fails, or if value exceeds database limits.
`ItemStatus`	`settings.ItemFreeFieldNameForItemStatus`, `extraFields`	Derived from the value of a custom extra field if `settings.ItemFreeFieldNameForItemStatus` is configured. Otherwise, defaults to "Stock".
`Sysmodified`	`entity.Modified`	Direct mapping.
`NextDelivery`	Exact Online Purchase Orders, Assembly Orders	Determined from the earliest future receipt date from relevant purchase order lines and assembly orders for the item, considering quantities.
`FreeItemFields`	`item.ExtraValuesDictionary`	A combination of free fields generated throughout the process (including delivery dates, staffle prices) is serialized into an XML string and stored here.

Special Logic & Filters

Item Exclusion: Items can be excluded from synchronization based on settings.PassWebShopItem (if not a webshop item), settings.IncludeNonSalesItems (if not a sales item), settings.CheckIfItemIsActive (if item is inactive), or a custom field specified by settings.FieldUsedToIncludeItemsInSync.
Pagination: REST API calls for fetching large lists of entities (e.g., items, sales prices, assortments) utilize skip tokens for efficient pagination.
Incremental Updates: The connector uses ItemTimestamp and ItemSalesPriceTimestamp settings to retrieve only changes since the last synchronization, optimizing performance.
Error Handling: Robust error handling is implemented for REST API calls, logging errors and preventing the entire synchronization from failing due to individual item issues.
Item Renaming/Deletion: If item codes change in Exact Online, the old items are removed from App4Sales based on a mapping of internal IDs.
Language Descriptions: Multi-language item descriptions are fetched and processed if configured, mapping up to five description fields in App4Sales.
Stock Calculation: Stock values are retrieved from Exact Online, and if the connector is ExactOnlinePremium, these are adjusted to account for assembled items (Bill of Materials) using AssemblyItemStockHelper and a formula executor.
Delivery Date Calculation: Next delivery dates are calculated from future purchase order lines and, for the Premium connector, also from assembly orders. These can also be exposed as free fields.
Price List Synchronization: The synchronization includes complex logic for handling default sales prices, generating currency-specific price lists based on exchange rates, and processing volume discounts. It ensures that App4Sales price lists accurately reflect Exact Online pricing structures.
Price Consistency Check: A critical check is performed (RemoveAllDbPricesWhenDifferent) to identify and remove any existing database prices for a given price list that do not match the newly synchronized prices from Exact Online. This prevents stale price data from persisting.

Domain Specifics (Expanded)

Price Logic

The connector supports a flexible pricing model, allowing for base sales prices, currency-specific price lists, and tiered/volume (staffle) pricing.

Base Sales Price: The primary sales price for an item is taken from Exact Online's default sales price.
Currency Price Lists: If settings.GenerateCurrencyPriceLists is enabled, the connector automatically generates App4Sales price lists for various currencies. These are created by converting the default price using retrieved exchange rates. If Exact Online provides specific sales prices for a currency, those values override the exchange-rate-converted prices.
Volume Discounts (Staffle Prices): Volume discounts are retrieved from Exact Online (ExactOnlineSalesPriceListVolumeDiscountSync) and integrated into App4Sales price lists. These can also be explicitly exposed as item free fields if a specific price list code is configured in settings.PriceListCodeForStaffelFreeField, which reads pricing data from a CSV source.
Price Overrides: The system prioritizes directly specified currency prices over exchange-rate-calculated prices.
Expiration: Expired sales prices in Exact Online are removed from App4Sales during synchronization.

Image Handling

The connector can download a single primary image per item from Exact Online.

Source: The PictureUrl property of the ExactOnlineItem entity.
Conditional Download: Image download is active only if both settings.DisablePicturesFromEOL is false and the PIM setting AdministrationSession.CurrentSession.PimSettings.UseImagesOnlyFromPIM is false.
Processing: Images are downloaded in a batch after all item metadata has been processed, using the Exact Online access token.
Storage: Downloaded images are added to the App4Sales item's PicturesBytes collection, with a hash check to prevent storing duplicate images.

Stock & Availability

Stock synchronization is robust, especially for the Premium connector, which accounts for assembled items.

Sources: Stock data is retrieved from Exact Online's Stock API.
Multi-Warehouse Support: Stock can be filtered by a specific warehouse defined in settings.WarehouseForStock.
Assembled Items: For ExactOnlinePremium, stock calculations consider Bill of Materials (BOM). The connector fetches details of assembled items and their components, then adjusts stock values using the AssemblyItemStockHelper. This ensures accurate stock figures for products built from multiple parts.
Stock Indicator: An item's stock indicator can be calculated based on a configurable formula (Session.ConnectorBaseSettings.GetStockIndicatorByFormula) or derived from the available stock and other relevant quantities (shelf stock, to be delivered, to be received).
Next Delivery Dates: Calculated from future purchase order lines. For the Premium connector, future assembly orders are also considered to determine the earliest possible next delivery date. These dates can be stored as App4Sales item free fields if settings.GetDeliveryDatesOffline is enabled.
"In Stock" Item Class: An item class "In stock" is generated, with a value of "Yes" if LastAvailableStock is greater than 0, and "No" otherwise.

Matrix & Attributes

Item categorization and custom attributes are extensively supported.

Item Classes:
- An "Assortiment" item class is created from the Exact Online Item Group description.
- Default item classes for "Notes", "Extra Description", "Search code", and "Statistical Code" are created.
- Item assortments (Class_01 to Class_10) from Exact Online are mapped to corresponding item classes in App4Sales, using their descriptions or codes based on settings.UseItemAssortmentDescriptions.
- Custom item extra fields from Exact Online are converted into App4Sales item classes.
- Dynamic item classes can be created based on KeyRename settings, allowing for flexible mapping of Exact Online properties to App4Sales item classes.
- If settings.UseSalesPriceInclVatAsFreeField is enabled, a "ConsumerPrice" item class (with VAT included) is added.
Custom Fields: The ExactOnlinePremium connector specifically fetches and maps custom fields configured in Exact Online to new item categories in App4Sales, using the custom field's property name and caption.

Related Settings & Prerequisites

Applicationkey: Essential for authenticating with the Exact Online API.
CurrentDivision: The Exact Online division from which to synchronize data.
ItemTimestamp: Used for incremental item updates; stores the timestamp of the last successful item synchronization.
ItemSalesPriceTimestamp: Used for incremental sales price updates; stores the timestamp of the last successful sales price synchronization.
WarehouseForStock: (Optional) Specifies a particular warehouse code to filter stock information.
GenerateCurrencyPriceLists: (Boolean) If true, the connector generates App4Sales price lists for each currency based on exchange rates.
ExcludePriceList: (String, semicolon-separated) A list of Exact Online price list codes to exclude from synchronization.
PriceListCodeForStaffelFreeField: (String) If set, enables reading staffle (tiered) prices from a CSV source associated with this price list code and mapping them as item free fields.
ExtraDescriptionOnDescription: (Boolean) If true, uses the Exact Online item's ExtraDescription as the primary App4Sales Description if available.
GetPurchasePackageSizeFromSearchCode: (Boolean) If true, attempts to parse the item's SearchCode for the purchase package size.
GetPurchasePackageSizeOnExtraItemDescription: (Boolean) If true, attempts to parse the item's ExtraDescription for the purchase package size.
SplitCharacterForExtraItemDescription: (String) Used with GetPurchasePackageSizeOnExtraItemDescription to split the extra description.
PurchasePackeSizeIndex: (Integer) Used with GetPurchasePackageSizeOnExtraItemDescription to specify which part of the split extra description to use.
GetPurchasePackageSizeFromFreeField: (String) If set, attempts to retrieve the purchase package size from a custom extra field matching this description.
SearchCodeForEanCode: (Boolean) If true, uses the item's SearchCode as the EAN code.
UseItemExtraDescriptionForItemField: (String) If set to "eancode", uses the item's ExtraDescription as the EAN code.
UseItemNotesForItemField: (String) If set to "eancode", uses the item's Notes as the EAN code.
FreeSortField: (String) Specifies an Exact Online item property to use for the App4Sales FreeSortField.
PassWebShopItem: (Boolean) If true, only items marked as webshop items in Exact Online will be synchronized.
IncludeNonSalesItems: (Boolean) If true, non-sales items from Exact Online will be synchronized.
CheckIfItemIsActive: (Boolean) If true, only active items in Exact Online will be synchronized.
FieldUsedToIncludeItemsInSync: (String) Specifies a custom field whose boolean value determines if an item should be included in the sync.
UseSalesPriceInclVatAsFreeField: (Boolean) If true, creates an "ConsumerPrice" item class with the sales price including VAT.
UseItemAssortmentDescriptions: (Boolean) If true, uses descriptions for item assortment properties; otherwise, uses their codes.
DisablePicturesFromEOL: (Boolean) If true, prevents downloading pictures from Exact Online.
SyncNextDeliveryDate: (Boolean) If true, calculates and synchronizes the earliest next delivery date for items.
GetDeliveryDatesOffline: (Boolean) If true, stores detailed future delivery dates as item free fields.
EnableOfflineTierPrices: (Boolean) If true, enables the synchronization of offline tier prices.

Known Limitations

The image handling currently only processes a single primary image per item (PictureUrl).
The UnitFactorAsPurchasePackageSize setting is present in code but marked as a "TODO" and explicitly noted as not implemented, suggesting this functionality is not available.
Multi-language descriptions are mapped to generic Description, Description2, etc., fields. The specific language is indicated by a suffix in the item class name (e.g., "ExtraDescription EN").

ExactOnlinePremium - Item sync