FtpXml Connector - Create Customer

Overview

The FtpXml connector facilitates customer creation by converting App4Sales customer data into an XML file and uploading it to a configured FTP/SFTP server. An external process, typically within the ERP system, is expected to monitor this FTP location, retrieve the XML file, and integrate the new customer information into the ERP. This process is triggered when a new customer is created or an existing one is updated within App4Sales.

Trigger & Permissions

The customer creation flow is initiated by the InsertOrUpdateCustomerCommand, which is subsequently handled by the OptA4SNewCustomers method in the FtpXml connector. For this functionality to be active, the following connector information flags must be enabled in the App4Sales administration:

Create Customer (corresponds to Constants.ConnectorInfoInternalIds.CreateCustomer)
Edit Customer (corresponds to Constants.ConnectorInfoInternalIds.EditCustomer)

Data Source Configuration

The FtpXml connector functions as a file transfer mechanism rather than a direct API integration. The customer data, serialized as an XML file, is uploaded to an FTP/SFTP server configured in the App4Sales administration.

FTP/SFTP Server Details: Configured via the Address field in Session.Administration.Address (e.g., ftp://yourhost.com/path or sftp://yourhost.com/path). This specifies the host, port, and base directory.
Authentication: Uses the username and password provided in the App4Sales administration for the FTP/SFTP connection.
Upload Path: The generated customer XML files are uploaded to [Base Folder Name]/customers/[customerCode].xml on the FTP/SFTP server, where [Base Folder Name] is derived from the configured address.
File Format: XML, adhering to the <NewCustomers> and <Customer> schema defined internally by App4Sales.

Payload Mapping - Core Customer Fields

The following table details the mapping from App4Sales internal Customer model fields to the XML elements in the generated Customer.xml file.

App4Sales Field	Source Field (XML Element Name)	Logic/Notes
`customer.CustomerCode`	`debCode`	Uses existing customer code or defaults to an empty string if null in `InsertOrUpdateCustomerCommand`.
`customer.CustomerName`	`customerName`	Direct mapping.
`customer.CustomerGuid`	`customerGuid`	Generated if empty; otherwise, uses the provided GUID.
`customer.MainContactPerson?.FullName`	`contactFullName`	Full name of the main contact person.
`customer.Email`, `customer.MainContactPerson?.Email`	`contactEmail`	Prioritizes main contact person's email; falls back to customer's email. Defaults to empty string if neither is available.
`customer.Email`	`customerEmail`	Direct mapping.
`customer.Addresses (Visit/Delivery)`	`contactFax`	Fax number from visit address, falling back to delivery address.
`customer.Phone`, `customer.MainContactPerson?.Phonenumber`	`contactPhone`	Prioritizes main contact person's phone number; falls back to customer's phone. Defaults to empty string if neither is available.
`customer.Phone`	`customerPhone`	Direct mapping.
Derived	`sysmodified`	Current timestamp when the XML is generated (`DateTime.Now`).
`customer.LanguageCode`	`languageCode`	Direct mapping.
`customer.Addresses (Visit/Delivery)?.Iso2`	`countryCode`	ISO 2-letter country code from visit address, falling back to delivery address. Defaults to "nl" if neither is available.
`customer.Discount`	`discount`	Converted to string using invariant culture.
`customer.UsesPriceField`	`usesPrice`	Converted to string using invariant culture.
`customer.PaymentConditionCode`	`paymentCondition`	Direct mapping.
`customer.VatLiable`	`isVATLiable`	Converted to "True" or "False" string.
`customer.VatCode`	`vatCode`	Direct mapping.
`customer.MainContactPerson?.MobileNumber`	`mobilePhone`	Mobile number of the main contact person.
`customer.ChamberOfCommerceCode`	`chamberOfCommerceCode`	Direct mapping.
`customer.Website`	`website`	Direct mapping.

Payload Mapping - Address Fields

Address information for the customer is mapped from the App4Sales Address objects, prioritizing visit addresses over delivery addresses.

App4Sales Field	Source Field (XML Element Name)	Logic/Notes
`customer.Addresses (Visit)?.AddressLine1`	`visitAddress1`	Visit address line 1.
`customer.Addresses (Visit)?.AddressLine2`	`visitAddress2`	Visit address line 2.
`customer.Addresses (Visit)?.PostCode`	`visitPostCode`	Visit address postal code.
`customer.Addresses (Visit)?.City`	`visitCity`	Visit address city.
`customer.Addresses (Visit)?.State`	`visitState`	Visit address state.
`customer.Addresses (Delivery)?.AddressLine1`	`deliveryAddress1`	Delivery address line 1.
`customer.Addresses (Delivery)?.AddressLine2`	`deliveryAddress2`	Delivery address line 2.
`customer.Addresses (Delivery)?.PostCode`	`deliveryPostCode`	Delivery address postal code.
`customer.Addresses (Delivery)?.City`	`deliveryCity`	Delivery address city.
`customer.Addresses (Delivery)?.State`	`deliveryState`	Delivery address state.

Payload Mapping - Dynamic Custom Fields

App4Sales Field	Source Field (XML Element Name)	Logic/Notes
`customer.UnknownElements`	Dynamic (Key of Dictionary)	Any key-value pairs in the `UnknownElements` dictionary are serialized as separate XML elements with the key as the element name and the value HTML-encoded.

Validation & Defaults

Customer GUID: If an incoming customer object has an empty CustomerGuid, a new GUID is automatically generated.
Customer Code: The customer.CustomerCode is ensured to be non-null by defaulting to an empty string before processing.
Country Code: If both visit and delivery addresses lack an ISO 2-letter country code, the countryCode defaults to "nl".
Email/Phone: If neither the main contact person nor the customer has an email/phone, the respective XML fields will be empty strings.

Response & Error Handling

After processing, the FtpXml connector returns a string indicating the outcome.

Success: If the customer XML file is successfully uploaded to the FTP/SFTP server, the connector returns a string prefixed with "Succes:" (Constants.RequestParameter.SUCCESS_CUSTOMER) followed by the customerCode. This customer code is then stored back into the App4Sales internal customer record.
Error during upload: If an exception occurs during the FTP/SFTP upload process, the connector returns an error message prefixed with "ERROR: ", including details about the exception.
Error during internal customer code lookup: A basic check for the customer code in the internal database is performed. If this query encounters an error, the connector immediately returns an error message prefixed with "ERROR: ".

Special Logic & Filters

Duplicate Detection: The connector performs a lightweight duplicate check by querying the internal App4Sales database for an existing customer with the same customerGUID as provided in the incoming XML. This is primarily for internal consistency and does not involve checking for duplicates in the external ERP system.
XML Generation and Upload: The primary logic involves generating an XML file with customer data and uploading it to a specified FTP/SFTP directory. The connector relies on an external system to pick up and process these XML files.
Logging: The generated customer XML payload is logged at an "Essential" level, providing visibility into the data being sent to the ERP.

Known Limitations

No Direct ERP API Integration: The FtpXml connector does not directly interact with the ERP system via an API. It relies solely on file transfer (FTP/SFTP) for data exchange. This means real-time feedback or complex transactional operations with the ERP are not natively supported by the connector itself.
Basic Duplicate Checking: Duplicate checking for customers is performed against the internal App4Sales database based on customerGUID. There is no inherent mechanism within this connector to check for existing customers directly within the target ERP system before uploading the XML file. The ERP system is responsible for handling duplicates on its end when processing the XML.
Asynchronous Processing: The customer creation is an asynchronous process from the perspective of App4Sales. Once the XML is uploaded to the FTP/SFTP server, the success or failure of its processing by the ERP system is not directly communicated back to the connector in real-time. The connector only confirms the successful upload of the file.

FtpXml - Create customer