NewBaseV4 Connector - Create Customer

This document details the process by which new customer records are created in the NewBaseV4 ERP system via the App4Sales platform. The process handles both customer and associated contact/address information, converting App4Sales customer data into the appropriate NewBaseV4 entities (Organisation and Debtor). The connector performs validation, generates unique customer codes, and updates App4Sales with the ERP-assigned identifiers.

Trigger & Permissions

The customer creation flow is typically triggered by a user action within the App4Sales mobile app or a backoffice sync request. The connector must have the necessary permissions to access the NewBaseV4 API endpoints for creating organisations, debtors, and updating customer and contact person data within App4Sales. The process involves creating an 'Organisation' and a 'Debtor' record in NewBaseV4.

Payload Mapping - Organisation Creation

When creating a new customer, the initial step involves creating an 'Organisation' record in NewBaseV4. The following table details the mapping from App4Sales Customer fields to NewBaseV4 Organisation fields:

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
CustomerName	`customer.CustomerName`	Mapped directly to Organisation Name.
MainContactPerson.FirstName	`customer.MainContactPerson?.FirstName`	Mapped directly to Contact First Name.
MainContactPerson.LastName	`customer.MainContactPerson?.LastName`	Mapped directly to Contact Last Name.
LanguageCode	`customer.LanguageCode?.ToLower()`	Mapped to Contact Language, converted to lowercase.
Website	`customer.Website`	Mapped directly to Contact URL.
ChamberOfCommerceCode	`customer.ChamberOfCommerceCode`	Mapped directly to Organisation Chamber Of Commerce Number.
MainContactPerson.Gender	`customer.MainContactPerson?.Gender`	Mapped to Gender, using `GetGenderCode()` extension. Defaults to 'Unknown' if not specified.
MainContactPerson.Function	`customer.MainContactPerson?.Function`	Mapped directly to Function.
Email	`customer.Email`, `customer.MainContactPerson?.Email`	If `customer.Email` is provided, it is used. Otherwise, `customer.MainContactPerson?.Email` is used. If both are empty, defaults to "no mail".
Phone	`customer.Phone`, `customer.MainContactPerson?.Phonenumber`	If `customer.Phone` is provided, it is used. Otherwise, `customer.MainContactPerson?.Phonenumber` is used. If both are empty, defaults to "000-0000000".
Fax	`visitAddress?.Fax`, `deliveryAddress?.Fax`	Uses Fax from visit address, otherwise from delivery address.
MainContactPerson.MobileNumber	`customer.MainContactPerson?.MobileNumber`	If provided, used as Contact Mobile. If empty, defaults to "000-0000000".
Country Code	`customer.Addresses.FirstOrDefault(e => e.IsMainAddress)?.Iso2` or `customer.Addresses.FirstOrDefault()?.Iso2`	The ISO2 country code from the main address (or first address if no main is specified) is used for Contact Fax Access Code, Contact Mobile Access Code, and Contact Phone Access Code.
Additional Data	`customer.GetAdditionalData(...)`	Custom fields or additional data are mapped using a generic extension method based on the NewBaseV4Constants.TableNames.Organisation.

Address Mapping (Organisation)

Address handling during organisation creation depends on the connector setting UseAddressesListForOrganisationAddresses:

If UseAddressesListForOrganisationAddresses is enabled: Addresses are sent as a list of OrganisationAddress objects.

App4Sales Field	Source Field	Logic/Notes
Delivery Address -> Street	`deliveryAddress.AddressLine1`, `deliveryAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Street is `AddressLine1`. Otherwise, it's `AddressLine1` followed by a newline and `AddressLine2`.
Delivery Address -> Number	`deliveryAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Number is `AddressLine2`. Otherwise, it's empty.
Delivery Address -> ZipCode	`deliveryAddress.PostCode`	Mapped directly.
Delivery Address -> City	`deliveryAddress.City`	Mapped directly.
Delivery Address -> CountryIso	`deliveryAddress.Iso2`	Mapped directly.
Delivery Address -> Type	Derived	Hardcoded to `(int)AddressType.Delivery`.
Visit Address -> Street	`visitAddress.AddressLine1`, `visitAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Street is `AddressLine1`. Otherwise, it's `AddressLine1` followed by a newline and `AddressLine2`.
Visit Address -> Number	`visitAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Number is `AddressLine2`. Otherwise, it's empty.
Visit Address -> ZipCode	`visitAddress.PostCode`	Mapped directly.
Visit Address -> City	`visitAddress.City`	Mapped directly.
Visit Address -> CountryIso	`visitAddress.Iso2`	Mapped directly.
Visit Address -> Type	Derived	Hardcoded to `(int)AddressType.Visit`.

If UseAddressesListForOrganisationAddresses is disabled: Addresses are mapped directly to individual fields on the OrganisationData object.

App4Sales Field	Source Field	Logic/Notes
DeliveryAddressStreet	`deliveryAddress.AddressLine1`, `deliveryAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Street is `AddressLine1`. Otherwise, it's `AddressLine1` followed by a newline and `AddressLine2`.
DeliveryAddressNumber	`deliveryAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Number is `AddressLine2`. Otherwise, it's empty.
DeliveryAddressZipCode	`deliveryAddress.PostCode`	Mapped directly.
DeliveryAddressCity	`deliveryAddress.City`	Mapped directly.
DeliveryAddressCountryIso	`deliveryAddress.Iso2`	Mapped directly.
VisitAddressStreet	`visitAddress.AddressLine1`, `visitAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Street is `AddressLine1`. Otherwise, it's `AddressLine1` followed by a newline and `AddressLine2`.
VisitAddressNumber	`visitAddress.AddressLine2`	If `UseAddressLine2AsHouseNumber` setting is true, Number is `AddressLine2`. Otherwise, it's empty.
VisitAddressZipCode	`visitAddress.PostCode`	Mapped directly.
VisitAddressCity	`visitAddress.City`	Mapped directly.
VisitAddressCountryIso	`visitAddress.Iso2`	Mapped directly.

Payload Mapping - Debtor Creation

After successful Organisation creation, a 'Debtor' record is created in NewBaseV4. The following table details the mapping from App4Sales Customer fields and generated values to NewBaseV4 Debtor fields:

App4Sales Field	Source Field	Logic/Notes
CustomerCode	Generated Internally	A unique customer code is generated by the connector using a configurable prefix, an incrementing ID, and zero-padding based on `CustomerNumberGenerationPrefix`, `CustomerNumberGenerationLastId`, and `CustomerNumberGenerationNumDigits` settings.
OrganisationId	NewBaseV4 Organisation ID	The `OrganisationId` returned from the NewBaseV4 Organisation creation response.
VatCode	`customer.VatCode`	Mapped directly to VAT Number.
ChamberOfCommerceCode	`customer.ChamberOfCommerceCode`	Mapped directly to Chamber of Commerce.
LanguageCode	`customer.LanguageCode?.ToLower()`	Mapped directly to Language Code, converted to lowercase.
UsesPriceField (Price List)	`customerPriceListExternalId`	The external ID of the customer's price list (`customer.UsesPriceField`) obtained from `PriceListsContext`. Mapped to PriceListId.
PricingAgreement	`connectorSettings.PricingAgreementForNewCustomers`	Determined by the connector setting `PricingAgreementForNewCustomers`.
Additional Data	`customer.GetAdditionalData(...)`	Custom fields or additional data are mapped using a generic extension method based on the NewBaseV4Constants.TableNames.Debtor.

Validation & Defaults

Prior to creating an Organisation, a basic validation is performed on the App4Sales Customer object:

The Phone field is checked to ensure it is not empty.
The MainContactPerson.MobileNumber field is checked to ensure it is not empty.
The Fax field is checked to ensure it is not empty.
The Email field is checked to ensure it is not empty.

If any of these fields are empty, the connector attempts to reset the corresponding reachability fields in NewBaseV4 to empty strings during an update operation, ensuring that NewBaseV4 does not retain old or invalid contact information if the App4Sales fields are cleared.

Default values are applied for contact information (Phone, Mobile, Email) if the App4Sales fields are empty, using "000-0000000" for phone/mobile and "no mail" for email during the initial Organisation creation request.

Response & Error Handling

After sending the Organisation and Debtor creation requests to NewBaseV4, the connector processes the responses:

If the Organisation creation response is null, unsuccessful, or lacks an OrganisationId or ContactId, an error is logged, and the customer creation fails.
If the Debtor creation response is null or unsuccessful, an error is logged, and the customer creation fails.
Upon successful creation of both Organisation and Debtor, the generated customer code is assigned to the App4Sales customer record.
The connector's internal CustomerNumberGenerationLastId setting is updated to reflect the newly assigned customer ID.
The App4Sales customer's CustomerCode is updated with the generated code.
Customer free fields are updated with the NewBaseV4 DebtorId, OrganisationId, and CustomerType (set to 'Debtor').
The ContactId for the main contact person in App4Sales is updated with the ContactId returned by NewBaseV4.
Any exceptions during the process are caught, logged, and result in a failed ConnectorActionResult.

Related Settings & Prerequisites

CustomerNumberGenerationPrefix: (Text) A prefix used for generating new customer codes.
CustomerNumberGenerationNumDigits: (Number) The number of digits to use for the numeric part of the generated customer code. Defaults to 5 if less than 2.
UseAddressesListForOrganisationAddresses: (Checkbox) If enabled, addresses are sent as a list of address objects during organisation creation. If disabled, addresses are sent as individual fields.
UseAddressLine2AsHouseNumber: (Checkbox) Influences how AddressLine1 and AddressLine2 from App4Sales are mapped to Street and Number fields in NewBaseV4.
PricingAgreementForNewCustomers: (Text) Specifies the pricing agreement to be used for newly created customers in NewBaseV4.

Known Limitations

The connector assumes that if customer.Phone or customer.MainContactPerson?.Phonenumber is empty, "000-0000000" is an acceptable temporary placeholder in NewBaseV4.
The connector assumes that if customer.Email or customer.MainContactPerson?.Email is empty, "no mail" is an acceptable temporary placeholder in NewBaseV4.

NewBaseV4 - Create customer