MicrosoftBusinessCentralV2 - Send Order to Backoffice

This document details the process by which App4Sales orders are prepared and transmitted to Microsoft Business Central (MBC) using the MicrosoftBusinessCentralV2 connector. It covers the mapping of order headers, order lines, and special logic applied during the synchronization. This process is initiated when an order is placed in App4Sales and needs to be sent to the ERP system for further processing.

Order Header Logic

Before an order is sent to Microsoft Business Central, a pre-processing step (`PrepareSalesRecord`) is executed. This step first checks if the provided alternate delivery address for the order is identical to the customer's main delivery address already known in App4Sales (comparing postcode, address line 1, and city). If they are identical, the alternate address is disregarded to prevent redundant data from being sent to MBC. Additionally, any newline characters in the order's notes are replaced with spaces to ensure a single-line text format for MBC.

The App4Sales order is then mapped to a Microsoft Business Central Create Order entity (`MbcCreateOrder`). The type of sales record created in MBC (e.g., Order, Quote) is determined by the `ValueToBackoffice` property of the App4Sales order's `OrderType`. If this value is not specified or cannot be parsed, it defaults to creating a standard 'Order' in MBC.

Order Header Mapping Table

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
SellToContactId	`order.Customer.MainContactPerson.ContactId`	The Contact ID of the main contact person associated with the customer.
CustomerCode	`order.Customer.CustomerCode`	The customer code from App4Sales.
CurrencyCode	`order.Customer.Currency`	The currency code associated with the customer in App4Sales.
RequestedDeliveryDate	`order.OrderDate`	The order date from App4Sales, formatted as 'yyyy-MM-dd'.
ShipToName	`order.AlternateAddress.EstablishmentName` or `order.ConsumerName`	If an alternate address's establishment name is provided, it is used; otherwise, the consumer's name is used.
Phone	`order.AlternateAddress.Phone` or `order.ConsumerPhoneNumber`	If an alternate address's phone number is provided, it is used; otherwise, the consumer's phone number is used.
Email	`order.AlternateAddress.Email` or `order.ConsumerEmail`	If an alternate address's email is provided, it is used; otherwise, the consumer's email is used.
CommentLines	`order.Notes`	The order notes from App4Sales. Newline characters are replaced with spaces. Sent as a list of comment lines to MBC.
YourReference	`order.YourReference`	Your reference from the App4Sales order.
ShipToAddressLine1	`order.AlternateAddress.AddressLine1`	The first line of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.
ShipToAddressLine2	`order.AlternateAddress.AddressLine2`	The second line of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.
ShipToCity	`order.AlternateAddress.City`	The city of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.
ShipToCountryRegionCode	`order.AlternateAddress.Iso2`	The ISO2 country code of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.
ShipToPostCode	`order.AlternateAddress.PostCode`	The postcode of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.
ShipToState	`order.AlternateAddress.State`	The state of the alternate delivery address. Only sent if an alternate address is present and differs from the main delivery address.

Line & Pricing Logic

Each order line from App4Sales is translated into a Microsoft Business Central Create Order Line entity (`MbcCreateOrderLine`).

Order Line Mapping Table

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	`orderLine.Item.ItemCode`, or `itemExtraData.ItemCode`	Initially the item code from the App4Sales order line item. If the item has `ExtraData` (JSON format), the `ItemCode` from this extra data will override the default `ItemCode`.
LineType	Hardcoded value	Always set to "Item".
Description	`orderLine.Description`	The description of the order line.
UnitOfMeasureCode	N/A (Not explicitly mapped)	This field is part of the `MbcCreateOrderLine` but is not directly mapped from the `OrderLine` in the provided code snippet.
Quantity	`orderLine.Quantity`	The quantity of the item in the order line. Defaults to 0 if null.
UnitPrice	`orderLine.Price`	The unit price of the item in the order line.
ShipmentDate	`orderLine.DeliveryDate`	The requested delivery date for the order line.
DiscountPercent	`orderLine.Discount`	The discount percentage applied to the order line.
VariantCode	`itemExtraData.VariantCode`	If the item has `ExtraData` (JSON format), the `VariantCode` from this extra data is used.

Charges & Attachments

Based on the analyzed code, there is no explicit mapping for separate charge lines or attachments (like PDFs, signatures) to dedicated fields or entities in Microsoft Business Central during the `SendOrderToBackoffice` process. Order notes are transferred as comment lines in MBC. Any other charges or attachments would need to be handled outside of this specific order sending mechanism or rely on custom implementations within Microsoft Business Central to interpret the order notes or other standard fields.

Responses & Error Handling

After sending the order, Microsoft Business Central returns an order number. This order number is then used by App4Sales. The connector incorporates error handling, where exceptions during the order creation process are logged. The `SyncOrderHeaders` function in the connector periodically synchronizes order headers from MBC to update the App4Sales order history. This includes both current and optionally archived orders (if IncludeArchivedOrdersInHistory setting is enabled). It also handles the deletion of orders from App4Sales's overview if they are no longer present in MBC (if DeleteOrdersWhichAreNotAvailableAtMBCFromOrdersOverview setting is enabled).

Related Settings & Prerequisites

The following connector settings influence the order synchronization behavior:

Tenant Domain: Specifies the Azure Active Directory GUID required for authentication.
Environment Name: Defines the target Microsoft Business Central environment (e.g., Production, Sandbox).
Client Id: The client ID for the Business Central application registration in Azure AD.
Client Secret: The client secret for the Business Central application registration in Azure AD.
Company Name: The specific company name within Business Central where orders will be created.
Include archived orders in history: If enabled, archived sales orders from MBC will also be synchronized into App4Sales history.
Delete orders which are not available at MBC from orders overview: If enabled, orders that exist in App4Sales but are not found in MBC will be removed from the App4Sales order overview.
Extension Version: The version of the Core-Sales BC extension in use.

Known Limitations

The `UnitOfMeasureCode` for order lines is not explicitly mapped from App4Sales in the current order sending logic.
Dedicated fields for charges (e.g., freight, payment fees) are not explicitly mapped. They might need to be included as part of the order lines or managed through order notes/custom fields in MBC.
Attachments (e.g., PDFs, images) are not directly transferred as separate entities. The current implementation only transfers order notes as comment lines.

MicrosoftBusinessCentralV2 - Send order