Microsoft Business Central Connector - Send Order To Backoffice

This document details the process by which the App4Sales platform transmits orders, invoices, and quotes to Microsoft Business Central. It covers the logic for order header creation, line item processing, discount handling, and the mapping of various App4Sales fields to their corresponding fields in MBC.

Order Header Logic

The connector intelligently routes orders based on their type (Order, Invoice, or Quote) and handles return orders separately. It composes customer and delivery information, applying conditional logic for contact details and shipping addresses based on API versions and connector settings.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order.Customer.MainContactPerson.ContactId	MBC Sales Order ContactId	Mapped only if `DontSendContactIdOnSalesOrder` is false AND `UseApiVersion2` is false.
App4Sales Order.Customer.InternalCode	MBC Sales Order CustomerId	Parsed as a GUID.
App4Sales Order.Customer.CustomerCode	MBC Sales Order CustomerNumber	Direct mapping.
App4Sales Order.Customer.Currency	MBC Sales Order CurrencyCode	Direct mapping.
App4Sales Order.Delivered	MBC Sales Order FullyShipped	Boolean flag indicating if the order is fully shipped.
App4Sales Order.OrderDate	MBC Sales Order RequestedDeliveryDate	Formatted as "yyyy-MM-dd".
App4Sales Order.AlternateAddress?.EstablishmentName OR App4Sales Order.ConsumerName	MBC Sales Order ShipToContact, ShipToName	If an alternate address establishment name is provided, it is used; otherwise, the consumer name is used.
App4Sales Order.AlternateAddress?.Phone OR App4Sales Order.ConsumerPhoneNumber	MBC Sales Order Phone	If an alternate address phone is provided, it is used; otherwise, the consumer phone number is used.
App4Sales Order.AlternateAddress?.Email OR App4Sales Order.ConsumerEmail	MBC Sales Order Email	If an alternate address email is provided, it is used; otherwise, the consumer email is used.
App4Sales ConnectorSetting: AllowPartialShippingOnOrders	MBC Sales Order PartialShipping	Direct boolean mapping from connector setting.
Conditional Shipping Address Mapping (If Alternate Address is Present)	Conditional Shipping Address Mapping (If Alternate Address is Present)	Conditional Shipping Address Mapping (If Alternate Address is Present)
App4Sales Order.AlternateAddress.AddressLine1	MBC Sales Order ShipToAddressLine1 (V2 API) MBC Sales Order ShippingPostalAddress.Street (V1 API)	Mapped based on `UseApiVersion2` setting.
App4Sales Order.AlternateAddress.AddressLine2	MBC Sales Order ShipToAddressLine2 (V2 API)	Mapped only if `UseApiVersion2` is true.
App4Sales Order.AlternateAddress.City	MBC Sales Order ShipToCity (V2 API) MBC Sales Order ShippingPostalAddress.City (V1 API)	Mapped based on `UseApiVersion2` setting.
App4Sales Order.AlternateAddress.Iso2 OR App4Sales Order.AlternateAddress.Country	MBC Sales Order ShipToCountry (V2 API) MBC Sales Order ShippingPostalAddress.CountryLetterCode (V1 API)	If ISO2 is available, it's used; otherwise, the Country is used. Mapped based on `UseApiVersion2` setting.
App4Sales Order.AlternateAddress.PostCode	MBC Sales Order ShipToPostCode (V2 API) MBC Sales Order ShippingPostalAddress.PostalCode (V1 API)	Mapped based on `UseApiVersion2` setting.
App4Sales Order.AlternateAddress.State	MBC Sales Order ShipToState (V2 API) MBC Sales Order ShippingPostalAddress.State (V1 API)	Mapped based on `UseApiVersion2` setting.
Order Type Routing	Order Type Routing	Order Type Routing
App4Sales Order.OrderType.ValueToBackoffice	MBC Sales Record Type	Determines if the order is sent as an 'Order', 'Invoice', or 'Quote'. Defaults to 'Order' if not specified or invalid.

Line & Pricing Logic

Each order line is processed, with quantities and prices potentially adjusted based on package sizes. Discounts are carefully handled to prevent double application, and item variants are supported through extra data.

App4Sales Field	MBC Field	Logic/Notes
App4Sales OrderLine.Quantity AND App4Sales OrderLine.Item.PurchasePackageSize	MBC OrderLine Quantity	If `AdjustOrderedItemsAmountWithPackageSize` is true, `Quantity` is multiplied by `Item.PurchasePackageSize`. Otherwise, `OrderLine.Quantity` is used.
App4Sales OrderLine.Price AND App4Sales OrderLine.Item.PurchasePackageSize	MBC OrderLine UnitPrice	If `AdjustOrderedItemsAmountWithPackageSize` is true, `Price` is divided by `Item.PurchasePackageSize`. Otherwise, `OrderLine.Price` is used.
App4Sales OrderLine.Item.InternalItemCode	MBC OrderLine ItemId	Parsed as a GUID.
Hardcoded	MBC OrderLine LineType	Always "Item".
App4Sales OrderLine.LineNumber	MBC OrderLine LineDetails.Number (V1 API)	Only mapped if `UseApiVersion2` is false.
App4Sales OrderLine.Description AND App4Sales OrderLine.Instruction	MBC OrderLine Description	If `AddInstructionToItemDescription` is true and `Instruction` is not empty, concatenates "Description \| Instruction". Otherwise, `OrderLine.Description` is used.
App4Sales OrderLine.Discount OR App4Sales OrderLine.DiscountFromOriginalPrice	MBC OrderLine DiscountPercent	If `OnlySendManualDiscountOrTheChangedUnitPrice` is true, uses `OrderLine.Discount`. Otherwise, uses `OrderLine.DiscountFromOriginalPrice`. Defaults to 0 if null.
App4Sales OrderLine.DeliveryDate	MBC OrderLine ShipmentDate	Formatted as "yyyy-MM-dd".
App4Sales OrderLine.QuantityDelivered	MBC OrderLine ShippedQuantity	If `NotIncludeShipmentQuantityIntoSendOrderLine` is true, then null; otherwise, `OrderLine.QuantityDelivered` is used.
App4Sales OrderLine.Item.ExtraData (VariantId)	MBC OrderLine ItemVariantId	If `Item.ExtraData` is present, deserialized to extract `VariantId`.

Charges & Attachments

This connector does not explicitly define how charges (freight, payment fees, coupons) are sent as distinct order lines, but it provides mechanisms for sending order notes which could be used for charges. For attachments, it directly supports retrieving order attachments.

App4Sales Field	MBC Field	Logic/Notes
App4Sales Order.Notes	MBC Sales Record Note / Comment Line / Work Description	Depending on settings: `SendOrderNoteToBackofficeUsingWebserviceCall`: Sends notes via a dedicated web service call. `SendOrderNoteAsSalesCommentLine`: Creates a sales comment line (truncated to 80 chars if longer). `MapOrderNotesToOrderWorkDescription`: Maps notes to the order's work description.
App4Sales Order.Reference	MBC Sales Record YourReference / ExternalDocumentNo	Mapped based on `MapSalesOrderYourReferenceToExternalDocumentNo` and `MapSalesOrderWebshopReferenceToExternalDocumentNo`.
App4Sales Order.Source	MBC Sales Record ExternalDocumentNo / ReasonCode	If `SendPrefixPlusOrderTimestampToMBC` is true, prepends a source-specific prefix (A4C-, A4S-, P4S-) and timestamp to `ExternalDocumentNo`. Also mapped to `ReasonCode` if `SendSalesOrderSourceAsReasonCode` is true, using specific reason codes for Portal4SalesPro, ChannelEngine, or a default.

Responses & Error Handling

The connector robustly handles responses from MBC, logging success messages and updating the internal App4Sales order with the assigned Business Central order number. It includes rollback mechanisms in case of partial failures.

Success: Upon successful creation, the assigned order number from MBC is returned and used to update the App4Sales internal order record.
Order Type Mismatch (Return Orders): If an order is explicitly marked as a return order but its type does not match Constants.SalesHeaderTypes.ReturnOrder, an exception is thrown.
Partial Failure Rollback: If sending the order header succeeds but creating the order lines fails (when not using the expanded line option), the connector attempts to delete the created order header and any lines from MBC to maintain data consistency.
General Errors: Any exceptions during the send process are logged with detailed information and an error message (Error.ERRORORDERNR) is returned to the user, including the exception message.
No Order Number: If MBC does not return an order number, Error.ERRORORDERNR is returned.

Related Settings & Prerequisites

The following connector settings significantly influence the order sending process:

UseExpandToSendOrderIncludingLines: (Boolean) If true, sends order header and lines in a single API call. If false, sends them separately.
CalculateWebshopDiscountOverLines: (Boolean) If true, applies webshop discount logic to order lines before sending.
DontSendContactIdOnSalesOrder: (Boolean) If true, prevents sending the contact ID on sales orders.
UseApiVersion2: (Boolean) Dictates whether to use API Version 2 for routing and address mapping.
AllowPartialShippingOnOrders: (Boolean) Sets the partial shipping flag on the MBC sales order.
AdjustOrderedItemsAmountWithPackageSize: (Boolean) If true, adjusts order line quantities and prices based on item purchase package size.
AddInstructionToItemDescription: (Boolean) If true, concatenates order line instructions to the item description sent to MBC.
OnlySendManualDiscountOrTheChangedUnitPrice: (Boolean) Controls whether to send manual discounts or the changed unit price, affecting price recalculations.
NotIncludeShipmentQuantityIntoSendOrderLine: (Boolean) If true, prevents sending the shipped quantity for order lines.
CustomSalesOrderRoute: (String) Allows specifying a custom API route for sales orders.
SendOrdersUsingAlExtension: (Boolean) Indicates if an AL extension should be used during order creation/modification.
AddAdditionalDataToSalesHeadersUsingOptimizersALScript: (Boolean) If true, allows patching additional data to sales headers using an Optimizers AL script.
UpdateSalesHeaderShippingAddressUsingWebservice: (Boolean) If true, updates the shipping address via a dedicated web service.
MapSalesOrderYourReferenceToExternalDocumentNo: (Boolean) If true, maps the 'Your Reference' field to MBC's external document number.
SendPrefixPlusOrderTimestampToMBC: (Boolean) If true, prepends a source-specific prefix (A4C-, A4S-, P4S-) and timestamp to the external document number.
MapSalesOrderWebshopReferenceToExternalDocumentNo: (Boolean) If true, maps the webshop reference to MBC's external document number.
SendSalesOrderSourceAsReasonCode: (Boolean) If true, maps the order source to a reason code in MBC.
SalesOrderPortal4SalesProReasonCode: (String) Reason code for Portal4SalesPro orders.
SalesOrderChannelEngineReasonCode: (String) Reason code for ChannelEngine orders.
SalesOrderDefaultReasonCode: (String) Default reason code for other order sources.
SendOrderNoteToBackofficeUsingWebserviceCall: (Boolean) If true, sends order notes via a specific web service.
SendOrderNoteAsSalesCommentLine: (Boolean) If true, adds order notes as a sales comment line.
MapOrderNotesToOrderWorkDescription: (Boolean) If true, maps order notes to the order's work description.

Known Limitations

This documentation is based on the Microsoft Business Central Connector, as the "DkHome connector" could not be located in the provided codebase. Implementations for other connectors may vary.
Order notes sent as sales comment lines are truncated to 80 characters.
The exact behavior of custom AL extensions and web services (e.g., for patching additional data or shipping address updates) depends on the implementation within the Business Central environment itself.

DkHome - Send order