Xlsx Connector - Send Order to Backoffice
The Xlsx Connector's `SendOrderToBackoffice` function is responsible for exporting App4Sales orders into an Excel (XLSX) file format and uploading them to a configured FTP server. This process handles the generation of order numbers (if not already present), transforms the internal App4Sales order structure into a flat XLSX format across two sheets, and then transmits this file.
Order Header Logic
Before exporting, if an App4Sales order does not have an `OrderNr` (order number) assigned, the system will automatically calculate and assign a unique order number. This new number is then saved back into the App4Sales database. The order header data is then prepared for export. Customer details are sourced from the `Customer` object associated with the order. Delivery address information prioritizes an `AlternateAddress` if provided; otherwise, it defaults to the main delivery address (`AddressType.Delivery` and `IsMainAddress = true`) from the customer's addresses.
Line & Pricing Logic
Each line item within an App4Sales order is processed to extract relevant details such as item code, description, quantity, price, discount, and any specific instructions. These are then written to a dedicated 'OrderLines' sheet within the generated XLSX file.
Charges & Attachments
The current implementation explicitly maps `TotalVat` (VAT), `TotalAmount` (total including VAT), `SubTotal` (total excluding VAT), and `ShippingCostsIncl` (shipping costs including VAT) directly from the App4Sales order header. There are no explicit provisions in this connector for handling additional surcharge lines or attachments like PDF exports, signature images, or other extra payloads directly in the generated XLSX files beyond what is implicitly included in the total amounts.
Responses & Error Handling
Upon successful processing, the function returns the `OrderNr` (order number) that was assigned or generated for the order. In the event that `Session.Administration.Address` (FTP server address) is not configured, the file upload step will be skipped, but the order number generation and database update will still occur. Any errors during the FTP upload are caught and logged. The system does not explicitly parse back-office responses for ERP order numbers or quote numbers, nor does it handle duplicate order detection at this stage; instead, it relies on the internal order number generation and FTP transmission.
Order Header Data Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
OrderNo | order.OrderNr | Generated if empty using `Session.PortalServerProvider.CalculateOrderNumber`. |
OrderDate | order.OrderDate | Direct mapping of the order date. |
Created | order.SysCreated | Timestamp of system creation. |
CustomerName | order.Customer?.CustomerName | Customer name associated with the order. |
CustomerCode | order.Customer?.CustomerCode | Customer code associated with the order. |
AddressLine1 | order.AlternateAddress.AddressLine1 OR mainAddress.AddressLine1 | Prioritizes alternate address; falls back to main delivery address line 1. |
AddressLine2 | order.AlternateAddress.AddressLine2 OR mainAddress.AddressLine2 | Prioritizes alternate address; falls back to main delivery address line 2. |
AddressLine3 | order.AlternateAddress.AddressLine3 OR mainAddress.AddressLine3 | Prioritizes alternate address; falls back to main delivery address line 3. |
PostCode | order.AlternateAddress.PostCode OR mainAddress.PostCode | Prioritizes alternate address; falls back to main delivery address postcode. |
City | order.AlternateAddress.City OR mainAddress.City | Prioritizes alternate address; falls back to main delivery address city. |
State | order.AlternateAddress.State OR mainAddress.State | Prioritizes alternate address; falls back to main delivery address state. |
Country | order.AlternateAddress.Country OR mainAddress.Country | Prioritizes alternate address; falls back to main delivery address country. |
Reference | order.Reference | Direct mapping of the customer reference. |
YourReference | order.YourReference | Direct mapping of your reference. |
Notes | order.Notes | General notes for the order. |
Remark1 | order.Description1 | Additional description field 1. |
Remark2 | order.Description2 | Additional description field 2. |
Remark3 | order.Description3 | Additional description field 3. |
Vat | order.TotalVat | Total VAT amount for the order. |
Total | order.TotalAmount | Total amount of the order, including VAT. |
SubTotal | order.SubTotal | Subtotal of the order, excluding VAT. |
ShippingCostsIncVat | order.ShippingCostsIncl | Shipping costs including VAT. |
Order Line Data Mapping
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
OrderNo | order.OrderNr | The order number of the parent order. |
LineNumber | line.Sequence | Sequence number of the order line. |
ItemCode | line.ItemCode | Code of the ordered item. |
Description | line.Description | Description of the ordered item. |
Quantity | line.Quantity | Quantity of the item ordered. |
Price | line.Price | Unit price of the item. |
Discount | line.Discount | Discount applied to the item line. |
Instruction | line.Instruction | Specific instructions for the item line. |
Data Source Configuration
The Xlsx Connector retrieves order data from the internal App4Sales database. It then transforms this data into an XLSX file. The generated XLSX file is then uploaded via FTP to a configurable remote server. The FTP server address, username, and password are all configured within the App4Sales Administration settings (`Session.Administration.Address`, `Session.Administration.Username`, `Session.Administration.Password`). The file is uploaded to a subfolder named "Orders" on the FTP server.
Special Logic & Filters
Order Number Generation: If an order lacks an `OrderNr`, a new one is generated and stored in the App4Sales database before export.
Address Selection: Delivery address details prioritize an `AlternateAddress` if available. Otherwise, the primary delivery address associated with the customer is used.
XLSX Export Format: The connector exclusively supports `ExportFormat.XLSX` for order data export. Any other format will result in an error.
File Naming: The exported XLSX file is named after the generated or existing order number (e.g., `[OrderNr].xlsx`).
FTP Upload: The order data is uploaded to the configured FTP server in the "Orders" subfolder. If no FTP address is configured, the upload is skipped.
Related Settings & Prerequisites
For the Xlsx connector to successfully send orders, the following administration settings must be configured:
Address: The FTP server address (e.g., `ftp://ftp.example.com`).
Username: The username for authenticating with the FTP server.
Password: The password for authenticating with the FTP server.