DbFact Connector - Item Update

This document details the process by which item data, including prices, images, and stock information, is synchronized from the DbFact ERP system into the App4Sales platform. The connector retrieves item information via a SOAP web service and transforms it into the App4Sales internal item model.

Data Source Configuration

The connector interacts with the DbFact ERP system primarily through SOAP web services.

Main Item Data: Item information is retrieved by calling the ArtExportDossier method of the DbFact web service. This method returns item data in an XML format.
Item Images: Item images are fetched through a separate web service call, GetArtImage. This service takes an image ID (obtained from the main item data) and returns the image content as a Base64 encoded string.
Item Stock: Basic stock levels are included in the main item data. For real-time stock checks, the connector utilizes the StockExportDossier web service method.

Data Mapping Table: Items

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	ArtNummer, VolgNummer, Referentie	Derived based on connector settings: If 'Use serial number as item code' is enabled, uses `VolgNummer`. If 'Use reference as item code (itemsync)' is enabled, uses `Referentie`. Otherwise, defaults to `ArtNummer`.
InternalItemCode	ArtCode	Direct mapping.
EanCode	StukNummer	Direct mapping.
Description	Omschrijving, ExtraTekstTaal1	If 'Use extra text as description' is enabled, uses `ExtraTekstTaal1`; otherwise, uses `Omschrijving`.
Description2	Omschrijving2, ExtraTekstTaal2	If 'Use extra text as description' is enabled, uses `ExtraTekstTaal2`; otherwise, uses `Omschrijving2`.
Description3	Omschrijving3, ExtraTekstTaal3	If 'Use extra text as description' is enabled, uses `ExtraTekstTaal3`; otherwise, uses `Omschrijving3`.
Description4	Omschrijving4, ExtraTekstTaal4	If 'Use extra text as description' is enabled, uses `ExtraTekstTaal4`; otherwise, uses `Omschrijving4`.
LastAvailableStock	Stock	Parsed as a decimal, invariant culture.
CreatedDate	CreatieDat	Parsed as a date with format "yyyyMMdd".
NextDelivery	VerwachtDat	Parsed as a date with format "yyyyMMdd". If empty or whitespace, set to null.
VatPercentage	BtwPercentage	Parsed as a decimal.
PurchasePackageSize	VerkoopsVerpakking, VerkoopsAantal	If 'Use VerkoopsVerpakking as purchase package size' is enabled, uses `VerkoopsVerpakking`; otherwise, uses `VerkoopsAantal`. Parsed as a decimal, invariant culture.
VatIncluded	Hardcoded	Hardcoded to 'E'.
Currency	Prices.Valuta	If `Prices.Valuta` is empty, whitespace, or longer than 3 characters, defaults to "EUR"; otherwise, uses the provided value.
Category / ItemClass / FreeField	Groep, Soort, Merk, Kleur, Status, VeldC1-C6, VeldN1-N5	Used for item classification and custom fields. Specific mapping details depend on configuration. The `GetFreeFields` method also adds "Verwachte Levertijd" (from `VerwachtDat`) and "Extra Tekst" (from `ExtraTekstTaal1`) as free fields.

Data Mapping Table: Item Prices

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
SalesPrice (various price lists)	WinkelExcl, WinkelIncl, Dealer, PromoPrijsExcl, PromoPrijsIncl, PromoPrijsDealerExcl, PromoPrijsDealerIncl, PromoPrijsMinVerkExcl, PromoPrijsMinVerkIncl, AanbevolenIncl, BasisExcl, MinimumVerkoopExcl, Prijs1, Prijs2, Prijs3, Prijs4, Prijs5	The specific price field used is determined by the connector settings `PriceList1Id` through `PriceList4Id`. If a configured price list ID matches a property in `DbFactArticlePrice`, that value is used. If no match is found or the value is empty, it falls back to `WinkelExcl`. All values are parsed as decimals (invariant culture).
PromotionPriceValidFrom	PromoPrijsVan	Date indicating the start of a promotion.
PromotionPriceValidTo	PromoPrijsTot	Date indicating the end of a promotion.

Special Logic & Filters

Item Code Resolution: The GetItemCode method dynamically determines the item code based on configured settings (UseSerialNumberAsItemCode, UseReferenceAsItemCode).
Sales Price Retrieval: The GetSalesPrice method allows for flexible price retrieval. It attempts to use the price field specified by the PriceListXId settings. If the specified field is not found or is empty, it defaults to WinkelExcl.
Free Sort Field: The GetFreeSortField method allows mapping a configurable field from the DbFact article to an integer for sorting purposes. It attempts to parse the value as an integer, taking only the part before any decimal separator.
Free Fields Generation: The GetFreeFields method generates additional free fields for the item, including "Verwachte Levertijd" (Expected Delivery Time) derived from VerwachtDat and "Extra Tekst" from ExtraTekstTaal1.
Image Processing: The MakePictureInBytes method is responsible for making a separate web service call (GetArtImage) to retrieve images for each item, which are then returned as a Base64 string.
Stock Retrieval: The OptA4SGetStockForItem method handles the real-time retrieval of stock information using the StockExportDossier web service.

Domain Specifics (Expanded)

Price Logic

Pricing in the DbFact connector is highly flexible and configurable. Item prices are sourced from the DbFactArticlePrice entity, which offers various price fields (e.g., WinkelExcl, Dealer, PromoPrijsExcl, Prijs1-Prijs5).

The connector uses the PriceList1Id to PriceList4Id settings to determine which specific price field from DbFact maps to an App4Sales sales price. If a configured price list ID does not correspond to an available price field or if the field's value is empty, the system defaults to using the WinkelExcl (Retail Price Excl. VAT) as the sales price.

Image Handling

Images for items are retrieved independently of the main item data. For each item, the connector makes a separate web service call to the GetArtImage method, passing an image ID. The image data is then received as a Base64 encoded string. The connector does not explicitly define any resizing, compression, or maximum image count logic within the observed code.

Stock & Availability

Basic stock information is provided within the primary item data (Stock field). For more dynamic or real-time stock figures, the connector leverages the StockExportDossier web service. The current implementation does not explicitly detail handling for multiple warehouses, reserved stock, or specific rules for zero/negative stock items beyond what is directly provided by the ERP.

Matrix & Attributes

The DbFact connector uses several fields for item classification and attributes:

Brand (Merk): The Merk field from DbFact is used to classify the item's brand.
Color (Kleur): The Kleur field serves as a classification for the item's color.
Status: The Status field provides an item's current status.
Group (Groep): The Groep field categorizes items into groups.
Type (Soort): The Soort field defines the item's type.
Free Fields: Generic free text/numeric fields (VeldC1-C6, VeldN1-N5) can be used for additional item attributes. The connector also generates "Verwachte Levertijd" (Expected Delivery Time) and "Extra Tekst" as free fields.

The investigation did not reveal specific functionality for handling complex matrix items or product variants where parent-child relationships are defined based on attributes like size and color. The Maat (Size) and Kleur (Color) fields are treated as simple classifications rather than dimensions of a matrix.

Related Settings & Prerequisites

The behavior of the Item Update process is influenced by the following connector settings:

Setting Name	Description
Environment	Specifies the DbFact environment to connect to.
Warehouse	Defines the warehouse to retrieve stock information from.
Dossier	The dossier number or identifier relevant for the DbFact integration.
Price List 1 Id	Identifier for the first price list to be used for item pricing. This maps to a specific price field in DbFact.
Price List 2 Id	Identifier for the second price list to be used for item pricing.
Price List 3 Id	Identifier for the third price list to be used for item pricing.
Price List 4 Id	Identifier for the fourth price list to be used for item pricing.
Item Status	Filter items based on their status in DbFact.
Free Sort Field	A DbFact article field used to define a custom sorting order for items.
Field C5 Article Exclude	If checked, items where DbFact field C5 is set will be excluded from the item sync.
Article Batch	Enables or disables batch processing for article updates.
Use Price Matrix	Indicates whether a price matrix (multi-dimensional pricing) is in use. (Note: Current code analysis did not reveal specific matrix item handling).
Use Serial Number As Item Code	If checked, the DbFact `VolgNummer` will be used as the App4Sales Item Code.
Use Extra Text As Description	If checked, the DbFact `ExtraTekstTaalX` fields will be used for item descriptions instead of `OmschrijvingX`.
Use Verkoops Verpakking As Purchase Package Size	If checked, the DbFact `VerkoopsVerpakking` field is mapped to the App4Sales Purchase Package Size; otherwise, `VerkoopsAantal` is used.
Use Groep And Soort As Item Filters	If checked, items can be filtered based on their 'Groep' and 'Soort' values.
Use reference as itemcode (itemsync)	If checked, the DbFact `Referentie` field will be used as the App4Sales Item Code, overriding 'Use Serial Number As Item Code' if both are active.

Known Limitations

Matrix/Variant Items: The current implementation does not appear to support the sophisticated handling of matrix items or product variants, where distinct child items are generated based on attribute combinations (e.g., Size, Color). The 'Maat' and 'Kleur' fields are treated as simple classifications.
Image Processing: While images are retrieved, the connector does not explicitly implement features like image resizing, compression, or enforcement of a maximum number of images per item.
Multi-Warehouse Stock: The current stock retrieval mechanism primarily focuses on a single warehouse as configured in the settings. There is no explicit support for synchronizing stock levels from multiple distinct warehouses.

DbFact - Item sync