ERPNext Connector - Create/Update Customer
This document describes the process of creating and updating customers in ERPNext from App4Sales.
Trigger & Permissions
The creation or update of a customer is triggered by the InsertOrUpdateCustomerCommand. This command is enabled when either the CreateCustomer or EditCustomer connector info flags are active. The logic differentiates between creating a new customer and updating an existing one based on the presence of the CustomerCode on the incoming customer model. If the CustomerCode is empty, a new customer is created. Otherwise, the existing customer with the matching code is updated.
Payload Mapping
The data from App4Sales is mapped to ERPNext entities. The following tables describe the field mappings for Customer, Contact Person and Address.
Customer
App4Sales Field | ERPNext Field | Logic/Notes |
CustomerName | CustomerName | Direct mapping. |
Currency | Currency | Direct mapping. |
Discount | Discount | Direct mapping from nullable decimal to decimal. |
LanguageCode | Language | Direct mapping. |
MainContactPerson.MobileNumber | MobileNumber | The mobile number of the main contact person. |
Phone | PhoneNumber | Direct mapping. |
Direct mapping. | ||
Website | Website | Direct mapping. |
DynamicFreeFields (CustomerGroupDynamicFreeFieldName setting) | CustomerGroup | The value of the dynamic free field specified in the |
DynamicFreeFields (CustomerTypeDynamicFreeFieldName setting) | CustomerType | The value of the dynamic free field specified in the |
DynamicFreeFields (TerritoryDynamicFreeFieldName setting) | Territory | The value of the dynamic free field specified in the |
Contact Person
App4Sales Field | ERPNext Field | Logic/Notes |
Direct mapping. | ||
FirstName | FirstName | Direct mapping. |
LastName | LastName | Direct mapping. |
Phonenumber | Phone | Direct mapping. |
IsMainContactPerson | IsPrimaryContact | Converted from boolean to an integer (1 for true, 0 for false). |
- | Links | A link to the customer is added, with |
Address
App4Sales Field | ERPNext Field | Logic/Notes |
- | Title | Generated by combining the customer's ERPNext name and the ERPNext address type (e.g., "CUSTOMER-NAME - Billing"). |
AddressLine1 | AddressLine1 | Direct mapping. |
AddressLine2 | AddressLine2 | Direct mapping. |
AddressLine3 | AddressLine3 | Direct mapping. |
City | City | Direct mapping. |
Iso2 / Country | Country | If |
Direct mapping. | ||
Phone | Phone | Direct mapping. |
PostCode | PostCode | Direct mapping. |
IsMainAddress | IsPrimaryAddress | Converted from boolean to an integer (1 for true, 0 for false). |
AddressType | AddressType | The App4Sales address type is converted to an ERPNext address type ('Invoice' -> 'Billing', 'Delivery' -> 'Shipping', others -> 'Other'). |
- | Links | A link to the customer is added, with |
Validation & Defaults
The system does not perform any explicit validation before sending the data to ERPNext. It relies on ERPNext to handle data validation. There are no default values set in the connector; if a field is empty in App4Sales, it will be sent as empty to ERPNext.
Response & Error Handling
After a successful customer creation or update, ERPNext returns a customer object. The Name property of this object is used as the customer's unique identifier (`CustomerCode`) in App4Sales. If the creation or update was for a new customer (i.e., no `CustomerCode` was initially provided), the App4Sales customer database is updated with the new code.
If ERPNext fails to return a customer code, an error is returned with the message "ERPNext backoffice not return customer code". Any other exceptions during the process are caught, logged, and returned as an error message to the user.
Related Settings & Prerequisites
The following settings in the connector configuration can influence the customer creation/update process:
CustomerGroupDynamicFreeFieldName: The name of the dynamic free field that contains the Customer Group.CustomerTypeDynamicFreeFieldName: The name of the dynamic free field that contains the Customer Type.TerritoryDynamicFreeFieldName: The name of the dynamic free field that contains the Territory.