DbFact Connector - Create/Update Customer

Overview

This function handles the creation and updating of customer data in the DbFact ERP system. It is triggered when a user creates or edits a customer in App4Sales. The connector constructs an XML message with the customer's information and sends it to the DbFact web service.

Trigger & Permissions

This functionality can be invoked in two ways:

When a new customer is created in the App4Sales application. This requires the ConnectorInfoInternalIds.CreateCustomer flag to be enabled for the connector.
When an existing customer is edited in App4Sales. This requires the ConnectorInfoInternalIds.EditCustomer flag to be enabled.

The connector authenticates with the DbFact API using a session ID obtained through a login request with a username and password configured in the administration settings.

Data Source Configuration

The connector sends data to the DbFact web service. The endpoint URL is constructed dynamically based on the administration address and name, following the pattern: {AdministrationAddress}/Tml_{AdministrationName}/Tml_{AdministrationName}.asp.

The data is sent as a `POST` request with an XML payload.

Validation & Defaults

If a customer is not found in the App4Sales database using the provided GUID, the process is aborted with an error.
Several fields are converted to uppercase before being sent: CustomerName, VisitAddress1, VisitAddress2, VisitCity, ContactFullName, CountryCode, and LanguageCode.
For new customers, a temporary key is stored to link the temporary App4Sales customer code to the customer's GUID until the definitive ERP code is synchronized back.

Payload Mapping

The following table details the mapping of App4Sales customer fields to the DbFact XML payload.

Customer Header

DbFact Field (XML)	App4Sales Source Field	Logic/Notes
CustomerCode	CustomerCode	Sent if the customer already has a code (update scenario). Otherwise, it's an empty string.
CustomerGuid	CustomerGuid	Sent only for new customers (when `CustomerCode` is empty).
Name	CustomerName	Converted to uppercase.
Phone	Phone	Direct mapping.
Mobile	Mobile	Direct mapping.
Address	VisitAddress1	Converted to uppercase.
Address2	VisitAddress2	Converted to uppercase.
ZipCode	VisitPostCode	Converted to uppercase.
City	VisitCity	Converted to uppercase.
Country	CountryCode	Direct mapping.
IsoCountryCode	CountryCode	Converted to uppercase.
ContactName	ContactFullName	Converted to uppercase.
Email	Email	Direct mapping.
Fax	Fax	Direct mapping.
Language	LanguageCode	Converted to uppercase.
VatNumber	VatCode	Direct mapping.
CustomerType	N/A	Hardcoded to 'P'.
Discount	Discount	Direct mapping.
PaymentCondition	PaymentCondition	Direct mapping.
PriceList	UsesPrice	Mapped via the `GetDbFactPriceListId` method, which translates the App4Sales price list number (1-4) to a DbFact price list ID based on connector settings. Defaults to 1 if mapping fails.
VatTypeCode	UnknownElements["vat_type_code"]	Sent only for new customers. The value is retrieved from the request's unknown elements.
Representative	UnknownElements["representative"] or current user	The representative from the request is used, otherwise the logged in user is used as fallback.

Response & Error Handling

The connector expects an XML response from DbFact containing a Success node. If this node's value is "OK", the submission is considered successful.
If the submission is successful for a new customer, a key is saved in the KeySettings table to associate the temporary customer code with the App4Sales customer GUID.
If the response does not indicate success, an error message "DbFact did not accept the customer" is returned to App4Sales.
Any exceptions during the process are caught, logged, and returned as a generic error message to App4Sales.

Related Settings & Prerequisites

The following settings in the administration console affect the behavior of this function:

Environment: Specifies the dossier in DbFact where the customer data should be written.
PriceList1Id, PriceList2Id, PriceList3Id, PriceList4Id: These settings map the App4Sales price list numbers (1 through 4) to specific price list IDs in DbFact.

DbFact - Create customer