DkHome Connector - Item Update
The DkHome Connector's Item Update function synchronizes product information from the DkHome REST API to the App4Sales internal item database. This process runs periodically to ensure that product details, pricing, stock levels, images, and classifications are up-to-date within the App4Sales platform. It retrieves items in batches and processes them, updating various related entities like item descriptions, free fields, prices, and classifications.
Data Source Configuration
The DkHome connector retrieves item data via a REST API, which is configured using various endpoints. The base URL for the API is defined in the connector's settings. Data is pulled from the API in a paginated manner, allowing for efficient synchronization of large datasets.
Items: Fetched from the
/Itemsendpoint. Supports pagination using the$skipparameter (e.g.,/Items?$orderby=ItemCode&$skip={offset}).Sales Prices: Item-specific sales prices are included with each item or fetched in batches from the
/ItemPricesendpoint ifUseItemPricesBatchis enabled.Warehouses: Retrieved from the
/Warehousesendpoint.Item Group Name Translations: Retrieved from the
/ItemGroupNameTranslationsendpoint.Item Group Value Translations: Retrieved from the
/ItemGroupValueTranslationsendpoint.
Data Mapping Table: Items (RestJsonItem to App4Sales Item)
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| Timestamp of item creation. Falls back to current date/time if source is null. |
|
| European Article Number. Direct mapping. |
|
| A flexible field for custom sorting criteria. Direct mapping. |
|
| Unique identifier for the item. Whitespace is trimmed. |
|
| The most recently available stock quantity. Direct mapping. |
|
| Expected date of next stock delivery. Direct mapping. |
|
| Quantity per purchase package. Direct mapping. |
|
| Base sales price excluding VAT. |
|
| Unit of measure for the item (e.g., 'pcs', 'kg'). Direct mapping. |
|
| Timestamp of last modification in the ERP. Falls back to current date/time if source is null. |
| Derived | Hardcoded to 'E'. |
|
| The VAT percentage applicable to the item. Direct mapping. |
|
| Boolean indicating if the item is eligible for default discounts. Direct mapping. |
|
| Code for the parent item in a matrix structure. |
|
| Description for the parent item in a matrix structure. |
|
| Unique ID for the parent item in a matrix structure. |
|
| Value for the X-axis of a matrix item (e.g., 'Small', 'Red'). |
|
| Description for the X-axis of a matrix item. |
|
| Value for the Y-axis of a matrix item (e.g., 'Cotton', 'Blue'). |
|
| Description for the Y-axis of a matrix item. |
Data Mapping Table: Item Descriptions
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| The |
Data Mapping Table: Free Item Fields
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| Converts a list of key-value pairs ( |
Data Mapping Table: Item Prices
The connector processes sales prices provided with the items. Each RestJsonItemPrice from the source is used to update the App4Sales item price data.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| The |
|
| The sales price excluding VAT. |
|
| The connector attempts to match the |
Data Mapping Table: Item Classes / Item Groups (Hierarchical - when 'Use multiple item group levels' is enabled)
When the 'Use multiple item group levels' setting is enabled, the connector processes hierarchical item groups from the source. These are mapped to App4Sales ItemClass and ItemClassValueDescription entities.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
| Derived from hierarchy level | The description of the ItemClass is set to the hierarchy level (e.g., "1", "2", "3"). |
| Derived from hierarchy level | The ID of the ItemClass is set to the hierarchy level (e.g., 1, 2, 3). |
|
| The concrete value for an ItemClass. |
|
| Translations for the |
Data Mapping Table: Item Classes / Item Groups (Flat - when 'Use multiple item group levels' is disabled)
When the 'Use multiple item group levels' setting is disabled, the connector processes a flat list of item groups from the source. These are mapped to App4Sales ItemClass entities.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| The name of the item class. |
|
| The concrete value for the item class, only if |
Special Logic & Filters
Pagination: Items are retrieved iteratively using
$skipto handle large datasets, fetching a batch of items in each loop.Duplicate Item Code Detection: If
DisallowDuplicateDatais enabled in settings, the system checks for duplicate item codes within batches. If duplicates are found, the synchronization is stopped.Batch Update Control: The synchronization loop can be prematurely exited if
DisableBatchUpdateis enabled in settings (e.g., for specific legacy connectors).Item Group Processing: The method uses
UseMultipleItemGroupLevelssetting to determine whether to process item groups as a flat list or a hierarchical structure (Lookbooks/Editions).If
UseMultipleItemGroupLevelsis true andSession.Administration.Upgradedis true, Lookbooks and Lookbook Items are updated.If
UseMultipleItemGroupLevelsis true andSession.Administration.Upgradedis false, Editions and Mood Pictures are updated.
Picture Handling: Images are downloaded only if
AdministrationSession.CurrentSession.PimSettings.UseImagesOnlyFromPIMis false. Pictures can be downloaded fromPictureUrls(a list of URLs with sequence) or a singlePictureUrl.SetPictureOnItem: This helper method downloads images from the provided URL, handles Base64 conversion, caches downloaded images to avoid re-downloading, and stores them initem.PicturesBytes. It also tracks invalid URLs to prevent repeated download attempts.Settings.UseRelativePictureUrldetermines whether to download raw content or from a full URL.
Stock Indicator: The item's
StockIndicatoris taken directly from theRestJsonItemif available; otherwise, it's looked up from the database using theItemCode. If no stock indicator is found, it defaults to -1.Full Stock Values: If a specific
Settings.Warehouseis not defined, andRestJsonItem.StockValuesare present, these are stored infullStockValues. IfAvailableStockis not explicitly provided inStockValues, it's calculated using a formula (`ExecuteStockFormula()`).Language Processing: Languages for descriptions are added dynamically based on available translations.
Error Handling: Catches
RestException,RequestException, and generalExceptionduring API calls and processing, logging errors with relevant context (route, content).
Domain Specifics (Expanded)
Price Logic
The DkHome connector retrieves sales prices directly from the SalesPriceExcl field within the item data or via a batch call to the /ItemPrices endpoint. These prices are stored in the App4Sales system as ItemPriceDataTable entries.
**Base Price:**
SalesPriceExclfrom theRestJsonItemmaps toSalesPricein App4Sales.**Price Lists:** The
PriceListGUID orPriceListExternalIdassociated with each sales price from the source is used to identify or create the corresponding Price List in App4Sales.If the ERP provides a PriceList with Code 1, this is used as the default.
If no PriceList is explicitly linked to a price and no ERP-provided PriceList with Code 1 exists, a "Default" Price List (Code 1) is created in App4Sales.
Prices from the ERP that are not linked to a known PriceList are skipped if a default PriceList 1 is already provided by the ERP.
**Currency:** The currency symbol for the default price list is derived from
Session.Administration.CurrencySymbol.
Image Handling
The connector can retrieve product images from specified URLs. This process is active only if images are not solely managed by PIM (Product Information Management) system.
**Data Sources:** Image URLs are provided either as a list (
PictureUrls) with sequence numbers or as a singlePictureUrlwithin theRestJsonItementity.**Filenames & Matching:** Image URLs are processed directly.
**Formats:** Assumes images can be converted to Base64.
**Limitations:** No explicit resize/compression logic is mentioned in the code; it downloads and converts the image as-is. Error handling is present for download failures and invalid Base64 strings. Missing images will result in an empty
Base64Pictureand the URL being marked as invalid.**Relative URLs:** The
UseRelativePictureUrlsetting determines if image URLs are treated as relative paths for downloading raw content.
Stock & Availability
Stock information is updated with each item synchronization, providing both an overall stock indicator and detailed stock values per item.
**Stock Indicator:** The
StockIndicator(integer) from theRestJsonItemis directly used if available. Otherwise, the system attempts to retrieve it from existing stock indicators in the database based on theItemCode. If still not found, it defaults to -1.**Detailed Stock Values:** The
StockValues(a list of key-value pairs likeAvailableStock,ShelfStock,ToBeReceived,ToBeDelivered) from theRestJsonItemare used when no specific warehouse is configured in settings.LastAvailableStockin App4Sales is set fromRestJsonItem.LastAvailableStockdirectly, or calculated using theExecuteStockFormula()if not explicitly provided inStockValues.
**Multi-warehouse:** The
Warehousesetting allows filtering stock for a specific warehouse. If this setting is empty, all stock values provided by the ERP are considered.
Matrix & Attributes
The DkHome connector supports the synchronization of matrix items and their attributes.
**Parent-Child Relationships:** Identified through
MatrixCode,MatrixDescription, andMatrixId(for the parent) andMatrixXValue,MatrixXDescription,MatrixYValue,MatrixYDescriptionfor the child variants.**Attributes:** Item classifications are handled via Item Groups from the source.
Classification & Attributes
Item classifications are derived from RestJsonItemGroup entities, which can be processed in a flat or hierarchical manner based on connector settings.
**Item Classes & Values:**
RestJsonItemGroup.NameandRestJsonItemGroup.Valueare used to createItemClassandItemClassValueobjects in App4Sales. TheDutchTextproperty can serve as a fallback for theItemClassValue.ValueifNameis empty.**Hierarchical (Lookbooks/Editions):** If
UseMultipleItemGroupLevelsis enabled, item groups are mapped to a multi-level structure.Level "1", "2", etc., become
ItemClass.DescriptionandItemClass.Id.Translations for
ItemClassValueDescription(Dutch, German, French) are created fromRestJsonItemGroup.DutchText,GermanText,FrenchText.
**Translations:** Item group names and values can have associated translations which are retrieved from the API via
/ItemGroupNameTranslationsand/ItemGroupValueTranslationsendpoints and used to updateItemClassDescriptionsandItemClassValueDescriptions.
Related Settings & Prerequisites
The following settings influence the DkHome Item Update process. These can typically be configured in the App4Sales administration panel for the connector instance.
Warehouse: (Text field) Specifies a default warehouse code to filter stock data. If left empty, all stock values provided by the ERP are considered.Use Relative Picture Url: (Boolean) If true, picture URLs are treated as relative paths for raw content download; otherwise, they are treated as full URLs.Use Multiple Item Group Levels: (Boolean) If true, item groups are processed as a hierarchical structure (Lookbooks/Editions); otherwise, they are processed as a flat list.Real-time info calls based on comma-separated: (Boolean) Influences the format of URL parameters for real-time information queries, including item stock.Supports Stock Batch Call: (Boolean, defaults to true) Indicates if the connector supports batch calls for stock retrieval.Disallow Duplicate Data: (Boolean) If true, the connector will throw an exception and stop synchronization if duplicate item codes are detected within a batch, indicating instability in the REST API implementation.Disable Batch Update: (Boolean) If true, the item update process will stop after the first batch, typically used for connectors with specific limitations.Use Warehouse From User: (Boolean) If true, the warehouse for stock searches will be determined from the logged-in user's warehouse setting, overriding the connector's defaultWarehousesetting.Use Stock For Items Batch: (Boolean) If true, the connector attempts to retrieve stock for multiple items in a single batch call.Use Item Prices Batch: (Boolean) If true, the connector attempts to retrieve item prices for multiple items in a single batch call (via the/ItemPricesendpoint).Use Url Parameters For Item Stock Search: (Boolean) If true, item stock search uses URL parameters (e.g.,?ItemCode=X&Warehouse=Y). If false, it uses OData filtering.Use OData Filter For Stock: (Boolean) If true, OData filter syntax is used for item stock queries (e.g.,$filter=ItemCode eq 'X').
Known Limitations
The connector hardcodes
VatIncludedto 'E'. If DkHome uses a different logic for VAT inclusion, this might lead to discrepancies.Image resizing or compression is not explicitly handled by the connector; images are downloaded and stored as-is.
The system explicitly checks for and throws an exception on duplicate item codes if
DisallowDuplicateDatais enabled, suggesting potential issues with the source API's data consistency for certain ERPs.If the ERP provides a PriceList with Code 1, prices without an explicit price list are skipped to prevent overwriting ERP data, which means if the default PriceList in DkHome is not consistently linked to all prices, some prices might not be synchronized.