MultiversExtendedV3 - Customer Update

This document describes the process of synchronizing customer data from Multivers Extended V3 to the App4Sales platform. The process updates customers, addresses, contact persons, and related commercial information.

Data Source Configuration

The connector retrieves customer data from the Multivers Extended V3 API. The following API entities are used:

Debtors: The primary source for customer information. Debtors can be filtered based on the AllowedDebtorCodes and DisabledCustomersPrefix connector settings. Inactive debtors can be skipped using the SkipInactiveCustomersDuringSync setting.
Organisations: Provides additional details about the customer, including addresses and contact persons.
PaymentConditions: Used to retrieve payment condition details.
DiscountProductGroupDebtors: Used to retrieve customer-specific discounts if the CustomerDiscountProductGroupCode setting is configured.

Customer Core Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
CustomerCode	Debtor.Id	Unique identifier of the customer.
CustomerName	Organisation.Name	Name of the customer.
CustomerManager	Debtor.RepresentativeCode	The sales representative assigned to the customer.
PaymentConditionCode	Debtor.PaymentConditionCode	The payment condition for the customer. The payment condition must exist in App4Sales.
LanguageCode	Organisation.LanguageCode	The language code for the customer. This is mapped to an App4Sales language.
VatCode	Debtor.VatNumber	The VAT number of the customer.
VatLiable	Debtor.CalculateVat	Set to 'true' if `CalculateVat` is 'J'. For USA administrations, this is always set to 'false'.
DiscountGroup	Debtor.OrderDiscountGroupCode	The discount group for the customer.
Currency	Debtor.CurrencyCode	The currency of the customer.
Website	Debtor.WebSiteInfo.UrlAddress	The website of the customer.
ChamberOfCommerceCode	Organisation.CocNumber	The Chamber of Commerce number of the customer.
ItemShouldHaveStock	Organisation.Classifications	Determined by the 'OrganisationCategoryGroupIdForPortal4SalesItemStock' setting. The classification group code must be 'JA'.
CustomerClassification	Organisation.Classifications	Determined by the 'CategoryCodeToRetrieveAsCustomerClassification' setting. The description of the classification group is used.
UsesPriceField	Debtor.PriceListCode, Debtor.CurrencyCode	The pricelist for the customer. The pricelist code is generated based on the debtor's pricelist, currency, and a potential discount.
ActionPriceList	Debtor.PriceListCode, Debtor.CurrencyCode	Set if 'RetrieveActionPriceLists' is enabled. The pricelist code is generated based on the debtor's pricelist and currency.
Discount	-	Retrieved from a default discount item if 'DefaultDiscountItem' setting is configured. The discount is retrieved from the item's prices for the specific customer.
Email	Organisation.Emails	The primary email address of the customer. Can be controlled by the 'TeleComUsedTypeEmail' setting.
Phone	Organisation.TelephoneNumbers	The primary phone number of the customer. Can be controlled by the 'TeleComUsedTypeTelephone' setting.
ExtraData	-	A JSON object containing `OrganisationCode` and `OriginalPriceListCode` from the debtor.
DynamicFreeFields	Organisation.Classifications	Mapped from classifications if the classification ID is configured as a custom field.

Addresses

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
AddressLine	Address.Street, Address.StreetNumber	The street and house number of the address.
AddressLine2	Address.Addition	Additional address information.
AddressType	OrganisationAddress.AddressTypeCode	If 'General', both 'Visit' and 'Delivery' addresses are created. Otherwise, mapped from 'DeliveryAddress', 'VisitingAddress', 'PostalAddress', or 'InvoiceAddress'.
IsMainAddress	Debtor.DeliveryAddressInfo, Debtor.PostalAddressInfo	The main delivery address is determined by `Debtor.DeliveryAddressInfo`. The main invoice address is determined by `Debtor.PostalAddressInfo`. The first visit address is always the main one.
Country	Address.CountryCode	The country of the address.
Iso2	Address.CountryInfo.Description	The ISO2 country code, derived from the country description.
City	Address.City	The city of the address.
PostCode	Address.ZipCode	The postal code of the address.
AddressId	Address.Id	The unique identifier of the address.
ExternalId	Address.Id	The external identifier of the address.

Contacts

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
FullName	Person.FirstName, Person.FullName	Combination of the person's first name and full name.
FirstName	Person.FirstName	The first name of the contact person.
LastName	Person.FullName	The last name of the contact person.
Gender	Person.Gender	The gender of the contact person.
Initials	Person.Initials	The initials of the contact person.
Function	Person.PrefixTitle, Person.SuffixTitle	Combination of prefix and suffix titles.
ContactId	Person.PersonCode	The unique identifier of the contact person.
Phonenumber	Person.TelephoneNumbers	The phone number of the contact person. Falls back to the customer's phone number if not available.
Email	Person.EmailAddresses	The email address of the contact person. Falls back to the customer's email address if not available.

Special Logic & Filters

Customer Filtering

Customers can be filtered using the AllowedDebtorCodes setting, which is a comma-separated list of debtor codes.
Customers with a prefix matching the DisabledCustomersPrefix setting are excluded.
Inactive customers can be skipped by enabling the SkipInactiveCustomersDuringSync setting.

Address Processing

If a Multivers address has the type 'General', the connector creates both a 'Visit' and a 'Delivery' address in App4Sales.
The system ensures that a 'Visit' and 'Delivery' address exist for each customer. If one is missing, it is copied from an existing address.
Address line 1 is parsed into street, house number, and addition.

Contact Person Processing

The main contact person is determined by the ContactPersonCode on the debtor. If not set, the first contact person in the list is marked as the main contact.
Contact person phone numbers and email addresses can fall back to the main customer's phone and email if they are not specified.

Extra Data from FTP/CSV

The connector can enrich customer data with information from a CSV file. The file is expected to have a 'CustomerCode' column to match the data with existing customers. The properties from the CSV file will overwrite the corresponding properties on the App4Sales customer object.

Free Fields: Columns with a `FreeField_` prefix are added to the customer's free fields.
Item Filters: Columns with an `ItemFilter_` prefix are used to create fixed item filters for the customer, if the `CustomerItemFilter` setting is enabled.

Related Settings & Prerequisites

AllowedDebtorCodes: A comma-separated list of debtor codes to sync.
DisabledCustomersPrefix: Customers with a debtor code starting with this prefix will be skipped.
SkipInactiveCustomersDuringSync: If enabled, inactive debtors will not be synchronized.
CustomerDiscountProductGroupCode: If set, the connector will retrieve customer-specific discounts from this product group.
RetrieveActionPriceLists: If enabled, action price lists are retrieved for the customer.
DefaultDiscountItem: If set, the connector retrieves the customer's discount from this item.
TeleComUsedTypeEmail: Specifies the telecom usage type for the primary email address.
TeleComUsedTypeTelephone: Specifies the telecom usage type for the primary phone number.
OrganisationCategoryGroupIdForPortal4SalesItemStock: The category group ID for determining the 'ItemShouldHaveStock' flag.
CategoryCodeToRetrieveAsCustomerClassification: The category code for retrieving the customer classification.
CustomerItemFilter: Enables the processing of fixed item filters from extra data.
EnablePriceDeduplication: Enables the migration of customers to deduplicated price lists.

MultiversExtendedV3 - Customer sync