SAPB1SL Connector - Customer Creation/Update

This document details the process by which customer data from App4Sales is created or updated in SAP Business One Service Layer (SAP B1SL) via the SAPB1SL connector. This functionality is crucial for synchronizing customer information between App4Sales and the ERP system, supporting both new customer onboarding and maintaining existing customer records.

Trigger & Permissions

The customer creation or update process is triggered from within the App4Sales platform. To enable this functionality, the connector must have the EditCustomer or CreateCustomer flags enabled within the connector's settings (ConnectorInfoInternalIds).

Data Source Configuration

The source of data is the App4Sales Customer model. This data is then transformed and sent to the SAP B1SL via a REST API call to the /BusinessPartners endpoint. Data is pushed from App4Sales to SAP B1SL.

Payload Mapping - App4Sales Customer to SAP B1SL Customer

The following tables detail how App4Sales customer fields are mapped to the SAP B1SL Business Partner (Customer) entity during creation and update operations. Transformations, default values, and conditional logic are also explained.

Core Customer Fields Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`CustomerCode`	`CustomerCode`	For new customers: Generated based on `NewCustomersCodePrefix` (default "A4S0000") and `NewCustomerCodeNumber` settings. If `SendEmptyCardCode` setting is true, an empty string is sent, allowing SAP B1SL to auto-generate the code. For existing customers: The existing `CustomerCode` is used for updates.
`CustomerName`	`CustomerName`	Directly mapped.
`Email`	`Email`	Directly mapped.
`Phone`	`Phone1`	Directly mapped.
`MobilePhone`	`Cellular`	Directly mapped from App4Sales customer's mobile phone to SAP B1SL's Cellular field.
`VatLiable`	`VatLiable`	Determined by a combination of connector settings and SAP B1SL customer data: If `UseVatLiableForCustomerVatLiable` is true: Based on the SAP B1SL `VatLiable` field (`Y` for liable, `N` for not liable). Else if `UseBillAddressFederalTaxIDAsCustomerVATLiableIndicator` is false: True if `VatNumber` is not empty and SAP B1SL `VatLiable` is `Y` or `vLiable`. Else (`UseBillAddressFederalTaxIDAsCustomerVATLiableIndicator` is true): True if any BillTo or ShipTo address has a non-empty `FederalTaxID`. When sending to SAP B1SL, `VatLiable` is mapped to `Y` if true, `N` if false.
`UsesPriceField`	`PriceListNum`	Maps to SAP B1SL PriceListCode. If `UsesPriceField` is 0, `PriceListNum` is set to null.
`PaymentConditionCode`	`PayTermsGrpCode`	Parses `PaymentConditionCode` to an integer for `PayTermsGrpCode`. If parsing fails or code is empty, `PayTermsGrpCode` is null.
`Discount`	`DiscountPercent`	Mapped if `UseCustomerDiscount` setting is true; otherwise, defaults to 0.0m.
`Currency`	`Currency`	Directly mapped.
`VatCode`	`VatNumber`, `FederalTaxID`	If `SendVatNumberInFederalTaxIDField` setting is true, `VatCode` is mapped to `FederalTaxID`, and `VatNumber` is null. Otherwise, `VatCode` is mapped to `VatNumber`, and `FederalTaxID` is null.
(Hardcoded)	`Series`	Set by the `CustomerSeries` connector setting.
(Hardcoded)	`CardType`	Set to `NewSapCustomerCardType` during creation. For updates, this field is not set.
`CustomerManager`	`SalesPersonCode`	Derived from the `SalesPersonCode` from SAP B1SL. If a sales person is found matching the code, the `SalesEmployeeName` is mapped to `CustomerManager`.
`CustomerClassification`	Dynamic Property	If `CustomerClassificationProperty` setting is configured, attempts to retrieve the value from a dynamic free field or an existing property of `SapB1SLCustomer`.
`CustomerEnabled`	`Valid`, `Frozen`	Determined by SAP B1SL `Valid` and `Frozen` fields and the `ExcludeInvalidCustomersFromSync` setting. If `ExcludeInvalidCustomersFromSync` is true and `Valid` is 'N' or `Frozen` is 'Y', `CustomerEnabled` is false.

Address Mapping (BPAddresses)

App4Sales addresses are mapped to SapB1SLAddress objects within the BPAddresses collection of the SapB1SLCustomer. During customer creation, all non-empty addresses from App4Sales are sent. For updates, existing external IDs (RowNumber and AddressName) are used to identify and update addresses in SAP B1SL.

App4Sales Address Field	Source Field (API/Excel/DB)	Logic/Notes
`AddressLine1`	`Street`	Directly mapped.
`AddressLine1` (concatenated)	`Name`	Derived from `CustomerName` and the readable SAP address type (e.g., "Customer A - Bill To"). For updates, if an external ID is present, its `AddressName` is used.
`City`	`City`	Directly mapped.
`Country` (ISO2)	`Country`	Mapped from App4Sales `Iso2` (ISO 2-letter country code) to SAP B1SL `Country`.
`State`	`State`	Directly mapped.
`PostCode`	`ZipCode`	Directly mapped.
`AddressType`	`AddressType`	App4Sales `Invoice` and `Visit` address types map to SAP B1SL `BillTo`. App4Sales `Delivery` address type maps to SAP B1SL `ShipTo`.
`CustomerCode`	`CustomerCode`	The customer's code is attached to each address.
`ExternalId`	`RowNumber`, `AddressName`	During updates, the `RowNumber` and `AddressName` for an address are retrieved from the `ExternalId` stored in the App4Sales database for existing addresses.

Contact Person Mapping (ContactEmployees)

Only the App4Sales MainContactPerson is sent to SAP B1SL during customer creation/update. It is mapped to a SapB1SLContactPerson object within the ContactEmployees collection.

App4Sales ContactPerson Field	Source Field (API/Excel/DB)	Logic/Notes
`ContactId`	`ContactId`	Mapped if not empty and parsable to an integer.
`Email`	`Email`	Directly mapped.
`FirstName`	`FirstName`	Directly mapped.
`MiddleName`	`MiddleName`	Directly mapped.
`LastName`	`LastName`	Directly mapped.
`FullName`	`FullName`	Directly mapped.
`MobileNumber`	`MobilePhone`	Directly mapped.
`Gender`	`Gender`	Directly mapped.

Dynamic Free Fields Mapping

If the App4Sales customer has DynamicFreeFields and the connector setting CustomCustomerFieldsMapping is configured, custom fields can be mapped to properties of the SapB1SLCustomer, SapB1SLContactPerson, or SapB1SLAddress. The CustomCustomerFieldsMapping setting expects a JSON array of objects with PropertyName (the name of the field in App4Sales) and ObjectName (Customer, ContactPerson, or Address) specifying where to apply the field in SAP B1SL.

Validation & Defaults

Customer Code Generation: For new customers, the CustomerCode is either generated using a prefix and a sequential number (controlled by NewCustomersCodePrefix and NewCustomerCodeNumber settings) or sent as an empty string to allow SAP B1SL to assign it (if SendEmptyCardCode is true).
VAT Liable Status: The VAT liable status is determined by multiple settings (UseVatLiableForCustomerVatLiable, UseBillAddressFederalTaxIDAsCustomerVATLiableIndicator) and the presence of VAT numbers in the customer or address data.
Price List Code: If the App4Sales UsesPriceField is 0, no price list code is sent to SAP B1SL.
Payment Terms Group Code: The App4Sales PaymentConditionCode must be an integer to be mapped to SAP B1SL PayTermsGrpCode.
Customer Status: When synchronizing customers from SAP B1SL to App4Sales, customers marked as 'invalid' (Valid='N') or 'frozen' (Frozen='Y') in SAP B1SL will be excluded from synchronization if the ExcludeInvalidCustomersFromSync setting is enabled.
Addresses: App4Sales 'Visit' address types are converted to 'Bill To' (Invoice) addresses when sending to SAP B1SL due to SAP B1SL limitations, but a copy is made during mapping from SAP B1SL to App4Sales to maintain the correct address type in App4Sales.
Language Code: The LanguageCode field in SapB1SLCustomer is not currently mapped from App4Sales, as there is no clear source for integer language codes.

Response & Error Handling

After attempting to create or update a customer in SAP B1SL:

Successful Creation: Upon successful creation, SAP B1SL returns the newly created customer object, from which the CustomerCode is extracted. This CustomerCode is then stored in App4Sales.
Successful Update: SAP B1SL returns a 204 (No Content) response for successful updates. The updated customer details are then fetched from SAP B1SL using the customer's code to ensure data consistency in App4Sales.
Errors: Any exceptions encountered during the API calls (e.g., if the SAP B1SL response for a create operation is null) are caught, logged, and re-thrown, indicating a failure in the customer creation/update process. Error messages are logged with relevant details, such as the customer's name.
Duplicate Detection: The connector primarily relies on the CustomerCode for identifying existing customers. For updates, a non-empty CustomerCode in the App4Sales customer object signals an update operation.

Related Settings & Prerequisites

SendEmptyCardCode: Boolean. If true, the CustomerCode is sent as an empty string during creation, allowing SAP B1SL to generate it.
NewCustomersCodePrefix: String. Prefix used when generating new customer codes (e.g., "A4S").
NewCustomerCodeNumber: Integer. Starting number for new customer codes (e.g., 0001).
UseVatLiableForCustomerVatLiable: Boolean. If true, the VAT liable status is directly taken from the SAP B1SL VatLiable field.
UseBillAddressFederalTaxIDAsCustomerVATLiableIndicator: Boolean. If true, the VAT liable status is determined by the presence of a FederalTaxID in BillTo or ShipTo addresses.
UseCustomerDiscount: Boolean. If true, the App4Sales customer Discount is mapped to SAP B1SL DiscountPercent.
SendVatNumberInFederalTaxIDField: Boolean. If true, the App4Sales VatCode is sent to SAP B1SL's FederalTaxID field instead of VatNumber.
CustomerSeries: Integer. Specifies the number series to be used for the customer in SAP B1SL.
CustomerClassificationProperty: String. Specifies a property name to use for customer classification from dynamic free fields or existing properties.
CustomCustomerFieldsMapping: JSON string. Defines mappings for dynamic free fields from App4Sales to SAP B1SL customer, contact person, or address properties.
ExcludeInvalidCustomersFromSync: Boolean. If true, customers with 'invalid' or 'frozen' status in SAP B1SL are excluded from synchronization to App4Sales.

Known Limitations

Language Code Mapping: The language code (LanguageCode) for SAP B1SL customers is not currently mapped from App4Sales due to a lack of clear source for integer language codes in the App4Sales model.
Address Types: SAP B1SL does not explicitly support a "Visit" address type. App4Sales "Visit" addresses are mapped to "Bill To" in SAP B1SL, with a workaround implemented to ensure the correct type is maintained within App4Sales during synchronization.

SAPB1SL - Create customer