Economic Connector - CustomerUpdate Function

This function synchronizes customer data from the Economic ERP system to App4Sales. It periodically retrieves customer information, including core customer details, addresses, and contact persons. It also dynamically creates dropdown fields in App4Sales based on Economic's VAT zones, customer groups, layouts, payment terms, and sales persons. The synchronization runs in batches of up to 1000 customers per page.

Data Source Configuration

The Economic connector retrieves customer data directly from the Economic REST API. It pulls data from the following endpoints:

GET /customers?filter=barred$eq:0: Retrieves active customer records, excluding those marked as 'barred'. Data is paginated with a page size of 1000.
GET /employees: Retrieves employee records, used for sales person mapping. Data is paginated with a page size of 1000.
GET /vat-zones: Used to populate the 'VAT Zone' dropdown in App4Sales.
GET /customer-groups: Used to populate the 'Customer Group' dropdown in App4Sales.
GET /layouts: Used to populate the 'Layout' dropdown in App4Sales.
GET /payment-terms: Used to populate the 'Payment Terms' dropdown in App4Sales.
GET /customers/{customerNumber}/delivery-locations: Retrieves delivery addresses for each customer. This is fetched in batches.
GET /customers/{customerCode}/contacts: Retrieves contact persons for each customer. This is fetched in batches.

Authentication to the Economic API is handled via 'X-AppSecretToken' and 'X-AgreementGrantToken' headers, which are configured in the connector settings.

Customer Core Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
VatCode	`corporateIdentificationNumber`	Direct mapping.
ChamberOfCommerceCode	`publicEntryNumber`	Direct mapping.
CustomerCode	`customerNumber`	Converted to string.
CustomerName	`name`	Direct mapping.
PaymentConditionCode	`paymentTerms.paymentTermsNumber`	Converted to string.
UsesPriceField	`customer.currency`	Hash code of the lowercased currency code.
VatLiable	`customer.vatZone.vatZoneNumber`	Determined by checking if the `vatZoneNumber` is present in the connector setting `VatLiableVatZones` (a semicolon or comma separated list of VAT zone numbers).
CustomerManager	`customer.salesPerson.employeeNumber`	Looked up from the list of employees based on `salesPerson.employeeNumber` to get the employee name.
Phone	`telephoneAndFaxNumber`	Direct mapping.
Discount	Dynamic (configured by setting)	If the connector setting `CustomerFieldForPercentageDiscount` is set, the value from the specified customer field in Economic is parsed as a decimal and mapped as the customer's discount.

Addresses

The connector processes customer addresses in two ways:

A default 'Visit' address is created directly from the main customer information.
Additional 'Delivery' addresses are retrieved from the /customers/{customerNumber}/delivery-locations endpoint.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Default Visit Address (derived from main customer data)	Default Visit Address (derived from main customer data)	Default Visit Address (derived from main customer data)
AddressId	`customerNumber`	Customer number converted to string.
AddressLine1	`address`	Main customer address.
PostCode	`zip`	Main customer zip code.
City	`city`	Main customer city.
Country	`country`	Main customer country.
Phone	`telephoneAndFaxNumber`	Main customer phone/fax number.
Fax	`telephoneAndFaxNumber`	Main customer phone/fax number.
Email	`email`	Main customer email.
AddressType	Hardcoded	Set to "VIS" (Visit).
IsMainAddress	Hardcoded	Set to `true`.
Delivery Addresses (from Delivery Locations)	Delivery Addresses (from Delivery Locations)	Delivery Addresses (from Delivery Locations)
AddressId	`customerNumber`	Customer number converted to string.
ExternalId	`deliveryLocation.DeliveryLocationNumber`	Delivery location number converted to string.
AddressLine1	`deliveryLocation.Address`	Delivery location address.
AddressLine3	`deliveryLocation.DeliveryLocationNumber`	Delivery location number converted to string.
PostCode	`deliveryLocation.PostalCode`	Delivery location postal code.
City	`deliveryLocation.City`	Delivery location city.
Country	`deliveryLocation.Country`	Delivery location country.
Phone	`customer.telephoneAndFaxNumber`	Inherited from the main customer's phone/fax number.
Fax	`customer.telephoneAndFaxNumber`	Inherited from the main customer's phone/fax number.
Email	`customer.email`	Inherited from the main customer's email.
AddressType	Hardcoded	Set to "DEL" (Delivery).
IsMainAddress	Calculated	Not explicitly set to true.
Filter	`deliveryLocation.Barred`	Delivery locations marked as `Barred = true` are skipped.

Extra Data & Free Fields

The connector serializes several Economic-specific fields into the App4Sales DynamicFreeFields XML payload for each customer. These fields are dynamically created as dropdowns in the App4Sales customer screen.

App4Sales XML Element Name	Source Field (Economic)	Logic/Notes
`VatZoneElementName`	`customer.vatZone.vatZoneNumber`	The VAT zone number is stored. This corresponds to the 'VAT Zone' dropdown in App4Sales.
`LayoutElementName`	`customer.layout.LayoutNumber` or `customer.customerGroup.layout.LayoutNumber`	The layout number is stored. If a layout is defined directly on the customer, that is used; otherwise, the layout from the customer's group is used. This corresponds to the 'Layout' dropdown in App4Sales.
`PaymentTermsElementName`	`customer.paymentTerms.paymentTermsNumber`	The payment terms number is stored. This corresponds to the 'Payment Terms' dropdown in App4Sales.
`SalesPersonElementName`	`customer.salesPerson.employeeNumber`	The employee number of the sales person is stored. This corresponds to the 'Sales Persons' dropdown in App4Sales.

Contacts

The connector retrieves contact persons associated with each customer from the Economic API and maps them to App4Sales ContactPerson entities.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Email	`contact.Email`	Direct mapping.
FullName	`contact.Name`	Direct mapping.
Phonenumber	`contact.Phone`	Direct mapping.
ContactId	`contact.ContactId`	Converted to string.

Special Logic & Filters

Barred Customer Filtering: Only customers not marked as 'barred' (filter=barred$eq:0) are retrieved from the Economic API during the update process.
Batch Processing: Customer data is retrieved and processed in batches of up to 1000 records per page to optimize API calls and memory usage. This applies to customers, employees, delivery locations, and contact persons.
Dynamic Dropdowns: The connector dynamically creates and populates dropdown custom extra fields in App4Sales for VAT Zones, Customer Groups, Layouts, Payment Terms, and Sales Persons based on data fetched from Economic.
Error Handling for Contacts: If contact persons for a customer cannot be retrieved from Economic, an error is logged, but the customer update process continues for other customers.
Discount Mapping (Conditional): A discount can be mapped to the App4Sales customer if the CustomerFieldForPercentageDiscount setting is configured and the corresponding field exists and contains a valid decimal value in Economic.

Related Settings & Prerequisites

The following connector settings influence the behavior of the customer synchronization process:

Agreement Grant Token: This token is essential for authenticating with the Economic API to retrieve and update data. It must be configured correctly for the connector to function.
VAT Liable VAT Zones (VatLiableVatZones): A semicolon or comma-separated list of VAT zone numbers from Economic. If a customer's VAT zone number is in this list, the App4Sales customer's VatLiable flag will be set to true.
Customer Field for Percentage Discount (CustomerFieldForPercentageDiscount): Specifies the exact field name in Economic's customer data that holds a percentage discount value. If configured and a valid decimal value is present, this will be mapped to the App4Sales customer's discount field.

Known Limitations

Discounts & Dashboards: This connector's CustomerUpdate function does not directly handle item-class specific discounts ( DiscountsPerItemClassValue), customer dashboards, or generic customer notes. These functionalities, if required, would need to be managed through other App4Sales mechanisms or separate connector implementations.

Economic - Customer sync