Microsoft Business Central Connector - Send Order Process

This document details how App4Sales orders, invoices, quotes, and return orders are transformed and sent to Microsoft Business Central. It covers the business rules applied during the process and how responses are handled.

Data Source Configuration

The connector processes orders originating from App4Sales. These orders contain header information (customer, general order details), line items (product, quantity, price), and potentially additional information like notes and alternate delivery addresses.

Order Header Logic

Customer selection, numbering, order-type routing, payment/shipping fields.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order Customer Internal Code	MBC Sales Order Customer Id	Mapped directly to Business Central Customer ID (GUID).
App4Sales Order Customer CustomerCode	MBC Sales Order Customer Number	Mapped directly.
App4Sales Order Customer Currency	MBC Sales Order Currency Code	Mapped directly.
App4Sales Order OrderDate	MBC Sales Order Requested Delivery Date	Formatted as "yyyy-MM-dd".
App4Sales Order Customer MainContactPerson ContactId	MBC Sales Order ContactId	Used for V1 API; not sent if `DontSendContactIdOnSalesOrder` setting is enabled or if using V2 API.
App4Sales Order Delivered	MBC Sales Order Fully Shipped	Mapped directly.
App4Sales Order AlternateAddress EstablishmentName or ConsumerName	MBC Sales Order ShipToContact, ShipToName	Uses Alternate Address establishment name if available, otherwise consumer name.
App4Sales Order AlternateAddress Phone or ConsumerPhoneNumber	MBC Sales Order Phone	Uses Alternate Address phone if available, otherwise consumer phone number.
App4Sales Order AlternateAddress Email or ConsumerEmail	MBC Sales Order Email	Uses Alternate Address email if available, otherwise consumer email.
Connector Setting: AllowPartialShippingOnOrders	MBC Sales Order PartialShipping	Determines if partial shipping is allowed.
App4Sales Order AlternateAddress (V2 API)	MBC Sales Order ShipToAddressLine1, ShipToAddressLine2, ShipToCity, ShipToCountry, ShipToPostCode, ShipToState	Direct mapping of alternate address fields for API Version 2.
App4Sales Order AlternateAddress (V1 API)	MBC Sales Order ShippingPostalAddress (City, CountryLetterCode, PostalCode, State, Street)	Maps to a `ShippingPostalAddress` object for API Version 1. `CountryLetterCode` uses ISO2 code or full country name.
App4Sales Order Reference	MBC Sales Order YourReference / ExternalDocumentNo	Mapped based on `MapSalesOrderYourReferenceToExternalDocumentNo` and `MapSalesOrderWebshopReferenceToExternalDocumentNo` settings.
App4Sales Order Source	MBC Sales Order ReasonCode	Mapped if `SendSalesOrderSourceAsReasonCode` is enabled, using specific reason codes defined in settings (e.g., `SalesOrderPortal4SalesProReasonCode`, `SalesOrderChannelEngineReasonCode`, `SalesOrderDefaultReasonCode`).
App4Sales Order Notes	MBC Sales Order Note	Mapped if `SendOrderNoteToMBC` is enabled.
App4Sales Order OrderID (internal)	MBC Sales Record Number (after creation)	App4Sales internal order ID is updated with the number returned by Business Central.

Order Header Mapping (Sales Invoice)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order Customer Internal Code	MBC Sales Invoice Customer Id	Mapped directly to Business Central Customer ID (GUID).
App4Sales Order Customer CustomerCode	MBC Sales Invoice Customer Number	Mapped directly.
App4Sales Order Customer Currency	MBC Sales Invoice Currency Code	Mapped directly.
App4Sales Order OrderDate	MBC Sales Invoice Invoice Date	Formatted as "yyyy-MM-dd".
App4Sales Order Customer MainContactPerson ContactId	MBC Sales Invoice ContactId	Mapped directly.
App4Sales Order AlternateAddress (if AddressId is empty)	MBC Sales Invoice ShippingPostalAddress (City, CountryLetterCode, PostalCode, State, Street)	Maps to a `ShippingPostalAddress` object.

Order Header Mapping (Sales Quote V1)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order Customer Internal Code	MBC Sales Quote Customer Id	Mapped directly to Business Central Customer ID (GUID).
App4Sales Order Customer CustomerCode	MBC Sales Quote Customer Number, BillToCustomerNumber	Mapped directly.
App4Sales Order Customer Currency	MBC Sales Quote Currency Code	Mapped directly.
App4Sales Order Customer Phone	MBC Sales Quote PhoneNumber	Mapped directly.
App4Sales Order Customer Email	MBC Sales Quote Email	Mapped directly.
App4Sales Order Customer CustomerName	MBC Sales Quote ShipToName	Mapped directly.
App4Sales Order Customer MainContactPerson FullName	MBC Sales Quote ShipToContact	Mapped directly.
App4Sales Order OrderDate	MBC Sales Quote DocumentDate	Formatted as "yyyy-MM-dd".
App4Sales Order AlternateAddress (if AddressId is empty)	MBC Sales Quote ShippingPostalAddress (City, CountryLetterCode, PostalCode, State, Street)	Maps to a `ShippingPostalAddress` object.
App4Sales Order Customer Addresses (type 'Invoice')	MBC Sales Quote BillingPostalAddress (Street, City, PostalCode, State)	Maps to a `BillingPostalAddress` object.

Order Header Mapping (Sales Quote V2)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order Customer Internal Code	MBC Sales Quote Customer Id	Mapped directly to Business Central Customer ID (GUID).
App4Sales Order Customer CustomerCode	MBC Sales Quote Customer Number, BillToCustomerNumber	Mapped directly.
App4Sales Order Customer Currency	MBC Sales Quote Currency Code	Mapped directly.
App4Sales Order Customer Phone	MBC Sales Quote PhoneNumber	Mapped directly.
App4Sales Order Customer Email	MBC Sales Quote Email	Mapped directly.
App4Sales Order Customer CustomerName	MBC Sales Quote ShipToName	Mapped directly.
App4Sales Order Customer MainContactPerson FullName	MBC Sales Quote ShipToContact	Mapped directly.
App4Sales Order OrderDate	MBC Sales Quote DocumentDate	Formatted as "yyyy-MM-dd".
App4Sales Order AlternateAddress (if AddressId is empty)	MBC Sales Quote ShipToAddressLine1, ShipToAddressLine2, ShipToCity, ShipToCountry, ShipToPostCode, ShipToState	Direct mapping of alternate address fields for API Version 2.
App4Sales Order Customer Addresses (type 'Invoice')	MBC Sales Quote BillToAddressLine1, BillToAddressLine2, BillToCity, BillToCountry, BillToPostCode, BillToState	Direct mapping of billing address fields.

Order Header Mapping (Return Order)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Order CustomerCode	MBC Return Order SellToCustomerNo	Mapped directly.
App4Sales Order YourReference / Reference	MBC Return Order YourReference	Concatenation of YourReference and Reference.
Constant	MBC Return Order Type	Hardcoded to "Return Order".

Line & Pricing Logic

Source fields for items, quantities, prices, discounts, VAT adjustments.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales OrderLine Quantity	MBC Sales Order Line Quantity	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Price	MBC Sales Order Line UnitPrice	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Item InternalItemCode	MBC Sales Order Line ItemId	Mapped directly to Business Central Item ID (GUID).
Constant	MBC Sales Order Line LineType	Hardcoded to "Item".
App4Sales OrderLine LineNumber (V1 API)	MBC Sales Order Line LineDetails Number	Mapped directly for API Version 1.
App4Sales OrderLine Description and Instruction	MBC Sales Order Line Description	Combines description and instruction if `AddInstructionToItemDescription` setting is enabled, otherwise only description.
App4Sales OrderLine Discount or DiscountFromOriginalPrice	MBC Sales Order Line DiscountPercent	Uses `Discount` if `OnlySendManualDiscountOrTheChangedUnitPrice` is enabled, otherwise uses `DiscountFromOriginalPrice`.
App4Sales OrderLine DeliveryDate	MBC Sales Order Line ShipmentDate	Formatted as "yyyy-MM-dd".
App4Sales OrderLine QuantityDelivered	MBC Sales Order Line ShippedQuantity	Not included if `NotIncludeShipmentQuantityIntoSendOrderLine` setting is enabled.
App4Sales OrderLine Item ExtraData (JSON, VariantId)	MBC Sales Order Line ItemVariantId	Deserialized from `ExtraData` field of the item.

Order Line Mapping (Return Order)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Return Order Number	MBC Return Order Line Number	Mapped from the created return order header.
Constant	MBC Return Order Line DocumentType	Hardcoded to "Return Order".
Constant	MBC Return Order Line Type	Hardcoded to "Item".
App4Sales OrderLine ItemCode	MBC Return Order Line ItemCode	Mapped directly.
App4Sales OrderLine Description or Item Description	MBC Return Order Line Description	Uses order line description if available, otherwise item description.
App4Sales OrderLine Quantity	MBC Return Order Line Quantity	Mapped directly.
App4Sales OrderLine Price	MBC Return Order Line UnitPrice	Mapped directly.
App4Sales OrderLine Discount	MBC Return Order Line LineDiscountPercent	Mapped directly.
App4Sales OrderLine DeliveryDate	MBC Return Order Line ShipmentDate	Formatted as "yyyy-MM-dd".
Line Number (internal counter)	MBC Return Order Line LineNo	Sequential number assigned during line creation.
Connector Setting: LocationForReturnOrders	MBC Return Order Line LocationCode	Mapped from connector settings.

Order Line Mapping (Sales Invoice)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales OrderLine Quantity	MBC Sales Invoice Line Quantity	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Price	MBC Sales Invoice Line UnitPrice	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Item InternalItemCode	MBC Sales Invoice Line ItemId	Mapped directly to Business Central Item ID (GUID).
Constant	MBC Sales Invoice Line LineType	Hardcoded to "Item".
App4Sales OrderLine LineNumber	MBC Sales Invoice Line LineDetails Number	Mapped directly.
App4Sales OrderLine Description and Instruction	MBC Sales Invoice Line Description	Combines description and instruction if `AddInstructionToItemDescription` setting is enabled, otherwise only description.
App4Sales OrderLine Discount or DiscountFromOriginalPrice	MBC Sales Invoice Line DiscountPercent	Uses `Discount` if `OnlySendManualDiscountOrTheChangedUnitPrice` is enabled, otherwise uses `DiscountFromOriginalPrice`.
App4Sales OrderLine DeliveryDate	MBC Sales Invoice Line ShipmentDate	Formatted as "yyyy-MM-dd".

Order Line Mapping (Sales Quote)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales OrderLine Quantity	MBC Sales Quote Line Quantity	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Price	MBC Sales Quote Line UnitPrice	Adjusted by `orderLine.Item.PurchasePackageSize` if `AdjustOrderedItemsAmountWithPackageSize` setting is enabled.
App4Sales OrderLine Item InternalItemCode	MBC Sales Quote Line ItemId	Mapped directly to Business Central Item ID (GUID).
Constant	MBC Sales Quote Line LineType	Hardcoded to "Item".
App4Sales OrderLine LineNumber (V1 API)	MBC Sales Quote Line LineDetails Number	Mapped directly for API Version 1.
App4Sales OrderLine Description and Instruction	MBC Sales Quote Line Description	Combines description and instruction if `AddInstructionToItemDescription` setting is enabled, otherwise only description.
App4Sales OrderLine Discount or DiscountFromOriginalPrice	MBC Sales Quote Line DiscountPercent	Uses `Discount` if `OnlySendManualDiscountOrTheChangedUnitPrice` is enabled, otherwise uses `DiscountFromOriginalPrice`.
App4Sales OrderLine DeliveryDate	MBC Sales Quote Line ShipmentDate	Formatted as "yyyy-MM-dd".

Special Logic & Filters

**Dynamic VAT Percentage Determination:** If the setting EnableDynamicItemVATPercentDeterminationDuringOrderSend is enabled, the connector retrieves VAT percentages for order items from Business Central based on customer VAT business posting group (from customer dynamic free fields) and item VAT product posting group (from item free fields). This is applied before the order is sent.
**Webshop Discount Application:** If the setting CalculateWebshopDiscountOverLines is enabled, webshop discounts are applied to order lines before sending.
**Alternate Address Handling:** If an alternate delivery address is provided for an order, the connector checks if it matches the customer's main delivery address. If so, the alternate address is ignored to prevent sending redundant information, and the default address is used in Business Central.
**Rollback Mechanism:** For orders, invoices, and quotes sent without using the $expand option (i.e., header and lines are sent in separate calls), if an error occurs during the creation of order lines, the connector attempts to delete the already created header and any lines from Business Central to ensure data consistency.
**Order Note Handling:** Order notes can be sent to Business Central in several ways, configurable by settings:
- SendOrderNoteToBackofficeUsingWebserviceCall: Sends notes via a dedicated web service action.
- SendOrderNoteAsSalesCommentLine: Sends notes as sales comment lines, truncating them to 80 characters.
- MapOrderNotesToOrderWorkDescription: Maps notes to the workDescription field of the sales header.
**Quantity and Price Adjustment:** If the setting AdjustOrderedItemsAmountWithPackageSize is enabled, the order line quantity is multiplied by orderLine.Item.PurchasePackageSize, and the unit price is divided by it.
**Discount Calculation:** The DiscountPercent sent to Business Central depends on the OnlySendManualDiscountOrTheChangedUnitPrice setting. If enabled, it sends the orderLine.Discount (manual discount); otherwise, it uses orderLine.DiscountFromOriginalPrice.
**Item Variant ID:** If an item has extra data containing a VariantId (deserialized from JSON), this ID is mapped to the ItemVariantId in Business Central.
**Custom Order/Line Mappings:** The connector supports highly flexible custom mappings for order headers and lines via JSON configurations in CustomerSpecificOrderFieldsMapping and CustomerSpecificOrderLineFieldsMapping settings. These settings define how App4Sales fields map to custom Business Central entity routes and fields, allowing for specialized integrations.

Charges & Attachments

The current implementation primarily handles order lines and header details. Specific mappings for freight, payment surcharges, or other charge lines as distinct entities are not explicitly defined in the core order sending process. Attachments are handled via specific methods (OptA4SGetOrderAttachments, OptA4SGetInvoiceAttachments) for retrieval, but there is no explicit mechanism for sending attachments alongside orders within the SendOrderToBackoffice flow.

Responses & Error Handling

**Order Number Confirmation:** Upon successful creation of an order, invoice, or quote in Business Central, the returned number is used to update the corresponding order in App4Sales.
**Error Logging:** Detailed error messages and stack traces are logged for any exceptions occurring during the send process, including issues with API calls, data conversions, or rollback failures.
**Rollback on Line Creation Failure:** If an order header is successfully created but subsequent line item creation fails, the connector attempts to delete the created header and lines from Business Central to prevent orphaned records.
**Duplicate Order Detection:** Not explicitly detailed in the `SendOrderToBackoffice` flow, but might be handled by Business Central itself or custom AL scripts if configured.
**Return Order Location Validation:** Before sending a return order, the connector validates that the LocationForReturnOrders specified in the settings exists in Business Central; otherwise, it throws an exception.

Related Settings & Prerequisites

**EnableDynamicItemVATPercentDeterminationDuringOrderSend**: Enables dynamic retrieval and application of VAT percentages from Business Central during order sending.
**CalculateWebshopDiscountOverLines**: If enabled, webshop discounts are applied to order lines.
**DontSendContactIdOnSalesOrder**: If enabled, the ContactId is not sent for sales orders.
**UseApiVersion2**: Specifies whether to use API Version 2 for Business Central integration.
**AllowPartialShippingOnOrders**: Controls whether partial shipping is allowed for orders.
**AddInstructionToItemDescription**: If enabled, combines item description with instruction in order line description.
**OnlySendManualDiscountOrTheChangedUnitPrice**: Determines whether to send manual discount or discount from original price.
**NotIncludeShipmentQuantityIntoSendOrderLine**: If enabled, shipment quantity is not included in the sent order line.
**AdjustOrderedItemsAmountWithPackageSize**: If enabled, adjusts quantity and price based on item's purchase package size.
**UseExpandToSendOrderIncludingLines**: If enabled, sends order header and lines in a single API call using $expand.
**SendOnlyDiscountAndDefaultSalesPrice**: If enabled, resets sales price if discount is calculated for order lines.
**AddAdditionalDataToSalesHeadersUsingOptimizersALScript**: Enables additional data to be added to sales headers via an Optimizers AL script.
**UpdateSalesHeaderShippingAddressUsingWebservice**: If enabled, updates shipping address via a web service call.
**LocationForReturnOrders**: Specifies the Business Central location code to be used for return orders. This location must exist in Business Central.
**SendOrderNoteToBackofficeUsingWebserviceCall**: If enabled, order notes are sent via a web service call.
**SendOrderNoteAsSalesCommentLine**: If enabled, order notes are sent as sales comment lines (truncated to 80 characters).
**MapOrderNotesToOrderWorkDescription**: If enabled, order notes are mapped to the workDescription field of the sales header.
**CustomerSpecificOrderFieldsMapping**: JSON configuration for custom mappings of order header fields.
**CustomerSpecificOrderLineFieldsMapping**: JSON configuration for custom mappings of order line fields.
**StartSalesHeaderLinesNumerationFrom**: Specifies the starting line number for sales header lines in custom mappings.
**MapSalesOrderYourReferenceToExternalDocumentNo**: If enabled, maps YourReference to ExternalDocumentNo.
**SendPrefixPlusOrderTimestampToMBC**: If enabled, prefixes ExternalDocumentNo with a timestamp and order source.
**MapSalesOrderWebshopReferenceToExternalDocumentNo**: If enabled, maps webshop reference to ExternalDocumentNo.
**SalesOrderPortal4SalesProReasonCode**: Reason code for Portal4SalesPro orders.
**SalesOrderChannelEngineReasonCode**: Reason code for ChannelEngine orders.
**SalesOrderDefaultReasonCode**: Default reason code for sales orders.

Known Limitations

The connector does not explicitly define how custom charge lines (e.g., freight, payment fees) are sent to Business Central, beyond being potentially included within custom field mappings if configured.
Sending attachments directly alongside order creation is not supported; attachments are retrieved via separate methods.
Sales comments lines are truncated to 80 characters when SendOrderNoteAsSalesCommentLine is enabled.

MicrosoftBusinessCentral - Send order