MultiversExtendedV2 - Customer Update
This document describes the customer synchronization process for the MultiversExtendedV2 connector. The process updates customers, their addresses, contact persons, and related commercial data like price lists, discounts, and dashboards. The data is retrieved from the Multivers WebAPI and an FTP server.
Data Source Configuration
The connector fetches data from two main sources:
Multivers WebAPI: The primary source for customer, address, and contact person data. The connector uses the SOAP API. The base URL is configured in the administration settings.
FTP/SFTP Server: Used to retrieve customer-specific PDF dashboards and potentially extra customer data via CSV files. The FTP/SFTP server details (address, username, password) are configured in the connector settings.
Data Mapping
The following tables detail the mapping from the Multivers data source to the App4Sales entities.
Customer Core Fields
App4Sales Field | Source Field (API) | Logic/Notes |
CustomerCode | DebtorShort.DebtorId | The unique identifier for the customer. |
CustomerName | DebtorShort.OrganisationName | Name of the customer. |
CustomerManager | OrganisationV2.DebtorV2.RepresentativeId | The ID of the sales representative responsible for the customer. |
PaymentConditionCode | OrganisationV2.DebtorV2.TermsOfPayment | The code for the customer's payment terms. |
ChamberOfCommerceCode | OrganisationV2.ChamberOfCommerce | The customer's Chamber of Commerce number. |
LanguageCode | OrganisationV2.LanguageId | The language code for the customer. This is mapped to an App4Sales language code. |
VatCode | OrganisationV2.DebtorV2.VatNumber | The customer's VAT number. |
VatLiable | OrganisationV2.DebtorV2.VatType | Boolean flag indicating if the customer is liable for VAT. Set to true if VatType is 'J'. |
OrganisationV2.TelecomsV2 (where TelecomType is 'E') | The customer's email address. A specific email can be selected based on the 'TeleComUsedTypeEmail' setting. | |
Phone | OrganisationV2.TelecomsV2 (where TelecomType is 'T') | The customer's phone number. A specific phone can be selected based on the 'TeleComUsedTypeTelephone' setting. |
Fax | OrganisationV2.TelecomsV2 (where TelecomType is 'F') | The customer's fax number. |
UsesPriceField | OrganisationV2.DebtorV2.PriceList | The hashcode of the pricelist name is used. If 'RetrieveMultipleCurrencyPricelists' is enabled, the currency code is appended to the pricelist name before hashing. |
ActionPriceList | OrganisationV2.DebtorV2.PriceList | The hashcode of the pricelist name with "_Action" appended. |
Discount | ProductPriceV2.ProductPriceDetailsV2.Discount | The customer's general discount. This is retrieved only if 'GetCustomerDiscountFromProductGroup' is enabled. |
DynamicFreeFields | OrganisationV2.OrganisationCategoryGroupsV2 | Organisation categories are mapped to dynamic free fields based on the configuration in the 'CustomExtraFields' context. |
CustomerDashboard | FTP Server | A PDF file named [CustomerCode].pdf is downloaded from the FTP 'FtpDashboardLocation' directory, converted to Base64, and stored in this field. |
Addresses
App4Sales Field | Source Field (API) | Logic/Notes |
AddressType | AddressV2.AddressUsage | 'a' maps to 'Delivery', 'f' to 'Invoice', and 'x' to both 'Visit' and 'Delivery'. |
AddressLine1 | AddressV2.AddressLine1 | The first line of the address. |
AddressLine2 | AddressV2.AddressLine2 | The second line of the address. |
AddressLine3 | AddressV2.AddressLine3 | The third line of the address. |
Street | Parsed from AddressLine1 | The street name part of the address line. |
HouseNumber | Parsed from AddressLine1 | The house number part of the address line. |
Addition | Parsed from AddressLine1 | The house number addition part of the address line. |
IsMainAddress | AddressV2.AddressId, DebtorV2.DeliveryAddress, DebtorV2.InvoiceAddress | True if the address ID matches the delivery or invoice address ID on the debtor. For 'Visit' addresses, this is always true. |
Country | AddressV2.AddressCountry | The country of the address. |
Iso2 | AddressV2.AddressCountryIso | The ISO2 country code. The connector has logic to map and normalize country codes. |
City | AddressV2.AddressCity | The city of the address. |
PostCode | AddressV2.AddressZipCode | The postal code of the address. |
Customer's default email | The email address associated with the address. It defaults to the customer's main email. | |
Phone | Customer's default phone | The phone number associated with the address. It defaults to the customer's main phone number. |
Fax | Customer's default fax | The fax number associated with the address. It defaults to the customer's main fax number. |
Route | OrganisationV2.OrganisationCategoryGroupsV2.GroupId | A free field for the address, taken from the 'GroupId' of the organization category that matches the 'OrganisationCategoryForFreeAddressField' setting. |
Contact Persons
App4Sales Field | Source Field (API) | Logic/Notes |
Language_iso2 | PersonV2.LanguageId | The language code for the contact person. |
FullName | PersonV2.FirstName + " " + PersonV2.PersonName | The full name of the contact person. |
FirstName | PersonV2.FirstName | The first name of the contact person. |
LastName | PersonV2.PersonName | The last name of the contact person. |
Gender | PersonV2.MaleFemale | The contact person's gender. |
Initials | PersonV2.SuffixTitle | The contact person's initials. |
Function | PersonV2.Title | The job title of the contact person. |
ContactId | PersonV2.PersonId | The unique identifier for the contact person from Multivers. |
Phonenumber | PersonV2.PersonTelecomsV2 (where TelecomType is 'T') | The contact person's phone number. Falls back to the customer's default phone number. |
PersonV2.PersonTelecomsV2 (where TelecomType is 'E') | The contact person's email address. Falls back to the customer's default email address. | |
IsMainContactPerson | Derived | The first contact person in the list is marked as the main contact person. |
Customer-Specific Item Class Discounts
App4Sales Field | Source Field (API) | Logic/Notes |
discount | ProductPriceV2.ProductPriceDetailsV2.Discount | A discount percentage for a specific item class value. This is retrieved if the 'SecondaryDiscountItem' and 'SecondaryDiscountItemClass' settings are configured. |
Special Logic & Filters
Customer Filtering: The synchronization can be limited to a specific list of customers using the 'AllowedDebtorCodes' setting. Customers with a name starting with the 'disabledCustomersPrefix' are also skipped.
Address Filtering: If 'SyncOnlyLowestAddressPriority' is enabled, only addresses with the lowest priority number are synchronized.
Address Normalization: The connector ensures that every customer has at least a 'Visit' and a 'Delivery' address. If one is missing, it is created by copying the other. Country codes are normalized to ISO 2 standards.
Extra Customer Data: The connector can process extra customer data from a CSV file located on an FTP server. This data can overwrite existing customer fields or be added as free fields.
Fixed Item Filters: When 'CustomerItemFilter' is enabled, item filters can be defined in the extra customer data CSV file. These filters are stored in the 'ItemFilter' field on the customer.
Price List De-duplication: If 'EnablePriceDeduplication' is enabled, the connector migrates customers to use de-duplicated price lists.
Dashboards: PDF dashboards are downloaded from an FTP server and stored in the database. The files are matched by customer code.
Notes: Customer notes from the back office are recreated during each sync. Existing back office notes are deleted and then re-inserted.
Related Settings & Prerequisites
The following settings influence the customer update process:
AllowedDebtorCodes: A semi-colon separated list of customer codes to sync. If empty, all customers are synced.
disabledCustomersPrefix: Customers with a name starting with this prefix will be skipped.
FtpDashboardLocation: The FTP directory where customer dashboards (PDFs) are located.
SyncOnlyLowestAddressPriority: If true, only syncs addresses with the lowest priority.
TeleComUsedTypeEmail: Use a specific telecom 'used' type for the customer's email address.
TeleComUsedTypeTelephone: Use a specific telecom 'used' type for the customer's phone number.
RetrieveMultipleCurrencyPricelists: If true, the connector will attempt to resolve currency-specific price lists.
GetCustomerDiscountFromProductGroup: If true, retrieves the customer's general discount from a product group.
DefaultDiscountItem: The item used to retrieve the general customer discount.
SecondaryDiscountItem: The item used to retrieve customer-specific item class discounts.
SecondaryDiscountItemClass: The item class used to retrieve customer-specific item class discounts.
CustomerItemFilter: Enables the processing of fixed item filters from extra customer data.
EnablePriceDeduplication: Enables migration to de-duplicated price lists.
DefaultActionPriceListCode: A default action price list to be set on all customers.
OrganisationCategoryForFreeAddressField: The organisation category to use for the 'Route' free field on addresses.