DynamicsNav Connector - SendOrderToBackoffice
This document details the process by which App4Sales orders are sent to the Dynamics NAV back office system via the SendOrderToBackoffice function. This function translates App4Sales order data into a Dynamics NAV XMLPort structure (RootCreateOrder) and transmits it to the ERP. It handles order headers, order lines, and shipping addresses, including various transformations and validations based on connector settings. The process also captures the order number returned by Dynamics NAV and updates the internal App4Sales order record.
Order Header Logic
Customer selection, numbering, order-type routing, payment/shipping fields.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Customer Code |
| Maps the App4Sales customer code to the Dynamics NAV customer number. |
Your Reference |
| If |
Requested Delivery Date |
| The App4Sales order date, formatted as a date string. |
Campaign Number |
| Derived from the second part of the order type (e.g., "Order:FPS" uses "FPS") or directly from the order reference if no order type campaign is specified. |
Notes |
| Combines |
Document Type |
| The first part of the order type (e.g., "Order:FPS" uses "Order"). Default is "Order" if not specified. |
Ship To Code |
| If an alternate address is provided and matches an existing delivery address for the customer, the |
Sales Person |
| The sales representative code is set if the |
Customer Ship To Address |
| A new ship-to address is created in Dynamics NAV if an alternate address is provided and it is not an existing delivery address for the customer. |
Line & Pricing Logic
Source fields for items, quantities, prices, discounts, VAT adjustments.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Line Number |
| Sequential number for each order line, starting from 0. |
Item Number |
| The item code from the App4Sales order line. |
Quantity |
| The quantity of the item, formatted as a number. |
Unit Price |
| If the |
Line Discount Percentage |
| The discount percentage from the order line, formatted as a number with 5 decimal places, only if |
Instruction |
| The instruction text for the order line, only if |
Charges & Attachments
Freight/payment surcharges, PDF/JSON exports, signature/image uploads.
This connector does not explicitly handle charges, attachments, or extra payloads. Functionality related to these aspects is not implemented in the SendOrderToBackoffice process or associated DTOs.
Responses & Error Handling
Returned order numbers, duplicate detection, retry/backoff strategies.
The connector attempts to create the order in Dynamics NAV via the _client.CreateOrder method. If successful, it extracts the order number from the returned RootCreateOrder.SalesHeader[0].SalesHeaderOrderNo. This order number is then used to update the internal App4Sales order record. If the order number is empty or null, an error is returned. Errors during the API call (e.g., network issues, Dynamics NAV specific errors) are caught, logged, and returned to App4Sales with an ERROR prefix and the exception message.
Domain Specifics / Extension Section
Order Header Logic
The order.ApplyWebshopDiscountOnOrderLines method is called before converting the order to a Dynamics NAV entity, indicating that webshop discounts are processed at the App4Sales level and applied to order lines prior to transmission.
Customer Ship To Address Logic
When an alternate address is provided for an order, the connector first checks if it corresponds to an already existing delivery address for the customer in App4Sales. If it's not an existing address, a new ship-to address is constructed and sent to Dynamics NAV.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Ship To Address Name |
| The establishment name from the alternate address. |
Ship To Address Name 2 | (Empty String) | This field is always sent as an empty string. |
Ship To Address Address |
| The first address line from the alternate address. |
Ship To Address Address 2 |
| The second address line from the alternate address. |
Ship To Address Code | (Empty String) | This field is always sent as an empty string. |
Ship To Address Post Code |
| The postal code from the alternate address. |
Ship To Address City |
| The city from the alternate address. |
Ship To Address Country Region |
| If the |
Ship To Address Email |
| The email from the alternate address if valid; otherwise, |
Ship To Address Phone No |
| The phone number from the alternate address if not empty; otherwise, |
Related Settings & Prerequisites
Use reference as your reference: (Boolean) If enabled, the order's
Referencefield is used for Dynamics NAV's "Your Reference" field in the sales header, and the original "Your Reference" is appended to the notes. Otherwise,YourReferenceis used for "Your Reference" andReferenceis appended to the notes.Set sales rep on order: (Boolean) If enabled, the sales representative associated with the App4Sales order is sent to Dynamics NAV.
Send order line discount to Nav: (Boolean) If enabled, discount percentages on order lines are sent to Dynamics NAV, and the unit price is recalculated based on the discount.
Send order line prices to Nav: (Boolean) If enabled, unit prices for order lines are sent to Dynamics NAV.
Send order line prices to Nav based on source: (Text) A comma-separated list of order sources. If the order's source matches one in this list, unit prices are sent to Dynamics NAV regardless of the
Send order line prices to Navsetting.Enable order line instruction: (Boolean) If enabled, any instruction text on the App4Sales order line is sent to Dynamics NAV.
Send ISO Code As Ship To Address Country Region Order Field: (Boolean) If enabled, the ISO2 country code is used for the ship-to address country region; otherwise, the full country name is used.