EzXml Connector - Create Customer

This function synchronizes an existing App4Sales customer with the ERP system by exporting its data in XML format via FTP. It is triggered when a customer, identified by its unique App4Sales CustomerGuid, needs to be created or updated in the connected ERP system.

Trigger & Permissions

The customer creation flow is initiated by the OptA4SNewCustomers method within the EzXml Connector. This method is invoked when the App4Sales platform requests the creation or update of a customer in the ERP.

For this functionality to be active, the connector settings must have the following capabilities enabled:

Create Customer (ConnectorInfoInternalIds.CreateCustomer)
Edit Customer (ConnectorInfoInternalIds.EditCustomer)

The incoming data is an XML payload containing customer information, which is parsed into an XmlCustomer object.

Data Source Configuration

The primary data source for creating an ERP customer via the EzXml connector is an existing App4Sales customer record. This record is identified by the CustomerGuid provided in the incoming XML payload. The connector then retrieves the full customer details from the App4Sales internal database.

The output is an XML file (FD_customers_.xml) which is generated from the App4Sales customer data and uploaded to the configured FTP server.

Validation & Defaults

Upon receiving an XML payload for customer creation, the connector performs the following validation and applies default logic:

**Customer Existence Check:** The CustomerGuid from the incoming XML payload is used to look up an existing customer within the App4Sales system. If no customer with the provided CustomerGuid is found in App4Sales, the operation is aborted, and an error message "Customer not found." is returned.
**Data Integrity:** Since the EzCustomer object is populated from an existing App4Sales customer record, it relies on the data integrity established within App4Sales.
**Address Defaults:** If a 'Delivery' address is not explicitly available, the connector attempts to use any other available address for mapping.
**Contact Person Defaults:** If a main contact person is not explicitly set for the App4Sales customer, the general customer's phone and email are used for the ERP contact fields.

Payload Mapping (Incoming XmlCustomer to App4Sales Customer Lookup)

The incoming XML payload, represented by the XmlCustomer object, is primarily used to identify an existing App4Sales customer for export.

App4Sales Field (Lookup)	Source Field (Incoming XML)	Logic/Notes
`CustomerGuid`	`customerGuid`	Used to retrieve the complete customer record from the App4Sales database.

Payload Mapping (App4Sales Customer to EzCustomer for ERP Export)

This table details how fields from the App4Sales customer model are mapped and transformed into the EzCustomer XML structure, which is then sent to the ERP via FTP.

Customer Header Fields

ERP Field (EzCustomer)	Source Field (App4Sales Customer)	Logic/Notes
`customer_no`	`CustomerCode`	Direct mapping.
`name`	`Name` or `Name2`	Uses `customer.Name`, falls back to `customer.Name2` if `Name` is null.
`e-mail`	`Email` / `MainContactPerson.Email`	Uses `customer.Email`. Overridden by `customer.MainContactPerson.Email` if `MainContactPerson` exists.
`telephone`	`Phone` / `MainContactPerson.Phonenumber`	Uses `customer.Phone`. Overridden by `customer.MainContactPerson.Phonenumber` if `MainContactPerson` exists.
`language_code`	`LanguageCode`	Direct mapping.
`currency_code`	`Currency`	Direct mapping.
`vat_registration_no`	`VatCode`	Direct mapping.
`invoice_discount_perc`	`Discount`	Mapped directly. Converted to string for XML.
`block_sales_order_entry`	N/A	Hardcoded to `false` initially during object creation, but can be set by code based on internal logic. Converted to "0" or "1" string for XML.
`contact`	`MainContactPerson.FullName`	Uses `customer.MainContactPerson.FullName` if `MainContactPerson` exists. Falls back to a default value if not set.
`vat_bus_posting_group`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.
`commision_salesagent_code`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.
`superfilters`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.
`payment_terms_text`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.
`shipment_method_text`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.
`shipping_agent_text`	N/A	Value not explicitly set in `CreateCustomer` method, but available as an ERP field.

Address Fields

The connector attempts to find a 'Delivery' address for the customer. If a 'Delivery' address is not found, the first available address is used. If no address is found, these fields may remain empty.

ERP Field (EzCustomer)	Source Field (App4Sales Address)	Logic/Notes
`address`	`AddressLine1`	First line of the selected address.
`address2`	`AddressLine2`	Second line of the selected address.
`post_code`	`PostCode`	Postcode of the selected address.
`city`	`City`	City of the selected address.
`country`	`Country`	Country of the selected address.

Price List Assignment

The connector determines the price list for the customer based on the following hierarchy:

App4Sales Field	Source Field (EzCustomer)	Logic/Notes
`UsesPriceField`	`CustomerNumber` & `Currency`	Attempts to find a price list with a code matching `{CustomerCode}-{Currency}` (e.g., "CUST123-EUR").
`UsesPriceField`	`PriceGroup` & `Currency`	If no customer-specific price list is found, it attempts to find a price list with a code matching `{PriceGroup}-{Currency}` (e.g., "GROUP_A-EUR"), provided `PriceGroup` is not empty.
`UsesPriceField`	N/A	If neither of the above is found, it defaults to a price list with the code defined as `Constants.Prices.DefaultPriceType`.

Response & Error Handling

Upon successful processing, the CustomerCode of the created/updated customer is returned.

If the incoming XML payload does not contain a valid XmlCustomer object, an error message "Incorrect XML input." is returned.

If the CustomerGuid from the incoming payload does not match an existing App4Sales customer, "Customer not found." is returned.

Any unhandled exceptions during the process will result in a generic ERROR_Unhandled message.

Special Logic & Filters

**Duplicate Detection:** The connector identifies the customer to be exported by matching the CustomerGuid from the incoming XML payload with an existing App4Sales customer record. This process does not create new App4Sales customer records but synchronizes existing ones with the ERP.
**Address Prioritization:** When mapping address details, the connector prioritizes the App4Sales customer's address marked as 'Delivery'. If no 'Delivery' address exists, it will use the first available address.
**Contact Person Resolution:** The main contact person's details (phone, email, full name) from the App4Sales customer are used preferentially for the ERP contact information.
**Price List Determination:** The system applies a hierarchical logic to determine the appropriate price list to associate with the customer in the ERP (customer-specific, then group-specific, then system default).

Related Settings & Prerequisites

**Connector Capabilities:** The connector must have 'Create Customer' and 'Edit Customer' flags enabled in its configuration.
**VAT Liability Configuration:** The connector uses the VatLiableCountryCode setting from Administrations.ConnectorSettings.EzXml to determine VAT liability based on the customer's country.
**FTP Configuration:** Proper FTP server details (host, credentials, paths) must be configured in the connector settings for the XML file upload.
**Default Price Type:** A default price list must be configured in App4Sales (matching Constants.Prices.DefaultPriceType) for fallback price list assignment.

Known Limitations

This connector function currently serves as an export/update mechanism for existing App4Sales customers to the ERP. It does not support the creation of entirely new customer records within App4Sales based on incoming ERP data.
The outgoing XML format for EzCustomer expects specific fields; any App4Sales customer data not explicitly mapped will not be included in the ERP synchronization.

EzXml - Create customer