DynamicsNav Connector - Item Update

The Item Update function synchronizes product information from Dynamics NAV to the App4Sales platform. This includes core item details, pricing, stock levels, classification attributes, and units of measure. The process involves retrieving items from Dynamics NAV via a SOAP web service, applying filtering rules, and transforming the data into App4Sales' internal item structure. Pagination is used during data retrieval to handle large datasets efficiently.

Data Source Configuration

Item data is sourced from a Dynamics NAV web service endpoint, typically exposed as an XMLport. The connector utilizes the APP4SALES_PortClient to invoke the ExportItems method on the Dynamics NAV system. This method fetches a comprehensive set of item details, including inventory, pricing, attributes, and translations. Data retrieval is paginated, with the page size configurable via connector settings. Additional data for item attributes and categories are fetched via ExportItemAttributes and ExportItemCategories methods, respectively.

Data Mapping Table - Item

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`ItemNo`	Direct mapping from Dynamics NAV Item Number.
`EanCode`	`ItemEANCode`	Direct mapping from Dynamics NAV EAN Code.
`Description`	`ItemDescription`, `ItemDescription2`	Mapped from `ItemDescription`. If 'Include Description 2 in item description' setting is enabled and `ItemDescription2` is available, it is appended as " - [ItemDescription2]".
`SalesPrice`	`SalesPriceUnitPrice`, `ItemUnitPrice`	Determined by 'Default salesprice based on pricelist' setting. If a specific pricelist code is configured, the price from that pricelist is used. Otherwise, the price for 'All Customers' with the lowest minimum quantity is selected. If no specific sales price is found, `ItemUnitPrice` is used as a fallback.
`Currency`	`SalesPriceCurrencyCode`	Derived from the selected default sales price.
`LastAvailableStock`	`ItemInventory`	Direct mapping of the item's current inventory level.
`VatPercentage`	`ItemVatPercentage`	Mapped from Dynamics NAV VAT percentage, converted to a decimal.
`PurchasePackageSize`	`ItemSalesUOM`	Parsed from the item's sales unit of measure. Defaults to 1 if parsing fails.
`AcceptsDefaultDiscount`	`SalesPriceAllowLineDisc`, `ItemDiscGroup`	Determined by several factors: If 'When line-discount is disabled for the price for all customers, no customer discount should be calculated for that item' setting is ON, and the default sales price explicitly disallows line discounts, then `False`. Otherwise, checks if the item's `ItemDiscGroup` is in the 'Discountgroups to exclude from default discount' setting. If it is, `False`; otherwise, `True`.
`Unit`	`SalesPriceUnitOfMeasure`	If 'Use default sales price unit as item unit' setting is enabled and a unit is specified for the default sales price, it is used as the item's unit.
Translated Descriptions (e.g., `Description2`, `Description3`)	`ItemTranslationDescription`, `ItemTranslationDescription2`	Based on `ItemTranslation` entries. The language mapping determines which App4Sales description field (up to 5) receives the translated text. If 'Include Description 2 in item description' is enabled, `ItemTranslationDescription2` is appended to the translated description.

Data Mapping Table - Staffle Prices (Tier Pricing)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ItemCode`	`ItemNo`	Mapped from the parent item's number.
`Price`	`SalesPriceUnitPrice`	The unit price for the specific tier.
`MinQuantity`	`SalesPriceMinimumQuantity`	The minimum quantity required to qualify for this price tier. Only prices with a minimum quantity greater than 1 are considered.
`CustomerCode`	`SalesPriceSalesCode`	Populated if `SalesPriceSalesType` is 'Customer'.
`CustomerGroup`	`SalesPriceSalesCode`	Populated if `SalesPriceSalesType` is 'Customer Price Group'.

Data Mapping Table - Price Lists

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Code` (PriceList)	`SalesPriceSalesCode`, `SalesPriceCurrencyCode`	If 'Pricelist based on code and currency' is enabled, the code is formatted as "[SalesPriceSalesCode]-[SalesPriceCurrencyCode]". Otherwise, it's directly `SalesPriceSalesCode`. Campaign pricelists and pricelists without a sales code are excluded.
`Description` (PriceList)	Derived	Same as the generated `Code`.
`Currency` (PriceList)	`SalesPriceCurrencyCode`	The currency code associated with the sales price.
`Selectable` (PriceList)	`SalesPriceSalesType`	Set to `True` if `SalesPriceSalesType` is 'Customer Price Group', indicating it's a customer-specific price list.
`ItemCode` (PriceListPrice)	`SalesPriceItemNo`	The item number for which this price applies.
`Price` (PriceListPrice)	`SalesPriceUnitPrice`	The unit price for the item within this price list.
`PriceListId` (PriceListPrice)	Derived	Internal ID generated from the PriceList `Code`.

Special Logic & Filters

The connector applies several filtering rules during item synchronization:

Item Inclusion: Only non-service items (ItemType '0') or service items where the 'Include service items in synchronization' setting is true are synced. Additionally, items marked as blocked are excluded unless 'Include blocked items in sync' is enabled.
Price List Filtering: Sales prices with a SalesPriceSalesType of 'Campaign' are excluded. Price lists without a defined SalesPriceSalesCode are also ignored. If 'Maximum quantity to load pricelist prices for' is set, only sales prices with a SalesPriceMinimumQuantity less than or equal to this value are included.
Error Handling: The system logs non-fatal errors from Dynamics NAV during item retrieval (e.g., when the end of data is reached during pagination) and continues the synchronization process. Other exceptions will halt the synchronization.
Pagination: Items are retrieved in pages. The 'Item Sync Page Size' setting controls how many items are fetched in each request. A value of 0 indicates legacy behavior with no paging.

Domain Specifics (Expanded)

Price Logic

The connector can determine item sales prices based on specific pricelists configured in Dynamics NAV. The 'Default salesprice based on pricelist' setting allows administrators to specify a particular pricelist code (e.g., "RRP") to be used as the primary source for item sales prices. If this setting is not used, the system will attempt to find a sales price applicable to 'All Customers' with the lowest minimum quantity. Tier pricing (staffle prices) is supported, where different prices apply based on the minimum purchase quantity. These are derived from the SalesPrice entries where SalesPriceMinimumQuantity is greater than 1.

The ConvertToPriceLists method generates App4Sales price lists and their associated prices based on the sales prices exported from Dynamics NAV. It can optionally combine the sales code and currency code to form unique pricelist identifiers, controlled by the 'Pricelist based on code and currency' setting.

Stock & Availability

The ItemInventory field from Dynamics NAV is mapped directly to LastAvailableStock in App4Sales. The connector allows for including or excluding service items and blocked items in the synchronization, as governed by the 'Include service items in synchronization' and 'Include blocked items in sync' settings, respectively.

Matrix & Attributes

Item classifications in App4Sales (ItemClasses, ItemClassValues, and Free Fields) are derived from several sources in Dynamics NAV:

Default Classes: 'Category' and 'Productgroup' ItemClasses are created from ItemCategoryDescription and ItemProductGroupDescription.
Item Categories: If an item has an ItemCategoryCode, the connector uses a hierarchical category tree (built from ExportItemCategories) to extract ItemClasses and Free Fields.
Item Attributes: For Dynamics NAV 2017 and higher, item attributes (ItemAttributeValueMapping) are converted into ItemClasses or Free Fields. The attribute's name and value, optionally combined with its unit of measure, form the basis for these classifications.
Custom Fields: User-defined custom fields (ItemCustomField) from Dynamics NAV are mapped as ItemClasses or Free Fields if both their name and value are present.
Custom Tables: Data from custom tables (ItemCustomTable) linked to items in Dynamics NAV can also be mapped as ItemClasses or Free Fields, using the table name, field name, and field value.
Units of Measure: Dimensions and quantities defined in ItemUOM (e.g., length, width, height, weight, cubage, quantity per unit) are also mapped as ItemClasses or Free Fields, prefixed with "[UnitOfMeasure]".

Related Settings & Prerequisites

The following connector settings influence the Item Update process:

Default salesprice based on pricelist: (Text) Specifies the pricelist code to be used as the default sales price source.
Include service items in synchronization: (Boolean) If checked, service items will be included in the synchronization.
VAT domestic posting group: (Text) Used in the ExportItems method call to Dynamics NAV, potentially influencing the VAT treatment of exported items.
Discountgroups to exclude from default discount: (Text, comma or semicolon separated) A list of item discount groups that should not receive default discounts in App4Sales.
Include blocked items in sync: (Boolean) If checked, items marked as blocked in Dynamics NAV will be included in the synchronization.
Include Description 2 in item description: (Boolean) If checked, the ItemDescription2 field from Dynamics NAV will be appended to the main item description and translated descriptions.
Maximum quantity to load pricelist prices for (used for tier pricing-pricelists): (Integer) Sets a maximum quantity for loading pricelist prices. Sales prices with a minimum quantity higher than this value will be excluded from price lists.
When line-discount is disabled for the price for all customers, no customer discount should be calculated for that item: (Boolean) If checked, and the default sales price disallows line discounts, then no customer discount will be applied to the item.
Use default sales price unit as item unit: (Boolean) If checked, the unit of measure from the default sales price will be used as the item's primary unit.
Pricelist based on code and currency: (Boolean) If checked, pricelist codes in App4Sales will be generated using both the sales code and the currency code (e.g., "RRP-EUR").

Known Limitations

The current implementation does not explicitly handle image synchronization directly within the ItemUpdate process. Image handling logic would need to be implemented separately or is assumed to be managed by other connector components. The mapping of Item Category hierarchies and Item Attributes relies on pre-built data structures (ItemCategoriesTree and attributeMap), implying these must be correctly configured and exported from Dynamics NAV.

DynamicsNav - Item sync