Winbas Connector - Send Order To Backoffice

This document details the process by which App4Sales orders are prepared and transmitted to the Winbas ERP system. The process involves mapping App4Sales order data to a Winbas-specific XML structure, saving it locally, and then uploading it via FTP. This function primarily handles order headers, order lines, and associated customer information.

Data Source Configuration

Orders originate from the App4Sales platform. The Winbas connector retrieves the order details from the App4Sales internal data structure. The processed order data is then exported as an XML file. This XML file is subsequently transferred to the Winbas ERP system via FTP using the connection details configured in the connector settings.

Data Mapping Table: Order Header

App4Sales Field	Source Field (XML Node)	Logic/Notes
Order ID (Internal)	UID	Mapped from the connector setting "Unique Identier" (`UniqueIdentier`).
Last Synchronization Date	LastSync	Automatically set to the current date and time of the synchronization.
Connector Version	Version	Hardcoded to "1.8.5366.26707".
Order Number (Winbas)	OrderItems[0].Number	Mapped from `Order.OrderNr`. If the connector setting "Use no order prefix" (`UseNoOrderPrefix`) is enabled, leading zeros are added to ensure a 5-digit number, prefixed with "1". Example: if App4Sales order number is "123", it becomes "100123".
Customer Order Number	OrderItems[0].YourOrderNumber	Mapped directly from `Order.OrderNr`.
VAT Code	OrderItems[0].VATCode	Determined by customer's VAT liability: if `Order.Customer.VatLiable` is true, it uses the value from connector setting "VatLiable code" (`VatLiableCode`); otherwise, it uses "Not vatLiable code" (`NoVatLiableCode`). (Typically 2 for liable, 3 for not liable).
Total VAT Amount	OrderItems[0].VATAmount	Mapped from `Order.TotalVat`.
Order Type	OrderItems[0].Type	Hardcoded to "1".
Salesperson Code	OrderItems[0].SalesmanCode	Based on connector settings: If "Set salesmancode based on customer manager off a customer for sending order" (`UseCustomerManager`) is enabled, uses `Order.Customer.CustomerManager`. If not, and "Set salesmancode based on username for sending order" (`UseApp4SalesUser`) is enabled, uses the App4Sales username. Otherwise, it is left empty.
Customer's Reference	OrderItems[0].Reference	Mapped from `Order.YourReference`. If empty, it sends null.
Our Reference	OrderItems[0].OurReference	Mapped from `Order.Reference`. If empty, it sends null.
Order Date	OrderItems[0].OrderDate	If connector setting "Send order date as delivery date" (`SendOrderDateAsDelivery`) is true, uses the current date and time (`DateTime.Now`). Otherwise, maps from `Order.OrderDate`.
Delivery Date	OrderItems[0].TimeOfDelivery	If connector setting "Send order date as delivery date" (`SendOrderDateAsDelivery`) is true, maps `Order.OrderDate` formatted as YYYYMMDD (integer). Otherwise, set to 0.
Import Status	OrderItems[0].ImportStatus	Hardcoded to "1".
Customer Number	OrderItems[0].CustomerNumber	Mapped from `Order.Customer.CustomerCode`.
Order Notes/Comment	OrderItems[0].Comment	Mapped from `Order.Notes`. If empty, it sends null.
Customer Name	OrderItems[0].Customer.Name	Mapped from `Order.Customer.CustomerName`.
Customer Number (within Customer node)	OrderItems[0].Customer.Number	Mapped from `Order.Customer.CustomerCode`.
Price List	OrderItems[0].Customer.PriceList	Mapped from `Order.Customer.UsesPriceField`.
Terms of Payment	OrderItems[0].Customer.TermsOfPayment	Mapped from `Order.Customer.PaymentConditionCode`.
Terms of Delivery	OrderItems[0].Customer.TermsOfDelivery	Mapped from `Order.Customer.DeliveryMethod`. Defaults to "1" if empty.
Customer VAT Code	OrderItems[0].Customer.VATCode	Determined by customer's VAT liability, same logic as Order Header VAT Code.
Customer Post Address	OrderItems[0].Customer.PostAddress	Composed from the App4Sales customer's delivery address (type "DEL") or, if not available, visiting address (type "VIS"). Format: "PostCode City".
Customer Country Code	OrderItems[0].Customer.CountryCode	Mapped from the `Iso2` of the selected App4Sales customer address (DEL or VIS).
Customer Telephone	OrderItems[0].Customer.Telephone	Mapped from the `Phone` of the selected App4Sales customer address (DEL or VIS).
Customer Email	OrderItems[0].Customer.eMail	Mapped from the `Email` of the selected App4Sales customer address (DEL or VIS).

Data Mapping Table: Order Line

App4Sales Field	Source Field (XML Node)	Logic/Notes
Line Number	OrderItems[0].Row[i].Number	Sequential index (0-based) for each order line.
Product Number	OrderItems[0].Row[i].ProdNumber	Mapped from `OrderLine.Item.ItemCode`.
Quantity	OrderItems[0].Row[i].Amount	Mapped from `OrderLine.Quantity`. If connector setting "Use unit for purchasepackagesize" (`UseUnitForPurchasePackageSize`) is enabled, the quantity is divided by `OrderLine.Item.PurchasePackageSize`. Defaults to 1 if quantity is null.
Discount Percentage	OrderItems[0].Row[i].Discount	Calculated based on original price and actual selling price. Only sent if connector setting "Send original price and calculate discount" (`SendOriginalPriceAndCalculateDiscount`) is enabled. If "Round order line discount percentages to nearest full number" (`RoundOrderLineDiscountPercentages`) is enabled, the percentage is rounded.
Override Price Flag	OrderItems[0].Row[i].OverridePrice	Set to true if connector setting "Send original price and calculate discount" (`SendOriginalPriceAndCalculateDiscount`) is enabled.
Unit Price	OrderItems[0].Row[i].Price	If connector setting "Send original price and calculate discount" (`SendOriginalPriceAndCalculateDiscount`) is true, the original item price is used (retrieved from `ItemPricesContext`). Otherwise, mapped from `OrderLine.Price`.
VAT Code	OrderItems[0].Row[i].VATCode	Determined by customer's VAT liability, same logic as Order Header VAT Code.
Line Comment	OrderItems[0].Row[i].Comment	Mapped from `OrderLine.Instruction` if "Use instruction as orderline delivery date" (`UseInstructionAsDeliveryDate`) is false. If empty, it sends null.
Line Delivery Date	OrderItems[0].Row[i].TimeOfDelivery	If connector setting "Use instruction as orderline delivery date" (`UseInstructionAsDeliveryDate`) is true, it attempts to parse the delivery date from `OrderLine.Instruction` (format YYYYMMDD). If parsing fails, logs an info message and sets to 0. If "Use order date for time of delivery at every orderline" (`UseDeliveryDateAsTimeOfDelivery`) is true, uses the order's delivery time (YYYMMDD).

Special Logic & Filters

Order Number Generation: If an App4Sales order does not have an assigned order number, the connector generates a new one using the Portal Server Provider and updates the App4Sales order accordingly.
XML Serialization: The generated Winbas OrderInfo object is serialized into an XML string using windows-1252 encoding. The connector specifically handles and replaces self-closing XML tags (e.g., <Tag /> becomes <Tag></Tag>) to accommodate Winbas's XML parsing limitations.
FTP Transfer: The serialized XML file is saved locally and then uploaded to the Winbas system via FTP. Errors during the FTP transfer are logged, and the order number is reset in App4Sales if the transfer fails.
Address Selection: When populating customer address details in the Winbas XML, the connector prioritizes the App4Sales customer's address with type "DEL" (delivery). If a delivery address is not found, it falls back to an address with type "VIS" (visiting). Other address types are ignored for the order export.
Pricing Logic: The calculation of order line prices and discounts is influenced by the "Send original price and calculate discount" setting. If enabled, the original item price from the App4Sales ItemPricesContext is used, and a percentage discount is calculated based on the difference from the order line's selling price.

Domain Specifics / Extension Section

Order Header Logic

The order header captures essential customer and order-level metadata. The connector handles customer identification via CustomerCode, and critical fields like VAT liability, payment, and delivery terms are directly mapped. The salesperson code can be dynamically assigned based on either the customer's assigned manager or the App4Sales user who placed the order, configurable via settings.

Line & Pricing Logic

Each order line includes product details, quantity, and pricing. Quantity handling can adjust for purchase package sizes. Pricing is flexible, allowing for either direct transmission of the negotiated price or recalculation of a discount percentage based on an original price, depending on system configuration. VAT codes are applied at the line level, mirroring the order header's VAT liability logic.

Charges & Attachments

Based on the analyzed code, there is no explicit mapping for surcharges (like freight or payment fees) or attachments (such as PDFs or signature images) from App4Sales to the Winbas order XML structure within the SendOrderToBackoffice process. If such elements are required by the Winbas ERP, they would need to be handled by additional custom logic or manual intervention within the Winbas system itself.

Responses & Error Handling

Upon successful transmission, the connector returns the Winbas order number to App4Sales. In case of any errors during the XML generation, local file saving, or FTP upload, an error message is returned, and the order number in App4Sales is reset. Detailed errors are logged for troubleshooting. The connector does not explicitly parse back any additional ERP order identifiers (like a unique ID from Winbas) beyond the order number generated or confirmed during the initial sending process.

Related Settings & Prerequisites

Unique Identier: A unique identifier for the connector, often a license key.
Send original price and calculate discount: (Boolean) If true, the connector sends the original item price and calculates a discount percentage for Winbas. Otherwise, it sends the net price directly.
Round order line discount percentages to nearest full number: (Boolean) If true, calculated discount percentages on order lines are rounded to the nearest whole number.
Send order date as delivery date: (Boolean) If true, the order date is also used as the delivery date in Winbas.
Use unit for purchasepackagesize: (Boolean) If true, order line quantities are divided by the item's purchase package size.
Use instruction as orderline delivery date: (Boolean) If true, the connector attempts to parse the delivery date for an order line from its instruction field (expected format YYYYMMDD).
VatLiable code: (String) The VAT code to use for VAT-liable customers/items in Winbas.
Not vatLiable code: (String) The VAT code to use for non-VAT-liable customers/items in Winbas.
Use order date for time of delivery at every orderline: (Boolean) If true, the order date is also used as the time of delivery for each order line.
Use no order prefix: (Boolean) If true, the App4Sales order number is prefixed with "1" and padded with leading zeros to a total of 5 digits before being sent as the Winbas order number.
Use customer manager: (Boolean) If true, the salesperson code in Winbas is derived from the App4Sales customer's manager.
Use App4Sales user: (Boolean) If true (and "Use customer manager" is false), the salesperson code in Winbas is derived from the App4Sales username.
Delivery Address Type: (Dropdown: None, Delivery, Invoice, Visit) Specifies which App4Sales address type is primarily used for customer delivery address mapping.
Shipping Address Type: (Dropdown: None, Delivery, Invoice, Visit) Specifies which App4Sales address type is used for customer shipping address mapping.

Known Limitations

The connector does not currently support sending surcharges (e.g., freight, payment fees) as distinct line items to Winbas.
No explicit handling or mapping for order attachments (e.g., PDFs, signature images) was observed in the code for the SendOrderToBackoffice process.
The connector does not currently retrieve or update App4Sales with additional Winbas-specific order identifiers beyond the order number itself.
The Version field in the Winbas XML export is hardcoded and not configurable via settings.

Winbas - Send order