DynamicsNav Connector - Create Customer

This function facilitates the creation of new customer records within the Dynamics NAV ERP system. It processes incoming customer data, typically originating from the App4Sales platform as an XML stream, transforms it into a Dynamics NAV-compatible format, and then uses a web service to create the customer.

Trigger & Permissions

The customer creation process is initiated by an InternalRequest, which is usually sent from the App4Sales application (e.g., when a user submits a new customer from the mobile app). For this function to be operational, the connector requires the CreateCustomer (and potentially EditCustomer) flags to be enabled within the connector's ConnectorInfoInternalIds settings.

Data Source Configuration

The primary data source for customer information is an XML input stream provided within the InternalRequest. This XML stream is deserialized into XmlCustomer objects, representing the App4Sales customer data structure. The target system is Dynamics NAV, with customer data being transmitted via a SOAP web service using the CreateCustomer method of the Dynamics NAV web service client.

Payload Mapping

Main Customer Fields

App4Sales Field	Source Field (XML Node in `XmlCustomer`)	Logic/Notes
Customer Number	`debCode`	Mapped directly.
Customer Name	`customerName`	Mapped directly.
Customer GUID	`customerGuid`	Mapped directly.
Primary Address Line 1	`visitAddress1`	Mapped to Dynamics NAV Customer Address.
Primary Address Line 2	`visitAddress2`	Mapped to Dynamics NAV Customer Address 2.
Primary Postcode	`visitPostCode`	Mapped to Dynamics NAV Customer Post Code.
Primary City	`visitCity`	Mapped to Dynamics NAV Customer City.
Country Code (ISO2)	`countryCode`	Mapped to Dynamics NAV Customer Country/Region Code.
Phone Number	`contactPhone`	Mapped to Dynamics NAV Customer Phone No.
Email Address	`contactEmail`	Mapped to Dynamics NAV Customer E-Mail.
Payment Terms Code	`paymentCondition`	Mapped to Dynamics NAV Customer Payment Terms Code.
VAT Registration Number	`vatCode`	Mapped to Dynamics NAV Customer VAT Registration No.
Language Code	`languageCode`	If not provided, defaults to the value specified in connector setting `CustomerDefaultLanguageCode`.
Discount Percentage	`discount`	Mapped to `CustomerInvoiceDiscountPercentage`, unless setting `DontSendInvoiceDiscountOnCustomer` is enabled.
Price Group	`usesPrice`	Mapped based on the selected price list. If `PriceListBasedOnCodeAndCurrency` setting is enabled, the price list code is formatted as `<CODE>-<CURRENCY>`.
Chamber of Commerce Code	`chamberOfCommerceCode`	Mapped directly.
Website	`website`	Mapped directly.
Salesperson Code	(Derived)	If `UnknownElements` contains `NavConstants.CustomerSalesPersonCode`, its value is used. Otherwise, it uses the sales representative's ID (`sales?.ResIdString`) or defaults to `CustomerDefaultSalesPersonCode` from connector settings.
General Business Posting Group	(Derived)	If `UnknownElements` contains `NavConstants.CustomerGenBusPostingGroup`, its value is used. Otherwise, defaults to `CustomerDefaultGenBusPostingGroup` from connector settings.
VAT Business Posting Group	(Derived)	Determined by the `VatLiableCode` logic based on `isVATLiable` and `countryCode`. See "Validation & Defaults" for details.
Customer Posting Group	(Derived)	If `UnknownElements` contains `NavConstants.CustomerPostingGroup`, its value is used. Otherwise, defaults to `CustomerDefaultPostingGroup` from connector settings.
Shipment Method Code	(Derived)	If `UnknownElements` contains `NavConstants.CustomerShipmentMethodCode`, its value is used. Otherwise, defaults to `CustomerShippingCodeMethod` from connector settings.
Shipping Agent Code	(Derived)	If `UnknownElements` contains `NavConstants.CustomerShippingAgentCode`, its value is used. Otherwise, defaults to `CustomerShippingAgentCodeMethod` from connector settings.
Base Calendar Code	(Setting)	Defaults to `CustomerBaseCalendarCode` from connector settings.
Location Code	(Setting)	Defaults to `CustomerLocationCode` from connector settings.
Currency Code	(Derived)	Based on the selected price list's currency. If the price list currency matches `DefaultCustomerCurrencyCode` setting, an empty string is sent to NAV; otherwise, the price list currency is used.
Credit Limit (LCY)	(Derived)	If `UnknownElements` contains `NavConstants.CustomerCreditLimitLCY`, its value is used. Otherwise, not sent.
Reminder Terms Code	(Derived)	If `UnknownElements` contains `NavConstants.CustomerReminderTermsCode`, its value is used. Otherwise, not sent.
Customer Discount Group	(Derived)	If `UnknownElements` contains `NavConstants.CustomerCustomerDiscGroup`, its value is used. Otherwise, not sent.
Customer Invoice Discount Code	(Setting)	Defaults to `CustomerInvoiceDiscountCode` from connector settings.

Contact Person Fields

App4Sales Field	Source Field (XML Node in `XmlCustomer`)	Logic/Notes
Contact Full Name	`contactFullName`	Mapped to Dynamics NAV Contact Name.
Primary Address Line 1	`visitAddress1`	Mapped to Dynamics NAV Contact Address.
Primary Address Line 2	`visitAddress2`	Mapped to Dynamics NAV Contact Address 2.
Primary Postcode	`visitPostCode`	Mapped to Dynamics NAV Contact Post Code.
Primary City	`visitCity`	Mapped to Dynamics NAV Contact City.
Country Code (ISO2)	`countryCode`	Mapped to Dynamics NAV Contact Country/Region Code.
Phone Number	`contactPhone`	Mapped to Dynamics NAV Contact Phone No.
Mobile Number	`mobilePhone`	Mapped to Dynamics NAV Contact Mobile Phone No.
Email Address	`contactEmail`	Mapped to Dynamics NAV Contact E-Mail.
Language Code	(Derived)	Uses the same logic as the main customer language code.
Contact Type	(Hardcoded)	Hardcoded to "Person".
Salutation Code	(Derived)	If `UnknownElements` contains `NavConstants.ContactSalutationCode`, its value is used. Otherwise, defaults to `CustomerDefaultSalutationCode` from connector settings.

Ship-To Address Fields

A Ship-To Address record is created. Note: A CustomerShipToAddressCode must be provided for the address to be created by NAV.

App4Sales Field	Source Field (XML Node in `XmlCustomer`)	Logic/Notes
Ship-To Address Code	(Setting)	Defaults to "A4S" if `CustomerShipToAddressCode` setting is empty, otherwise uses the value from the setting.
Ship-To Address Name	`customerName`	Mapped directly to Dynamics NAV Customer Ship-To Address Name.
Ship-To Address Line 1	`deliveryAddress1`	Mapped to Dynamics NAV Customer Ship-To Address Address.
Ship-To Address Line 2	`deliveryAddress2`	Mapped to Dynamics NAV Customer Ship-To Address Address 2.
Ship-To Postcode	`deliveryPostCode`	Mapped to Dynamics NAV Customer Ship-To Address Post Code.
Ship-To City	`deliveryCity`	Mapped to Dynamics NAV Customer Ship-To Address City.
Phone Number	`contactPhone`	Mapped to Dynamics NAV Customer Ship-To Address Phone No.
Contact Person	`contactFullName`	Mapped to Dynamics NAV Customer Ship-To Address Contact.
Location Code	(Setting)	Defaults to `CustomerLocationCode` from connector settings.
Shipment Method Code	(Derived)	Uses the same logic as the main customer shipment method code.
Shipping Agent Code	(Derived)	Uses the same logic as the main customer shipping agent code.
Shipping Agent Service Code	(Setting)	Defaults to `CustomerShippingAgentServiceCodeMethod` from connector settings.
Email Address	`contactEmail`	Mapped to Dynamics NAV Customer Ship-To Address Email.

Custom Fields

The connector supports dynamic custom fields. Any elements within the incoming XML that are not explicitly mapped but start with the prefix defined in NavConstants.CustomFieldPrefix are treated as custom fields.

App4Sales Field	Source Field (XML Node in `XmlCustomer`)	Logic/Notes
Custom Field Key	`UnknownElements` dictionary keys	The key of the custom field in the `UnknownElements` dictionary (after removing the `NavConstants.CustomFieldPrefix`).
Custom Field Value	`UnknownElements` dictionary values	The value associated with the custom field.

Validation & Defaults

**VAT Liability:** The VatLiableCode is determined based on the isVATLiable XML element and the countryCode:
- If the country code matches the VatDomesticCountryCode setting, VatDomesticPostingGroup is used.
- If the country is in the European Union (based on CountryCodesEuropeanUnion enum), VatEuLiablePostingGroup is used if isVATLiable is true, otherwise VatEuNotLiablePostingGroup is used.
- For all other countries, VatOtherPostingGroup is used.
**Language Code:** If languageCode is not provided in the XML, the value from the CustomerDefaultLanguageCode connector setting is used.
**Currency Code:** If the currency of the selected price list matches the DefaultCustomerCurrencyCode setting, an empty string is sent to NAV for the currency code. Otherwise, the price list currency is used.
**Empty String Handling:** The function ensures that certain string fields in the Dynamics NAV Customer1, Contact1, and CustomerShipToAddress2 objects are not null before sending to NAV by converting any null string values to empty strings. This handles cases where NAV definitions might be "sloppy" and expect empty strings instead of nulls.
**Version-Specific Fields:**
- For App4Sales Administration versions less than 2, fields like CustomerInvoiceDiscountPercentage, CustomerCreditLimitLCY, and CustomerReminderTermsCode are not sent to NAV.
- For App4Sales Administration versions less than 3, CustomerCustomerDiscGroup is not sent to NAV.
**Ship-To Address Filtering:** Ship-To addresses are only sent if at least one of their address lines, postcode, or city fields are not empty.

Response & Error Handling

Upon successful creation of the customer in Dynamics NAV, the CustomerNo (customer number) returned by NAV is captured and included in the success response.

The function includes comprehensive error handling. If the Dynamics NAV web service call fails (e.g., due to a FaultException or any other Exception), the error message is logged with relevant details (including the request XML) and returned to the caller, prefixed with Constants.Error.CONST_ERROR. This ensures that administrators are aware of any issues during customer creation.

Related Settings & Prerequisites

CustomerDefaultLanguageCode: Default language code for new customers.
CustomerDefaultSalesPersonCode: Default salesperson code if not provided in the XML.
CustomerDefaultGenBusPostingGroup: Default general business posting group.
CustomerDefaultPostingGroup: Default customer posting group.
CustomerShippingCodeMethod: Default shipment method code.
CustomerShippingAgentCodeMethod: Default shipping agent code.
CustomerShipToAddressCode: Code used for the ship-to address. Defaults to "A4S".
CustomerLocationCode: Default location code for new customers and ship-to addresses.
CustomerShipToAddressCode: Default Ship-To Address Code.
CustomerShippingAgentServiceCodeMethod: Default Shipping Agent Service Code for ship-to addresses.
CustomerBaseCalendarCode: Default base calendar code for new customers.
VatDomesticCountryCode: Country code considered domestic for VAT purposes.
VatDomesticPostingGroup: VAT posting group for domestic VAT.
VatEuLiablePostingGroup: VAT posting group for EU liable customers.
VatEuNotLiablePostingGroup: VAT posting group for EU non-liable customers.
VatOtherPostingGroup: VAT posting group for other countries.
DefaultCustomerCurrencyCode: Default currency code for new customers.
PriceListBasedOnCodeAndCurrency: Boolean setting to indicate if price list codes are composed of code and currency.
CustomerDefaultSalutationCode: Default salutation code for new contacts.
DontSendInvoiceDiscountOnCustomer: If true, the invoice discount percentage is not sent to NAV.
ContactFunctionToDetermineMain: (Not directly used in mapping, but affects MainContactPerson determination in ConvertToModel which is not this flow).

DynamicsNav - Create customer