Skip to main content

NewBase - Customer sync

NewBase Connector - Customer Update This document describes the Customer Update pipeline for the NewBase connector. It details how cu...

Updated over a week ago

NewBase Connector - Customer Update

This document describes the Customer Update pipeline for the NewBase connector. It details how customer-related data from the App4Sales platform is updated in the NewBase ERP system. This includes core customer information, associated addresses, contact persons, and reachability details.

Data Source Configuration

The connector updates customer information in NewBase by first retrieving existing records and then pushing changes based on the data provided by App4Sales. Data is retrieved from the NewBase API using specific queries for contacts, debtors, addresses, and reachabilities.

The following NewBase API endpoints are queried to retrieve existing customer-related data:

  • Contact Query: Fetches contact information from the 'contact' table using the serial (which maps to App4Sales CustomerCode) to retrieve k_contact_id, k_organisation_id, and k_person_id.

  • Debtor Query: Fetches debtor information from the 'debtor' table using k_organisation_id to retrieve k_debtor_id.

  • Address Query: Fetches address information from the 'address' table. For visit addresses, it uses k_person_id. For delivery addresses, it uses k_organisation_id. It retrieves k_address_id and type_address.

  • Reachability Query: Fetches reachability information from the 'reachability' table. It uses k_organisation_id for Organisation reachability, k_person_id for Person reachability, and k_contact_id for Contact reachability. It retrieves k_reachability_id, reachability (value), and type_reachability.

Customer Core Fields

The following table outlines the mapping of App4Sales customer fields (from XmlCustomer) to the NewBase Organisation, Debtor, and Person entities.

App4Sales Field (XmlCustomer)

Source Field (NewBase ERP)

Logic/Notes

CustomerName

Organisation.Name

Directly mapped to the Organisation's name.

VatCode

Debtor.VatNumber

Directly mapped to the Debtor's VAT number.

ChamberOfCommerceCode

Debtor.ChamberOfCommerce

Directly mapped to the Debtor's Chamber of Commerce number.

LanguageCode

Debtor.LanguageCode

Mapped to the Debtor's language code, converted to lowercase.

ContactFullName (FirstName)

Person.FirstName

Derived from the ContactFullName field using the GetFirstNameV2() helper method.

ContactFullName (LastName)

Person.LastName

Derived from the ContactFullName field using the GetLastNameV2() helper method.

LanguageCode

Person.Language

Mapped to the Person's language, converted to lowercase, only if the LanguageCode is not empty.

Addresses

Customer addresses are updated in NewBase based on the Visit and Delivery address information provided by App4Sales.

App4Sales Field (XmlCustomer)

Source Field (NewBase ERP)

Logic/Notes

Visit Address

Visit Address

Visit Address

VisitAddress1, VisitAddress2

Address.Street (for AddressType.Visit)

Concatenation of VisitAddress1 and VisitAddress2, separated by a newline character. The setting 'Use AddressLine2 as house number' can influence the parsing logic at a higher level.

VisitCity

Address.City (for AddressType.Visit)

Directly mapped.

VisitPostCode

Address.ZipCode (for AddressType.Visit)

Directly mapped.

Delivery Address

Delivery Address

Delivery Address

DeliveryAddress1, DeliveryAddress2

Address.Street (for AddressType.Delivery)

Concatenation of DeliveryAddress1 and DeliveryAddress2, separated by a newline character. The setting 'Use AddressLine2 as house number' can influence the parsing logic at a higher level.

DeliveryCity

Address.City (for AddressType.Delivery)

Directly mapped.

DeliveryPostCode

Address.ZipCode (for AddressType.Delivery)

Directly mapped.

CountryCode

Address.CountryIso (for both types)

Directly mapped to the ISO country code for both visit and delivery addresses.

Contact Information (Reachabilities)

Contact reachability details (phone, fax, mobile, email) are updated in NewBase.

App4Sales Field (XmlCustomer)

Source Field (NewBase ERP)

Logic/Notes

Phone

Reachability.Value (for ReachabilityType.ContactPhone)

Directly mapped.

Fax

Reachability.Value (for ReachabilityType.PersonFax)

Directly mapped.

Mobile

Reachability.Value (for ReachabilityType.PersonMobile)

Directly mapped.

Email

Reachability.Value (for ReachabilityType.ContactEmail)

Directly mapped.

Special Logic & Filters

Resetting Reachability Information

The ResetReachabilities function handles scenarios where contact information fields (Phone, Mobile, Fax, Email) in App4Sales are empty or null, requiring them to be cleared in NewBase. If a field needs to be reset, the corresponding reachability value in NewBase is updated with an empty string. This ensures that empty fields in App4Sales are reflected as cleared values in the ERP.

This process is triggered based on the ContactInformationValidationResult, which indicates which specific reachability types (Phone, Mobile, Fax, Email) need to be reset.

Flow:

  • Fetches the existing Contact and Reachabilities for the customer.

  • If validationResult.ResetPhone is true, the ReachabilityType.ContactPhone is updated to an empty string.

  • If validationResult.ResetMobile is true, the ReachabilityType.PersonMobile is updated to an empty string.

  • If validationResult.ResetFax is true, the ReachabilityType.PersonFax is updated to an empty string.

  • If validationResult.ResetEmail is true, the ReachabilityType.ContactEmail is updated to an empty string.

Domain Specifics

Customer Core Fields

The core customer identity is established through the Organisation entity, with additional commercial and linguistic details managed via the Debtor and Person entities. VAT and Chamber of Commerce details are synced to the Debtor. Contact person names and language preferences are synced to the Person entity.

Addresses

NewBase distinguishes between Visit and Delivery addresses. The connector maps App4Sales VisitAddress1/VisitAddress2 and DeliveryAddress1/DeliveryAddress2 to the corresponding street fields in NewBase, concatenating them with a newline. City, postcode, and country ISO codes are mapped directly. The connector setting 'Use AddressLine2 as house number' can influence how these address lines are interpreted and parsed at a higher level within the connector's logic.

Contacts

Contact persons' primary communication channels (phone, mobile, fax, email) are managed as 'Reachabilities' in NewBase. The connector ensures these are updated or cleared based on the data in App4Sales.

Extra Data & Free Fields

The NewBase connector supports custom field mappings for customers through the 'Customer custom fields mapping' setting. This setting allows administrators to define how custom fields from App4Sales map to specific NewBase fields for various entities (Organisation, Debtor, Person, Contact). This enables flexibility in extending the customer data synchronization beyond the standard fields.

The mapping is defined in JSON format, specifying the entity type (e.g., "organisation"), the App4Sales field name, the NewBase field name, and whether the App4Sales field is a standard customer field or a free field.

Discounts & Dashboards

(Based on the current analysis of CustomerUpdater.cs, there is no explicit handling for customer-specific item class discounts or dashboard layouts. This functionality would be managed by other components or services within the NewBase connector or the broader App4Sales platform.)

Related Settings & Prerequisites

The following connector settings can influence the customer update process:

  • Customer custom fields mapping: Defines custom mappings for customer fields to NewBase, allowing for synchronization of additional data.

  • Use AddressLine2 as house number: Influences the parsing logic for address lines, specifically how AddressLine2 is interpreted for house numbers.

Known Limitations

The CustomerUpdater.cs component specifically focuses on updating existing customer, address, contact, and reachability information. It does not directly handle:

  • The creation of new customer records (which would involve customer number generation settings).

  • Synchronization of customer-specific item class discounts.

  • Management of customer dashboard layouts.

  • Advanced processing of 'extra data' or 'free fields' beyond what is configured in the 'Customer custom fields mapping' setting.

Did this answer your question?