DynamicsNAV Connector - Customer Update

This document describes how customer data is synchronized from Dynamics NAV into the App4Sales platform. The process involves retrieving customer, address, and contact person information from Dynamics NAV, transforming it into the App4Sales internal data structure, and updating the App4Sales database. It also handles associated entities like customer notes, item class discounts, and customer dashboards.

Data Source Configuration

Customer data is pulled from Dynamics NAV using a webservice call to the ExportCustomers endpoint. The retrieval is paginated, with the page size controlled by the CustomerSyncPageSize setting. Customers can be excluded based on their 'Blocked' status in Dynamics NAV, configured via the ExcludeCustomers setting.

The connector connects to Dynamics NAV using the URL, username, password, and authentication type specified in the connector settings. The authentication type can be configured as Windows, Ntlm, Digest, or Basic using the AuthenticationType setting.

Customer Data Mapping

App4Sales Field	Source Field (Dynamics NAV)	Logic/Notes
CustomerCode	`CustomerNo`	Direct mapping.
CustomerName	`CustomerName`	Direct mapping.
VatCode	`CustomerVatRegistrationNo`	Direct mapping. This field is set to null if the App4Sales administration is configured for USA.
FreeFields	Dynamic	Populated from a combination of the `CustomerFreeFieldsConfig` setting and `CustomerCustomfield` or `CustomerCustomTable` fields. Fields prefixed with `CustomField.` or `CustomTable.` (e.g., `CustomField.EmailInvoice`) are mapped from corresponding custom fields in Dynamics NAV.
DynamicFreeFields	Dynamic	Populated from `CustomExtraField` definitions. These can map directly from properties of the Dynamics NAV customer entity (e.g., `CustomerCreditLimitLCY`) or from specific custom fields (prefixed with `CustomField.`). The values are serialized to XML.
Discount	`CustomerInvoiceDiscountDiscountPercentage` or Custom Fields	If `DiscountCustomTableField` setting is defined and starts with "CustomTable.", the discount is read from the corresponding `ItemCustomTableFieldValue`. If `DiscountCustomTableField` setting is defined and starts with "CustomField.", the discount is read from the corresponding `CustomerCustomfieldValue`. Otherwise, it's read from `CustomerInvoiceDiscount.CustomerInvoiceDiscountDiscountPercentage`. The value is parsed to a decimal.
VatLiable	`CustomerVatYesNo`	Converts the string "Yes" or "No" from Dynamics NAV to a boolean value. This field is set to false if the App4Sales administration is configured for USA.
UsesPriceField	`CustomerPriceGroup`, `CustomerCurrencyCode`	Determines the App4Sales PriceList ID. If `PriceListBasedOnCodeAndCurrency` is true, the pricelist code is constructed as "{CustomerPriceGroup}-{customerCurrency}". Otherwise, it uses `CustomerPriceGroup` directly. Matches this code against existing App4Sales pricelists. Falls back to 0 if no matching pricelist is found.
CustomerManager	`CustomerSalespersonCode`	Direct mapping.
PaymentConditionCode	`CustomerPaymentTermsCode`	Direct mapping. If empty, it's set to null to prevent foreign key issues.
DiscountGroup	`CustomerCustomerDiscGroup`	Direct mapping.
LanguageCode	`CustomerLanguageCode`	Direct mapping, then mapped to App4Sales language codes using the `MappedLanguages` configuration.
Phone	`CustomerPhoneNo`	Direct mapping, trimmed for whitespace.
Email	`CustomerEmail`	Direct mapping, trimmed for whitespace.
MainContactPerson	Dynamic	If `ContactFunctionToDetermineMain` setting is specified, the contact person whose 'Function' matches this setting is designated as the main contact. Otherwise, the contact person whose `ContactId` matches `CustomerPrimaryContactNo` is designated as the main contact. If no explicit main contact is identified, the first available contact person is set as main.
CustomerDashboard	`CustomerDashboard`	Base64 encoded string from Dynamics NAV. Decoded and stored separately. The field in the App4Sales customer object is set to null after processing to optimize memory.
CustomerNote	`CustomerComments`	Dynamics NAV `CustomerComments` are converted to App4Sales `CustomerNote` objects. These notes are recreated (deleted and inserted) during each sync.

Addresses

App4Sales distinguishes between Invoice, Delivery, and Visit addresses. The connector consolidates address information from various Dynamics NAV fields.

App4Sales Field	Source Field (Dynamics NAV)	Logic/Notes
Invoice Address (AddressType: "INV")	Invoice Address (AddressType: "INV")	Invoice Address (AddressType: "INV")
AddressLine1	`CustomerAddres`	Direct mapping.
AddressLine2	`CustomerAddres2`	Direct mapping.
PostCode	`CustomerPostCode`	Direct mapping.
City	`CustomerCity`	Direct mapping.
Country	`CustomerCountryRegion`	Direct mapping.
Iso2	`CustomerCountryRegionCode`	Direct mapping, then normalized using `MappedCountries` configuration.
Email	`CustomerEmail`	Direct mapping.
Phone	`CustomerPhoneNo`	Direct mapping.
Delivery Addresses (AddressType: "DEL")	Delivery Addresses (AddressType: "DEL")	Delivery Addresses (AddressType: "DEL")
AddressLine1	`CustomerShipToAddressAddress`	If no specific Ship-To Address exists, the Invoice Address is used as a fallback.
AddressLine2	`CustomerShipToAddressAddress2`	If no specific Ship-To Address exists, the Invoice Address is used as a fallback.
AddressLine3	`CustomerShipToAddressCode`	Used for internal processing (e.g., when sending orders).
PostCode	`CustomerShipToAddressPostCode`	If no specific Ship-To Address exists, the Invoice Address is used as a fallback.
City	`CustomerShipToAddressCity`	If no specific Ship-To Address exists, the Invoice Address is used as a fallback.
Country	`CustomerShipToAddressCountryRegion`	If no specific Ship-To Address exists, the Invoice Address is used as a fallback.
Iso2	`CustomerShipToAddressCountryRegionCode`	If no specific Ship-To Address exists, the Invoice Address's `CustomerCountryRegionCode` is used as a fallback. Normalized using `MappedCountries` configuration.
Phone	`CustomerShipToAddressPhoneNo`	Direct mapping.
Contact	`CustomerShipToAddressContact`	Direct mapping.
Visit Addresses (AddressType: "VIS")	Visit Addresses (AddressType: "VIS")	Visit Addresses (AddressType: "VIS")
AddressLine1	`ContactAddres` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
AddressLine2	`ContactAddres2` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
PostCode	`ContactPostCode` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
City	`ContactCity` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
Country	`ContactCountryRegion` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
Email	`ContactEmail` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.
Phone	`ContactPhoneNo` (from `entity.Contact`)	If no specific contact address exists, the Invoice Address is used as a fallback.

Contacts

Contact persons associated with the customer are mapped from Dynamics NAV. Full name parsing and dynamic free field mapping are supported.

App4Sales Field	Source Field (Dynamics NAV)	Logic/Notes
ContactId	`ContactNo`	If empty and the system is running in Updater mode, a ContactId is generated from the hash code of the contact person object.
FullName	`ContactName`	If `FirstName`, `LastName`, and `MiddleName` are null but `FullName` is present, `FullName` is parsed to populate the individual name fields. If `FullName` is null but individual name fields are present, `FullName` is constructed from them.
FirstName	Derived from `ContactName`	Parsed from `FullName`.
MiddleName	Derived from `ContactName`	Parsed from `FullName`.
LastName	Derived from `ContactName`	Parsed from `FullName`.
Initials	Derived from `FirstName`	First character of `FirstName`.
Email	`ContactEmail`	Direct mapping, trimmed for whitespace.
Phonenumber	`ContactPhoneNo`	Direct mapping.
MobileNumber	`ContactMobilePhoneNo`	Direct mapping.
Function	`ContactJobTitle`	Direct mapping.
DynamicFreeFields	Dynamic	Similar to customer dynamic free fields, contact person dynamic free fields are mapped from `CustomExtraField` definitions and serialized to XML.

Discounts

Customer-specific discounts, including those per item class value, are synchronized.

App4Sales Field	Source Field (Dynamics NAV)	Logic/Notes
DiscountsPerItemCLassValue	Derived from Extra Data (CSV/FTP)	If `CustomerItemFilter` setting is enabled and extra data for the customer contains fields prefixed with "ItemFilter_", these are parsed as item class value discounts. The values from the extra data are expected to be "~" separated. Only discounts with a value greater than 0 are processed.

Dashboards & Notes

Customer dashboard layouts and notes are synchronized. Customer dashboards are base64 encoded XML structures.

App4Sales Field	Source Field (Dynamics NAV)	Logic/Notes
CustomerDashboard	`CustomerDashboard`	Base64-encoded string representing the dashboard layout. This is decoded and stored separately in the database. The customer object's `CustomerDashboard` field is then cleared to save memory.
CustomerNotes	`CustomerComments`	`CustomerComments` from Dynamics NAV are converted into App4Sales `CustomerNote` objects. Existing notes for the customer from the "BackOffice" are deleted before new ones are inserted. The Subject of the note is currently mapped from the comment date.

Extra Data & Free Fields

Extra data from FTP/CSV sources can override standard customer fields and populate free fields.

App4Sales Field	Source Field (FTP/CSV Extra Data)	Logic/Notes
Customer properties	Matching property names in `CsvCustomer`	Properties in the `CsvCustomer` object (derived from FTP/CSV extra data) with non-null values will overwrite corresponding properties in the App4Sales Customer object if their names match.
FreeFieldList	`UnknownElements` prefixed with "FreeField_"	Elements in the `UnknownElements` dictionary of the `CsvCustomer` object that start with "FreeField_" (e.g., "FreeField_MyCustomField") are added to the customer's `FreeFieldList`. The prefix "FreeField_" is removed to get the caption.
ItemFilter	`UnknownElements` prefixed with "ItemFilter_"	If `CustomerItemFilter` setting is enabled, elements in `UnknownElements` starting with "ItemFilter_" are parsed to create customer-specific item filters. The values are expected to be delimited by "~".

Special Logic & Filters

Paging: Customer retrieval from Dynamics NAV uses pagination, configured by the CustomerSyncPageSize setting.
Customer Exclusion: Customers can be excluded from synchronization based on their 'Blocked' status in Dynamics NAV, using the ExcludeCustomers setting. Valid values for ExcludeCustomers are "Ship", "Invoice", "All", which correspond to different blocking states in Dynamics NAV.
GUID Management: The system attempts to reuse GUIDs for inactive customers to maintain data integrity and links to historical data (e.g., notes, orders). If no GUID is found, a new one is generated.
Script Hooks:
- BeforeUpdateCustomers: Executed before any customer processing begins, allowing for custom logic on the raw customer data.
- UpdateCustomers: Executed after each batch of customers is processed, and again after all batches are complete, allowing for further custom modifications.
Email Address Normalization: Email addresses for both customers and contact persons are trimmed of leading/trailing whitespace and invalid unicode characters.
VAT for USA Administrations: For App4Sales administrations configured for the USA, VAT-related fields (VatCode and VatLiable) are explicitly set to null/false.
Missing Address Handling: If a customer lacks valid delivery or visit addresses, the system attempts to create dummy addresses based on the available invoice address to ensure complete address information.
Empty Payment Condition Code: An empty PaymentConditionCode from Dynamics NAV is converted to null to prevent foreign key constraint issues in App4Sales.
Price Deduplication Migration: If enabled (via EnablePriceDeduplication in connector base settings or sync settings), customers' associated pricelists are migrated to deduplicated versions based on a lookup table.

Related Settings & Prerequisites

CustomerVatProductPostingGroup: Defines the VAT Product Posting Group used when retrieving customer data from Dynamics NAV.
CustomerFreeFieldsConfig: (Hidden Setting) Configuration string for mapping custom free fields.
ExcludeCustomers: Comma-separated list of values (e.g., "Ship,Invoice") to exclude customers based on their 'Blocked' status in Dynamics NAV.
CustomerShippingCodeMethod: Default shipment method code for new customers.
CustomerShippingAgentCodeMethod: Default shipment agent code for new customers.
CustomerShippingAgentServiceCodeMethod: Default shipment agent service code for new customers.
CustomerInvoiceDiscountCode: Default invoice discount code for new customers.
CustomerLocationCode: Default location code for new customers.
CustomerDefaultLanguageCode: Default language code for new customers.
CustomerDefaultSalesPersonCode: Default salesperson code for new customers.
CustomerShipToAddressCode: Default shipping address code for new customers.
CustomerDefaultSalutationCode: Default salutation code for new customers.
VatDomesticPostingGroup: VAT Domestic Posting Group used for VAT liable code determination.
VatDomesticCountryCode: VAT Domestic Country Code used for VAT liable code determination.
VatEuLiablePostingGroup: VAT EU Liable Posting Group used for VAT liable code determination.
VatEuNotLiablePostingGroup: VAT EU Not Liable Posting Group used for VAT liable code determination.
VatOtherPostingGroup: VAT Other Posting Group used for VAT liable code determination.
CustomerBaseCalendarCode: Base calendar code for new customers.
CustomerDefaultGenBusPostingGroup: Default customer general business posting group for new customers.
CustomerDefaultPostingGroup: Default customer posting group for new customers.
DiscountCustomTableField: Specifies a custom table or field in Dynamics NAV from which to retrieve customer discount.
PriceListBasedOnCodeAndCurrency: Boolean flag indicating if the pricelist code should be constructed using both the customer price group and currency code.
DefaultCustomerCurrencyCode: Default currency code used if CustomerCurrencyCode is empty.
ContactFunctionToDetermineMain: Text value representing the 'Function' of a contact person in Dynamics NAV to identify the main contact.
CustomerSyncPageSize: (Hidden Setting) Defines the number of customer records to retrieve per page during synchronization.
CustomerItemFilter: (Sync Setting) Boolean flag to enable processing of customer-specific item filters from extra data.
DefaultActionPriceListCode: (Connector Base Setting) If set, this pricelist code will be applied as the action pricelist for all customers if they don't have one specified.
DontSendInvoiceDiscountOnCustomer: If true, prevents the invoice discount from being sent when creating or updating a customer.

Known Limitations

The Subject field for customer notes currently maps directly from the CommentDate in Dynamics NAV, which may not always be an appropriate subject.
If ContactId is empty for a contact person and the system is not in Updater mode, a new ContactId is not generated automatically based on the hash code.

DynamicsNav - Customer sync