Sage100 Connector - Send Order to Backoffice

This function synchronizes App4Sales orders, including their header details and individual order lines, to the Sage 100 ERP system. The process involves structuring the order data into a format expected by Sage 100's API and then transmitting it. Upon successful transmission, Sage 100 returns an order number, which is then recorded by App4Sales. The function runs when an order is finalized in App4Sales and pushed to the back office.

Data Source Configuration

The connector communicates with the Sage 100 ERP system via its REST API. The base URL for the API is configured in the connector's administration settings (Session.Administration.Name). Orders are sent to the DocumentService/rest/InsertDocumentEtLignes endpoint using an HTTP POST request. Authentication is handled using a token provided in the connector settings.

Data Mapping Tables

Order Header Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order Type	`TypeDocument`	Maps to the document type in Sage 100.
Order Number	`NumeroDocument`	The order number within Sage 100. For new orders, this is typically generated by Sage 100.
Order Date	`Date`	The order date, transformed to an epoch string using an internal extension method.
Reference	`Reference`	External reference for the order.
Customer Code	`NumeroTiers`	The customer's unique identifier in Sage 100.
Order State	`Statut`	The status of the order in Sage 100.
Contact Person	`Contact`	The name of the contact person associated with the order.
Document Type (Hardcoded)	`__type`	Always sent as "DocumentVente:http://www.proconsult.lu/WebServices100".

Order Line Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Line ID	`Id`	Unique identifier for the order line.
Document Type	`TypeDocument`	Maps to the document type in Sage 100, inherited from the order header.
Order Number	`NumeroDocument`	The order number in Sage 100, linking the line to its header.
Line Date	`Date`	The date of the order line, transformed to an epoch string.
Line Number	`NumeroLigne`	The sequential number of the line within the order.
Description/Instruction	`Designation`	Free text or instruction associated with the order line.
Item Code	`RefArticle`	The unique identifier for the item in Sage 100.
Unit Price	`PrixUnitaire`	The unit price of the item.
Quantity	`Quantite`	The quantity of the item ordered.
Is Valued (Hardcoded)	`EstValorise`	Always sent as '1'. Used for calculating correct total price in Sage.
Discount Type	`RemiseType1`	Set to '1' if a discount value is present on the order line, otherwise null.
Discount Value	`RemiseValeur1`	The discount amount for the line. Only sent if the value is greater than 0, otherwise null.
Line Type (Hardcoded)	`__type`	Always sent as "LigneArticle:http://www.proconsult.lu/WebServices100".

Special Logic & Filters

**Order Request Construction**: The `OrderHeader` and `OrderLine` objects from App4Sales are combined into an `OrderFullRequest` object before being sent.
**JSON Serialization**: The order data is serialized into a specific JSON format required by the Sage 100 API, including special `__type` fields for both order header and lines.
**Date Formatting**: Dates are converted to an epoch string format before transmission.
**Discount Handling**: Discounts are only sent if their value is greater than zero. A `RemiseType1` field is set to indicate the presence of a discount.

Domain Specifics

Order Header Logic

The connector composes the order header using various fields from the App4Sales order. Key identifiers like the customer code, order reference, and contact person are directly mapped. The order date is transformed to ensure compatibility with the Sage 100 API.

Line & Pricing Logic

Each order line includes the item code, quantity, and unit price. Discounts are handled conditionally: a discount type flag is set only if a discount value is applied and is greater than zero. A hardcoded value `EstValorise = 1` is sent for each line, which is noted as necessary for correct total price calculation in Sage.

Charges & Attachments

This implementation of `SendOrderToBackoffice` does not explicitly handle surcharges, attachments, or additional payloads. Only the core order header and line items are transmitted.

Responses & Error Handling

After sending the order, the connector expects an `OrderResponse` from Sage 100. This response contains the `OrderNumber` assigned by the ERP. If no order number is received, an error message is returned. Any exceptions during the API call are caught, and a generic error message including the exception details is returned to App4Sales.

Related Settings & Prerequisites

The Sage 100 connector requires a valid Token to be configured in its settings for authenticating with the Sage 100 API. This token is crucial for successful communication with the ERP system. No other specific connector settings directly influence the business logic of how an order is transformed or sent by this function.

Known Limitations

Does not explicitly handle surcharges or additional charges.
Does not support sending attachments (e.g., PDF, images) alongside the order.
Assumes a single order type for both header and lines based on the TypeDocument field.
Order Number is expected to be generated by Sage 100 for new orders.

Sage100 - Send order