Skip to main content

MicrosoftBusinessCentral - Create customer

Microsoft Business Central Connector - Create/Update Customer This document describes the process by which the Microsoft Business Centra...

Updated over a week ago

Microsoft Business Central Connector - Create/Update Customer

This document describes the process by which the Microsoft Business Central connector creates or updates customer records within Microsoft Business Central (MBC) based on data from the App4Sales platform. This functionality is primarily used when a new customer is registered via App4Sales or when existing customer details are synchronized. The connector handles core customer information, contact persons, and delivery addresses.

Trigger & Permissions

The customer creation/update process is triggered within App4Sales when an action invokes the InsertOrUpdateCustomerCommand. This command is active only if the following connector information flags are enabled in the App4Sales Administration:

  • EditCustomer: Allows modification of existing customer records.
  • CreateCustomer: Allows the creation of new customer records.

Data Source Configuration

The primary data source for this process is the App4Sales internal Customer model. The connector then communicates with the Microsoft Business Central API to create or update the corresponding entities.

The connector utilizes the following Microsoft Business Central API endpoints:

  • Customers: /api/{MBCApiVersion}/companies({CompanyId})/Customers (or AL extension equivalent /api/OptimizersBV/App4Sales/{ALExtensionsVersion}/companies({CompanyId})/Customers) for creating and updating core customer data.
  • Contacts: /api/{MBCApiVersion}/companies({CompanyId})/Contacts (or AL extension equivalent) for creating and updating contact persons.
  • ShipToAddresses: /api/{MBCApiVersion}/companies({CompanyId})/ShipToAddresses (or AL extension equivalent) for creating and updating customer delivery addresses.
The base URL for API calls is https://api.businesscentral.dynamics.com/. The specific API version, environment name, and company ID are derived from the connector's settings.

Payload Mapping

The App4Sales Customer object is mapped to the Microsoft Business Central Customer entity. This section details the field-by-field mapping.

Core Customer Fields

App4Sales Field Source Field (API/Excel/DB) Logic/Notes
CustomerCode Customer.CustomerCode Directly mapped.
CustomerName Customer.DisplayName Directly mapped to the Business Central customer's display name.
VatLiable Customer.TaxLiable Mapped based on connector settings for VAT liability (see "Validation & Defaults" section).
VatCode Customer.VatNumber Directly mapped.
Phone Customer.PhoneNumber Directly mapped.
Email Customer.MainContactPerson?.Email or Customer.Email If a main contact person exists, their email is used. Otherwise, the customer's general email is used. Also influenced by Use fax field (if not empty) from BC as customer email setting.
PaymentConditionCode Customer.PaymentMethodCode or Customer.PaymentTermsCode Determined by the connector setting Use payment terms as payment conditions. If true, PaymentTermsCode is used; otherwise, PaymentMethodCode.
Fax Customer.Fax Directly mapped.
Website Customer.Website Directly mapped.
LanguageCode Customer.LanguageCode Mapped from App4Sales language code to a Business Central language code if a mapping exists and the Send customer language code setting is enabled.
CustomerNote Customer.Comment Mapped if the setting Sync customer comment as customer note is enabled.
CustomerManager Customer.SalesPersonCode Directly mapped.
UsesPriceField Customer.PriceGroup The internal App4Sales price list ID is converted to a Business Central price group code (ExternalId). If the price list is the default one, the price group is not sent, unless Ignore customer price group when create customer is false.
InternalCode Customer.Id App4Sales internal GUID for the customer.
GenBusPostingGroup Customer.GenBusPostingGroup Set based on connector settings NL customer default Gen. Bus. Posting Group or EU customer default Gen. Bus. Posting Group depending on customer's country.
CustomerPostingGroup Customer.CustomerPostingGroup Set based on connector settings NL customer default Customer Posting Group or EU customer default Customer Posting Group depending on customer's country.
PaymentTermsCode Customer.PaymentTermsCode Set if Customer default Payment terms code is configured in connector settings.
ReminderTermsCode Customer.ReminderTermsCode Set based on connector settings NL customer default Reminder Terms Code or Not NL customer default Reminder Terms Code depending on customer's country.
LocationCode Customer.LocationCode Set if Customer default Location code is configured in connector settings.

Main Contact Person Fields

App4Sales Field Source Field (API/Excel/DB) Logic/Notes
MainContactPerson.FullName Contact.FullName, Contact.FirstName, Contact.MiddleName, Contact.LastName The full name from App4Sales is parsed into first name, middle name (initials), and last name for Business Central. If FullName is empty, the contact person is not created.
MainContactPerson.Email Contact.Email Directly mapped.
MainContactPerson.MobileNumber Contact.MobilePhoneNo Directly mapped.
Phone (from Customer) Contact.PhoneNo The primary phone number from the App4Sales customer is mapped to the contact person's phone number in Business Central.
ContactType Contact.Type Hardcoded as "Person".
MainContactPerson.ContactId MainContactPerson.ContactId Contact.Number The Business Central contact number is stored back into MainContactPerson.ContactId after creation.

Main Address Fields (Visit Address)

App4Sales Field Source Field (API/Excel/DB) Logic/Notes
Addresses (where IsMainAddress is true or first address) Customer.AddressLine1, Customer.AddressLine2, Customer.City, Customer.PostCode, Customer.RegionCode, Customer.County The primary address from App4Sales (the one marked as main, or the first in the list) is mapped to the main address fields of the Business Central customer.
Addresses.AddressLine1 Customer.AddressLine1 Directly mapped.
Addresses.AddressLine2 Customer.AddressLine2 Directly mapped.
Addresses.City Customer.City Directly mapped.
Addresses.PostCode Customer.PostCode Directly mapped.
Addresses.Iso2 Customer.RegionCode Mapped to the Business Central region code.

Delivery Address Fields

Delivery addresses are created as 'Ship-To Addresses' in Business Central only if the connector setting Post delivery address to MBC during customer create/update is enabled. If no delivery address is explicitly specified in App4Sales, the connector can use the customer's visit address as a fallback if Use customer visit address as delivery address if delivery not specified is enabled.

App4Sales Field Source Field (API/Excel/DB) Logic/Notes
Addresses (where AddressType is "Delivery") ShipToAddress.AddressLine1, ShipToAddress.AddressLine2, ShipToAddress.City, ShipToAddress.PostCode, ShipToAddress.Country, ShipToAddress.State The delivery address from App4Sales is mapped to a Business Central Ship-To Address. If multiple delivery addresses exist, all are processed.
Addresses.AddressLine1 ShipToAddress.AddressLine1 Directly mapped.
Addresses.AddressLine2 ShipToAddress.AddressLine2 Directly mapped.
Addresses.City ShipToAddress.City Directly mapped.
Addresses.PostCode ShipToAddress.PostCode Directly mapped.
Addresses.Country ShipToAddress.Country Mapped from the App4Sales address country.
Addresses.State ShipToAddress.State Mapped to the state/county field in Business Central.
Addresses.AddressId / Generated ShipToAddress.Code If AddressId is available and does not contain the New MBC address code prefix (default: A4S), it is used. Otherwise, a new code is generated using the specified New MBC address code prefix and an incrementor. The incrementor is stored in the connector's internal settings.
Customer.CustomerCode Customer.CustomerCode The customer code from App4Sales is used to link the Ship-To Address to the customer in Business Central.

Dynamic Free Fields and Custom Fields

App4Sales Field Source Field (API/Excel/DB) Logic/Notes
DynamicFreeFields Varies (dynamic) XML content from App4Sales DynamicFreeFields is deserialized. Each DynamicField with a Key (which corresponds to an XmlElementName in CustomExtraFields) and Value is mapped to the corresponding property on the Business Central Customer. Supports dropdown values mapping from BackofficeValue to Value.

Validation & Defaults

VAT Liability Determination

The TaxLiable field in Business Central is set based on a combination of connector settings and customer data:

  • If Country code for always VAT liable customers is set and matches the customer's region code, the customer is marked as VAT liable.
  • If Mark customers without VAT number as VAT liable is enabled, and the customer's region code does NOT match Country code for always VAT liable customers AND the customer has no VAT number, they are marked as VAT liable.
  • If VAT business posting group code for vat liable customers (comma separated) is set, the customer is marked VAT liable if their VatBusPostingGroup matches any of the specified codes.
  • If VAT business posting group code for not vat liable customers (comma separated) is set, the customer is marked as NOT VAT liable if their VatBusPostingGroup matches any of the specified codes.

Language Code Handling

The LanguageCode is sent to Business Central if a mapping exists between the App4Sales language code and a Business Central language code (configured internally), and the connector setting Send customer language code is enabled.

Default Posting Groups, Payment, Reminder Terms, and Location Codes

The connector can apply default values for various Business Central fields based on the customer's country and connector settings:

  • General Business Posting Group (GenBusPostingGroup):
    • If the customer is identified as an NL (Netherlands) customer, the value from NL customer default Gen. Bus. Posting Group is used.
    • If the customer is an EU (European Union) customer, the value from EU customer default Gen. Bus. Posting Group is used.
  • Customer Posting Group (CustomerPostingGroup):
    • If the customer is an NL customer, the value from NL customer default Customer Posting Group is used.
    • If the customer is an EU customer, the value from EU customer default Customer Posting Group is used.
  • Payment Terms Code (PaymentTermsCode): The value from Customer default Payment terms code is applied if specified.
  • Reminder Terms Code (ReminderTermsCode):
    • If the customer is an NL customer, the value from NL customer default Reminder Terms Code is used.
    • Otherwise, the value from Not NL customer default Reminder Terms Code is used.
  • Location Code (LocationCode): The value from Customer default Location code is applied if specified.

Response & Error Handling

Upon a successful customer creation or update in Business Central, the connector captures the newly assigned CustomerCode (which is the Business Central customer number) and the internal CustomerId (GUID) from the Business Central response. The customer.CustomerCode property in App4Sales is then updated with the Business Central customer number.

If the Business Central API call returns a result starting with the string "ERROR" (case-sensitive), the connector logs an error and throws an exception, indicating a failure in the customer creation/update process. This error is then propagated through the App4Sales system.

Related Settings & Prerequisites

To ensure proper functioning of the customer creation/update process, review and configure the following connector settings in App4Sales Administration:

  • Use fax field (if not empty) from BC as customer email: If enabled, the customer's fax number from Business Central will be used as their email address in App4Sales if the email field is empty.
  • Use payment terms as payment conditions: Dictates whether Business Central's Payment Terms Code or Payment Method Code is used for the App4Sales Payment Condition Code.
  • Sync customer comment as customer note: If enabled, the 'Comment' field from Business Central customer will be synchronized to the 'Customer Note' field in App4Sales.
  • CustomCustomerFieldsMapping: Allows defining custom mappings for customer fields between App4Sales and Business Central using a JSON array.
  • Send customer language code: When enabled, the customer's language code from App4Sales will be sent to Business Central.
  • Post delivery address to MBC during customer create/update: If enabled, delivery addresses from App4Sales will be created or updated as Ship-To Addresses in Business Central.
  • Use customer visit address as delivery address if delivery not specified: If enabled, and no specific delivery address is provided, the customer's main visit address will be used as the delivery address.
  • New MBC address code prefix: Defines the prefix used when generating new codes for Business Central Ship-To Addresses (default: "A4S").
  • Ignore delivery addresses without code during customers sync: If enabled, delivery addresses without an explicit code will be ignored during synchronization.
  • Update contact information on Customer update call: If enabled, contact person details will be updated in Business Central when a customer record is updated in App4Sales.
  • NL customer default Gen. Bus. Posting Group: Default General Business Posting Group for customers identified as being from the Netherlands.
  • EU customer default Gen. Bus. Posting Group: Default General Business Posting Group for customers identified as being from the European Union (but not Netherlands).
  • NL customer default Customer Posting Group: Default Customer Posting Group for customers identified as being from the Netherlands.
  • EU customer default Customer Posting Group: Default Customer Posting Group for customers identified as being from the European Union (but not Netherlands).
  • Customer default Payment terms code: Sets a default Payment Terms Code for new customers in Business Central.
  • NL customer default Reminder Terms Code: Default Reminder Terms Code for customers identified as being from the Netherlands.
  • Not NL customer default Reminder Terms Code: Default Reminder Terms Code for customers not identified as being from the Netherlands.
  • Customer default Location code: Sets a default Location Code for new customers in Business Central.
  • Ignore customer price group when create customer: If enabled, the price group from App4Sales will not be sent to Business Central during customer creation.

Known Limitations

  • The connector assumes that if MainContactPerson.FullName is empty, no contact person needs to be created in Business Central.
  • The generation of new Business Central address codes is based on a simple incrementor stored in internal connector settings, which might lead to collisions if not managed properly in a multi-instance or high-volume environment.
  • Only one main contact person is handled for creation/update per customer. Additional contact persons associated with the App4Sales customer are not currently synchronized during this process.
Did this answer your question?