MultiversExtendedV2 - Item Update

This process syncs item data from XML files, downloaded from an (S)FTP server, into the App4Sales database. It handles items, prices, stock, categories, and images. The synchronization processes files in a specific order, starting with categories, then prices, stock, and finally the item files themselves. It processes the newest files first and stops if it encounters a file with a different date to prevent using outdated information.

Data Source Configuration

The connector retrieves XML files from a configured (S)FTP server. The specific files and directories are configured in the connector settings.

Items: XML files containing the core item data. The file location is configured in the FtpItemLocation setting, and the file name prefix is configured in the FtpFileNameForItemSync setting.
Categories: XML files with item categories and classifications. The file location is configured in the FtpLocationCategories setting, and the file name prefix is configured in the FtpFileNameForCategorySync setting.
Prices: XML files containing price information. The file location is configured in the FtpLocationPrices setting, and the file name prefix is configured in the FtpFileNameForProductPrices setting.
Stock: XML files with stock information. The file location is configured in the FtpLocationStocks setting, and the file name prefix is configured in the FtpFileNameForProductStocks setting.
Images: Image files (e.g., JPG) are downloaded from the FTP server. The main image location is configured in FtpImageLocation, and a separate location for mood pictures can be set in FtpMoodPictureLocation.

Data Mapping Table - Items

App4Sales Field	Source Field (XML)	Logic/Notes
ItemCode	`ProductId`, `ExtProductId`, `UnitId`	The ItemCode is composed based on settings. It can be a combination of `ProductId`, `ExtProductId` and `UnitId`. Settings that influence this are: `UseExtendedProductId` and `ItemCodeWithoutUnit`.
InternalItemCode	`ProductId`	The internal item code is always the `ProductId` from the XML.
Description	`ProductDescription`, `Discontinued`	The item description. If the setting `UsePrefixForDiscontinuedItems` is enabled and the item is marked as discontinued, the prefix "Aflopend - " is added to the description.
SearchDescription	`Searchkeys`	The search keys for the item.
EanCode	`EanCode`	The EAN code of the item.
Unit	`UnitId`	The unit of the item.
PurchasePackageSize	`DeviationPackagingUnit` or a custom field	The purchase package size. By default, it's taken from `DeviationPackagingUnit`. A custom field can be configured using the `CustomFieldForPurchasePackageSize` setting. If `NormalizePurchasePackageSize` is enabled, this is set to 1.
VatPercentage	`VatPercentage`	The VAT percentage of the item.
LastAvailableStock	`StockQty1` or calculated	The available stock. It can be taken directly from `StockQty1`, calculated based on a formula, or retrieved from a separate stock file or API call. See the Stock & Availability section for more details.
IsActionItem	-	This is set to `true` if there is an active action price for the item.
AcceptsDefaultDiscount	-	This is set to `false` if the item is an action item.
FreeSortField	Category or Attribute	An integer value used for sorting. The source is determined by the `ItemAttributeForFreeSortField` setting, which can point to a category or an attribute.
RelatedItems	`ProductSubstitutes`	If the `UseProductSubstitutesForRelatedItems` setting is enabled, this field is filled with a list of related item codes based on the product substitutes from the XML.
Free Fields	Varies	Several pieces of information are mapped to free fields, including item status, unit description, and extra descriptions. See the "Special Logic & Filters" section for more details.

Data Mapping Table - Item Prices

App4Sales Field	Source Field (XML)	Logic/Notes
SalesPrice	`NettPrice`, `GrossPrice`, `PricePer`, `ConversionFactor`	The sales price of the item. The logic depends on several settings. If `SendPriceExclDiscount` is enabled, the `GrossPrice` is used; otherwise, the `NettPrice` is used. The price can be adjusted based on `PricePer` and `ConversionFactor` (if `NormalizePurchasePackageSize` is enabled).
Currency	`Currency`	The currency of the price.
VatIncluded	-	Hardcoded to 'E' (Excluded).

Data Mapping Table - Item Stock

App4Sales Field	Source Field (XML)	Logic/Notes
LastAvailableStock	`AvailableStock`, `ActualStock`, `ReservedStock`, `BlockedStock`	The stock is calculated based on a formula defined in the App4Sales settings. The formula uses fields from the `MultiversProductStock` entity, which is read from the stock XML files. If no stock file is provided, it can also be retrieved via an API call.
NextDelivery	-	The next delivery date, which can be retrieved from stock data.
StockIndicator	-	The stock indicator is calculated based on the `LastAvailableStock` and the thresholds defined in the App4Sales settings (`QuantityForRed` and `QuantityForGreen`).

Special Logic & Filters

Item Filtering: Items can be skipped based on several conditions:
- If they are blocked and SyncBlockedItems is disabled.
- If they are inactive and SyncInactiveItems is disabled.
- If they are discontinued and SkipDiscontinuedItems is enabled.
- If they match a specific attribute value defined in SkipItemsByAttribute.
- If no price information is found and DoNotSkipItemsWhenThereIsNoPriceInXml or DoNotSkipItemsWhenThereIsNoPriceInApi is disabled.
Status Free Field: A "Status" free field can be created with values based on the item's status (discontinued, inactive, blocked, active). The labels for these statuses are configured via settings like StatusFreeFieldTermForDiscontinuedItems.
Staffel/Tier Prices: The connector can create a "Staffel" free field containing tier pricing information. The logic for this is controlled by settings like AddStaffelBasedOnThisLadderPriceVolumeDiscount and PriceCodeForStaffel.
Multi-language Descriptions: The connector can handle multiple languages for item descriptions. The default language is set with DefaultLanguageCode, and additional languages can be configured. Short and long descriptions from the XML are mapped to the corresponding App4Sales description fields.

Domain Specifics

Price Logic

Prices are read from separate XML files specified by FtpLocationPrices and FtpFileNameForProductPrices. The connector can handle general prices, action prices, and tiered pricing (staffels). If the setting GetMultiversPriceList is enabled, the connector will also create and update pricelists and pricelist prices in App4Sales.

Image Handling

Images are downloaded from the (S)FTP server. The main image folder is configured in FtpImageLocation. Mood pictures for lookbooks can be downloaded from a separate folder specified in FtpMoodPictureLocation. The connector expects JPG files and matches them to items based on the item code.

Stock & Availability

Stock information is retrieved from XML files (configured via FtpLocationStocks and FtpFileNameForProductStocks) or through an API call. The final stock value is calculated using a formula that can be customized in the App4Sales settings. This formula can use fields like available stock, actual stock, reserved stock, and blocked stock from the source data. The connector can also determine the next delivery date.

Matrix & Attributes

The connector supports matrix items (parent/child relationships) and maps item attributes and categories to App4Sales item classes and free fields. Categories are read from the category XML files. The setting UseCodeForItemCategories determines whether the code or the description from the category is used for mapping. The connector can also create a hierarchical structure of item categories based on the MultiLevelItemCategories setting.

Related Settings & Prerequisites

FtpAddressForItemSync: The (S)FTP server address.
PortalUsername / PortalPassword: Credentials for the (S)FTP server.
UseSFTP: Must be enabled to use SFTP instead of FTP.
FtpItemLocation, FtpFileNameForItemSync: Path and file prefix for item XML files.
FtpLocationCategories, FtpFileNameForCategorySync: Path and file prefix for category XML files.
FtpLocationPrices, FtpFileNameForProductPrices: Path and file prefix for price XML files.
FtpLocationStocks, FtpFileNameForProductStocks: Path and file prefix for stock XML files.
UseExtendedProductId, ItemCodeWithoutUnit: Control the composition of the App4Sales ItemCode.
SyncBlockedItems, SyncInactiveItems, SkipDiscontinuedItems: Control which items are synchronized based on their status.
GetMultiversPriceList: Enables the synchronization of pricelists.
UseProductSubstitutesForRelatedItems: Enables the synchronization of related items.

Known Limitations

Based on the code analysis, the following limitations have been identified:

The connector seems to rely heavily on a specific naming convention for the XML files, including a date stamp (yyyyMMdd). Files that do not follow this convention might be ignored.
The error handling for file downloads is basic, with a retry mechanism of 5 attempts. If the FTP server is unreliable, this might lead to incomplete data synchronization.

MultiversExtendedV2 - Item sync