NewBaseV4 Connector - Item Update

The Item Update function in the NewBaseV4 connector synchronizes product information, including items, pricing, and stock, from the external NewBaseV4 ERP system to the internal App4Sales database. This process involves fetching product details, properties, descriptions, and static price breaks from NewBaseV4, applying various filters and transformations, and then updating the App4Sales Item, PriceList, and PriceListPrices entities. This synchronization ensures that App4Sales has up-to-date product catalogs, pricing, and stock availability for sales representatives.

Data Source Configuration

The NewBaseV4 connector retrieves product-related data from the NewBaseV4 API using a REST client configured with the connector's settings (Newbase Owner Id, Company Id, User Name, and User Password). Data is pulled from various API endpoints to construct the complete item information.

Product Properties: Fetched from the NewBaseV4 API to provide additional attributes for products. The specific endpoint and parameters are defined by NewBaseProductProperty.GetParameters().
Product Groups: Fetched from the NewBaseV4 API to categorize products. The specific endpoint and parameters are defined by NewBaseProductGroup.GetParameters().
Product Descriptions: Fetched from the NewBaseV4 API to provide detailed product descriptions in multiple languages. The specific endpoint and parameters are defined by NewbaseProductDescription.GetParameters().
Product Price Breaks (Static Prices): Fetched from the NewBaseV4 API to retrieve static pricing information for products. The specific endpoint and parameters are defined by NewBaseProductPriceBreak.GetParameters(NewBaseProductPriceBreakRequestType.StaticPrices). Only entries with a valid ProductId and ProductCode, and where Quantity Start is less than or equal to 0 or null, are considered.
NewBase Products: The core product data is fetched from the NewBaseV4 API. The specific endpoint and parameters are defined by NewBaseProduct.GetParameters(), which can be influenced by connector settings.
Stock: Stock information is retrieved via the StockProvider, which communicates with the NewBaseV4 API. Depending on the "Calculate stocks for composition products" setting, it may fetch stock for all products or specifically for composed products.
Value List: Contains various lookup values, including product property categories and product properties, which are used for item classification. This data is fetched from the NewBaseV4 API.

Data Mapping Table (Item)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	product.ItemCode	Direct mapping.
InternalItemCode	product.InternalId	Direct mapping.
CreatedDate	product.CreatedDate	Direct mapping.
EanCode	product.EanCode	Direct mapping.
SalesPrice	product.SalesPrice	Assigned based on the determined sales price from `NewBaseProductPriceBreak`. See "Price Logic" in Domain Specifics for details.
VatIncluded	'E'	Hardcoded value 'E'.
VatPercentage	product.VatCode	Derived from `product.VatCode`. Maps to HighVatNL, LowVatNL from application settings. If VatCode is null, NoVat, or Shifted, it defaults to 0.
FreeSortField	product.Remark	If the setting "Use product remark for free sort field" is enabled, the `product.Remark` is parsed as an integer. Otherwise, it defaults to 0.
ItemClasses	Derived	Mapped from `NewBaseProductGroup` entities and the `NewBaseProduct`. See "Matrix & Attributes" in Domain Specifics for details.
ItemCategories	Derived	Mapped from `product.Remark`, `product.RemarkComposition`, `product.InfoUrl`, `product.CostType`, `product.RemarkActivityLog` and `NewBaseProductProperty` entities. See "Classification & Attributes" in Domain Specifics for details.
LastAvailableStock	product.LastAvailableStock	Assigned based on stock provider. See "Stock & Availability" in Domain Specifics for details.
SearchDescription	Derived from ItemCategories	If the setting "Item category field for searchdescription" is configured, the value of the specified item category is used. Otherwise, it's null.
PicturesBytes	product.PictureBytes	Raw image bytes from `product.ImageUrl`. See "Image Handling" in Domain Specifics for details.
MinimumOrderQuantity	product.QtyOnPallet	If the setting "Use quantity on pallet as minimum order quantity" is enabled and `product.QtyOnPallet` is a valid decimal, it is used. Otherwise, it's not set.
Description (1-5)	NewbaseProductDescription.ProductDescr / product.Name	Product descriptions are mapped to Description1-5 fields based on language. If no description is found, `product.Name` is used for Description1.

Special Logic & Filters

Product Filtering: Before items are mapped to App4Sales models, a series of filters are applied to the products retrieved from NewBaseV4. These filters are controlled by connector settings:
- Blocked Products: Products marked as Blocked in NewBaseV4 are excluded from synchronization.
- Empty Item Code: Products with an empty NewBaseV4 ItemCode are excluded.
- Unique Products: Ensures that only unique products (based on InternalId) are processed.
- Skip Discontinued Products: If the setting "Don't sync discontinued products" is enabled, products marked as Discontinued in NewBaseV4 are excluded.
- Skip Products Without Sales Price: If the setting "Don't sync products without salesprice" is enabled, products that do not have a sales price determined are excluded.
- Skip Products with Name Prefix: If the setting "Don't sync products with internal name prefix (comma separated)" is configured, products whose name starts with any of the specified prefixes will be excluded.
- Sync Only Products with Subscription Types: If the setting "Only sync products with subscription types ids (comma separated)" is configured, only products matching the specified subscription types will be included.
- Sync Only Service Products: If the setting "Sync only service products" is enabled, only products marked as IsServiceProduct in NewBaseV4 will be included.
Price Selection: When multiple static price breaks are found for a product, the connector selects a single sales price based on the "Select maximum price for product" setting. If enabled, the maximum sales price is chosen; otherwise, the minimum sales price is used.

Domain Specifics

Price Logic

The sales price for an item is derived from the NewBaseProductPriceBreak entities.

The connector fetches static price breaks from NewBaseV4.
If multiple price breaks exist for a product and are identified as "Sales" price types, a single sales price is selected.
The selection logic is determined by the "Select maximum price for product" setting: if true, the highest sales price is used; otherwise, the lowest sales price is used.
The currency associated with the selected price break is also mapped.

Image Handling

Image bytes are retrieved from the ImageUrl property of the NewBase product.
Image synchronization is conditional: if the setting "Do not sync item pictures" is enabled, or if App4Sales is configured to use images only from PIM (Product Information Management), then no image synchronization occurs.
The retrieved image bytes are added to the App4Sales item's PicturesBytes collection, with a hash check to avoid duplicates.

Stock & Availability

Stock information is retrieved via the StockProvider from NewBaseV4.
The LastAvailableStock for an App4Sales item is set based on either the AvailableStock or TechnicalStock from NewBaseV4. This is controlled by the "Use available sales stock as available stock value" setting. If this setting is true, AvailableStock is used; otherwise, TechnicalStock is used.
If the setting "Calculate stocks for composition products" is enabled, the stock provider will fetch stock including composition products.

Matrix & Attributes

Item classifications and attributes are mapped from NewBaseV4 product groups and properties.

Item Classes: These are derived from NewBaseProductGroup entities linked to the product.
Item Categories: These are populated from several sources:
- product.Remark
- product.RemarkComposition
- product.InfoUrl
- product.CostType
- product.RemarkActivityLog
- Product Properties: If NewBaseProductProperty entities are available for a product, they are mapped to item categories. The PropertyCategory and Property values from NewBaseV4 are translated using the ValueList (ProductPropertyCategories and ProductProperties) and the default administration language. These are typically mapped as free fields.
- Extra Description: If NewbaseProductDescription.ProductDescrExtra is available, it is added as an item category, potentially with language-specific identifiers.

Related Settings & Prerequisites

The following connector settings influence the Item Update process:

Newbase Owner Id, Newbase Company Id, Newbase User Id, Newbase Owner Webservice User Name, Newbase Owner Webservice User Password: These credentials are required for authenticating with the NewBaseV4 API to retrieve product data.
Don't sync discontinued products: If enabled, products marked as discontinued in NewBaseV4 will not be synchronized to App4Sales.
Don't sync products without salesprice: If enabled, products for which a sales price cannot be determined will be excluded from synchronization.
Productgroup description: (Default: Productgroep) This setting can be used to override the default product group description.
Skip products with internal name prefix (comma separated): A comma-separated list of prefixes. Products whose names start with any of these prefixes will be skipped during synchronization.
Use product remark for free sort field: If enabled, the product's remark from NewBaseV4 will be used to populate the FreeSortField in App4Sales, attempting to parse it as an integer.
Item category field for searchdescription: Specifies which item category's value should be used for the App4Sales SearchDescription field.
Only sync products with subscription types ids (comma separated): A comma-separated list of subscription type IDs. Only products matching these subscription types will be synchronized.
Do not sync item pictures: If enabled, product images from NewBaseV4 will not be synchronized to App4Sales.
Sync only service products: If enabled, only products marked as "service products" in NewBaseV4 will be synchronized.
Calculate stocks for composition products: If enabled, the stock calculation will include composition products.
Select maximum price for product: If enabled, when multiple static prices are available, the highest sales price will be chosen; otherwise, the lowest will be used.
Use available sales stock as available stock value: If enabled, the AvailableStock from NewBaseV4 will be used for App4Sales's LastAvailableStock; otherwise, TechnicalStock will be used.
Use quantity on pallet as minimum order quantity: If enabled, the QtyOnPallet from NewBaseV4 will be used as the MinimumOrderQuantity in App4Sales if it's a valid decimal value.

NewBaseV4 - Item sync