DbFact - SendOrderToBackoffice

This function is responsible for preparing and sending App4Sales orders to the DbFact ERP system. It transforms an internal App4Sales order object, including its header, lines, and associated customer information, into a structured XML payload. This XML is then transmitted to DbFact via a SOAP web service. The function aims to ensure that order data is accurately mapped and transferred according to predefined business rules and connector settings.

Data Source Configuration

Order data is sourced directly from the internal App4Sales Order object. This object encapsulates all necessary information regarding the customer, order header details, and individual order lines. The target system is the DbFact ERP, with data transmission occurring through a SOAP web service endpoint. The XML payload is generated using the MakeOrderForDBfact method and sent via the Client.ReceiveFileWithComment method. All XML serialization uses the windows-1252 encoding.

Data Mapping Table - Order Header

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order Number	`order.OrderNr`	If empty, a new order number is generated using `Session.PortalServerProvider.CalculateOrderNumber`.
Customer ID (DbFact)	`order.Customer.CustomerCode` or `order.CustomerGuid`	Mapped from `order.Customer.CustomerCode` if the customer is existing. If it's a newly created customer (identified by `DbFactTempCustomer_` prefix in KeySettings), `CustomerGuid` is used for `DbFactCustomer.CustomerGuid` and `DbFactOrderHead.CustomerGuid`, while `CustomerCode` in `DbFactCustomer` is sent as empty, and `CustomerID` in `DbFactOrderHead` is null.
Customer Name	`order.Customer.CustomerName`	Directly mapped to `DbFactCustomer.Name`.
VAT Number	`order.Customer.VatCode`	Directly mapped to `DbFactCustomer.VatNumber`.
ISO Country Code (Customer)	`order.Customer.Addresses.FirstOrDefault(x => x.AddressType.IsEquals("vis"))?.Iso2`	Derived from the customer's "vis" (visit) address ISO2 code. Defaults to "NL" if not available.
Order Date	`order.OrderDate` or `DateTime.Now`	Mapped from `order.OrderDate` formatted as "yyyyMMdd". If `Settings.UseOrderDateAsDeliveryDate` is true, `DateTime.Now` is used instead.
Delivery Date	`order.OrderDate` or `DateTime.Now`	Mapped from `DateTime.Now` formatted as "yyyyMMdd". If `Settings.UseOrderDateAsDeliveryDate` is true, `order.OrderDate` is used instead.
Reference	`order.OrderNr`, `order.Reference`	Composed as "Order " + `order.OrderNr` + " - " + `order.Reference`.
Customer Reference	`order.YourReference`	Directly mapped.
Memo (Order Notes)	`order.Notes`	Mapped to `DbFactOrderHead.Memo` if `Settings.AddNotesToOrderLines` is false. Otherwise, order notes are added as separate order lines.
Type	Hardcoded	Sent as an empty string.
Payment Condition	`order.Customer.PaymentConditionCode`	Directly mapped.
Warehouse ID	`Settings.Warehouse`	Mapped from the connector setting "Warehouse".
Delivery Address	`order.AlternateAddress` (AddressLine1, AddressLine2, PostCode, City, Country, Iso2)	If an alternate delivery address is provided, its fields are mapped to `DbFactDeliveryAddress`. All string values are converted to uppercase using `SafeToUpper()`.
Send Delivery Date	`Settings.SendNoDeliveryDateOnOrder`	Boolean value, `true` if `Settings.SendNoDeliveryDateOnOrder` is false, otherwise `false`.

Data Mapping Table - Order Lines

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Item Code	`orderLine.Item.InternalItemCode` or `orderLine.Item.ItemCode`	If `Settings.UseSerialNumberAsItemCode` is true, `InternalItemCode` is used; otherwise, `ItemCode` is used.
Quantity	`orderLine.Quantity`	Mapped using `GetValueOrDefault()`.
Discount	`orderLine.Discount`	Mapped from `orderLine.Discount` if `IsFreeQuantity` is true or `Settings.IncludeDiscountInOrder` is true. If `Settings.IncludePriceByOrder` is true, the discount is sent as 0.
Price	`orderLine.Price`	Mapped from `orderLine.Price` if `Settings.IncludePriceByOrder` is true.
Description (for Notes)	`order.Notes`	If `Settings.AddNotesToOrderLines` is true, order notes are split into 60-character segments using `SpliceText(60)`, and each segment is sent as a separate order line with `ItemCode = "2"` and `Quantity = 1`.

Special Logic & Filters

**Order Number Generation:** If an order initially lacks an order number, a unique number is generated by the App4Sales platform.
**New Customer Handling:** The system checks for temporary customer codes (prefixed with DbFactTempCustomer_) to determine if a customer is new to DbFact. This influences how customer identification fields (CustomerCode, CustomerGuid) are populated in the XML.
**Free Quantity Logic:** The IsFreeQuantity method determines if an order line represents a free item based on the Settings.AllowFreeQuantity, a 100% discount, and a zero price. This influences the discount field in the generated XML.
**String Transformations:** Address fields (AddressLine1, AddressLine2, PostCode, City, Country, Iso2) are converted to uppercase using SafeToUpper() before being sent to DbFact.
**Order Notes Splitting:** If configured, long order notes are broken down into multiple 60-character lines to fit into DbFact order line descriptions.

Domain Specifics

Order Header Logic

The order header construction involves dynamic decisions based on existing customer data and connector settings. For new customers, a GUID is sent for identification. Dates for order and delivery are determined by the 'Use order date as delivery date' setting. The order reference combines the App4Sales order number and reference. A default warehouse can be configured via the 'Warehouse' setting. If an alternate delivery address is specified in App4Sales, it overrides the default customer address for delivery purposes.

Line & Pricing Logic

Order line item codes can be sourced either from the standard item code or an internal serial number, depending on the 'Use serial number as item code' setting. Discounts are conditionally included based on whether the item is considered a 'free quantity' (governed by 'Allow free quantity') or if the 'Include discount in order' setting is enabled. If 'Include price by order' is active, the unit price from App4Sales is sent, and any discount for that line is reset to zero. Furthermore, if 'Add notes to order lines' is active, general order notes are appended as distinct order lines, each with a special item code "2" and a quantity of 1.

Charges & Attachments

The MakeOrderForDBfact method does not explicitly handle specific charge lines (e.g., freight, payment fees) or attachments. Any such information would need to be incorporated as part of the order notes (and subsequently as order lines if 'Add notes to order lines' is enabled) or handled by a separate process outside of this function's scope.

Responses & Error Handling

After the XML payload is generated, it is sent to DbFact using Client.ReceiveFileWithComment(orderXmlDbFact). The SendOrderToBackoffice method then returns the App4Sales generated order number (order.OrderNr). While the direct response from DbFact is not used to update the App4Sales order within this method, the ReceiveFileWithComment call is expected to return an XML response. It is anticipated that this response is parsed for a success indicator (e.g., a "Success" node with value "OK"), similar to how customer updates are handled. If an error occurs during transmission or processing by DbFact, it is expected to be reflected in this response, and appropriate logging would capture the issue.

Related Settings & Prerequisites

The following connector settings directly influence the behavior of the SendOrderToBackoffice function:

Environment: Specifies the DbFact environment to which the order is sent.
Warehouse: Defines the default warehouse ID to be included in the order header.
Use serial number as item code: If true, the internal serial number is used as the item code in order lines instead of the standard item code.
Add notes to order lines: If true, order notes are split into multiple lines and added as separate order lines in the DbFact XML.
Allow free quantity: Used in conjunction with discount and price to determine if an item is a free quantity.
Include discount in order: If true, the discount percentage is included in the order line.
Use order date as delivery date: If true, the order date is used for the delivery date in DbFact, and vice-versa.
Send no delivery date on order: If true, the delivery date is not sent in the order header.
Include price by order: If true, the App4Sales unit price is included in the order lines, and the discount is set to 0 for that line.

Known Limitations

**Charges/Surcharges and Attachments:** The current implementation of MakeOrderForDBfact does not explicitly map separate charge lines (e.g., freight, payment fees) or order attachments. These would need to be handled outside this function or manually entered in DbFact.
**Real-time ERP Order Number Update:** The SendOrderToBackoffice method returns the App4Sales generated order number and does not directly capture and update the App4Sales order with an ERP-specific order number from the DbFact response. This implies that reconciliation of order numbers might occur through a different synchronization process.

DbFact - Send order