FtpXml Connector - Send Order To Backoffice
Overview
This function is responsible for processing App4Sales orders and transmitting them to an external ERP system via FTP as an XML file. It performs several data transformations, calculations, and validations before generating and uploading the order XML. The process handles order headers, lines, and various related data, with specific logic for discounts, order numbers, and references.
Data Source Configuration
The App4Sales internal Order object serves as the data source for this process. The generated XML file is then uploaded to an external FTP server. The FTP connection details (host, port, username, password, connection type, and encryption method) are configured within the connector's administration settings. The target directory for order XML files on the FTP server is typically /orders within the configured FolderName.
Data Mapping Table - Order Header
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
OrderNr | Order.OrderNr | If empty, a new order number is calculated using |
Reference | Order.Salesrep / SalesRepsContext | Can be replaced by the sales representative's code ( |
Notes | Order.Notes / Order.OrderNr | If 'PlaceOrderNumberBeforeTheOrderNotes' setting is enabled, the generated order number ( |
AlternateAddress.EstablishmentName | Order.ConsumerName | If |
All other Order Header fields | Order object properties | Mapped directly to the XML structure as generated by |
Data Mapping Table - Order Line
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Description | OrderLine.Description / OrderLine.Instruction | If 'MergeInstructionAndDescriptionInTheOrder' setting is enabled, the |
Discount | OrderLine.Discount / Calculated | If 'CalculateTotalDiscountForOrderLine' setting is enabled, the discount is calculated based on |
Price | OrderLine.Price / Calculated | Adjusted if 'DontSendDiscountToBackoffice' setting is enabled to incorporate the discount into the price. |
All other Order Line fields | OrderLine object properties | Mapped directly to the XML structure as generated by |
Special Logic & Filters
Order Number Generation: If an order lacks an order number, a new one is generated by the App4Sales platform and then assigned to the order. This ensures every order has a unique identifier for the ERP.
Reference Field Prioritization: The 'Our Reference' field in the order header can be dynamically updated based on connector settings to either the sales representative's code or their full name. This allows for flexible tracking of order origin.
Order Notes Enrichment: The order number can be automatically added to the beginning of the order notes, providing quick traceability within the ERP system.
Order Line Description Consolidation: Item-specific instructions can be merged directly into the description of each order line, ensuring all relevant information is visible within a single field in the ERP.
Discount Handling: The connector provides options to either calculate a total discount per order line based on original item prices or to zero out discounts and embed their value into the item price itself, depending on how the ERP system expects discount information.
Alternate Address Defaulting: If an alternate delivery address is provided but lacks an establishment name, the consumer's name from the order header is used as a fallback.
XML Generation: The complete order object is serialized into an XML string using
order.GenerateOrderXml. TheOmitEexactTagInXmlsetting controls whether an Exact-specific root tag is included in the output XML.Local File Storage: The generated XML is temporarily saved to a local file before being uploaded to the FTP server. This ensures data integrity and provides a local copy in case of upload failure.
FTP Upload: The order XML file is uploaded to a predefined 'orders' directory on the configured FTP server.
Domain Specifics
Order Header Logic
The order header contains core information about the transaction and the customer. The connector ensures that unique order numbers are present and offers flexible options for populating the 'Our Reference' field with sales representative data. Additionally, order notes can be automatically enriched with the order number for improved traceability. The alternate delivery address's establishment name can also be automatically populated if missing.
Line & Pricing Logic
Each order line is processed to ensure that all necessary information, including descriptions, instructions, prices, and discounts, is correctly prepared for the ERP. The connector offers two distinct methods for handling discounts: calculating and sending them as a separate field or embedding them directly into the item price, which caters to different ERP integration requirements.
Charges & Attachments
Currently, the provided code snippet for SendOrderToBackoffice does not explicitly show logic for handling separate charge lines (surcharges like freight or payment fees) or attachments (like PDFs or images). The order.GenerateOrderXml method is responsible for serializing the Order object into XML, which would include any charges or attachments that are part of the standard Order object structure in App4Sales. The output XML schema would define how these are represented.
Responses & Error Handling
Upon successful processing and FTP upload, the connector returns the generated order number. In case of an FTP upload failure, the system logs the error, attempts to extract a user-friendly error message, and critically, resets the generated order number within App4Sales using OrdersContext.Instance.ResetOrderNumber to prevent gaps in the numbering sequence. The error message is then returned to the user.
Related Settings & Prerequisites
Replace Our Reference With Sales Rep: (Boolean) If enabled, the 'Our Reference' field in the order header will be populated with the sales representative's code.
Replace Our Reference With Sales Rep Name: (Boolean) If enabled, the 'Our Reference' field will be populated with the sales representative's full name. This setting takes precedence over 'Replace Our Reference With Sales Rep' if both are enabled.
Place Order Number Before The Order Notes: (Boolean) If enabled, the generated order number will be prepended to the order notes.
Merge Instruction And Description In The Order: (Boolean) If enabled, the instruction text of each order line will be appended to its description.
Calculate Total Discount For Order Line: (Boolean) If enabled, the total discount for each order line is calculated based on the original item price and the order line's price.
Dont Send Discount To Backoffice: (Boolean) If enabled, discounts are removed from order lines and their value is integrated into the item price, adjusting the price accordingly.
Omit Eexact Tag In Xml: (Boolean) Controls whether an 'Eexact' specific root tag is omitted from the generated order XML.
FTP Connection Settings: Host, Port, Username, Password, Use TLS, Use SSL, Ftp Active Connection (settings related to FTP/SFTP connection details and security).
Known Limitations
The current code does not explicitly show specific handling or parsing for surcharges or attachments beyond what order.GenerateOrderXml automatically includes in the XML payload. The structure of these elements in the output XML depends entirely on the Order object's internal representation and the GenerateOrderXml method.