Microsoft Business Central V2 Connector - Create Customer

This document describes how the Microsoft Business Central V2 connector handles the creation and updating of customer records within Microsoft Business Central. This process is triggered when a new customer is created in App4Sales (e.g., via the mobile app) or when an existing customer is synchronized from App4Sales to Business Central. The connector first attempts to create a contact person in Business Central, then creates or updates the main customer record, and finally updates App4Sales with the Business Central identifiers.

Trigger & Permissions

The customer creation/update flow is typically triggered by a user action within the App4Sales platform, such as submitting a new customer from the mobile application. This functionality is enabled by the connector info flags EditCustomer and CreateCustomer, which must be active for the connector to process these requests.

Payload Mapping

Customer Header Fields

App4Sales Field	Source Field (Business Central)	Logic/Notes
`CustomerCode`	Derived	If the App4Sales `CustomerCode` is empty, a new customer record is created in Business Central, and the ERP-generated customer number is returned and assigned to App4Sales' `CustomerCode`. If `CustomerCode` is present, the existing customer in Business Central (identified by its internal `SystemId`) is updated.
`CustomerName`	`DisplayName`	Directly mapped from the App4Sales customer's name.
`VatLiable`	`TaxLiable`	Directly mapped. Indicates if the customer is liable for VAT.
`VatCode`	`VatNumber`	Directly mapped from the App4Sales VAT registration number.
`Phone`	`PhoneNumber`	Directly mapped from the App4Sales customer's phone number.
`Email`	`Email`	Uses the email of the App4Sales `MainContactPerson` if available; otherwise, it falls back to the general customer email address.
`PaymentConditionCode`	`PaymentMethodCode`	Directly mapped.
`Fax`	`Fax`	Directly mapped.
`Website`	`Website`	Directly mapped.
Hardcoded Value	`PrimaryContactNo`	This field in Business Central is populated with the `Number` of the contact person created or updated in Business Central during this process.
`UsesPriceField` (Price List ID)	`PriceGroup`, `DiscountGroupCode`, `CurrencyCode`	If `UsesPriceField` in App4Sales (which represents a price list ID) corresponds to a non-default price list, the `PriceGroupCode`, `DiscountGroupCode`, and `Currency` from that price list are mapped. The `CurrencyCode` is only set if it differs from the connector's base currency setting.
`DynamicFreeFields`	Various properties	App4Sales `DynamicFreeFields` (stored as XML) are deserialized. Each dynamic free field is mapped to a corresponding property on the Business Central customer payload using reflection.
Hardcoded Value	`CustomerPostingGroup`	Set based on the customer's country: If the customer's main address is in the Netherlands ("NL"), it uses the value from the connector setting `NLCustomerDefaultCustomerPostingGroup`. If the customer's main address is in a European Union country, it uses `EUCustomerDefaultCustomerPostingGroup`.
Hardcoded Value	`GenBusPostingGroup`	Set based on the customer's country: If the customer's main address is in the Netherlands ("NL"), it uses the value from the connector setting `NLCustomerDefaultGenBusPostingGroup`. If the customer's main address is in a European Union country, it uses `EUCustomerDefaultGenBusPostingGroup`.

Customer Address Fields

The connector primarily maps the main address of the App4Sales customer. The main address is determined by the IsMainAddress flag, or the first address in the list if no main address is explicitly set.

App4Sales Field	Source Field (Business Central)	Logic/Notes
`Addresses` (main address)	`AddressLine1`	First line of the customer's main address.
`Addresses` (main address)	`AddressLine2`	Second line of the customer's main address.
`Addresses` (main address)	`City`	City of the customer's main address.
`Addresses` (main address)	`PostCode`	Postal code of the customer's main address.
`Addresses` (main address)	`RegionCode`	ISO 2 country code (e.g., "NL", "DE") of the customer's main address.

Main Contact Person Fields

If an App4Sales MainContactPerson is provided, the connector attempts to create or update this contact person in Business Central.

App4Sales Field	Source Field (Business Central)	Logic/Notes
`MainContactPerson.ContactId`	`Number`	Used to identify the contact person in Business Central for updates. The ERP-generated number is stored back in App4Sales.
`MainContactPerson.FirstName`	`FirstName`	Mapped directly. If empty, derived from `FullName`.
`MainContactPerson.LastName`	`LastName`	Mapped directly. If empty, derived from `FullName`.
`MainContactPerson.MiddleName`	`MiddleName`	Mapped directly. If empty, derived from `FullName`.
`MainContactPerson.FullName`	`FullName`	Directly mapped.
`MainContactPerson.MobileNumber`	`MobilePhoneNo`	Directly mapped.
`MainContactPerson.Email`	`Email`	Directly mapped.
`MainContactPerson.Phonenumber`	`PhoneNo`	Directly mapped.

Validation & Defaults

If MainContactPerson.FullName is empty during creation/update of a contact person, the contact person creation/update is skipped, and a warning is logged.
If customer.CustomerCode is empty, a new customer is created. Otherwise, an existing customer is updated.
If the response from Business Central during customer creation/update is invalid or null, an exception is thrown.

Response & Error Handling

Upon successful creation or update of a customer in Business Central, the ERP-generated customer code is returned and stored in the App4Sales Customer.CustomerCode field. The Business Central SystemId is stored in App4Sales' Customer.InternalCode, and the contact person's ERP identifier is stored in App4Sales' ContactPerson.ContactId.

If an error occurs during the process (e.g., network issues, invalid data rejected by Business Central), an exception is logged, and an error message (starting with "ERROR:") is returned to App4Sales, which will then surface this error to the user interface.

Related Settings & Prerequisites

NLCustomerDefaultCustomerPostingGroup: Default customer posting group for customers identified as being from the Netherlands.
EUCustomerDefaultCustomerPostingGroup: Default customer posting group for customers identified as being from the European Union.
NLCustomerDefaultGenBusPostingGroup: Default general business posting group for customers identified as being from the Netherlands.
EUCustomerDefaultGenBusPostingGroup: Default general business posting group for customers identified as being from the European Union.
MbcBaseCurrencyCode: The base currency code configured for Microsoft Business Central, used for currency conversion logic related to price lists.

MicrosoftBusinessCentralV2 - Create customer