Economic Connector - Create Customer

This document details the customer creation and update process within the Economic connector. The connector supports both creating new customer records and updating existing ones in the Economic ERP system. Incoming customer data is provided via an XML payload, which is then processed and mapped to internal App4Sales and Economic ERP entities.

Data Source Configuration

The connector expects an XML payload as its input, contained within the inputStream of the InternalRequest. This XML must conform to the NewCustomers schema, which is a collection of XmlCustomer objects. Each XmlCustomer object represents a single customer record with its associated details.

The root XML element is <NewCustomers>, containing one or more <Customer> elements. Below are the expected XML elements within a <Customer> element:

XML Element	Description
`<debCode>`	The customer's code. If this is empty, a new customer will be created.
`<customerName>`	The name of the customer.
`<customerGuid>`	The GUID of the customer.
`<contactFullName>`	The full name of the primary contact person for the customer.
`<visitAddress1>`	The first line of the customer's visiting address.
`<visitAddress2>`	The second line of the customer's visiting address.
`<visitPostCode>`	The postal code of the customer's visiting address.
`<visitCity>`	The city of the customer's visiting address.
`<visitState>`	The state of the customer's visiting address.
`<deliveryAddress1>`	The first line of the customer's delivery address.
`<deliveryAddress2>`	The second line of the customer's delivery address.
`<deliveryPostCode>`	The postal code of the customer's delivery address.
`<deliveryCity>`	The city of the customer's delivery address.
`<deliveryState>`	The state of the customer's delivery address.
`<contactEmail>`	The email address of the primary contact person.
`<customerEmail>`	The email address of the customer.
`<contactFax>`	The fax number of the primary contact person.
`<contactPhone>`	The phone number of the primary contact person.
`<customerPhone>`	The phone number of the customer.
`<languageCode>`	The language code for the customer.
`<countryCode>`	The country code for the customer.
`<discount>`	The discount percentage for the customer.
`<usesPrice>`	Indicates whether the customer uses specific pricing.
`<paymentCondition>`	The payment condition code for the customer.
`<isVATLiable>`	Indicates if the customer is VAT liable (boolean, "0", "1", "true", "false").
`<vatCode>`	The VAT code for the customer.
`<mobilePhone>`	The mobile phone number of the customer.
`<chamberOfCommerceCode>`	The Chamber of Commerce code for the customer.
`<website>`	The customer's website URL.
`<VatZone>`	(Optional) The VAT Zone number, used for lookup.
`<CustomerGroup>`	(Optional) The Customer Group number, used for lookup.
`<Currency>`	(Optional) The currency code.

Data Mapping Table (App4Sales XmlCustomer -> Economic ERP Customer)

The following table illustrates how fields from the incoming XmlCustomer object are mapped to the Entities.Customer object for the Economic ERP system. Transformations and lookup logic are also detailed.

App4Sales Field (Economic.Entities.Customer)	Source Field (XmlCustomer)	Logic/Notes
`corporateIdentificationNumber`	`VatCode`	Directly mapped.
`customerNumber`	`CustomerCode`	Converted from string to nullable integer. If `CustomerCode` is empty or invalid, it will be `null`.
`name`	`CustomerName`	Directly mapped.
`email`	`Email`	Directly mapped.
`telephoneAndFaxNumber`	`Phone`	Directly mapped.
`address`	`VisitAddress1`	Directly mapped (first line of the visiting address).
`city`	`VisitCity`	Directly mapped.
`country`	`CountryCode`	Directly mapped.
`zip`	`VisitPostCode`	Directly mapped.
`lastUpdated`	`DateTime.Now`	Set to the current date and time when the customer entity is created/updated.
`publicEntryNumber`	`ChamberOfCommerceCode`	Directly mapped.
`paymentTerms`	`PaymentCondition`	Looked up from the available payment terms collection. The `PaymentCondition` from `XmlCustomer` (parsed as an integer) is used to find a matching `paymentTermsNumber`.
`vatZone`	`UnknownElements["VatZone"]`	Looked up from the available VAT zones collection. The value of the XML element `<VatZone>` (parsed as an integer) is used to find a matching `vatZoneNumber`.
`customerGroup`	`UnknownElements["CustomerGroup"]`	Looked up from the available customer groups collection. The value of the XML element `<CustomerGroup>` (parsed as an integer) is used to find a matching `customerGroupNumber`.
`currency`	`UnknownElements["Currency"]`	If the XML element `<Currency>` is present in the incoming XML, its value is used. Otherwise, it defaults to `null`.
Dynamic Discount Field	`Discount`	If the connector setting "Customer field to use as discount percentage" (`CustomerFieldForPercentageDiscount`) is configured and a `discount` value is present in the `XmlCustomer`, this value is set to the specified dynamic customer field in Economic.

Data Mapping Table (App4Sales XmlCustomer -> Economic ERP Contact Person)

The following table illustrates how fields from the incoming XmlCustomer object are mapped to the Entities.ContactPerson object for the Economic ERP system. This contact person is associated with the customer upon creation.

App4Sales Field (Economic.Entities.ContactPerson)	Source Field (XmlCustomer)	Logic/Notes
`Name`	`ContactFullName`	Directly mapped.
`Email`	`Email`	Directly mapped.
`Phone`	`Phone`	Directly mapped.

Special Logic & Filters

Customer Creation/Update Logic

The OptA4SNewCustomers method acts as the primary entry point, delegating to the UpsertCustomers method. This method iterates through each XmlCustomer received in the request. The logic for determining whether to create a new customer or update an existing one is as follows:

If XmlCustomer.CustomerCode is empty or null, the system considers it a new customer and attempts to create it using an HTTP POST request to the /customers endpoint of the Economic API.
If XmlCustomer.CustomerCode has a value, the system considers it an existing customer and attempts to update it using an HTTP PUT request to the /customers/{customerNumber} endpoint. The customerNumber is derived from the XmlCustomer.CustomerCode.

Contact Person Creation

After a customer is successfully created in Economic, the connector initiates an asynchronous task (Task.Run) to create a corresponding contact person. This contact person is built using the ContactFullName, Email, and Phone from the XmlCustomer. The contact person is created via an HTTP POST request to the /customers/{customerNumber}/contacts endpoint. The ContactId returned from Economic for the newly created contact person is then updated in the App4Sales session via Session.PortalServerProvider.UpdateContactId.

Handling of Unknown XML Elements

The XmlCustomer class implements IUnknownElementSupport, which allows the connector to process XML elements that are not explicitly defined as properties within the XmlCustomer schema. These "unknown" elements are stored in a dictionary (UnknownElements) and can be used for dynamic mapping, such as for VatZone, CustomerGroup, and Currency lookups, as detailed in the data mapping table.

Domain Specifics / Extension Section

Lookups for Related Entities

During the conversion of XmlCustomer to Entities.Customer, several related entities are looked up within the Economic system to ensure data consistency and referential integrity:

Payment Terms: The PaymentCondition from XmlCustomer is used to find a matching PaymentTerm object from a pre-fetched collection of Economic payment terms.
VAT Zones: The value from the <VatZone> XML element (if present) is used to find a matching VatZone object from a pre-fetched collection of Economic VAT zones.
Customer Groups: The value from the <CustomerGroup> XML element (if present) is used to find a matching CustomerGroup object from a pre-fetched collection of Economic customer groups.

Related Settings & Prerequisites

The following connector settings can influence the customer creation and update process:

VAT liable VAT Zone ID's (VatLiableVatZones): A semicolon or comma-separated list of VAT Zone IDs. This setting is used to determine if a customer should be marked as VAT liable based on their assigned VAT zone.
Customer field to use as discount percentage (CustomerFieldForPercentageDiscount): Specifies a custom customer field in Economic where the discount percentage from XmlCustomer.Discount should be stored.

Known Limitations

The documentation does not explicitly detail the handling of delivery addresses from XmlCustomer.DeliveryAddress1, DeliveryAddress2, DeliveryPostCode, DeliveryCity, and DeliveryState. While these fields are present in the incoming XML, their direct mapping or use in the ConvertToEntity or `SetDeliveryAddresses` methods for the primary customer entity or additional delivery locations is not fully clear from the analyzed code snippet.

The provided code snippet for `SetDeliveryAddresses` shows that existing delivery locations from Economic (ICollection deliveryLocations) are used to populate addresses in the App4Sales model, but it's not clear how XmlCustomer's delivery address fields would contribute to new delivery locations during customer creation/update. If no deliveryLocations exist, these fields from the XmlCustomer might not be used.

Economic - Create customer