Connector - Extra Item Data
The App4Sales platform allows for enriching item data with additional information through CSV files. This document explains how to configure and use the Extra Item Data and Extra Item Filter Data feeds.
Extra Item Data Feed
The Extra Item Data feed is used to add or override item properties, create item categories, and add free fields to items. The data is supplied as a CSV file, typically delivered via FTP.
Data Source Configuration
The CSV file for Extra Item Data is configured in the connector settings. This includes the file path, delimiter, and encoding. The connector reads this file and loads the data into a list of `CsvItem` objects.
Data Mapping
App4Sales Field | Source Field (CSV Column) | Logic/Notes |
Item Properties (e.g., `Description`, `SalesPrice`) | Column with the same name as the item property | If a column in the CSV has the same name as a property in the App4Sales `Item` object, and the value is not empty, the item property will be updated with the value from the CSV. This happens in the `OverrideValues` method. Properties like `ItemCode` and `FreeCsvFields` are explicitly skipped. |
ItemCategories | Any column that does not map to a specific `Item` property | Columns in the CSV that do not correspond to any of the `Item` properties are treated as "unknown elements." These are added to the item's `ItemCategories` dictionary. The column header becomes the category name (key), and the cell content becomes the category value. This is handled in the `SetItemCategories` method. |
FreeItemFields / FreeFieldList | Columns from the `ExtraItemData` feed | The connector can process the `ItemCategories` dictionary (filled from the unknown columns) to populate `FreeItemFields` as a serialized XML string and `FreeFieldList` for dynamic data. |
Item Filters & Classes
The Extra Item Filter Data feed is a separate CSV file used to create item classes and assign items to them. These are often used to create filters in the App4Sales application.
Data Source Configuration
Similar to the Extra Item Data feed, the CSV file for Item Filters is configured in the connector settings.
Data Mapping
App4Sales Entity | Source Field (CSV Column) | Logic/Notes |
ItemClass | `ItemClass` (from `GetItemClass()`) | The `ConvertToItemClassesAndValues` method reads the `ExtraItemFilterData` CSV. It uses the `GetItemClass()` method on each row to determine the name of the `ItemClass`. If an `ItemClass` with that name doesn't exist, a new one is created. The name is converted to lowercase to check for existence and a hash of the lowercase name is used as the ID for new classes. |
ItemClassValue | `ItemClassValue` (from `GetItemClassValue()`) and `ItemCode` | For each row in the `ExtraItemFilterData` CSV, an `ItemClassValue` is created. The value is determined by `GetItemClassValue()`, and it's associated with an item via `ItemCode`. This links an item to a specific value within an `ItemClass`. |
Special Logic & Filters
Processing Flow in `UpdateItems2`
An `ItemExtraDataServices` instance is created with the `ExtraItemData`.
`ExtendItemCategories` is called to populate the `ItemCategories` dictionary on each item with data from unknown columns in the extra item data CSV.
`OverrideValues` is called to update existing item properties from the extra item data CSV.
`ConvertToItemClassesAndValues` is called to process the `ExtraItemFilterData` and create `ItemClass` and `ItemClassValue` objects.
`FillItemClassesAndItemClassValues` is called to process any `ItemClasses` already on the `Item` object (including those added via `ExtendItemCategories`).
`UpdateItemClasses` and `UpdateItemClassValues` are called to save the classes and values to the database.
Validation & Fallbacks
Case-Insensitive Matching: When checking for items to update, the `ItemCode` and `InternalItemCode` from the extra data file are compared in a case-insensitive manner.
Duplicate ItemClassValues: The `ReplaceDuplicateItemClassValuesWhichAreCaseDifferent` method ensures that if two `ItemClassValue`s have the same `ItemClass` and `Value` but with different casing, they are treated as the same, and the first one's casing is used for all.
Description Truncation: `ItemClass` descriptions are truncated to 50 characters before being saved to the database to prevent errors.
Character Standardization: The `StandardizeCharacters` method is called on `ItemClass` and `ItemClassValue` objects to remove invalid characters. `ItemClassValue.Value` has the `=` character replaced with `๏ผ`.