Logic4 Connector - Item Update

This document describes the Item Update process for the Logic4 connector, detailing how item-related data is retrieved from Logic4 and transformed into App4Sales item payloads. This process handles product information, pricing, stock, images, and various classifications.

Data Source Configuration

The connector communicates with the Logic4 API to retrieve item data. Below are the key API endpoints used:

Product Data:
- /v1.1/Products/GetProducts: Retrieves general product information.
- /v1/Products/GetBasicProductDataForProducts: Fetches additional basic product details in batches.
Product Group Data:
- /v1/ProductGroups/GetProductGroups: Retrieves product categories and groups.
Stock Data:
- /v1.1/Stock/GetStockForWarehouses: Retrieves stock information for multiple items across specified warehouses.
- /v1/Stock/GetStockInformationForProduct: Retrieves stock details for a single product and warehouse.
- /v1/Stock/GetWarehousesForAdministration: Fetches a list of available warehouses for the current administration.
- /v1/Stock/GetWarehousesStockLocationsForAdministration: Fetches specific stock locations within warehouses.
- /v1/BuyOrders/GetBuyOrderRowsPerProduct: Retrieves future delivery dates and quantities for items.
Price Data:
- /v1.1/Products/GetPriceInformationForProduct: Retrieves shift (tier) price information for products.
Image Data: Product images are downloaded directly from the URLs provided in the product data (ImageUrl1, ImageUrl2, ImageUrl3) using HTTP GET requests.

Data Mapping Table (Items)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`product.ProductCode`	Direct mapping of the Logic4 product code.
`InternalItemCode`	`product.Id`	The Logic4 Product ID, converted to a string.
`Description`	`product.BasicData.Description1` or `product.Descriptions[0].Value`	Primary product description. Falls back to the first entry in `product.Descriptions` if `BasicData.Description1` is not available.
`Description2`	`product.BasicData.Description2` or `product.Descriptions[1].Value`	Secondary product description. Falls back to the second entry in `product.Descriptions` if `BasicData.Description2` is not available.
`Description3`	`product.Descriptions[2].Value`	Third product description.
`Description4`	`product.Descriptions[3].Value`	Fourth product description.
`Description5`	`product.Descriptions[4].Value`	Fifth product description.
`SalesPrice`	`product.SellPrice`	Retail price excluding VAT, typically the base price for a single unit.
`VatPercentage`	`product.VatPercent`	The VAT percentage associated with the product.
`EanCode`	`product.BarCode`	The product's barcode (EAN).
`VatIncluded`	`settings.ItemPriceInclVat`	Set to 'I' if the connector setting 'ItemPriceInclVat' is true (prices include VAT), otherwise 'E' (prices exclude VAT).
`LastAvailableStock`	`product.LastAvailableStock`	The last known available stock quantity (FreeStock) for the product. This does not consider multi-warehouse stock.
`CreatedDate`	`product.DateTimeAdded`	The date and time the product was added in Logic4. Defaults to an empty DateTime if not provided.
`NextDelivery`	`product.NextDelivery`	The next expected delivery date for the product.
`ItemCategories`	`product.ProductGroupId`, `productGroups`, `product.FreeValues`, `product.UnknownElements`	Derived from Logic4 product groups (including parent-child hierarchies) and free values/unknown elements. Each product group in the hierarchy creates an item category, which is also treated as a free field.
`PurchasePackageSize`	`product.PurchasePackageSize`	Minimum sales amount or package size for purchase.
`Sysmodified`	`product.DateTimeLastChanged`	The date and time of the last modification in Logic4. Defaults to an empty DateTime if not provided.
`ItemOrder`	`product.Sorting`	The sorting order of the item.
`PicturesBytes`	`product.ImageBytes1`, `product.ImageBytes2`, `product.ImageBytes3`	Raw image data (byte arrays) downloaded from Logic4 image URLs. Only images with actual byte data are added. Hash checks prevent duplicate image storage.
`FreeItemFields`	`product.ShiftPrices`, `warehouseStockLocations`, `product.BasicData.DefaultPickStockLocationId`	XML string containing additional free fields. If 'Shift prices as free fields' setting is enabled, shift prices with quantity greater than 1 are added (e.g., "5 stuks": "10.00"). If 'Pick locations as free fields' setting is enabled, the name of the default pick stock location is added (e.g., "Picklocatie": "Main Warehouse A"). Additionally, product categories derived from product groups are also added as free fields.

Data Mapping Table (Stock Values per Item)

This table details how stock values are processed and stored for each item when stock synchronization is enabled.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`StockValues` (Key: "Warehouse {ID}")	`Logic4ProductStock.WarehouseId`	If an item has stock entries across multiple warehouses, a header entry is added for each warehouse.
`StockValues` (Key: "Beschikbare voorraad")	`Logic4ProductStock.TotalStock`	The total stock quantity, formatted to two decimal places.
`StockValues` (Key: "Te leveren")	`Logic4ProductStock.ReservedStock`	The reserved stock quantity, formatted to two decimal places. Calculated as `TotalStock - FreeStock` from Logic4 API.
`StockValues` (Key: "Schap Voorraad")	`Logic4ProductStock.FreeStock`	The free stock quantity, formatted to two decimal places.
`StockValues` (Key: "Next delivery")	`Logic4ProductStock.NextDelivery`	The next expected delivery date for stock, formatted as "dd-MMM-yyyy". Only included if a next delivery date is available.

Domain Specifics

Price Logic

The primary sales price (SalesPrice) for an item is taken directly from Logic4Product.SellPrice, representing the retail price excluding VAT for a single unit.

Logic4 also provides "shift prices" (product.ShiftPrices), which are tiered prices based on quantity. If the connector setting "Shift prices as free fields" is enabled, these tiered prices (for quantities greater than 1) are converted into free fields associated with the item. For example, a shift price for 5 units at €10.00 would appear as a free field "5 stuks: 10.00".

Additionally, the connector can retrieve live prices for a specific customer, item, and quantity via the GetItemPriceForCustomer method, which queries the /v1.1/Products/GetPriceInformationForProduct API endpoint and considers any configured shift prices.

Image Handling

The connector supports up to three images per product from Logic4, identified by ImageUrl1, ImageUrl2, and ImageUrl3.

Image downloading is conditional:

In debug mode, image download is typically disabled.
In release mode, images are downloaded unless FTP picture synchronization is enabled (controlled by FtpSyncManager.Instance.FtpPictureSyncEnabled).

Images are only downloaded if their URL has changed since the last synchronization, based on a comparison with previously stored ItemPictureLink information. Downloaded images are stored as raw byte arrays (ImageBytes1, ImageBytes2, ImageBytes3) and added to the App4Sales item's PicturesBytes collection after a hash check to prevent duplicates.

Stock & Availability

Basic stock information, specifically the LastAvailableStock (FreeStock), is directly mapped from the main product data.

When the "Item Stock Sync" setting is enabled in the administration session, a more detailed stock synchronization occurs:

The connector first identifies all relevant warehouses, either a default warehouse specified in settings or all warehouses associated with the administration.
It then retrieves detailed stock information from Logic4 using API calls to /v1/Stock/GetStockInformationForProduct (for single items) or /v1.1/Stock/GetStockForWarehouses (for multiple items).
This detailed stock information includes:
- Total Stock: The overall quantity of the item available.
- Reserved Stock: The quantity of the item that is reserved.
- Free Stock: The quantity of the item immediately available for sale.
- Next Delivery: Upcoming delivery dates and quantities for items.
These stock details are then added to the item's StockValues as structured key-value pairs (e.g., "Beschikbare voorraad", "Te leveren", "Schap Voorraad").

Matrix & Attributes

Item classification in App4Sales (ItemCategories and FreeItemFields) is extensively derived from Logic4 product groups and free values.

Product Groups: Logic4 product groups (Logic4ProductGroup) are hierarchical. The connector traverses this hierarchy to create App4Sales item categories. Each product group name in the hierarchy can become an ItemCategory and also contributes to the item's free fields. For example, if a product belongs to "Electronics > Laptops > Gaming", categories like "Electronics", "Laptops", and "Gaming" might be created.
Free Values: Any key-value pairs stored in product.FreeValues in Logic4 are directly mapped as ItemCategories and subsequently appear as free fields.
Pick Locations as Free Fields: If enabled, the name of the product's default pick stock location (derived from product.BasicData.DefaultPickStockLocationId and Logic4WarehouseStockLocation) is added as a free field (e.g., "Picklocatie: Main Warehouse A").

Special Logic & Filters

Language Code Update: The connector updates language codes in the App4Sales database based on the globalization codes found in product descriptions from Logic4. Only the first two characters of the globalization code are used.
Image Download Control: Image downloads are enabled in release builds unless overridden by the FTP picture synchronization setting. In debug builds, image downloads are generally off by default.
Stock Synchronization: Detailed stock updates (multi-warehouse, reserved, free stock, next delivery) only occur if the "Item Stock Sync" setting is enabled in the current administration session.
Batching for Basic Product Data: When fetching basic product data (e.g., descriptions), the Logic4 API requests are batched into chunks of 2000 product IDs to optimize performance and adhere to API limits.
Picture Link Caching: The connector uses stored ItemPictureLink information to determine if an image URL has changed, avoiding unnecessary re-downloads of product images.

Related Settings & Prerequisites

The following connector settings influence the Item Update process:

Item price includes VAT: (Internal name: ItemPriceInclVat)
Determines whether prices fetched from Logic4 are treated as including or excluding VAT in App4Sales. Affects the VatIncluded field.
Shift prices as free fields: (Internal name: ShiftPricesAsFreeFields)
If enabled, tiered pricing information (shift prices) from Logic4 will be added as free fields to the App4Sales item. This provides visibility to administrators about quantity-based pricing. Format: "Quantity stuks: Price".
Pick locations as free fields: (Internal name: PickLocationsAsFreeFields)
If enabled, the default pick stock location name for a product in Logic4 will be added as a free field to the App4Sales item. This helps identify the primary storage location. Format: "Picklocatie: LocationName".
Default warehouse ID: (Internal name: DefaultWarehouseId)
Specifies a default warehouse to use for stock synchronization. If set to 0 or not found, stock will be synchronized for all warehouses associated with the administration.
FTP picture sync enabled: (Managed by FtpSyncManager, not a direct connector setting)
If an external FTP picture synchronization process is active, the connector will skip downloading images directly from Logic4 to avoid conflicts or redundant operations.
Enable info logging: (Internal name: ConnectorBaseSettings.EnableInfoLogging)
If enabled, the connector will log detailed information about order statuses, VAT codes, shipping methods, and warehouses during setup, which can be useful for troubleshooting.
Item Stock Sync: (Internal name: SyncSettings.ItemStockSync)
This session-level setting must be enabled for the connector to perform detailed stock synchronization, including multi-warehouse stock, reserved quantities, and next delivery dates.

Known Limitations

The connector currently supports mapping up to 5 descriptions from Logic4 to App4Sales. Any additional descriptions from Logic4 will not be synchronized.
Image synchronization is limited to three image URLs (ImageUrl1, ImageUrl2, ImageUrl3) per product.

Logic4 - Item sync