Visma AccountView Connector - Send Order to Backoffice

This function is responsible for transmitting App4Sales orders to the Visma AccountView ERP system. It handles the conversion of App4Sales order data (including header, lines, charges, and attachments) into a format suitable for AccountView, manages batching of large orders, and processes the ERP's response.

Data Source Configuration

Order data originates from the App4Sales platform. The connector retrieves a comprehensive Order object, which encapsulates all details of a placed order, including customer information, order lines, and other relevant metadata.

Order Header Logic

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Internal ID	RowId	Hardcoded to "000001".
Customer Code	rpl_inv, rpl_del	Mapped from `Order.Customer.CustomerCode`. Used for both invoice and delivery relation.
Employee Number	emp_nr	Derived from `Settings.FixedEmployeeCode` (if set) or the `userName` passed to the function.
Order Date	ord_date	Current date and time (`DateTime.Now`) formatted as "yyyy-MM-dd".
Delivery Date	del_date	Mapped from `Order.OrderDate` formatted as "yyyy-MM-dd".
Your Reference / Comment 1	comment1	Mapped from `Order.YourReference`. If empty, defaults to "App4Sales Order". Only applies to Sales Orders (SO1).
Order Notes / Comment 2	comment2	Composed from `Settings.OrderNoteLabel` concatenated with `Order.Notes`. If `Order.Notes` is empty, it sends an empty string. Only applies to Sales Orders (SO1).
Internal Reference / Comment 3	comment3	Mapped from `Order.Reference`. If `Settings.MapOrderReferenceToCustomField` is configured, it maps `Order.Reference` to that custom field instead, and `comment3` defaults to "App4Sales Order". Only applies to Sales Orders (SO1).
Alternate Delivery Address	address1, post_code, city, cnt_code	If `Order.AlternateAddress` is provided, its `AddressLine1`, `PostCode`, `City`, and `Iso2` (country code) are mapped.
Selection Code	ord_expn	Mapped from `Settings.SelectionCodeForOrders` if it is not empty.
Order Type (Kubussports Specific)	ORDER_TYPE (FieldType L)	If the application is "kubussports" and the order type in App4Sales is "preorder", "ps", or "Presale", this field is set to `true`. Only applies to Sales Orders (SO1).
Dropshipment (Kubussports Specific)	X11_CHK_DS (FieldType L)	If the application is "kubussports" and `Order.IsDropShipment` is `true`, this field is set to `true`. Only applies to Sales Orders (SO1).
Consumer Name (Kubussports Dropshipment)	ACCT_NAME (FieldType C)	If the application is "kubussports" and `Order.IsDropShipment` is `true`, and `Order.ConsumerName` is provided, it is mapped to this field.
Shipping Method	SHIP_MTH	Mapped from `Order.DeliveryMethod.Code` if available.
Order Reference to Custom Field	Dynamically named field	If `Settings.MapOrderReferenceToCustomField` is specified, `Order.Reference` is mapped to this custom field.

Line & Pricing Logic

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
App4Sales Internal Line ID	RowId	Line number derived from its position in the order lines list, starting from "000001".
Header ID	HeaderId	Hardcoded to "000001". Links the line to its parent order header.
Item Code	art_code	Mapped from `OrderLine.Item.InternalItemCode` if available, otherwise from `OrderLine.Item.ItemCode`.
Quantity	ord_qtyu (if Unit Module active), ord_qty (otherwise)	Mapped from `OrderLine.Quantity`, converted to an integer. The field name depends on the `Settings.UnitModule`.
Size (SBA Items)	size	Mapped from `OrderLine.Item.ExtraData` if `Settings.UseSbaItems` is enabled.
Discount Percentage	disc_pct	Mapped from `OrderLine.Discount` or `OrderLine.DiscountFromOriginalPrice`. If `Settings.UsePriceFromApp` is true and `OrderLine.Discount` is 0, the price from the app is used. This field is not sent if `Settings.DontSendDiscountToBackoffice` is true.
Unit Price	art_px	Mapped from the calculated unit price. This field is not sent if `Settings.DontSendPriceToBackoffice` is true. Special logic applies if `Settings.UsePriceFromApp` is true and no discount is applied. If the price has no value or is 0 and no discount is sent, the price is calculated as `OrderLine.Price * (1 + (OrderLine.Item.VatPercentage / 100))`.
Item Description with Instruction	art_desc1	If `Settings.AddOrderLineInstructionToItemDescription` is true, composed from `OrderLine.Item.Description` and `OrderLine.Instruction` (if present). Otherwise, just `OrderLine.Item.Description`.

Charges & Attachments

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order PDF	link_file, doc_desc, file_data	If the order is a Sales Order (SO1) and the `sendPdf` parameter is true (default behavior for non-batched orders), an order PDF is generated, converted to a Base64 string, and sent as an attachment. The filename is dynamically generated with the current date and time.

Responses & Error Handling

Upon sending the order, the connector expects a response from AccountView. This response is parsed to extract the ERP's order number or any relevant error messages. If the initial part of a batched order does not return an order number, subsequent parts are not sent.

Special Logic & Filters

Order Batching: Large orders are split into smaller batches based on the OrderLinesBatchCount setting to accommodate potential API limitations or optimize performance. The first part of the order is sent to obtain an initial order number, and subsequent parts update this existing order.
Error Handling: API communication errors (e.g., RestException) are caught, and the error details from the AccountView response are extracted and returned to App4Sales for display. If no order number is returned by AccountView, a generic error message is provided.

Related Settings & Prerequisites

The following settings influence the behavior of the Send Order function:

OrderLinesBatchCount: Defines the maximum number of order lines to send in a single batch.
- OrderLinesBatchCount: Defines the maximum number of order lines to send in a single batch. (Label: "Number of orderlines per request")
- FixedEmployeeCode: A fixed employee code to use for all orders. If empty, the `userName` (sales representative) from App4Sales is used. (Label: "Fixed value on orders as employee code")
- OrderNoteLabel: A prefix for the order notes sent to AccountView. (Label: "Label for order note")
- MapOrderReferenceToCustomField: Specifies a custom field in AccountView to which the App4Sales order reference should be mapped. If empty, the order reference is mapped to comment3. (Label: "Map order reference to custom field (leave empty to use comment3/INTERNAL_NOTE)")
- SelectionCodeForOrders: A selection code to be applied to orders in AccountView. (Label: "Selection code for orders")
- UnitModule: Indicates whether the unit module is active in AccountView, affecting which quantity field is used for order lines. (Label: "Unit module active")
- UseSbaItems: Indicates whether SBA (size/color/matrix) items are used, affecting how item codes and sizes are handled in order lines. (Label: "Use SBA table from Accountview to retrieve the matrix items")
- DontSendDiscountToBackoffice: If true, discount percentages are not sent to AccountView for order lines. (Label: "Don't send discount to AccountView")
- DontSendPriceToBackoffice: If true, unit prices are not sent to AccountView for order lines. (Label: "Don't send price to AccountView")
- AddOrderLineInstructionToItemDescription: If true, the instruction from the App4Sales order line is appended to the item description sent to AccountView. (Label: "Add orderline instruction to item description")
- UsePriceFromApp: If true, the price from App4Sales is used when no discount is applied. (Label: "Use price from app when discount isn't filled")

Visma - Send order