Skip to main content

Winbas - Customer sync

Winbas Connector - CustomerUpdate Function Overview The CustomerUpdate function in the Winbas connector synchronizes customer data from t...

Updated over a week ago

Winbas Connector - CustomerUpdate Function

Overview

The CustomerUpdate function in the Winbas connector synchronizes customer data from the Winbas ERP system to the App4Sales platform. This process involves retrieving customer records, mapping their details to the App4Sales customer model, updating associated addresses, contact persons, price lists, item class discounts, and customer dashboards. The function processes customers in batches of 100.

Data Source Configuration

Customer data is retrieved from an XML file hosted on an FTP server. The connector downloads this file, which is specified in the connector settings, and processes its contents. The file is read using windows-1252 encoding.

  • File Name: Configured via the Customer File Name setting (e.g., _customers.xml).

  • Location: FTP server as configured in the Winbas connector settings.

  • Format: XML, deserialized into the internal Customers and CustomerInfo data structures.

Data Mapping Table (Customers)

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

CustomerCode

Customer.Number

Direct mapping.

CustomerName

Customer.Name, Customer.SearchName

Direct mapping from Customer.Name. If the Add Search Name To Customer Name setting is enabled, Customer.SearchName is appended with " - SN: " prefix.

Discount

Customer.GeneralDiscount

If Create Price Lists Based On Customer Discount And Discount Allowed setting is true, this field is hardcoded to 0. Otherwise, it's mapped directly from Customer.GeneralDiscount (float converted to decimal).

CustomerManager

Customer.SalesmanCode

Direct mapping.

LanguageCode

Customer.LanguageCode

Mapped via configured language mappings. If a mapping exists, the mapped language is used; otherwise, the original code is retained.

UsesPriceField

Derived

Represents a hash code of the combined default and special price list codes for the customer. Its generation depends on the Create Price Lists Based On Customer Discount And Discount Allowed setting.

PaymentConditionCode

Customer.TermsOfPayment

Direct mapping. Empty strings are converted to null to prevent foreign key issues.

VatLiable

Customer.VATCode

Determined by comparing Customer.VATCode with the value returned by Get Vat Liable Code setting. If the administration is configured for USA, this is always false.

DeliveryMethod

Customer.TermsOfDelivery

Direct mapping.

Phone

Customer.Telephone

Direct mapping.

VatCode

Customer.OrgNumber

Direct mapping. If the administration is configured for USA, this is always null.

Created

DateTime.Now

If not set, defaults to the current timestamp. Truncated to seconds.

Sysmodified

(Internal)

Timestamp of last modification, truncated to seconds.

CustomerDashboard

Customer.CustomerDashboard

If present, decoded from Base64 and stored separately. The field itself is then cleared.

PasswordWebshop

(Internal)

Always set to null if the connector is running in 'Updater' mode.

DynamicFreeFields

Customer.DynamicFreeFields

If not empty, deserialized from XML and converted to structured extra fields.

FreeFields

Customer.FreeFieldList

If FreeFieldList contains items, they are serialized to XML and stored in this field.

ItemFilter

Derived from ExtraCustomerData

Processed from ItemFilter_ prefixed fields within extra customer data (CSV/FTP) if Customer Item Filter setting is enabled.

CustomerGuid

(Internal)

Retrieved from local cache, Portal API, or newly generated if not found. Reactivation logic reuses GUIDs of previously inactive customers.

Addresses

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

AddressLine1

Customer.VisitingAddress, Customer.DeliveryAddress, CustomerShippingAddress.Address

Mapped from various Winbas address fields based on address type. Structured address lines are parsed or formatted from/to this field.

AddressType

"VIS", "DEL", Settings.ShippingAddressType, Settings.DeliveryAddressType

Hardcoded for visiting address ("VIS"). Configurable for main delivery address (default "DEL") and shipping addresses. Defaulted to "VIS" if empty.

PostCode

Customer.PostAddress, CustomerShippingAddress.PostAddress

Parsed from the Winbas PostAddress field. Assumes format "POSTCODE CITY".

City

Customer.PostAddress, CustomerShippingAddress.PostAddress

Parsed from the Winbas PostAddress field. Assumes format "POSTCODE CITY".

Iso2

Customer.CountryCode

Inherited from main customer or derived from country name. Mapped via configured country mappings.

Country

Customer.CountryCode

Inherited from main customer. Defaults to ISO2 if country is empty.

Email

Customer.eMail, ContactPerson.EMail

Inherited from main customer's email or main contact person's email if not explicitly set for the address. Unicode unit separators are removed.

Phone

Customer.Telephone

Inherited from main customer's telephone for primary addresses.

Fax

Customer.Telefax

Inherited from main customer's telefax for primary addresses.

IsMainAddress

true, false

Visiting and main delivery addresses are marked as true. Shipping addresses are marked as false. At least one VIS and one DEL address will be marked as main if they exist.

CustomerGuid

(Internal)

Assigned from the parent customer's GUID.

Contacts

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

FullName

CustomerReference.Name

Mapped directly. Can be parsed into / constructed from FirstName, MiddleName, LastName.

Email

CustomerReference.EMail

Mapped directly. Always trimmed.

Phonenumber

CustomerReference.Telephone

Mapped directly.

Pred

CustomerReference.Title

Mapped directly.

Function

CustomerReference.Department

Mapped directly.

Language_iso2

Customer.LanguageCode

Inherited from the parent customer's language code.

ContactId

(Internal)

Generated as a hash code of the Winbas CustomerReference object. If running in 'Updater' mode and empty, a hash code is generated.

IsMainContactPerson

CustomerReference.isMainReference

One contact person is designated as main based on the isMainReference flag from Winbas. If no main contact is specified but others exist, the first one becomes main.

CustomerGuid

(Internal)

Assigned from the parent customer's GUID.

DynamicFreeFields

ContactPerson.DynamicFreeFields

If not empty, deserialized from XML and converted to structured extra fields.

PasswordWebshop

(Internal)

Always set to null if the connector is running in 'Updater' mode.

Item Class Value Discounts

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

CustomerGuid

(Internal)

Assigned from the parent customer's GUID.

discount

Customer.DiscountsPerItemCLassValue

Only discounts greater than 0 are stored.

Special Logic & Filters

  • Customer Filtering: Customers with empty CustomerName or CustomerCode are skipped and logged as invalid. Only unblocked customers (!customer.isBlocked) are processed.

  • Customer GUID Reactivation: The system attempts to reuse GUIDs of previously inactive customers to preserve notes and order links.

  • Address Creation Logic: The system ensures that each customer has at least a visiting ("VIS") and a delivery ("DEL") address. If only one is present, it duplicates the existing address and changes its type. Dummy addresses are created if no valid addresses are found, but an ISO2 country code is available. Email addresses for addresses can be inherited from the main customer or contact persons.

  • Customer Notes: If customer.CustomerNote is provided, existing notes for the customer from "BackOffice" are deleted and a new note is inserted into the CustomerNotes table.

  • VAT Handling for USA: For administrations configured for the USA, customer.VatCode is set to null and customer.VatLiable to false.

  • Script Hooks: The connector supports custom scripts before and after customer updates:

    • BeforeUpdateCustomers: Executed before customer processing in batches.

    • UpdateCustomers: Executed after customer processing in batches and a final execution after all batches are processed.

  • Error Handling: Errors during customer processing are logged, and data update intervals are reset.

Domain Specifics / Extension Section

Customer Core Fields

The core customer fields are primarily derived from the Winbas Customer object. CustomerCode and CustomerName are fundamental. The Discount field's behavior is influenced by the Create Price Lists Based On Customer Discount And Discount Allowed setting, allowing either a direct mapping or a forced zero value when discount-based price lists are generated. Payment terms (PaymentConditionCode) are mapped directly, and VAT liability (VatLiable, VatCode) is determined by the VATCode from Winbas and the administration's country setting (specifically for USA). Language and currency codes are also directly mapped, with language codes subject to internal mappings.

Addresses

Winbas provides visiting, delivery, and a collection of shipping addresses. The connector consolidates these into App4Sales Address objects. Crucially, it ensures the presence of both a "VIS" (visiting) and a "DEL" (delivery) address type for each customer, even creating duplicates or dummy entries if necessary. Postal codes and cities are parsed from single "PostAddress" fields in Winbas, assuming a "POSTCODE CITY" format. Email, phone, and fax details for primary addresses are often inherited from the main customer record. Country codes are subject to mapping and fallback logic.

Contacts

Contact persons in App4Sales are created from the CustomerReference collection within the Winbas customer data. Each Winbas reference becomes an App4Sales ContactPerson, with one marked as the IsMainContactPerson based on the Winbas isMainReference flag. If no main contact is explicitly marked, the first contact found is designated as main. Names are processed to ensure proper parsing into first, middle, and last names, or vice-versa. Email addresses are always trimmed.

Extra Data & Free Fields

The connector can incorporate additional customer data, often provided via CSV/FTP. This "extra data" can overwrite standard customer properties if field names match. Furthermore, any unrecognized fields in the extra data that start with FreeField_ are parsed as custom free fields and stored in customer.FreeFieldList. Item filters can also be defined in this extra data using ItemFilter_ prefixes, which are then used to construct the customer.ItemFilter string, provided the Customer Item Filter setting is enabled.

Discounts & Dashboards

Customer-specific item class discounts are derived from customer.DiscountsPerItemCLassValue. Only discounts greater than zero are processed. Customer dashboards, if provided as Base64 encoded strings in customer.CustomerDashboard, are decoded and stored separately via the CustomerDataManager. Customer notes are handled by deleting existing back-office notes and inserting new ones directly into the database.

Related Settings & Prerequisites

  • Customer File Name: Specifies the XML file name on the FTP server (e.g., _customers.xml).

  • Add Search Name To Customer Name: (Boolean) If enabled, appends the Winbas SearchName to the App4Sales CustomerName.

  • Shipping Address Type: (String) Defines the AddressType for imported shipping addresses (default "DEL").

  • Delivery Address Type: (String) Defines the AddressType for the main delivery address (default "DEL").

  • Create Price Lists Based On Customer Discount And Discount Allowed: (Boolean) If enabled, modifies discount handling and price list generation to include customer discounts.

  • Get Vat Liable Code: (String) Defines the Winbas VAT code that indicates a customer is VAT liable.

  • Customer Item Filter: (Boolean, Sync Setting) Enables processing of ItemFilter_ prefixed extra data fields.

  • Enable Price Deduplication: (Boolean, Connector Base Setting) Enables migration of price list IDs to deduplicated versions.

  • Default Action Price List Code: (String, Connector Base Setting) Specifies a default action price list to assign to customers without one.

Known Limitations

  • Parsing of postal codes and cities from Winbas's single PostAddress field assumes a "POSTCODE CITY" format, which might be fragile if the format varies.

  • Email addresses for shipping addresses are inherited from the main customer and not directly from the CustomerShippingAddress object itself.

  • The ContactId for contact persons is generated as a hash code and is not sourced directly from Winbas. This means it's not a persistent identifier from the ERP.

  • The connector assumes that customer.CustomerDashboard is always Base64 encoded if not empty.

Did this answer your question?