DkHome - Customer Update
This document describes the customer update process for the DkHome connector. The DkHome connector uses a generic CSV or FTP-based process to update customer data in App4Sales. The process handles customers, addresses, contact persons, discounts, and other related data.
Data Source Configuration
The customer data is expected to be provided in a CSV file. The connector retrieves this file from a configured source (e.g., FTP server). The connector can also be configured to use extra data from another CSV file to enrich the customer data.
Customer Data Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerCode |
| Mandatory. Used to identify the customer. |
CustomerName |
| Mandatory. |
CustomerGuid | Derived | The connector attempts to reuse existing GUIDs for inactive customers. If no GUID is found, a new one is generated. |
LanguageCode |
| The provided language code is mapped to an App4Sales language code using the `MappedLanguages` table. |
PasswordWebshop |
| The password is set to `null` when the `Updater` is running. |
CustomerDashboard |
| The dashboard data is expected to be a Base64 encoded string. It is decoded and stored separately. The original field is then set to `null`. |
ActionPriceList |
| If the `DefaultActionPriceListCode` setting is configured and the customer does not have an action price list, the default is used. |
PaymentConditionCode |
| If the value is an empty string, it is converted to `null`. |
VatCode |
| Set to `null` if the administration is in the USA. |
VatLiable |
| Set to `false` if the administration is in the USA. |
FreeFields |
| The `FreeFieldList` is serialized into the `FreeFields` XML field. |
ItemFilter | Derived from | Processed via `ProcessFixedItemFilterFromCustomerExtraData` if `CustomerItemFilter` setting is enabled. Filters are prefixed with `ItemFilter_`. |
CustomerNote |
| If a note is provided, all existing notes from the back office for that customer are deleted and the new note is inserted. |
Addresses
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
AddressType |
| If `Visit` and `Delivery` addresses are not both present, the missing one is created by copying the other. If no addresses are present, a dummy `Visit` address is created if an `Iso2` code is available. Defaults to 'Visit' if empty. |
Iso2 |
| The `Iso2` code is mapped using the `MappedCountries` table. If `Iso2` is empty, it's derived from the `Country` field. |
Country |
| If `Country` is empty, it's set to the `Iso2` value. |
| The email address is trimmed. If the email is empty on the main address, it's inherited from the customer's email or the first available address/contact person email. | |
AddressLine1 |
| Parsed from `AddressLine1` if `AddressLine` is not provided. It's formatted based on `Street`, `Number`, and `Addition` from the `AddressLine` object. |
IsMainAddress |
| If no main address is marked for `Visit` or `Delivery` types, the first one in the list is set as the main address. |
Contact Persons
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerGuid | Derived | Inherited from the parent customer. |
FullName |
| If `FullName` is empty, it's constructed from `FirstName`, `MiddleName`, and `LastName`. If `FullName` is provided, the other name fields are parsed from it. |
IsMainContactPerson |
| If a `MainContactPerson` is set on the customer, it's marked as the main contact. If not, the first contact person in the list with `IsMainContactPerson` set to true is used. If none, the first contact person in the list is marked as the main contact. |
ContactId |
| If `ContactId` is empty and the `Updater` is running, a hash is generated as the ID. |
PasswordWebshop |
| Set to `null` when the `Updater` is running. |
DynamicFreeFields |
| Deserialized from XML, converted to extra fields, and invalid XML characters are removed. |
Discounts per Item Class
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerGuid | Derived | Inherited from the parent customer. |
discount |
| Discounts with a value of 0 or null are ignored. |
Special Logic & Filters
Batch Processing: Customers are processed in batches of 100.
Invalid Customers: Customers without a `CustomerName` or `CustomerCode` are skipped and logged.
Reactivation: The system attempts to reactivate previously deleted customers by matching their `CustomerCode` to a stored list of inactive GUIDs.
Price List Deduplication: If `EnablePriceDeduplication` is enabled, the connector migrates customer price lists to their deduplicated versions based on a configured mapping.
Extra Data Processing: The connector can process extra customer data from a secondary source (e.g., another CSV file). This extra data can overwrite existing customer fields or be added as free fields.
Script Hooks: The process executes `BeforeUpdateCustomers` and `UpdateCustomers` scripts, allowing for custom logic to be injected.
Domain Specifics
Customer Core Fields
VAT Handling: For administrations in the USA, `VatCode` is set to null and `VatLiable` is set to false.
Payment Terms: Empty string `PaymentConditionCode` values are converted to null to prevent database errors.
Addresses
Address Normalization: The connector ensures that both `Visit` and `Delivery` addresses exist. If one is missing, it's created by copying the other. Address fields are parsed and normalized.
Country and ISO Codes: Country codes are mapped to ISO codes, with fallbacks based on the `MappedCountries` table.
Contacts
Main Contact Person: The main contact is determined based on the `MainContactPerson` field on the customer or the `IsMainContactPerson` flag on the contact person. If neither is set, the first contact in the list is designated as the main contact.
Contact ID Generation: In Updater mode, a `ContactId` is generated if it's missing.
Extra Data & Free Fields
FTP/CSV Overwrites: When extra customer data is provided, it can overwrite standard customer fields if the property names match.
Free Fields: Unknown elements from the extra data source can be added as free fields.
Item Filters: The `ItemFilter` field on the customer can be populated from the extra data if the `CustomerItemFilter` setting is enabled.
Discounts & Dashboards
Item Class Discounts: Customer-specific discounts per item class value are stored. Discounts with a value of 0 are ignored.
Dashboards: Customer dashboards are decoded from Base64 and stored separately.
Notes: Customer notes are recreated on each update; existing notes are deleted and replaced with the new note.
Related Settings & Prerequisites
`EnablePriceDeduplication`: Enables the migration of price lists to their deduplicated versions.
`CustomerItemFilter`: Enables the processing of fixed item filters from the extra customer data source.
`DefaultActionPriceListCode`: Specifies a default action price list to be used for all customers.
`Updater` mode: When running in Updater mode, the connector has slightly different behavior, such as clearing webshop passwords and generating contact IDs.
Known Limitations
This documentation is based on the generic CustomerUpdateHandler, which is used by many connectors. The specific behavior of the DkHome connector depends on its configuration as a CSV/FTP-based connector, and the data provided in the source file. Without the exact configuration and data file for the DkHome connector, this documentation reflects the general processing logic rather than a specific implementation.