RestJson Connector - Item Update
This document describes the process of synchronizing item data from a REST API to the App4Sales platform using the RestJson connector.
Data Source Configuration
The connector retrieves item data from a REST API. The base URL for the API is configured in the connector settings. The following endpoints are used for item synchronization:
/Items: Retrieves a list of all items./Warehouses: Retrieves warehouse information./PriceLists: Retrieves all available price lists.
Data Mapping
The following table outlines the mapping of fields from the RestJson API to the App4Sales database.
Items
App4Sales Field | Source Field (API) | Logic/Notes |
ItemCode | ItemCode | The value is trimmed. |
Description | Descriptions | The connector retrieves a list of descriptions in different languages. The correct description is selected based on the language configuration in App4Sales. |
SalesPrice | SalesPriceExcl | |
EanCode | EanCode | |
Unit | Unit | |
VatPercentage | VatPercentage | |
VatIncluded | 'E' | This field is hardcoded to 'E' (Exclusive). |
PurchasePackageSize | PurchasePackageSize | |
LastAvailableStock | LastAvailableStock | This value is used if the stock is not calculated from stock values. |
NextDelivery | NextDelivery | |
AcceptsDefaultDiscount | AcceptsDefaultDiscount | |
FreeSortField | FreeSortField | |
MatrixParent | MatrixCode | |
MatrixParentDescription | MatrixDescription | |
MatrixParentId | MatrixId | |
MatrixXValue | MatrixXValue | |
MatrixXDescription | MatrixXDescription | |
MatrixYValue | MatrixYValue | |
MatrixYDescription | MatrixYDescription | |
CreatedDate | Created | If the source field is null, the current date and time is used. |
Sysmodified | Modified | If the source field is null, the current date and time is used. |
Item Prices
App4Sales Field | Source Field (API) | Logic/Notes |
ItemCode | ItemCode | If the ItemCode is not present on a sales price, the ItemCode of the parent item is used. |
Price | PriceExcl | |
Code | PriceList | The connector maps the PriceList ID from the API to the correct PriceList Code in App4Sales. |
Item Groups and Classes
App4Sales Field | Source Field (API) | Logic/Notes |
ItemClasses | ItemGroups | The connector can create item classes in two ways, depending on the `UseMultipleItemGroupLevels` setting. See the "Matrix & Attributes" section for more details. |
Special Logic & Filters
Stock
The connector can retrieve stock information in two ways:
From the `LastAvailableStock` field on the item.
From a list of stock values (`StockValues`). If this list is present, the connector will calculate the available stock by executing a stock formula on the provided values.
If the `Warehouse` setting is not set, the connector will retrieve stock values for all warehouses.
Pictures
The connector can retrieve pictures from a list of picture URLs (`PictureUrls`) or from a single `PictureUrl` field. The pictures are downloaded and stored as Base64 strings. The connector uses a cache to avoid downloading the same picture multiple times. Pictures can be downloaded from a relative or absolute URL, depending on the `UseRelativePictureUrl` setting.
Item Classes
The creation of item classes is controlled by the `UseMultipleItemGroupLevels` setting.
When `UseMultipleItemGroupLevels` is enabled, the connector creates a hierarchical structure of item classes based on the `ItemGroups` list. Each level in the hierarchy corresponds to an `ItemClass`.
When `UseMultipleItemGroupLevels` is disabled, the connector creates a flat list of item classes. It uses the `Name` of the item group as the `ItemClass` description and the `Value` of the item group as the `ItemClassValue`.
Domain Specifics
Price Logic
The connector retrieves a list of all price lists from the `/PriceLists` endpoint. It then associates the sales prices with the correct price list based on the `PriceList` or `PriceListExternalId` field. If a price cannot be linked to a price list, it will be linked to the default price list (PriceList 1), unless the ERP provides a default price list itself.
Image Handling
Images are retrieved from the `PictureUrls` or `PictureUrl` field on an item. The connector downloads the images and stores them in the App4Sales database. A caching mechanism is in place to prevent downloading the same image multiple times in a single run. The `UseRelativePictureUrl` setting determines whether the picture URL is treated as a relative or absolute URL.
Stock & Availability
Stock can be provided in two ways. The `LastAvailableStock` field on an item provides a single stock value. Alternatively, a list of `StockValues` can be provided, which allows for more complex stock calculations. The connector executes a stock formula on these values to determine the final stock value.
Matrix & Attributes
The connector supports matrix items. The `MatrixCode`, `MatrixDescription`, and `MatrixId` fields are used to link a variant item to its parent. The `MatrixXValue`, `MatrixXDescription`, `MatrixYValue`, and `MatrixYDescription` fields are used to define the variant's properties.
Item attributes are created as `ItemClasses` and `ItemClassValues`. The `UseMultipleItemGroupLevels` setting controls how these are created from the `ItemGroups` data.
Related Settings & Prerequisites
UseMultipleItemGroupLevels: When enabled, the connector will create a hierarchical structure of item classes. When disabled, it will create a flat structure.UseRelativePictureUrl: When enabled, the connector will treat picture URLs as relative URLs.DisableBatchUpdate: When enabled, the connector will process items one by one instead of in batches. This setting is available to work around issues with specific ERP systems.DisallowDuplicateData: When enabled, the connector will throw an exception if duplicate items are detected in the API response.