NewBase - SendOrderToBackoffice

This function handles the process of sending an order from App4Sales to the NewBase ERP system. It involves generating an order number, preparing order data including customer and item details, and then posting this data to the NewBase API. It also handles the response from NewBase, updating the order number in App4Sales if necessary, and managing error conditions.

Data Source Configuration

The data primarily originates from the internal App4Sales Order object, which contains customer information, order lines, and other relevant details. Additional data is fetched from App4Sales contexts like ContactPersonsContext, CustomersContext, and ItemsContext. The NewBase API is the target system for the order.

Data Mapping Table (Order Header)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order Number	Derived	Generated internally by App4Sales. Uses `OrderNumberGenerationPrefix` as a prefix, increments the most recent order number (`OrdersContext.Instance.GetMostRecentOrderNr`), and pads with leading zeros based on `OrderNumberGenerationNumDigits`.
Customer Details	`order.Customer`	Passed directly from the App4Sales `Order` object.
Main Contact Person	`ContactPersonsContext.Instance.GetMainContactPersonByCustomerGuid(order.CustomerGuid)`	Retrieved from App4Sales internal context based on the customer GUID.
Customer Free Fields	`CustomersContext.Instance.GetCustomerFreeFields(order.Customer.CustomerCode)`	Retrieved from App4Sales internal context based on the customer code.
Settings	`Settings`	Various connector settings influence the order sending process.

Data Mapping Table (Order Lines)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Item Code	`ol.ItemCode`	Taken directly from the order line.
Price	`item.SalesPrice` (if `SendBasePriceForItemOrderLines` is true) otherwise `line.Price`	If `SendBasePriceForItemOrderLines` is enabled, the `SalesPrice` from `ItemsContext` is used as the line price. Otherwise, the original line price from the order is used.
Discount	Derived	If `SendBasePriceForItemOrderLines` is true and `item.SalesPrice` > `line.Price`, the discount percentage is calculated as `100 - (100 / item.SalesPrice * line.Price)` and rounded to two decimal places.

Special Logic & Filters

Order Number Generation: If the NewBase API does not support automatic order number generation, App4Sales generates a unique order number. This number is based on a configurable prefix (OrderNumberGenerationPrefix), the most recent order number, and a configurable number of digits (OrderNumberGenerationNumDigits).
Base Price for Order Lines: If SendBasePriceForItemOrderLines is enabled, the system retrieves the SalesPrice from the ItemsContext for each item in the order. If this SalesPrice is higher than the current line price, a discount percentage is calculated and applied to the line. The line's price is then set to the item's SalesPrice.
API Call: The order data, along with contact person details, customer free fields, and connector settings, is composed into a PostSalesOrder parameter object and sent to the NewBase API via an HTTP POST request.
Error Handling:
- If the NewBase API returns no response, an error is logged, the generated order number is reset in App4Sales, and an error message is returned.
- If the NewBase API response indicates failure (response.Success is false), an error is logged, the generated order number is reset, and an error message including the NewBase message is returned.
- If UseA4SOrderNumberAsOurRef is false and NewBase does not return an order number, an error is logged, the generated order number is reset, and an error message is returned.
- Any other exception during the process results in logging the error, resetting the order number, and returning an error message.
Order Number Update:
- If UseA4SOrderNumberAsOurRef is false (default behavior), the order number returned by NewBase (response.OrderNr) is used to update the order in App4Sales.
- If UseA4SOrderNumberAsOurRef is true, the internally generated order number is returned (it's assumed to have been sent to NewBase as their reference).

Domain Specifics / Extension Section

Order Header Logic

Order Numbering: App4Sales generates a unique order number locally if the ERP does not support automatic generation. This number respects OrderNumberGenerationPrefix and OrderNumberGenerationNumDigits.
Customer Information: Customer details from the App4Sales Order object are used. The main contact person and any custom free fields associated with the customer are also retrieved and included in the order payload.

Line & Pricing Logic

Item Pricing: The connector can be configured to send the base sales price for order lines (SendBasePriceForItemOrderLines). When this setting is enabled, the system will retrieve the SalesPrice of items from the App4Sales item context and recalculate discounts if the original line price is lower than the sales price.

Charges & Attachments

No explicit logic for handling charges or attachments is present within the SendOrderToBackoffice method. These might be handled at a different layer or not supported by this connector.

Responses & Error Handling

ERP Response: The connector expects a PostResponseSalesOrder from the NewBase API. This response includes a Success flag and potentially an OrderNr.
Duplicate Detection: Not explicitly handled in this method.
Retry/Backoff: Not explicitly handled in this method.
Order Number Update: The order number in App4Sales is updated with the ERP's order number if UseA4SOrderNumberAsOurRef is false. If UseA4SOrderNumberAsOurRef is true, the locally generated order number is retained.
Error Messages: Detailed error messages are returned to the user in case of API failure, no response, or missing order number from NewBase. The App4Sales order number is reset in case of any error during the process.

Related Settings & Prerequisites

Order Number Generation Prefix: A prefix used for generating App4Sales order numbers when NewBase does not provide one.
Order Number Generation Num Digits: The number of digits to use for the sequential part of the generated order number. Default is 5 if less than 2.
Send Base Price For Item Order Lines: A boolean flag. If true, the system will use the item's base sales price and calculate discounts accordingly.
Use A4S Order Number As Our Ref: A boolean flag. If true, the App4Sales generated order number is sent as NewBase's reference, and that same number is returned. If false, the order number returned by NewBase is used.

Known Limitations

NewBase API does not support automatic order number generation for orders sent via API, requiring App4Sales to generate it internally.
No explicit handling for charges or attachments is visible within this method.
No explicit retry or duplicate order detection logic is visible within this method.

NewBase - Send order