NewBase Connector - Create New Customer

This document describes the process by which new customers are created in the NewBase ERP system via the App4Sales platform. The process handles both initial customer creation and updates, ensuring data consistency and proper communication with the ERP. When a new customer is created in App4Sales, the connector translates the App4Sales customer data into the NewBase's organization and debtor structures, handles ID generation, and manages initial contact information.

Trigger & Permissions

The customer creation/update flow is triggered when an App4Sales user attempts to create a new customer or modify an existing one, which then initiates an upsert operation. For this functionality to be active, the following connector information flags must be enabled in the App4Sales administration:

Edit customer
Create new customer

Data Source Configuration

The connector receives customer data from the App4Sales platform, typically through a form submission in the App4Sales application. This data is structured internally as an App4Sales.Models.Customer object, which is then transformed into an Optimizers.App4Sales.Models.SerializationObjects.XmlCustomer object for serialization and transmission to the NewBase ERP. Data is pushed to the NewBase ERP via API calls.

Payload Mapping - Customer (XmlCustomer to NewBase Organisation)

The following table details the mapping from the internal XmlCustomer object to the fields used when creating an Organisation and a primary contact in NewBase via the ws_contact_quick_entry endpoint. If contact information fields (Fax, Mobile, Phone, Email) in App4Sales are empty during initial creation, temporary placeholder values are sent to NewBase ("000-0000000" for phone/fax/mobile and "no mail" for email). These placeholders are subsequently updated to empty strings by the CustomerUpdater if they remain empty in App4Sales.

App4Sales Field (XmlCustomer)	Source Field (NewBase Organisation/Contact)	Logic/Notes
`CustomerName`	`OrganisationName`	Directly mapped.
`DeliveryAddress1`, `DeliveryAddress2`	`DeliveryAddressStreet`	Concatenated with a newline character between Address1 and Address2.
`DeliveryPostCode`	`DeliveryAddressZipCode`	Directly mapped.
`DeliveryCity`	`DeliveryAddressCity`	Directly mapped.
`CountryCode`	`DeliveryAddressCountryIso`	Directly mapped.
`VisitAddress1`, `VisitAddress2`	`VisitAddressStreet`	Concatenated with a newline character between Address1 and Address2.
`VisitPostCode`	`VisitAddressZipCode`	Directly mapped.
`VisitCity`	`VisitAddressCity`	Directly mapped.
`CountryCode`	`VisitAddressCountryIso`	Directly mapped.
`ContactFullName`	`ContactFirstName`, `ContactLastName`	The full name is split into first and last names using an internal helper method (`GetFirstNameV2()`, `GetLastNameV2()`).
`LanguageCode`	`ContactLanguage`	Converted to lowercase.
`Fax`	`ContactFax`	If empty, "000-0000000" is sent as a temporary placeholder.
`Mobile`	`ContactMobile`	If empty, "000-0000000" is sent as a temporary placeholder.
`Phone`	`ContactPhone`	If empty, "000-0000000" is sent as a temporary placeholder.
`Email`	`ContactEmail`	If empty, "no mail" is sent as a temporary placeholder.
`UnknownElements`	Dynamic Custom Fields	Any `UnknownElements` (dynamic custom fields) are serialized as additional XML elements within the customer payload.

Payload Mapping - Customer (XmlCustomer to NewBase Debtor)

Once the organisation is created, a corresponding Debtor entry is created in NewBase via the ws_debtor endpoint. This links the App4Sales customer to the financial entity in NewBase.

App4Sales Field (XmlCustomer)	Source Field (NewBase Debtor)	Logic/Notes
Generated `CustomerCode`	`CustomerCode`	The customer code is generated by App4Sales based on connector settings (prefix, number of digits).
Organisation ID	`OrganisationId`	The ID received from the successful `PostOrganisation` API call.
`VatCode`	`VatNumber`	Directly mapped.
`ChamberOfCommerceCode`	`ChamberOfCommerce`	Directly mapped.
`LanguageCode`	`LanguageCode`	Converted to lowercase.

Validation & Defaults

Before sending data to NewBase, the connector performs contact information validation. Although temporary placeholder values are used for empty phone, mobile, fax, and email fields during the initial organisation creation, the CustomerUpdater.ResetReachabilities method is called afterward if these fields were originally empty in App4Sales. This ensures that the contact fields are set to empty strings in NewBase if the App4Sales input was empty.

The CustomerCode is automatically generated by App4Sales using a configurable prefix and a sequential numbering system. If a CustomerCode is already present in the incoming App4Sales customer data, the connector performs an update operation instead of an insert.

The CountryCode for both delivery and visit addresses defaults to "nl" if not explicitly provided.

The IsVatLiable field is mapped to "True" or "False" based on the boolean value of customer.VatLiable.

Response & Error Handling

Upon successful creation of the organisation and debtor in NewBase, the connector retrieves the newly generated NewBase Organisation ID, Contact ID, and the generated CustomerCode. This CustomerCode is then updated in the App4Sales CMS for the created customer. The internal CustomerNumberGenerationLastId setting is also updated to reflect the new highest customer ID.

If the API calls to NewBase for creating the organisation or debtor fail, an InvalidOperationException is thrown with a detailed error message from the NewBase ERP, which is then surfaced in the App4Sales UI.

If no response is received from NewBase during the creation process, a generic "No response from NewBase" error is returned.

Related Settings & Prerequisites

The following connector settings influence the customer creation process:

Automatic customernumber prefix: A string prefix applied to automatically generated customer numbers (e.g., "CUST-").
Automatic customernumber # of digits: The number of digits used for the sequential part of the customer number (default: 5).

NewBase - Create customer