StyleMan Connector - SendOrderToBackoffice

This function transmits an App4Sales order to the StyleMan ERP system. It orchestrates the conversion of App4Sales order data (including header and lines) into a format suitable for the StyleMan REST API and sends it for processing. The function performs validation checks and, if successful, updates the App4Sales order with the ERP-provided order number. This process is triggered when an order is sent from App4Sales to the back office.

Data Source Configuration

The primary data source is the App4Sales Order object, which encapsulates all order-related information. The target is the StyleMan REST API, specifically the /Orders endpoint, used with an HTTP POST method to create new orders in the ERP. Authentication is handled by the connector's base framework.

Domain Specifics

Order Header Logic

The ConvertToEntity method maps various fields from the App4Sales Order and Customer objects to the SalesOrder entity for the REST API. Key fields include order ID, customer information, timestamps, notes, references, and totals. It also handles the order type and alternative delivery addresses based on specific settings. The sales representative's warehouse is also included.

Order Header Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order ID (GUID)	`orderId` parameter	Passed directly from App4Sales.
Order Number	`model.OrderNr`	App4Sales internal order number.
Customer GUID	`customer.CustomerGuid`	Unique identifier for the customer.
Customer Code	`customer.CustomerCode`	Customer's alphanumeric code.
Created Date	`DateTime.Now`	Timestamp of when the order entity is created for the API call.
Order Date	`model.OrderDate`	Date of the order in App4Sales.
Is Open	`true`	Hardcoded as `true` for new orders being sent.
Notes	`model.Notes`	General notes associated with the order.
Description 1	`model.Description1`	Additional description field 1.
Description 2	`model.Description2`	Additional description field 2.
Description 3	`model.Description3`	Additional description field 3.
Reference	`model.Reference`	General reference for the order.
Subtotal (Excl. VAT)	`model.TotalNoVat`	Calculated total amount excluding VAT.
Total Amount	`model.TotalAmount`	Total amount of the order (incl. VAT).
VAT Total	`model.TotalVat`	Total VAT amount for the order.
Your Reference	`model.YourReference`	Customer's reference.
Username	`model.Salesrep`	Username of the sales representative who created the order.
Warehouse	`salesRep?.Warehouse`	Warehouse associated with the sales representative (if available). Retrieved from `SalesRepsContext`.
Signature	`model.Signature`	Digital signature associated with the order.
Delivery Method Code	`model.DeliveryMethod?.Code`	Code of the selected delivery method.
Order Type	`model.OrderType.ValueToBackoffice`	Value from the order type configuration, sent only if `model.OrderType?.SendToBackoffice` is `true`.
Delivery Address	`model.AlternateAddress`	If an `AlternateAddress` is provided and `Settings.DontSendAlternativeAddressOnOrder` is `false`, it's mapped to `DeliveryAddress` fields.
Delivery Address ID	`model.AlternateAddress.AddressId`	GUID of the alternative delivery address, if provided and valid. Otherwise, `null`.

Line & Pricing Logic

Each App4Sales OrderLine is converted into a RestJsonSalesEntryLine for transmission to the ERP. The conversion involves mapping item codes, quantities, prices, and discounts. It also calculates PriceIncl based on PriceExcl and VatPercentage. A defaultPrice and customerDiscount are passed to the conversion method, which can influence how pricing is handled, especially for discount calculations. The line number is assigned sequentially.

Order Line Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Line ID	`Guid.NewGuid()`	A new GUID is generated for each order line.
Customer GUID	`customerId` parameter	Unique identifier of the customer (passed from the order header).
Discount	`model.Discount`	Discount percentage applied to the line.
Total Discount	`model.DiscountFromOriginalPrice`	Total discount amount from the original price.
Item Code	`model.ItemCode`	Code of the item on the order line.
Quantity	`model.Quantity`	Ordered quantity.
Quantity Delivered	`model.QuantityDelivered`	Quantity that has already been delivered.
VAT Percentage	`model.Item.VatPercentage`	VAT percentage of the item.
Price Excl. VAT	`model.Price`	Unit price excluding VAT.
Price Incl. VAT	`Calc.PriceIncl(model.Price, false, model.Item.VatPercentage)`	Calculated unit price including VAT.
Default Price	`defaultPrice` parameter	Default price of the item, obtained from `Session.PortalServerProvider.GetItemPriceByPriceList`. Used in `GetTotalDiscount` calculation.
Line Number	`count` parameter	Sequential line number within the order.
Instruction	`model.Instruction`	Specific instructions for the order line.
Item Description	`model.Description`	Description of the item.
Delivery Date	`model.DeliveryDate`	Expected delivery date for the line. Only sent if value is present.

Charges & Attachments

This connector does not explicitly support separate "charge lines" (e.g., freight, payment fees) or "attachments" (e.g., PDF, XML documents) as distinct entities when sending an order to the StyleMan ERP via the SalesOrder API.

Surcharges: Any surcharges or additional fees must be factored into the SubTotal, Total, and VatTotal fields of the order header, or potentially represented as regular order lines with specific item codes if the ERP supports this.
Attachments: Explicit document attachments (like PDFs or custom XML payloads) are not directly transmitted through the SalesOrder structure. Information related to attachments may be conveyed indirectly via fields like model.Notes, model.Description1, model.Description2, model.Description3, or model.Reference. The model.Signature field captures a digital signature associated with the order.

Responses & Error Handling

Upon successful submission of an order to the StyleMan ERP, the connector expects an SalesOrder object in response.

Successful Response: If the response contains an OrderNumber, this number is used to update the corresponding order within App4Sales' internal database via OrdersContext.Instance.UpdateOrderNumber. The ERP's order number is then returned as the result of the SendOrderToBackoffice function.
Duplicate Order Detection: If Settings.ValidateOrderBeforeSending is enabled, the connector first checks if an order with the same OrderID (App4Sales internal GUID) already exists in the ERP by querying the Routes.Orders endpoint with a filter. If a matching order number is found, it updates the App4Sales order with the existing ERP number and prevents re-sending.
Error Handling:
- RestException: Catches REST-specific errors. The error message from the exception (ex.GetErrorMessage()) is returned to App4Sales, prefixed with Constants.Error.ERROR.
- RequestException: Catches errors related to HTTP requests (e.g., network issues, invalid URLs). The exception's message is returned, prefixed with Constants.Error.ERROR.
- General Exception: Catches any other unexpected errors during the process. The exception's message is returned, prefixed with Constants.Error.ERROR.
Missing Order Number: If the ERP response does not contain an order number (e.g., response?.Number is null or empty), the function returns a generic error message: Constants.Error.ERROR + "No order number retrieved from backoffice".

Related Settings & Prerequisites

Filter non-ISO-8859-1 Characters (FilterNonIso88591Characters):
- Description: When enabled, this setting removes any characters from the order details that are not part of the ISO-8859-1 character set before sending the order to the back office.
- Impact: Ensures compatibility with ERP systems that may have strict character encoding requirements.
Validate Order Before Sending (ValidateOrderBeforeSending):
- Description: If this setting is active, the connector will query the ERP system to check if an order with the same internal App4Sales ID already exists.
- Impact: Prevents the creation of duplicate orders in the ERP if an order was previously sent but App4Sales did not receive a confirmation (e.g., due to a network issue). If a duplicate is found, the existing ERP order number is used, and the order is not re-sent.
Use Results Tag For Request (UseResultsTagForRequest):
- Description: This setting alters the structure of the JSON payload sent to the ERP for order creation.
- Impact: If enabled, the SalesOrder object is wrapped within BaseResponse2 and BaseResponse objects, indicating a specific API expectation for the request format. If disabled, the SalesOrder object is sent directly. This setting is specific to the ERP's API design.
Do Not Send Alternative Address On Order (DontSendAlternativeAddressOnOrder):
- Description: When enabled, this setting prevents the alternative delivery address specified in App4Sales from being sent with the order to the ERP system.
- Impact: If an alternative delivery address is present in the App4Sales order and this setting is false, the alternative address details will be included in the DeliveryAddress section of the SalesOrder payload sent to the ERP. If true, the alternative address is omitted.

StyleMan - Send order