EzXml Connector - Send Order To Backoffice

The EzXml connector is responsible for transferring App4Sales orders to an external ERP system, typically via FTP. This process involves preparing the order data, converting it into a specific XML or CSV format based on connector settings, generating a unique order number, and then uploading the formatted order file to a predefined FTP folder. The system handles order headers, order lines, and freight costs, ensuring data is normalized for compatibility with the EzXml system.

Data Source Configuration

The primary data source for sending orders is the internal App4Sales OrderDb object, which encapsulates all details of an order placed within App4Sales. The prepared order data is then transmitted as a file (XML or CSV) to a configured FTP server.

Source: Internal App4Sales OrderDb object.
Target: An FTP server directory specified by the FtpOrderExportFolder setting.
Format: Can be XML (default and Reflecta) or CSV, determined by the OrderFormat connector setting.

Data Mapping Table - Order Header (Default XML Format)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Number`	`orderNumber`	Unique order number generated by the connector, combining order type and a sequential numeric ID.
`Id`	`order.InternalOrderNr` or `numericOrderNumber`	If `UseInternalOrdersAsWebOrderNr` setting is true and `order.InternalOrderNr` is provided, this field uses the internal order number. Otherwise, it uses the generated numeric order number.
`OrderType`	Hardcoded	Hardcoded value: "Default".
`OrderDate`	`order.OrderDate`	Direct mapping.
`SalesPerson`	`order.Salesrep`	Direct mapping.
`ShipmentDate`	`order.OrderLines.Max(x => x.DeliveryDate)`	The latest delivery date found among all order lines.
`CustomerGuid`	`customer.CustomerGuid`	Direct mapping from the associated customer.
`CustomerCode`	`customer.CustomerCode`	Direct mapping from the associated customer.
`CurrencyCode`	`customer.Currency`	Direct mapping from the associated customer.
`CustomerName`	`customer.Name`	Direct mapping from the associated customer.
`CustomerContact`	`customer.MainContactPerson?.FullName`	Full name of the main contact person for the customer.
`YourReference`	`order.YourReference`	Direct mapping.
`OrderComment1`	`order.Notes`	Direct mapping.
`Name`	`order.ConsumerName`	Consumer name if provided.
`Email`	`order.ConsumerEmail`	Consumer email if provided.
`Phonenumber`	`order.ConsumerPhoneNumber`	Consumer phone number if provided.
`Address`	`order.AlternateAddress?.AddressLine1`	First line of the alternate delivery address.
`PostCode`	`order.AlternateAddress?.PostCode`	Postal code of the alternate delivery address.
`City`	`order.AlternateAddress?.City`	City of the alternate delivery address.
`CountryState`	`order.AlternateAddress?.State`	State/province of the alternate delivery address.
`CountryCode`	`order.AlternateAddress?.Iso2`	ISO2 country code of the alternate delivery address.
`Customaddress`	`order.AlternateAddress`	"1" if an alternate delivery address is provided, "0" otherwise.
`Total_order_amount_ex_vat`	`order.TotalNoVat`	Total order amount excluding VAT, rounded to 2 decimal places.
`Total_order_vat_amount`	`order.TotalVat`	Total VAT amount for the order, rounded to 2 decimal places.
`Total_order_amount_incl_vat`	`order.TotalAmount`	Total order amount including VAT, rounded to 2 decimal places.
`Freight_costs`	`order.ShippingCostsIncl`	Freight costs including VAT, rounded to 2 decimal places.
`PaymentmethodId`	`order.IsPaid`	Hardcoded to "7" (for Mollie) if the order is marked as paid. Otherwise, `null`.
`Payment_id`	`order.IsPaid`, `PaymentDetailsContext`	If the order is marked as paid, the payment ID is retrieved from `PaymentDetailsContext`. Otherwise, `null`.
`Paid`	`order.IsPaid`	Hardcoded to "SUCCESS" if the order is marked as paid. Otherwise, `null`.

Data Mapping Table - Order Lines (Default XML Format)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Id`	Loop index	Sequential ID for each line, starting from 0.
`Quantity`	`line.Quantity`	Order line quantity. Rounded to a whole number before mapping.
`UnitOfMeasurement`	`line.Unit`	Direct mapping.
`Discount`	`line.Discount`	Direct mapping.
`Price`	`line.PriceExclVat`, `line.Price`	If `line.PriceExclVat` is available, it is used. Otherwise, `line.Price` is used. If `line.PriceExclVat` is null and item VAT is included, the price is recalculated to exclude VAT. All prices are rounded to 2 decimal places.
`BasePrice`	Calculated `Price`	Same as the calculated `Price`.
`ListPrice`	Calculated `Price`	Same as the calculated `Price`.
`LineAmount`	`Price * Quantity`	Calculated as the product of the line's price and quantity, formatted using invariant culture.
`EanCode`	`line.Item.EanCode`	EAN code of the item.
`VatPercentage`	`line.VatPercentage`	VAT percentage for the line, rounded to 2 decimal places.
`DeliveryWindowEnddate`	`line.DeliveryDate`	Direct mapping.
`VariantUniqueId`	`line.Item.ItemCode`	Item code for the variant.
`ModelDescription`	`line.Item.Description`	Description of the item model.
`BackorderStock`	`line.Item.LastAvailableStock`	Last available stock for the item, rounded to 2 decimal places.
`PriceInclItemDisc`	Calculated `Price`	Same as the calculated `Price`.
`GivenDiscountAmount`	Hardcoded	Hardcoded value: 0.
`Color`	`matrixChild.Description`	If the item is a matrix child, its color description is mapped.
`StyleNumber`	`matrixChild.YCode`	If the item is a matrix child, its style number is mapped.
`ColorSorting`	`matrixChild.Sequence`	If the item is a matrix child, its color sorting sequence is mapped.

Data Mapping Table - Order (CSV Format)

For the CSV format, header-level information is duplicated on each order line.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`WebOrderNo`	`order.InternalOrderNr` or `orderNumber`	If `UseInternalOrdersAsWebOrderNr` setting is true and `order.InternalOrderNr` is provided, this field uses the internal order number. Otherwise, it uses the generated order number.
`DateTimeStamp`	`DateTime.Now`	Current date and time, formatted as "yyyyMMdd HH:mm".
`SalesPerson`	`order.Salesrep`	Direct mapping.
`CustomerNo`	`order.Customer.CustomerCode`	Direct mapping.
`OrderType`	Hardcoded	Hardcoded value: "Inv".
`Address`	`order.AlternateAddress?.AddressLine1`	First line of the alternate delivery address.
`Address2`	`order.AlternateAddress?.AddressLine2`	Second line of the alternate delivery address.
`City`	`order.AlternateAddress?.City`	City of the alternate delivery address.
`PostCode`	`order.AlternateAddress?.PostCode`	Postal code of the alternate delivery address.
`CountryCode`	`order.AlternateAddress?.Iso2`	ISO2 country code of the alternate delivery address.
`CountyState`	`order.AlternateAddress?.State`	State/province of the alternate delivery address.
`EmailAddress`	`order.ConsumerEmail` or `order.Customer.Email`	Uses consumer email if available, otherwise customer email.
`Name`	`order.ConsumerName` or `order.Customer.Name`	Uses consumer name if available, otherwise customer name.
`OrderComment1`	`order.Notes`	Direct mapping.
`YourReference`	`order.YourReference`	Direct mapping.
`TotalOrderAmountExVAT`	`order.TotalNoVat`	Total order amount excluding VAT.
`TotalOrderAmountInclVAT`	`order.TotalAmount`	Total order amount including VAT.
`ShipmentDate`	Hardcoded	Hardcoded as an empty string.
`TotalOrderVATAmount`	`order.TotalVat`	Total VAT amount for the order.
`TotalOrderAmountExInvDisc`	`order.TotalNoVat`	Total order amount excluding invoice discount (same as total excluding VAT).
`VariantUniqueId`	`line.Item.ItemCode`	Item code for the variant.
`Quantity`	`e.Quantity`	Order line quantity. Rounded to a whole number before mapping.
`Discount`	`e.Discount`	Direct mapping.
`Price`	`e.Price`	Order line price. Rounded to 2 decimal places and adjusted for VAT before mapping.
`LineAmount`	`e.Quantity * e.Price`	Calculated as quantity multiplied by price.
`Color`	`matrixChild.Description`	If the item is a matrix child, its color description is mapped.
`StyleNo`	`matrixChild.YCode`	If the item is a matrix child, its style number is mapped.

Data Mapping Table - Order Header (Reflecta XML Format)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`WebOrderNr`	`order.InternalOrderNr` or `orderNumber`	If `UseInternalOrdersAsWebOrderNr` setting is true and `order.InternalOrderNr` is provided, this field uses the internal order number. Otherwise, it uses the generated order number.
`ProviderCode`	`ReflectaProviderCode`	Mapped from connector settings.
`ContextCode`	`ReflectaContextCode`	Mapped from connector settings.
`CompanyCode`	`ReflectaCompanyCode`	Mapped from connector settings.
`WarehouseGroupCode`	`ReflectaWarehouseGroupCode`	Mapped from connector settings.
`OrderDate`	`order.OrderDate`	Formatted as "dd-MM-yyyy".
`CustomerCode`	`order.Customer.CustomerCode`	Direct mapping.
`CurrencyCode`	`priceList?.IsoCurrency` or `priceList?.Currency`	Uses ISO currency code from the customer's price list if available, otherwise the general currency code from the price list.
`SalesRepCode`	`order.Salesrep`	Direct mapping.
`CustomerReference`	`order.YourReference`	Direct mapping.
`OrderOriginCode`	`ReflectaOrderOriginCode`	Mapped from connector settings.
`SeasonCode`	`ReflectaSeasonCode`	Mapped from connector settings.
`SalesDepartmentCode`	`ReflectaSalesDepartmentCode`	Mapped from connector settings.
`SalDeliveryTermCode`	`ReflectaDeliveryTermCodeWhenTheOrderHasNoShippingCosts` or `ReflectaDeliveryTermCode`	If `ReflectaDeliveryTermCodeWhenTheOrderHasNoShippingCosts` is set AND shipping costs are zero, this code is used. Otherwise, `ReflectaDeliveryTermCode` is used.
`FreightChargesAmt`	`order.ShippingCostsExcl`	Shipping costs excluding VAT, formatted to "0.00".
Address Fields (within Header)	`order.AlternateAddress`	If an alternate address is present, these fields are populated from it, with street, house number, and addition parsed from `AddressLine1`. Email, contact name, and phone prioritize consumer-provided values.

Data Mapping Table - Order Lines (Reflecta XML Format)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`WebOrderLineSeq`	Loop index	Sequential line number, starting from 1.
`ItemDimensionValidationObj`	`orderLine.ItemCode`	Direct mapping of the item code.
`OrderedQty`	`orderLine.Quantity`	Ordered quantity. Rounded to a whole number before mapping.
`SalesPriceAmt`	`orderLine.Price`	Sales price amount. Rounded to 2 decimal places and adjusted for VAT before mapping.

Special Logic & Filters

Data Normalization: All total amounts, VAT amounts, sub-totals, and individual line prices/quantities are rounded to 2 decimal places. Order line quantities are further rounded to whole numbers due to EzXml system limitations.
Order Number Generation: A unique order number is generated by combining the order type (defaulting to "Default" or "Inv" for CSV) with a sequentially incremented numeric order ID. The numeric ID is managed to ensure it always increases, even across system restarts or if external systems assign numbers.
Price Calculation: For default XML and Reflecta, if a price excluding VAT is not explicitly provided, and the original price includes VAT, the price is recalculated to remove the VAT component, ensuring the exported price is always exclusive of VAT.
Conditional Formatting: The output format (Default XML, CSV, or Reflecta XML) is dynamically selected based on the OrderFormat connector setting.
Alternate Address Parsing: For the Reflecta XML format, if an alternate delivery address is provided, AddressUtils.ParseAddress is used to extract street, house number, and addition from the first address line.
Consumer vs. Customer Data: For certain fields like Email, Name, and Phone in CSV and Reflecta formats, consumer-provided values (from OrderDb.ConsumerEmail, etc.) are prioritized over the general customer contact information.
Matrix Item Enrichment: For default XML and CSV formats, if an order line item is a matrix child, additional details such as Color, StyleNumber/StyleNo, and ColorSorting are populated from the MatrixChildrenContext.

Domain Specifics

Order Header Logic

Order Numbering: The generated order number can optionally use an internal order number from App4Sales if the UseInternalOrdersAsWebOrderNr setting is enabled. Otherwise, a sequentially generated number prefixed by the order type is used.
Order Type Routing: The default XML format uses "Default" as the order type, while the CSV format hardcodes "Inv". The Reflecta format uses connector settings for OrderOriginCode, SeasonCode, and SalesDepartmentCode to categorize the order.
Payment Information: For the default XML format, if an order is paid, the PaymentmethodId is hardcoded to "7" (for Mollie), and the Payment_id is retrieved from PaymentDetailsContext. The Paid field is set to "SUCCESS".
Delivery Terms (Reflecta): The SalDeliveryTermCode is conditionally set based on whether shipping costs are present and if a specific delivery term code for zero shipping costs is configured.

Line & Pricing Logic

Quantity Handling: All order line quantities are rounded to whole numbers before being sent to the EzXml system, as it does not support decimal quantities.
Price Precision: All prices (unit, sales, list) are rounded to 2 decimal places to meet EzXml system requirements.
VAT Adjustment: Prices are consistently adjusted to be exclusive of VAT when sent to the external system, even if the original App4Sales price included VAT.
Discount Representation: In the default XML format, the GivenDiscountAmount for order lines is currently hardcoded to 0. In CSV and Reflecta, direct discount fields are present at the line level.
Matrix Items: Detailed matrix item attributes like color and style are exported in default XML and CSV formats, enhancing product identification.

Charges & Attachments

Freight Costs: Freight charges are mapped as Freight_costs (including VAT) in the default XML format and FreightChargesAmt (excluding VAT, formatted to "0.00") in the Reflecta XML format.
Other Charges: There is no explicit mapping for other types of surcharges or charge lines beyond freight costs in the reviewed code.
Attachments: The reviewed code does not show explicit handling or mapping for attachments (e.g., PDFs, images) to be sent alongside the order.

Responses & Error Handling

Order Number Update: Upon successful transmission, the App4Sales internal order is updated with the generated external order number.
Last Order Number Persistence: The last used numeric order number is saved and persisted via KeySettingsContext to ensure continuity in order number generation.
Error Logging: Exceptions during the send order process are caught and logged, returning a generic ERROR_Unhandled message to App4Sales. The specific external system response for order numbers, quote numbers, or other status indicators is not directly parsed and mapped within the converters themselves but would be handled at a higher level if returned by the FTP process.

Related Settings & Prerequisites

The following connector settings influence the behavior of the "Send Order To Backoffice" function:

OrderFormat: Determines the output format of the order file (e.g., "CSV", "Reflecta", or default XML).
UseInternalOrdersAsWebOrderNr: (Boolean) If true, uses the App4Sales internal order number as the primary order identifier in the external system.
FtpOrderExportFolder: (String) The specific FTP directory where the generated order files will be uploaded. Defaults to "export" if not specified.
ReflectaProviderCode: (String, only for Reflecta format) Code identifying the provider in Reflecta.
ReflectaContextCode: (String, only for Reflecta format) Code identifying the context in Reflecta.
ReflectaCompanyCode: (String, only for Reflecta format) Code identifying the company in Reflecta.
ReflectaWarehouseGroupCode: (String, only for Reflecta format) Code identifying the warehouse group in Reflecta.
ReflectaOrderOriginCode: (String, only for Reflecta format) Code identifying the origin of the order in Reflecta.
ReflectaSeasonCode: (String, only for Reflecta format) Code identifying the season in Reflecta.
ReflectaSalesDepartmentCode: (String, only for Reflecta format) Code identifying the sales department in Reflecta.
ReflectaDeliveryTermCode: (String, only for Reflecta format) The default delivery term code for Reflecta orders.
ReflectaDeliveryTermCodeWhenTheOrderHasNoShippingCosts: (String, only for Reflecta format) A specific delivery term code to use when an order has no shipping costs.

Known Limitations

Payment Method Support (Default XML): Only Mollie is explicitly supported for payment method identification, with a hardcoded ID "7". Support for other payment methods is not apparent.
Discount Granularity (Default XML): The GivenDiscountAmount for individual order lines in the default XML format is always 0, indicating that item-level discounts might not be fully transferred or interpreted by the EzXml system.
Shipment Date (CSV): The ShipmentDate field in the CSV format is always an empty string.
Order Type (CSV): The OrderType field in the CSV format is hardcoded to "Inv".
Limited Line Details (Reflecta XML): The Reflecta XML format contains fewer details per order line compared to the default XML, lacking explicit fields for discount percentage, VAT percentage, or extensive item descriptions beyond the item code.
Missing Charges/Attachments Handling: Beyond freight costs, there is no explicit handling or mapping for other types of surcharges, charge lines, or attachments (e.g., PDFs, images) within the reviewed order conversion logic for any format.
Response Detail: The connector logs unhandled exceptions during the send process, but the current implementation doesn't appear to parse and map detailed ERP-specific order acknowledgment responses (like external order numbers or specific error messages beyond a generic "unhandled error") back into App4Sales. The generated order number is the primary identifier updated in App4Sales.

EzXml - Send order