SAPB1SL Connector - ItemUpdate

This function synchronizes item-related data from SAP Business One Service Layer (SAP B1 SL) to the App4Sales platform. It retrieves items, item groups, various item-specific attributes, stock information, and pricing data from SAP B1 SL, then processes and maps this information to the internal App4Sales data structures. The synchronization can be a full sync or a partial sync based on item update dates.

Data Source Configuration

The connector pulls data from the SAP Business One Service Layer (SAP B1 SL) API. The base URL and authentication details are configured within the connector settings. Item data is retrieved from the Item endpoint. Additionally, data is sourced from various other SAP B1 SL endpoints for related entities such as:

Item Groups: For categorizing items.
Discount Groups: For applying discount logic.
Item Properties: Custom properties defined in SAP B1 SL.
VAT Groups: For tax rate information.
Purchase Orders: To determine next delivery dates.
User-Defined Fields: Custom fields for items.
Item Brands, Product Types, Qualities, Mattresses, Versions, Colors, Item Statuses: These are retrieved if corresponding 'Item Free Field Names' are configured in the connector settings, acting as lookups for custom item attributes.
Product Trees (BOMs): Used for calculating stock for 'kit' or 'assembly' items.
Special Prices: For specific item pricing rules.

Data is generally pulled from SAP B1 SL using OData filters for partial synchronizations, based on the UpdateDate field.

Data Mapping Table: Item (Main Fields)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`SapB1SLItem.ItemCode`	Direct mapping from the SAP B1 SL Item Code.
`CreatedDate`	`SapB1SLItem.CreateDate`	Date when the item was created in SAP B1 SL. Converted from string to DateTime.
`Sysmodified`	`SapB1SLItem.UpdateDate`	Date when the item was last updated in SAP B1 SL. Converted from string to DateTime.
`Currency`	`SapB1SLItem.ItemPrices[PriceListCodeForDefaultItemPrice].Currency`	Currency of the default item price, based on the price list defined in the "Price List Code For Default Item Price" setting.
`Description`	`SapB1SLItem.ItemName`, `SapB1SLItem.Comment`	Item name from SAP B1 SL. If the setting "Add Comment Field To Item Categories" is disabled, the item's `Comment` field (if present) is appended to the description in the format: "Description - Comment".
`Description2`	`SapB1SLItem.ForeignName`	Foreign name of the item.
`EanCode`	`SapB1SLItem.BarCode`	Barcode of the item.
`ItemType`	`SapB1SLItem.ItemType`	Type of the item (e.g., 'Service', 'Inventory').
`LastAvailableStock`	`SapB1SLItem.QuantityOnStock` or custom field	If the "Last Available Stock Field" setting is specified, this field attempts to retrieve a value from a dynamic item property or unknown element with that name. Otherwise, it defaults to the item's `QuantityOnStock` from SAP B1 SL. Defaults to 0 if no value is found.
`SalesPrice`	`SapB1SLItem.ItemPrices[PriceListCodeForDefaultItemPrice].Price`	The default sales price of the item, obtained from the price list specified in the "Price List Code For Default Item Price" setting. Defaults to 0 if not found.
`Unit`	`SapB1SLItem.Unit`	The item's sales unit.
`VatIncluded`	Hardcoded	Always set to 'E'.
`VatPercentage`	`SapB1SLItem.SalesVatGroup.Lines`	If a sales VAT group is assigned and has VAT lines, the percentage is taken from the most recently effective VAT line (based on `EffectiveFromDate`).
`PurchasePackageSize`	`SapB1SLItem.ItemPropertyForPurchasePackageSize` (dynamic)	If the "Item Property For Purchase Package Size" setting is specified, the value is retrieved from the corresponding dynamic item property or unknown element. The value must be parsable as a decimal.
`RelatedItems`	Derived from `SapB1SLItem.ItemGroup`	If "Item Groups Names For Related Items" setting is configured and the current item's `ItemGroup.GroupName` is in the list, all other items within the same item group in SAP B1 SL are considered "related". Their item codes are serialized into an XML string.
`NextDelivery`	Derived from `Purchase Orders` or `Next Delivery Dates Dictionary`	If the "Use Next Delivery Date from Purchase Order" setting is enabled and a next delivery date is found for the item, that date is used. Otherwise, the system searches open purchase order lines for the item, looking for the earliest future `ShipDate` within the warehouses specified by "Warehouse Codes For Stock".
`ItemStatus`	`settings.ItemStatusField` or `itemStatuses.Name`	If the "Item Status Field" setting is specified, the value is retrieved from the specified dynamic item property. If "Use Endpoint To Retrieve Item Status Description" is also true, the descriptive name from the SAP B1 SL Item Status endpoint is used; otherwise, the raw property value is mapped.

Data Mapping Table: Item Categories (Dynamic Attributes)

The ItemCategories field in App4Sales stores a dictionary of flexible attributes. Values are added to this dictionary if they are not null or empty.

App4Sales Field (Key)	Source Field (API/Excel/DB)	Logic/Notes
`ItemGroup`	`SapB1SLItem.ItemGroup.GroupName`	Name of the item group the item belongs to.
`Length`	`SapB1SLItem.Length`	Item length, converted to invariant culture string.
`Height`	`SapB1SLItem.Height`	Item height, converted to invariant culture string.
`Width`	`SapB1SLItem.Width`	Item width, converted to invariant culture string.
`Volume`	`SapB1SLItem.Volume`	Item volume, converted to invariant culture string.
`Weight`	`SapB1SLItem.Weight`	Item weight, converted to invariant culture string.
`MinOrderQuantity`	`SapB1SLItem.MinOrderQuantity`	Minimum order quantity, converted to invariant culture string.
`ShipType`	`SapB1SLItem.ShipType`	Shipping type, converted to invariant culture string.
`VatGroup`	`SapB1SLItem.SalesVATGroupCode`	Sales VAT Group Code, converted to invariant culture string.
`SalesFactor1`	`SapB1SLItem.SalesFactor1`	Sales Factor 1.
`SalesFactor2`	`SapB1SLItem.SalesFactor2`	Sales Factor 2.
`SalesFactor3`	`SapB1SLItem.SalesFactor3`	Sales Factor 3.
`SalesFactor4`	`SapB1SLItem.SalesFactor4`	Sales Factor 4.
`Manufacturer`	`SapB1SLItem.Manufacturer`	Manufacturer name, converted to invariant culture string.
`Comment`	`SapB1SLItem.Comment`	Item comment.
`AttributeX`	`SapB1SLItem.ItemAttributeGroups`, `SapB1SLItem.GetPropertyValue("AttributeX")`	Values from item attribute groups (e.g., Attribute1 to Attribute64) are mapped if present.
Dynamic Item Properties	`SapB1SLItem.ItemPropertiesValues`	All key-value pairs from `ItemPropertiesValues` are added. Values 'Y'/'N' are converted to 'Yes'/'No'.
`RecommendedMarketPrice`	`SapB1SLItem.ItemPrices[PriceListCodeForRecommendedMarketPrice].Price`	If "Price List Code For Recommended Market Price" setting is configured, the corresponding price from the item's price list is mapped.
Unknown String Elements	`SapB1SLItem.GetUnknownStringCompatibleElements`	Any other unknown string-compatible elements found in the SAP B1 SL item data are added as categories.
`Brand`	Dynamic field named by "Item Free Field Name For Brand", then mapped to `SapB1SLItemBrand.Name`	If "Item Free Field Name For Brand" is set, the value from this field in SAP B1 SL is used as a code to look up the brand's descriptive name.
`Color`	Dynamic field named by "Item Free Field Name For Color", then mapped to `SapB1SLColor.Name`	If "Item Free Field Name For Color" is set, the value from this field in SAP B1 SL is used as a code to look up the color's descriptive name.
`Type`	Dynamic field named by "Item Free Field Name For Type", then mapped to `SapB1SLProductType.Name`	If "Item Free Field Name For Type" is set, the value from this field in SAP B1 SL is used as a code to look up the product type's descriptive name.
`Status`	Dynamic field named by "Item Free Field Name For Status", then mapped to `SapB1SLItemStatus.Name`	If "Item Free Field Name For Status" is set, the value from this field in SAP B1 SL is used as a code to look up the item status's descriptive name.
`Mattress`	Dynamic field named by "Item Free Field Name For Mattress", then mapped to `SapB1SLMattress.Name`	If "Item Free Field Name For Mattress" is set, the value from this field in SAP B1 SL is used as a code to look up the mattress type's descriptive name.
`Quality`	Dynamic field named by "Item Free Field Name For Quality", then mapped to `SapB1SLQuality.Name`	If "Item Free Field Name For Quality" is set, the value from this field in SAP B1 SL is used as a code to look up the quality's descriptive name.
`Version`	Dynamic field named by "Item Free Field Name For Version", then mapped to `SapB1SLVersion.Name`	If "Item Free Field Name For Version" is set, the value from this field in SAP B1 SL is used as a code to look up the version's descriptive name.

Data Mapping Table: Item Stock

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ShelfStock`	`SapB1SLItem.QuantityOnStock`, `ItemWarehouseInfoCollection.InStock` / `Counted`, Derived from Product Tree Components	For product trees, this is the minimum 'Shelf Stock' of its components divided by the component quantity in the bill of materials. For standard items, if "Warehouse Codes For Stock" is specified, it sums either `InStock` or `Counted` (based on "Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock" setting) from the specified warehouses. If no specific warehouse codes, and "Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock" is true, it uses `QuantityOnStock`. Otherwise, it defaults to 0.
`ToBeDelivered`	`SapB1SLItem.QuantityOrderedByCustomers`, `ItemWarehouseInfoCollection.Committed`, Derived from Product Tree Components	For product trees, it is `SapB1SLItem.QuantityOrderedByCustomers`. For standard items, if "Warehouse Codes For Stock" is specified, it sums `Committed` from the specified warehouses. If no specific warehouse codes, it uses `SapB1SLItem.QuantityOrderedByCustomers`.
`ToBeReceived`	`SapB1SLItem.QuantityOrderedFromVendors`, `ItemWarehouseInfoCollection.Ordered`, Derived from Product Tree Components	For product trees, this is the minimum 'To Be Received' of its components divided by the component quantity in the bill of materials. For standard items, if "Warehouse Codes For Stock" is specified, it sums `Ordered` from the specified warehouses. If no specific warehouse codes, it uses `SapB1SLItem.QuantityOrderedFromVendors`.
Custom Last Available Stock	Dynamic field named by "Last Available Stock Field"	If "Last Available Stock Field" is configured, its value from a dynamic property or unknown element is added to the stock information.

Data Mapping Table: Item Group Links

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemGroupCode`	`SapB1SLItem.ItemsGroupCode`	The numerical code of the item group.
`ItemCode`	`SapB1SLItem.ItemCode`	The item code.

Data Mapping Table: Price List Prices

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`PriceListId`	`SapB1SLItemPrice.PriceList`	The ID of the price list from SAP B1 SL.
`ItemCode`	`SapB1SLItem.ItemCode`	The item code.
`Price`	`SapB1SLItemPrice.Price`	The price of the item in the specific price list.
`Discount`	`SapB1SLItem.Discount` (calculated)	The discount percentage applied to the item, calculated based on SAP B1 SL Discount Groups if "Include All BPs Discount Groups Discounts Into Item Prices" is enabled.

Data Mapping Table: Staffle Prices (Tier Prices)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`CustomerCode`	`SapB1SLSpecialPrice.CardCode`	The customer code to whom this special price applies.
`ItemCode`	`SapB1SLSpecialPrice.ItemCode`	The item code for which this special price applies.
`Price`	`SapB1SLSpecialPrice.Price`	The special price for the item.
`PriceListId`	`SapB1SLSpecialPrice.PriceListNum`	The price list ID to which this special price belongs.
`Discount`	`SapB1SLDiscountGroupLine.Discount`	Discount percentage from SAP B1 SL Discount Groups. This is populated if "Use Staffle Prices For Specific Discount Groups Discounts During Live Prices Get" is enabled, combining discounts from various levels (customer, item group, item).
`MinQuantity`	Derived from Discount Groups	The minimum quantity for which the staffle price applies.
`CustomerGroup`	Derived from Discount Groups	The customer group for which the staffle price applies.

Special Logic & Filters

Full vs. Partial Sync: The synchronization type (full or partial) is determined by the "Do Next Sync As Full Sync" setting or if the current day is Saturday. Partial syncs use the last synchronization date to filter items by UpdateDate in SAP B1 SL.
Item Exclusion: Items are excluded from synchronization if the "Exclude Invalid Items From Sync" setting is true and the item's Valid status in SAP B1 SL is 'False' or its Frozen status is 'True'. These items are marked for deletion in App4Sales.
Conditional Item Sync: If the "Check Item Property With Name For Item Sync" setting is configured, items will only be synchronized if the specified item property exists and its value is not empty or 'False'.
Item Category Exclusion: If the "Exclude Items From Sync Based On Item Category" setting is set, items whose categories match predefined 'YesValues' for that specific category are excluded from synchronization.
Discount Group Processing: If "Include All BPs Discount Groups Discounts Into Item Prices" is enabled, the system retrieves SAP B1 SL Discount Groups and calculates an item discount based on various rules (specific customer/item, specific customer/item group, customer group/item, customer group/item group, customer group/manufacturer). The lowest discount is applied if "Use Customer Discount Relation For Live Prices Discount Calculation" and the customer's discount relation is 'LowestDiscount'; otherwise, the highest discount is applied.
Stock Calculation (Product Trees): For items identified as product trees (Bill of Materials), stock is calculated recursively based on the minimum available stock of their components, adjusted by the component quantity in the product tree.
Stock Calculation (Warehouses): If "Warehouse Codes For Stock" are specified, stock values (ShelfStock, ToBeDelivered, ToBeReceived) are aggregated from the specified warehouses in SAP B1 SL.
Stock Calculation (In/On Stock): The "Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock" setting determines whether InStock or Counted values are used for ShelfStock when specific warehouse codes are applied.
Language Mapping for Descriptions: The UpdateDescriptionLanguageMapping method maps a foreign language description (if "Foreign Item Description Language" is set) to DescriptionField = 2 in App4Sales, with the default language mapping to DescriptionField = 1.
Price List Updates: The UpdatePriceLists method is called at the beginning of the ItemUpdate process to ensure that all relevant price lists from SAP B1 SL are synchronized to App4Sales.
Staffle Prices Update: Special prices from SAP B1 SL are retrieved and converted into App4Sales StafflePrice entities. Discount Groups can also contribute to the staffle prices if "Use Staffle Prices For Specific Discount Groups Discounts During Live Prices Get" is enabled.
Database Updates: After processing, items, item group links, price list prices, and staffle prices are updated in the App4Sales internal database using DatabaseManager.Instance.UpdateItems2, UpdateItemGroups, UpdatePriceListPrices, and UpdateStafflePrices respectively.

Domain Specifics (Expanded)

Price Logic

The connector handles various pricing aspects, including a default sales price, recommended market prices, and dynamic discounts.

Default Sales Price: The primary sales price is derived from an item's price list in SAP B1 SL, specifically the one designated by the "Price List Code For Default Item Price" setting.
Recommended Market Price: If the "Price List Code For Recommended Market Price" setting is configured, an additional price from that specific price list in SAP B1 SL is retrieved and mapped as an item category.
Discount Groups: SAP B1 SL Discount Groups can influence item prices. When enabled via the "Include All BPs Discount Groups Discounts Into Item Prices" setting, the connector applies discounts based on a hierarchy of rules (customer-specific, item group-specific, customer group-specific). The calculation for whether the highest or lowest discount applies is determined by the customer's discount relation, if defined in a customer free field named 'DiscountRelation'.
Staffle Prices (Tier Prices): Special prices and volume-based discounts from SAP B1 SL are synchronized as App4Sales Staffle Prices. These can be specific to a customer, customer group, item, or item group, and can also be tied to specific price lists or apply to all customers.

Image Handling

(No direct image handling logic was observed within the ItemUpdate, GetItemsInfo, or ToItemDb methods. This typically implies image synchronization is handled by a separate process or module within the connector. If no images are explicitly linked or processed here, this section will remain brief.)

No explicit image handling logic was found within the analyzed methods. It is assumed that image synchronization is handled by a separate part of the connector or platform.

Stock & Availability

Stock information is a critical component of the item synchronization, with special considerations for product trees and multi-warehouse setups.

Stock Sources: Stock data originates from SapB1SLItem.QuantityOnStock, SapB1SLItem.QuantityOrderedByCustomers, SapB1SLItem.QuantityOrderedFromVendors, and SapB1SLItem.ItemWarehouseInfoCollection in SAP B1 SL.
Multi-Warehouse Support: The "Warehouse Codes For Stock" setting allows administrators to specify a comma-separated list of SAP B1 SL warehouse codes. When specified, stock quantities are aggregated only from these designated warehouses.
Product Tree Stock: For items defined as product trees (Bill of Materials) in SAP B1 SL, the system recursively calculates the available ShelfStock and ToBeReceived based on the minimum stock of their individual components. The "Warehouse Codes For Product Trees" setting can be used to filter warehouses considered for product tree stock calculations.
Shelf Stock Definition: The definition of ShelfStock depends on the "Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock" setting and whether specific warehouse codes are used. It can be derived from InStock or Counted quantities in SAP B1 SL.
Last Available Stock: A custom stock field can be mapped using the "Last Available Stock Field" setting, allowing for flexible integration of additional stock metrics from SAP B1 SL.

Matrix & Attributes

The connector maps various item attributes and classifies items using item groups and configurable free fields.

Item Groups: The primary item grouping from SAP B1 SL is mapped.
Item Attributes (1-64): Standard item attributes defined in SAP B1 SL are mapped as item categories.
Dynamic Item Properties: All configured dynamic item properties from SAP B1 SL are mapped as item categories, providing flexibility for custom attributes.
Configurable Free Fields: The connector supports mapping custom attributes like Brand, Color, Product Type, Status, Mattress, Quality, and Version using configurable free field names (e.g., "Item Free Field Name For Brand"). These settings allow administrators to specify the SAP B1 SL field that holds the code for these attributes, which are then looked up against their respective descriptive endpoints in SAP B1 SL.
Derived Attributes: Attributes like Length, Height, Width, Volume, Weight, Min Order Quantity, Ship Type, Sales Factors, Manufacturer, and Comment are directly mapped as item categories from their corresponding SAP B1 SL fields.

Related Settings & Prerequisites

Price List Code For Default Item Price: (Required) Specifies the SAP B1 SL price list to use for determining the default item sales price and currency.
Add Comment Field To Item Categories: (Boolean) If disabled, the item's Comment field from SAP B1 SL is appended to the item's main description.
Last Available Stock Field: (Optional) The name of a custom item property or user-defined field in SAP B1 SL that contains the 'Last Available Stock' value.
Item Property For Purchase Package Size: (Optional) The name of a custom item property or user-defined field in SAP B1 SL that contains the 'Purchase Package Size'.
Use Next Delivery Date from Purchase Order: (Boolean) If enabled, the system attempts to retrieve the next delivery date from SAP B1 SL purchase orders.
Warehouse Codes For Stock: (Optional) A comma-separated list of SAP B1 SL warehouse codes. If specified, stock calculations will only consider these warehouses.
Item Groups Names For Related Items: (Optional) A comma-separated list of SAP B1 SL item group names. Items within these groups will have other items from the same group listed as 'related items'.
Item Status Field: (Optional) The name of a custom item property or user-defined field in SAP B1 SL that contains the item's status.
Use Endpoint To Retrieve Item Status Description: (Boolean) If enabled, when "Item Status Field" is set, the connector attempts to retrieve the descriptive name of the item status from an SAP B1 SL endpoint.
Price List Code For Recommended Market Price: (Optional) Specifies an SAP B1 SL price list to use for a 'Recommended Market Price' which is mapped as an item category.
Exclude Invalid Items From Sync: (Boolean) If true, items marked as 'invalid' or 'frozen' in SAP B1 SL are excluded from synchronization and removed from App4Sales.
Check Item Property With Name For Item Sync: (Optional) If set, items will only be synchronized if the specified item property exists and its value is not empty or 'False'.
Exclude Items From Sync Based On Item Category: (Optional) Specifies an item category. Items whose value for this category matches predefined 'YesValues' will be excluded from synchronization.
Include All BPs Discount Groups Discounts Into Item Prices: (Boolean) If enabled, SAP B1 SL Discount Groups are used to calculate and apply discounts to item prices during synchronization.
Use Customer Discount Relation For Live Prices Discount Calculation: (Boolean) If enabled alongside discount group processing, a customer's 'DiscountRelation' free field (if present and 'LowestDiscount') influences whether the minimum or maximum discount from applicable discount groups is used.
Use Staffle Prices For Specific Discount Groups Discounts During Live Prices Get: (Boolean) If enabled, staffle prices are derived from discount groups.
Foreign Item Description Language: (Optional) Specifies a language code. If set, a second description field (Description2) will be mapped with the foreign language.
Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock: (Boolean) Influences how ShelfStock is calculated from SAP B1 SL warehouse data.
Warehouse Codes For Product Trees: (Optional) A comma-separated list of SAP B1 SL warehouse codes. If specified, product tree stock calculations will only consider these warehouses.

Known Limitations

The image handling logic was not directly observed in the analyzed code paths, suggesting it may be external or handled differently.
Some discount group scenarios (e.g., specific customer & manufacturer discount, all customers & manufacturer/item group/item discounts) are noted as "TODO: missing" in the source code, indicating they are not currently covered.
The calculation for ShelfStock when no specific "Warehouse Codes For Stock" are provided and "Use In Or On Stock As Shelf Stock And Stock Formula For Available Stock" is false defaults ShelfStock to 0, which might not be the intended fallback.

SAPB1SL - Item sync