EzXml Connector - Item Update

This document details the Item Update process for the EzXml connector. This process synchronizes item-related data from an external EzXml source (via FTP) into the App4Sales platform. It covers the retrieval of item catalog data, stock information, and semantic data, and then maps and transforms this data into App4Sales internal data structures such as Items, Matrix Parents, Children, Headers, Price Lists, and Item Categories.

Execution Flow

The Item Update is initiated by the ItemUpdate method in EzXmlConnector.cs. This method orchestrates the following high-level steps:

Fetches and processes item catalog data using ItemsService.SyncItems().
Imports semantic data for items using SemanticsService.ImportSemantics().
Updates the App4Sales database with the processed item data using DatabaseManager.Instance.UpdateItems2().

Data Source Configuration

The EzXml connector retrieves item data from several XML and CSV files, which are downloaded via FTP from a configured location.

Item Catalog Data: Retrieved from FD_catalog.xml. This file contains the core item definitions, styles, variants, and pricing.
Stock Data: Retrieved from FD_stock.xml. This file provides detailed stock levels and availability dates per item variant. If FD_stock.xml is not found or is empty, stock information from FD_catalog.xml is used as a fallback.
Semantic Data: Retrieved from semantics.csv. This CSV file provides additional categorization and descriptive information for items. The separator character for this CSV can be configured in the connector settings (default is comma).

Data Mapping Tables

Item (App4Sales.Models.ObjectsDb.Item)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`EzVariant.Id`	Direct mapping from the variant's unique identifier.
`Description`	`EzItem.Description`	Direct mapping from the item's general description. Also populated from multi-language description fields (`description_EN`, `description_NL`, etc.) based on `DescriptionFieldLanguageCodesContext` mapping.
`PurchasePackageSize`	`EzItem.MinimumOrderQuantity`	Mapped from `EzItem.min_order_qty`, parsed as an integer.
`VatPercentage`	`EzItem.VatPercentage`	Mapped from `EzItem.vat`, parsed as a decimal.
`VatIncluded`	`EzItem.PricesIncludingVat`	Set to 'I' if `EzItem.prices_including_vat` is true, otherwise 'E'.
`LastAvailableStock`	`EzVariant.Stock`	Mapped from `EzVariant.stock`, parsed as an integer.
`Unit`	`EzVariant.UnitOfMeasurement`	Direct mapping.
`EanCode`	`EzVariant.EanCode`	Mapped from `EzVariant.ean_barcode`.
`Currency`	`EzItemPrice.Currency`	Currency from the default price type (`PriceType = "D"`). If no default price is found, a default currency (if provided) is used.
`SalesPrice`	`EzItemPrice.UnitPrice`	Unit price from the default price type (`PriceType = "D"`). Defaults to 0 if not found.
`MatrixParent`	`EzItem.Number`	The Matrix Code of the parent item, derived from `EzItem.no`. Only set if the item is part of a matrix.
`MatrixParentDescription`	`EzItem.Description`	The description of the matrix parent, derived from `EzItem.description`. Only set if the item is part of a matrix.
`MatrixXDescription`	`EzVariant.Size`	The description of the matrix header (e.g., Size), derived from `EzVariant.size`.
`MatrixXValue`	`EzVariant.Size`	The value of the matrix header (e.g., Size Code), derived from `EzVariant.size`.
`MatrixXSequence`	Derived	Automatically generated sequence for matrix header.
`MatrixYDescription`	`EzStyle.ColorDescription`	The description of the matrix child (e.g., Color), derived from `EzStyle.color_description`.
`MatrixYValue`	`EzStyle.Color`	The value of the matrix child (e.g., Color Code), derived from `EzStyle.color`.
`MatrixYSequence`	`EzStyle.ColorSorting`	The sorting sequence for the matrix child, derived from `EzStyle.color_sorting`, parsed as an integer.

Item Prices (App4Sales.Models.PriceListPrice)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`PriceListId`	Derived	Hash code of the price list code.
`ItemCode`	`EzVariant.Id`	Direct mapping from the variant's unique identifier.
`Price`	`EzItemPrice.UnitPrice`	B2B price, mapped from `EzItemPrice.unit_price`, parsed as a decimal.
`Price`	`EzItemPrice.UnitListPrice`	Recommended retail price (RRP), mapped from `EzItemPrice.unit_list_price`, parsed as a decimal. Only created if different from `EzItemPrice.unit_price`.

Price Lists (App4Sales.Models.PriceList)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Code`	`EzItemPrice.PriceTypeCode`, `EzItemPrice.Currency`	If `EzItemPrice.price_type` is "D", code is "D". Otherwise, it's a concatenation of `EzItemPrice.price_type_code` and `EzItemPrice.currency` (e.g., "B2B-EUR"). For RRP prices, "RRP " is prepended to the code.
`Currency`	`EzItemPrice.Currency`	Direct mapping.
`Id`	Derived	Hash code of the price list code.

Matrix Parents (App4Sales.Models.MatrixParent)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`MatrixCode`	`EzItem.Number`	Direct mapping from the item's number (`EzItem.no`).
`Description`	`EzItem.Description`	Direct mapping from the item's description.
`UniqueID`	Derived	Hash code of the matrix parent.

Matrix Children (App4Sales.Models.MatrixChild)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`YCode`	`EzStyle.Color`	Direct mapping from the style's color code.
`Description`	`EzStyle.ColorDescription`	Direct mapping from the style's color description.
`Sequence`	`EzStyle.ColorSorting`	Mapped from the style's color sorting, parsed as an integer.
`UniqueId`	Derived	Hash code of the matrix child.

Matrix Children Extended (App4Sales.Models.MatrixChildEx)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ChildId`	Derived	Unique ID of the associated `MatrixChild`.
`Description`	`EzStyle.ColorDescriptionEN`, `EzStyle.ColorDescriptionIT`, `EzStyle.ColorDescriptionNL`, `EzStyle.ColorDescriptionFR`	Multi-language descriptions for the matrix child color. Each non-empty description creates a separate `MatrixChildEx` entry. Note: `EzStyle.ColorDescriptionDE` maps to language code "EN".
`LanguageCode`	Derived	"EN", "IT", "NL", "FR" based on the source description field.

Matrix Headers (App4Sales.Models.MatrixHeader)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Value`	`EzVariant.Size`	Direct mapping from the variant's size.
`Description`	`EzVariant.Size`	Direct mapping from the variant's size.
`UniqueIdentifier`	Derived	Hash code of the matrix header.

Domain Specifics (Expanded)

Price Logic

Prices are obtained from the <price> elements within each <variant> in FD_catalog.xml. Each <price> element can define different price types and currencies.

Default Price: Identified by price_type="D". The unit_price of this entry is used as the base SalesPrice for the item.
Multiple Price Lists: The connector supports multiple price lists. A price list code is generated based on the price_type_code and currency (e.g., "B2B-EUR").
Recommended Retail Price (RRP): If unit_list_price is different from unit_price, a separate price list is created with "RRP " prepended to the generated price list code.
Currency: The currency for a price list is taken directly from the currency field in the <price> element.

Image Handling

(No specific image handling logic was identified in the provided code snippets. Images are not directly processed or mapped by this connector's Item Update. Further investigation into other connector components might be necessary if image synchronization is expected.)

Stock & Availability

Stock information is primarily sourced from FD_stock.xml, which contains <variant> elements with id, stock, and available_on fields.

Stock Source Fallback: If FD_stock.xml is not found or contains no variants, stock information is extracted from the <variant> elements within FD_catalog.xml.
Current Available Stock: Stock values where available_on is empty or matches the current date are considered current available stock (mapped to Core.Constants.Stock.AvailableStock).
Future Stock: Stock values with an available_on date in the future are treated as "to be received" stock and are associated with a NextDeliveryDate (mapped to Core.Constants.Stock.ToBeReceived and Core.Constants.Stock.NextDeliveryDate).
Past Dates: Stock entries with `available_on` dates in the past are ignored.

Matrix & Attributes

The connector handles matrix (parent-child) items, where an EzItem can have multiple EzStyle entries, and each EzStyle can have multiple EzVariant entries.

Matrix Parent Identification: An item is considered a matrix parent if it has multiple styles or variants, or if its model number is different from its variant ID when there's only one style and variant.
Parent-Child Linking: EzItem.Number forms the MatrixCode for the parent. EzStyle.Color and EzStyle.ColorDescription are used for the Y-axis (MatrixChild) values. EzVariant.Size is used for the X-axis (MatrixHeader) values.
Attributes from Catalog:
- Brand: Mapped from EzItem.brand_id, matched against <brand> elements in FD_catalog.xml. Stored as an Item Category named "Brand".
- Category: Mapped from EzItem.category_id, matched against <category> elements in FD_catalog.xml. Stored as an Item Category named "Category".
- Product Group: Mapped from EzItem.productgroup_id, matched against <productgroup> elements in FD_catalog.xml. Stored as an Item Category named "Product Group".
- Collection: Mapped from EzItem.collection_id, matched against <collection> elements in FD_catalog.xml. Stored as an Item Category named "Collection".
- Season: Mapped from EzItem.season_id, matched against <season> elements in FD_catalog.xml. Stored as an Item Category named "Season".
Extra Filters: Up to five extra filters (EzItem.extra_filters.extra_filter_1 to extra_filter_5) can be applied. These are matched against <extra_filter> and their <filtervalue> elements in FD_catalog.xml. Each matched filter is added as an Item Category, with the category name taken from EzExtraFilter.description and the value from ExFilterValue.description.
Semantic Data Attributes: The semantics.csv file can provide additional item categories. Any column in semantics.csv other than "ItemCode" or "Modelnummer" is treated as an item category. These categories are applied to items either by matching ItemCode directly or by matching Modelnummer to the MatrixParent code, applying the category to all child items of that matrix parent.

Related Settings & Prerequisites

The following connector settings and prerequisites impact the item update process:

Separator Character: Used for parsing semantics.csv. Configurable via a connector setting, defaults to comma (,).
FTP Access: The connector requires read access to an FTP server to download FD_catalog.xml, FD_stock.xml, and semantics.csv from the configured import folder(s).

Known Limitations

The connector assumes that multi-language color descriptions (e.g., EzStyle.ColorDescriptionDE) when mapped to MatrixChildEx, the DE (German) description maps to language code "EN" (English). This might be an oversight or an intentional mapping.

EzXml - Item sync