Profit Connector - ItemUpdate Function

The ItemUpdate function in the Profit Connector is responsible for synchronizing item data from the Profit ERP system into the App4Sales platform. This process involves retrieving various item-related details such as general item information, prices, stock levels, delivery dates, images, item classifications (ItemClasses, Free Fields, Assortments), and handling of matrix/variant items. The synchronized data is then mapped to App4Sales' internal item structure and updated in the App4Sales database. The function is designed to run periodically to keep item information up-to-date.

Data Source Configuration

The connector retrieves item data from the Profit system through various GetConnectors (APIs). The data is pulled from Profit and mapped to the App4Sales internal database objects.

General Item Information: Retrieved from Profit's item GetConnector, specifically Routes.Get.Items or Routes.Get.Items2. The choice between these two is controlled by the connector setting UseGetConnectorForSecondAdministration.
Mapped Languages: Retrieved from Routes.Get.MappedLanguage.
Item Classes: Retrieved from Profit's item class GetConnector, specifically Routes.Get.ItemClassesV1. The name of this GetConnector can be prefixed by the connector setting PrefixFreeFieldConnectorAndItemClasses. Additionally, if ItemDimensionFreeFieldsAndClasses is enabled, item class dimensions are retrieved from Routes.Get.ItemClassDimension.
Free Fields: Retrieved from Profit's free field GetConnectors, specifically Routes.Get.FreeFields1 and Routes.Get.FreeFields2. The names of these GetConnectors can be prefixed by the connector setting PrefixFreeFieldConnectorAndItemClasses. Additionally, if ItemDimensionFreeFieldsAndClasses is enabled, free field dimensions are retrieved from Routes.Get.FreeFieldDimension.
Item Descriptions: Retrieved from Routes.Get.DifferentLanguageItemDescriptions.
Delivery Dates: Retrieved from the DeliveryDateRepository.
Item Prices: Retrieved via GetAfasItemPrices(), which internally uses a Profit item price GetConnector (e.g., Routes.Get.ItemPrices). This is active if the connector setting GetPriceLists is enabled.
Sales Discounts per Price Group: Retrieved from Routes.Get.SalesDiscount_per_PriceGroup if the connector setting CreatePriceListsOnDiscountgroups is enabled. This data is used to dynamically create additional price lists.
Item Pictures:
- Single Pictures: Retrieved from Routes.Get.ItemPictures.
- Multiple Pictures: Retrieved from Routes.Get.MultiplePictures, with batching controlled by Settings.MultiplePicturesBatch.
Picture retrieval is conditional on ExcludePictures and the PIM settings.
Item Stock: Retrieved from Profit's item stock GetConnector, specifically Routes.Get.ItemStock. This occurs within the GetStockResults helper method.
Stock Period Information:
- Stock Delivered: Retrieved from Routes.Get.StockDelivered.
- Stock Received: Retrieved from Routes.Get.StockReceived.
These are used within the GetStockPeriod helper method if the connector setting GetStockPeriod is enabled.
Item Assortments: Retrieved from Routes.Get.ItemAssortment if the connector setting SetCustomerFixedItemFilter is enabled.
Dimension Translations (for matrix items): Retrieved from Routes.Get.DimensionTranslation if the connector setting UseMatrixTranslations is enabled.

Data Mapping Table - Item Entity

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`ProfitItemBase.ItemCode`	Direct mapping, whitespace trimmed.
`ItemType`	`ProfitItemBase.ItemType`	Direct mapping.
`Currency`	Hardcoded	Set to "EUR".
`VatIncluded`	Hardcoded	Set to 'E'.
`Description`	`ProfitItemBase.ExtraPreDescription`, `ProfitItemBase.Description`, `ProfitItemBase.ExtraPostDescription`	Concatenation of these three fields, separated by " - ", from Profit.
`SalesPrice`	`ProfitItemBase.SalesPrice`	Direct mapping, converted to decimal. This value can be overridden by an Action Price if identified.
`Sysmodified`	`ProfitItemBase.DateCreated`	Mapped from the item's creation date, converted from string to DateTime.
`PurchasePackageSize`	`ProfitItemBase.PurchasePackageSize`	Mapped if connector setting `SetPurchasePackageSize` is true, converted from string to integer.
`Unit`	`ProfitItemBase.Unit`	Direct mapping.
`EanCode`	`ProfitItemBase.EanCode`	Direct mapping (typically represents barcode, GTIN, or UPC).
`VatPercentage`	`ProfitItemBase.VatGroup`	Calculated based on `VatGroup` and connector settings (`VatPercentageForVatliableGroup1`, `VatPercentageForVatliableGroup2`), with fallbacks to application default VAT rates.
`LastAvailableStock`	Derived from `ProfitItemStock` (ShelfStock, ToBeDelivered, ToBeReceived)	Calculated using a stock formula from various stock fields from Profit. If `Settings.GetStockPeriodAsLastAvailableStock` is true, it uses a formula; otherwise, it's mapped directly from `ProfitItemBase.LastAvailableStock`.
`StockIndicator`	Derived from `ProfitItemStock`	An integer value calculated based on the stock formula.
`AcceptsDefaultDiscount`	`ProfitItemBase.DiscountAllowed`, Action Prices	Initially set to the inverse of `ProfitItemBase.DiscountAllowed` (converted to boolean). If `Settings.SetDiscountAllowedBasedOnPriceLists` is true, it's set to `false` if the item has an action price.
`SearchDescription`	`ProfitItemBase.SearchDescription`	Direct mapping.
`FreeSortField`	`ProfitItemBase.FreeSortField`	Converted from string to integer.
`ItemStatus`	`ProfitItemBase.ItemStatus`	Direct mapping.
`DefaultWarehouse`	`ProfitItemBase.DefaultWareHouse`	Direct mapping.
`NextDelivery`	`DeliveryDateRepository` results (ItemCode, DeliveryDate, Quantity)	The nearest future delivery date for the item is selected. This is active if `Settings.SyncNextDeliveryDate` is true.
`IsActionItem`	Derived from Price Lists	Set to `true` if the item is found to have an associated Action Price List.

Data Mapping Table - Item Classes

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemClass.Description`	`Profit Item Class Key` (from `Routes.Get.ItemClassesV1` or `Routes.Get.ItemClassDimension`)	The key of the key-value pair representing the item class.
`ItemClassValue.Value`	`Profit Item Class Value` (from `Routes.Get.ItemClassesV1` or `Routes.Get.ItemClassDimension`)	The value of the key-value pair, with transformations: "false" becomes "Nee", "true" becomes "Ja", dates formatted to "dd-MM-yyyy".
`ItemClass.Description` (Assortment)	Hardcoded	Set to "Assortment" if `Settings.SetCustomerFixedItemFilter` is true.
`ItemClassValue.Value` (Assortment)	`ItemAssortment.Assortment` (from `Routes.Get.ItemAssortment`)	Direct mapping.
`ItemClassValue.ItemCode` (Assortment)	`ItemAssortment.ItemCode`, `ItemAssortment.Dimension1`, `ItemAssortment.Dimension2`	Can be constructed with dimensions based on `Settings.UseItemDimensions` and `Settings.SetAssortmentOnParentLevel`.

Data Mapping Table - Free Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`FreeItemFields.Caption`	Hardcoded	Set to "Free item info".
`FreeField.Key`	`Profit Free Field Key` (from `Routes.Get.FreeFields1`, `Routes.Get.FreeFields2`, or `Routes.Get.FreeFieldDimension`)	The key of the key-value pair representing the free field. Excludes "itemcode".
`FreeField.Value`	`Profit Free Field Value` (from `Routes.Get.FreeFields1`, `Routes.Get.FreeFields2`, or `Routes.Get.FreeFieldDimension`)	The value of the key-value pair, with transformations: "false" becomes "Nee", "true" becomes "Ja", dates formatted to "dd-MM-yyyy". Sanitized for XML.

Data Mapping Table - Price Lists

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`PriceList.Id`	Derived from `ProfitPriceListItemPrices.Id`, `ProfitPriceListItemPrices.Currency`, `SalesDiscount_per_PriceGroup.DiscountGroup`	Hash code generated from the price list code.
`PriceList.Code`	`ProfitPriceListItemPrices.Id`, `ProfitPriceListItemPrices.Currency`, `SalesDiscount_per_PriceGroup.DiscountGroup`	Base code is `ProfitPriceListItemPrices.Id`. If `Settings.PriceListBasedOnCurrencyCode` is true, currency is appended (e.g., `ID_CURRENCY`). For discount-based price lists, discount group is appended (e.g., `ID_DISCOUNTGROUP`). Default price list uses "*****".
`PriceList.Description`	`ProfitPriceListItemPrices.Description`, or derived from `Code`	If from Profit price list, direct mapping. For discount-based price lists, same as `Code`. Default price list is "Default".
`PriceList.Currency`	`ProfitPriceListItemPrices.Currency`, or Application Settings	Direct mapping from Profit price list. For default price list, uses the administration's currency symbol.
`PriceList.ExternalCurrency`	Application Settings	For default price list, uses the administration's currency symbol.
`PriceList.Selectable`	Hardcoded	For discount-based price lists, set to `false`.

Data Mapping Table - Price List Prices

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`PriceListPrice.ItemCode`	`ProfitPriceListItemPrices.ItemCode`, `ProfitPriceListItemPrices.ItemDimension1`, `ProfitPriceListItemPrices.ItemDimension2`	Base is `ProfitPriceListItemPrices.ItemCode`. If `Settings.GetPriceListsForItemDimensions` is true and dimensions are present, `ItemCode` is constructed with dimension codes (e.g., `ITEMCODE_DIM1_DIM2`).
`PriceListPrice.Price`	`ProfitPriceListItemPrices.Price`, `SalesDiscount_per_PriceGroup.Discount`, `SalesDiscount_per_PriceGroup.DiscountAmount`	Converted from string to decimal. If a sales discount is applied, the price is adjusted based on percentage or amount. Null prices are logged as warnings and skipped.
`PriceListPrice.PriceListId`	Derived from `ProfitPriceListItemPrices.Id`, `ProfitPriceListItemPrices.Currency`, `SalesDiscount_per_PriceGroup.DiscountGroup`	Hash code generated from the price list code (same logic as `PriceList.Id`).

Data Mapping Table - Item Pictures

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Item.PicturesBytes`	`ProfitItemPicture.Picture` (for single pictures), `MultiplePicture` (for multiple pictures)	For single pictures, Base64 string from `ProfitItemPicture.Picture` is converted to byte array. Added with hash check. For multiple pictures, the `MultiplePicture` object is used to set pictures for items.
`MatrixParent.Picture`	`ProfitItemPicture.Picture`	If `Settings.UseItemDimensions` is true, the Base64 image string is added to a `MatrixParent` object.

Special Logic & Filters

Item Retrieval Strategy: The connector can retrieve items using two different Profit GetConnectors (Routes.Get.Items or Routes.Get.Items2) based on the UseGetConnectorForSecondAdministration setting. This allows for flexibility in handling multiple Profit administrations or specific data layouts.
Price List Activation: Price list synchronization is only performed if the GetPriceLists setting is enabled.
Dynamic Price List Creation: If CreatePriceListsOnDiscountgroups is enabled, additional price lists are dynamically generated based on customer discount groups found in Profit. This involves retrieving customer and sales discount data. These dynamically created price lists are marked as non-selectable (Selectable = false) in App4Sales.
Action Price Handling:
- If an item has an "Action Price" (determined by a boolean flag in Profit's price data), its SalesPrice in App4Sales can be updated to this action price, and the IsActionItem flag is set to true.
- If RemovePricesForActionItems is enabled, all specific price list entries for items identified as action items are removed, effectively forcing them to use a fallback price.
- A warning is logged if DefaultPriceListForActionPrice is set but no matching price list is found in App4Sales.
Delivery Date Synchronization: Item delivery dates are only synchronized if the SyncNextDeliveryDate setting is enabled. The system identifies and stores the nearest future delivery date for each item.
Item Dimension Handling:
- If UseItemDimensions is enabled, the connector processes items with dimensions (variants). This affects how item codes are constructed for prices and stock.
- Images for matrix parents are handled separately, and matrix translations can be synchronized if UseMatrixTranslations is enabled.
- Item dimensions for free fields and item classes can be retrieved separately if ItemDimensionFreeFieldsAndClasses is enabled.
Picture Retrieval:
- Picture synchronization is bypassed if ExcludePictures is true or if App4Sales is configured to use images exclusively from a PIM system.
- Base64 decoding of images is handled with error catching; malformed images are skipped.
- Multiple pictures for an item are retrieved in batches, with the batch size configurable via MultiplePicturesBatch.
Stock Calculation:
- If GetStockPeriodAsLastAvailableStock is enabled, the LastAvailableStock is calculated using a complex formula that considers various stock figures from Profit.
- The StockIndicator is also derived from these calculations.
- Detailed stock period information (delivered and received stock for future weeks) is processed if GetStockPeriod is enabled.
- CheckStock helper ensures stock values are non-negative and correctly reflect "economic stock" where applicable.
- If GetAllStockValuesFromProfit is true, the connector retrieves all stock values without filtering by item code, which might impact performance.
Item Assortments: If SetCustomerFixedItemFilter is enabled, item assortments from Profit are mapped as ItemClasses in App4Sales, potentially at the parent or variant level based on SetAssortmentOnParentLevel.
Data Cleaning/Validation:
- Whitespace is trimmed from item codes.
- "false" / "true" strings are converted to "Nee" / "Ja" for certain fields.
- Dates are formatted to "dd-MM-yyyy" where appropriate.
- Duplicate free fields are removed.
- XML serialization is used for free item fields, implying string sanitization.

Domain Specifics (Expanded)

Price Logic

The connector processes item pricing from Profit, including base sales prices, price lists, and discounts.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Item.SalesPrice`	`ProfitItemBase.SalesPrice`, Action Price	Directly mapped from Profit's sales price. Can be overridden by an action price if configured.
`Item.VatPercentage`	`ProfitItemBase.VatGroup`	Calculated based on VAT group and connector settings. Fallback to default application VAT rates if specific settings are zero.
`Item.AcceptsDefaultDiscount`	`ProfitItemBase.DiscountAllowed`, Action Prices	Initially the inverse of Profit's discount allowed flag. Can be overridden to `false` if the item is an action item and `SetDiscountAllowedBasedOnPriceLists` is true.

Price Lists (`PriceList`) and Price List Prices (`PriceListPrice`) Mapping:

Refer to the "Data Mapping Table - Price Lists" and "Data Mapping Table - Price List Prices" sections for detailed field mappings.

Default Price List: A default price list with code "*****" and description "Default" is created if not already present.
Currency-Based Price Lists: If PriceListBasedOnCurrencyCode is enabled, price lists are created uniquely per currency code.
Discount Group Price Lists: If CreatePriceListsOnDiscountgroups is enabled, price lists are generated based on customer discount groups. These price lists are not selectable in App4Sales.
Action Prices: Items identified with action prices can have their main sales price overridden, and the IsActionItem flag is set. If RemovePricesForActionItems is true, all specific price list entries for these items are removed.

Image Handling

The connector supports synchronizing single and multiple images for items from Profit.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Item.PicturesBytes`	`ProfitItemPicture.Picture`, `MultiplePicture`	Image data (Base64 string) from Profit is decoded to byte arrays. Images are added with a hash check to prevent duplicates.
Matrix Parent Image	`ProfitItemPicture.Picture`	If `Settings.UseItemDimensions` is true, the Base64 image string is added to a `MatrixParent` object.

Conditional Sync: Image synchronization is skipped if ExcludePictures is true or if App4Sales is configured to use an external PIM system for images.
Base64 Encoding: Images are expected to be Base64 encoded strings in Profit. Decoding errors are caught, and affected images are skipped.
Batch Processing: Multiple images are fetched and processed in configurable batches (MultiplePicturesBatch).

Stock & Availability

The connector retrieves various stock figures from Profit and calculates the available stock and stock indicator for App4Sales.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Item.LastAvailableStock`	`ProfitItemStock` (ShelfStock, ToBeDelivered, ToBeReceived)	Calculated based on a formula using various stock components from Profit. Uses `ProfitItemBase.LastAvailableStock` as a fallback.
`Item.StockIndicator`	Derived from stock calculations	An integer value representing the stock status, calculated based on the available stock.

Detailed Stock Retrieval: If GetStockPeriodAsLastAvailableStock is enabled, the available stock is calculated using a formula that aggregates "Shelf Stock", "To Be Delivered", and "To Be Received" quantities.
Stock Period Overview: If GetStockPeriod is enabled, the connector provides a weekly overview of stock movements (deliveries and receipts).
Dimension-Specific Stock: If UseItemDimensions is enabled, stock can be tracked and displayed at the individual item dimension level.
Stock Filters: Stock data can be filtered by item code and dimensions. The GetAllStockValuesFromProfit setting can disable these filters, retrieving all stock data.
Negative Stock Handling: The CheckStock helper ensures that stock values do not fall below zero, displaying 0 in such cases. It also accounts for "economic stock".

Matrix & Attributes

The connector handles matrix items (variants) by recognizing parent-child relationships and mapping various attributes.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Item.ItemClasses`	`Profit Item Class`, `ItemAssortment`	Mapped from Profit's item class data. Assortments can also be mapped as item classes. Values can be transformed (e.g., "true" to "Ja").
`Item.FreeItemFields`	`Profit Free Field`	Mapped from Profit's free field data, excluding "itemcode". Values can be transformed and are XML serialized.

Matrix Item Identification: Matrix items are identified by the presence of HeaderId, MatrixChildId, and MatrixParentId in the App4Sales Item object, often indicated by specific patterns in the item code (e.g., PARENTCODE_DIMENSION1_DIMENSION2).
Dimension Mapping: Item dimensions affect how price list entries and stock records are associated with specific variants.
Matrix Translations: If UseMatrixTranslations is enabled, translations for matrix headers and children are fetched from Profit and updated in App4Sales, enabling localized display of variant attributes.
Parent-Level Assortments: The SetAssortmentOnParentLevel setting controls whether item assortments are applied to the main parent item or to individual variants when dimensions are in use.

Related Settings & Prerequisites

UseGetConnectorForSecondAdministration: (Boolean) If enabled, uses an alternative Profit GetConnector for retrieving items.
AssignItemPriceToAnItem: (Boolean) If enabled, allows assignment of specific item prices based on a dedicated Profit field.
GetPriceLists: (Boolean) Enables synchronization of price lists and item prices from Profit.
CreatePriceListsOnDiscountgroups: (Boolean) If enabled, price lists are dynamically created in App4Sales based on customer discount groups from Profit. Requires GetPriceLists to be true.
RemovePricesForActionItems: (Boolean) If enabled, price list entries for items marked as "action items" will be removed.
DefaultPriceListForActionPrice: (String) Specifies the code or description of a default price list to consider for action prices.
SyncNextDeliveryDate: (Boolean) Enables synchronization of next available delivery dates for items.
ItemDimensionFreeFieldsAndClasses: (Boolean) If enabled, separate item class and free field dimensions are retrieved from Profit.
ExcludePictures: (Boolean) If enabled, item picture synchronization is skipped entirely.
UseItemDimensions: (Boolean) Enables the processing of items with dimensions (variants), impacting how prices, stock, and images are handled.
GetStockPeriodAsLastAvailableStock: (Boolean) If enabled, LastAvailableStock is calculated using a formula involving various stock fields from Profit.
SetDiscountAllowedBasedOnPriceLists: (Boolean) If enabled, an item's ability to accept default discounts is determined by its association with action price lists.
SetCustomerFixedItemFilter: (Boolean) If enabled, item assortments from Profit are synchronized as item classes.
MultiplePictures: (Boolean) If enabled, the connector attempts to retrieve multiple pictures per item.
MultiplePicturesBatch: (Integer) Defines the batch size for retrieving multiple pictures. A value of 0 processes all at once.
PrefixFreeFieldConnectorAndItemClasses: (String) A prefix applied to GetConnector names for item classes and free fields.
SetPurchasePackageSize: (Boolean) If enabled, the purchase package size is mapped from Profit.
VatPercentageForVatliableGroup1: (Decimal) Custom VAT percentage for Profit VAT group "1".
VatPercentageForVatliableGroup2: (Decimal) Custom VAT percentage for other Profit VAT groups.
GetAllStockValuesFromProfit: (Boolean) If enabled, retrieves all stock values from Profit without item code filtering, potentially impacting performance.
GetStockPeriod: (Boolean) If enabled, detailed stock period information (delivered and received quantities) is synchronized.
UseMatrixTranslations: (Boolean) If enabled, translations for matrix headers and children are synchronized.
SetAssortmentOnParentLevel: (Boolean) Controls whether item assortments are applied to the parent item or individual variants when dimensions are in use.
PIM Integration: If App4Sales is configured to use images exclusively from an external PIM system (AdministrationSession.CurrentSession.PimSettings.UseImagesOnlyFromPIM), image synchronization via the connector is skipped.
Profit GetConnectors: The Profit environment must have the necessary GetConnectors configured and accessible for the various data points (items, prices, stock, images, etc.).

Known Limitations

Limited Barcode Mapping: Only a single EAN Code is explicitly mapped; support for multiple barcodes or alternative barcode types is not apparent.
Hardcoded Currency: The primary item currency is hardcoded to "EUR" for basic item information, though specific price lists can carry different currencies.
Generic Stock Formula: The documentation references a "stock formula" for calculating LastAvailableStock and StockIndicator, but the specifics of this formula are abstracted and not detailed in this documentation.
Performance with Full Stock Sync: Enabling GetAllStockValuesFromProfit can lead to performance degradation as it retrieves all stock data without filtering.
Date Created as Last Modified: Sysmodified in App4Sales maps to ProfitItemBase.DateCreated. This implies that the last modification date in App4Sales reflects the creation date in Profit, not necessarily the last actual modification date.
Absence of Explicit Categories: There is no direct mapping for a generic "ItemCategory" field; categories appear to be handled implicitly via "ItemClasses" (e.g., assortments).

Profit - Item sync