Overview
When a Sales Order is created or updated in Microsoft Dynamics 365 Business Central with a status of "Released" and the record is not an invoice, the corresponding transaction record is created or updated in iPaaS.com. This mapping collection transfers order header data, addresses, line items, payment terms, and tracking numbers.
Sales Order records can be transferred to iPaaS.com through both manual sync and polling. Polling automatically triggers the transfer of Sales Orders, limited to recent orders based on the TransactionPollSearchDays preset.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
MS Dynamics 365 Requirements
Web Services must be enabled for: Customer Price Groups, Item Card, Items, Item Categories, Items By Location, Sales Order, Sales Orders, and Sales Order Lines
Sales Order records must have Status = "Released" and IsInvoice = false to qualify for transfer
Contact your MiSP for assistance in customizing Business Central Web Services if additional custom fields are needed
iPaaS.com Requirements
Shipping methods referenced in tracking number lines must exist in iPaaS.com before transfer
The TransactionPollSearchDays preset must be configured to define the polling lookback window
ID Format
When performing a manual transfer of a MS Dynamics 365 Sales Order to iPaaS.com, use one of the following identifier formats:
Sales Order by Number: The Sales Order No serves as the primary identifier in the MS Dynamics 365 Sales Orders API in the format {{salesorder_no}}
Example:
SO1001
Sales Order by ID: The Sales Order ID is a unique GUID identifier for the Sales Order in the MS Dynamics 365 API in the format {{orderId}}
Example:
9b6f77f2-15db-4c56-94a0-d8b8c6762b8e
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Supported Child Collections
This flow uses four child collections to transfer the complete Sales Order record to iPaaS.com:
Polling Configuration
The Sales Order polling endpoint supports optional polling filters that control which transaction types are retrieved and allow additional API-level filtering. Filters are passed as a single string and may be combined using commas.
Important: Polling Sales Orders
To poll Sales Orders, do not use InvoiceOnly:true or ShipmentOnly:true. Using Invoice:true or Shipment:true still retrieves Sales Orders along with the respective transaction type.
Sales Order filter example:
Your_Reference ne '' — Includes Sales Orders where Your_Reference is not empty.
Polling Shipments
To poll shipments, include either ShipmentOnly:true or Shipment:true.
ShipmentOnly:true Polls only shipments. Sales orders and invoices are excluded.
Shipment:true Includes shipments in the polling results. Sales orders are also included unless explicitly excluded.
ShipmentOnly:true, Your_Reference ne '' Polls only shipments where Your_Reference is not empty. Sales orders and invoices are excluded.
Shipment:true, Your_Reference ne '' Includes shipments where Your_Reference is not empty. Sales orders are also included unless explicitly excluded.
Data Requirements
The following fields are required for a successful Sales Order transfer.
Mandatory Header Fields
TransactionNumber (mapped from No)
Type (static: "Order")
Status (mapped from Order_Status via AdditionalProperties)
SystemId (mapped from SpaceportSystemId)
Recommended Header Field
Order_Status (raw Business Central status)
EmailAddress
TaxAmount
Subtotal
Total
TotalQty
TransactionCreatedDateTime
System Caveats
MS Dynamics 365 Caveats
Order Status Mapping: Business Central order statuses are normalized to iPaaS.com statuses using conditional logic. The mapping consolidates multiple statuses: "Shipped", "Partially Shipped", "Cancelled", and "Released" all map to "Shipped"; "Pending" and "In Progress" both map to "Pending"; "Submitted" maps to "Pending"; and "Completed" maps to "Complete".
The status is retrieved from the AdditionalProperties collection usingGetValueFromCustomField(AdditionalProperties, "Order_Status")rather than from a standard field.Name Parsing: The address collection splits the Name field on spaces to extract FirstName and LastName. If the name contains only one word, LastName is set to an empty string. Names with more than two words will only capture the first two.
Static Country Value: The address collection currently returns a static "United States" for the Country field. If your integration spans multiple countries, this should be changed to a dynamic formula.
iPaaS.com Caveats
Shipping Method Validation: The tracking number child collection validates that each shipping method (based on LocationCode) exists in iPaaS.com before processing. If the shipping method does not exist, the transfer stops with an error prompting manual creation in iPaaS.com.
Integration Caveats
Line-Level vs. Header-Level Status: The header-level and line-level status formulas differ slightly. At the header level, "Completed" maps to "Complete"; at the line level, it maps to "Completed." At the header level, "Cancelled" maps to "Shipped"; at the line level, it maps to "Partially Shipped." Review both formulas to ensure alignment with your business requirements.
Total Quantity Calculation: TotalQty is calculated by summing quantities across all line items where Type = "Item". Non-item line types are excluded from the count.
TransactionCreatedDateTime Description Mismatch: The source mapping converts the OrderDate string to a DateTimeOffset. The original documentation description was incorrect (referenced an address field); this mapping converts the Business Central OrderDate to an iPaaS.com-compatible DateTimeOffset.
Custom Fields Support
MS Dynamics 365 Business Central supports extended fields for integration. Custom fields can be added to Sales Order models.
NOTE: The creation of external custom fields is possible for any model within Business Central, offering flexibility in data integration and business process automation. |
Adding Custom Fields
In MS Dynamics 365, customize the Web Services to accept the desired custom field in the Sales Order request. Contact your MiSP for assistance customizing Business Central Web Services.
In iPaaS.com, create a custom field in the MS Dynamics 365 Subscription matching the field name and data type.
In iPaaS.com, map the custom field to a static or dynamic data source in the appropriate mapping collection.
Validate that data flows correctly from Business Central to iPaaS.com and that field values are updated appropriately.
Authentication and Security
MS Dynamics 365 Business Central uses OAuth 2.0 authentication to authorize API requests during transfer operations. Ensure credentials are stored securely within the iPaaS.com credential manager.
Integration Flow
The integration processes MS Dynamics 365 Sales Order records as follows:
Sales Order is created or updated in Business Central.
Polling detects the order within the TransactionPollSearchDays window, or a manual sync is triggered using the Sales Order number or ID.
The mapping filter validates that IsInvoice = false and Status = "Released."
iPaaS.com authenticates with Business Central using OAuth 2.0.
Header fields are mapped: transaction number, type ("Order"), status (from Order_Status custom property), email, totals, and tax amounts.
TotalQty is calculated by summing quantities of all line items where Type = "Item."
TransactionCreatedDateTime is set from the OrderDate.
Address child collection maps billing and shipping addresses with name parsing.
Line-item child collection maps each line with SKU, quantity, pricing, discounts, and normalized status.
Payment child collection maps payment terms from the parent order's PaymentTermsCode.
Tracking number child collection validates shipping method existence in iPaaS.com and maps tracking numbers and shipment details.
Transaction is created or updated in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: Dynamics Add/Update Sales Order To iPaaS
Description
This mapping collection transfers Sales Order header data from Microsoft Dynamics 365 Business Central to iPaaS.com. It maps system identification, transaction details, status (via the Order_Status custom property), financial totals, and the order creation date. Child collections handle addresses, line items, payments, and tracking numbers.
Mapping Filter
!IsInvoice && Status == "Released"
Description
This filter transfers only Sales Orders from Business Central where the Status is "Released" and the record is not an invoice. Invoice records are handled by a separate mapping collection.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Field | Status | Order_Status | Maps the raw Business Central order status. |
Dynamic Formula |
| SystemId | Dynamically sets the system identifier to uniquely represent the source Business Central system in iPaaS.com. |
Field | No | TransactionNumber | Maps the Sales Order number as the transaction number. |
Static | Order | Type | Sets the transaction type to "Order." |
Dynamic Formula |
| Status | Translates Business Central order statuses (from the Order_Status custom property) into standardized iPaaS.com statuses (Shipped, Complete, Pending). |
Field | SellToEMail | EmailAddress | Maps the customer's sell-to email address. |
Field | TotalTaxAmount | TaxAmount | Maps the total tax amount. |
Field | TotalAmountExcludingTax | Subtotal | Maps the order subtotal excluding tax. |
Field | TotalAmountIncludingTax | Total | Maps the order total including tax. |
Dynamic Formula |
| TotalQty | Calculates total quantity by summing quantities of all line items where Type = "Item." Returns 0 if LineItems is null or empty. |
Dynamic Formula |
| TransactionCreatedDateTime | Converts the Business Central OrderDate string to a DateTimeOffset for iPaaS.com. |
Child 1: Dynamics Add/Update Order Sales Address TO iPaaS
Description
This mapping collection maps Business Central Sales Order addresses to iPaaS.com address records. It handles both billing and shipping addresses using the IsPrimaryBilling and IsPrimaryShipping flags, and parses the Name field into first and last name components.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Field | IsPrimaryBilling | IsPrimaryBilling | Identifies the primary billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Identifies the primary shipping address. |
Field | Address | Address1 | Maps the first line of the street address. |
Field | Address2 | Address2 | Maps the second line of the street address. |
Field | City | City | Maps the city. |
Field | County | Region | Maps the county/region. |
Dynamic Formula |
| Country | Returns a static country value. Update to a dynamic formula if your integration spans multiple countries. |
Field | PostCode | PostalCode | Maps the postal/zip code. |
Dynamic Formula |
| FirstName | Extracts the first word from the full name as the first name. |
Dynamic Formula |
| LastName | Extracts the second word from the full name as the last name; returns empty string if only one word. |
Child 2: Dynamics Add/Update Order Sales Line Item TO iPaaS
Description
This mapping collection maps Sales Order line items from Business Central to iPaaS.com transaction lines. Each line maps product details, quantities, pricing, and discounts. Line-level status is derived from the parent order's Order_Status custom property.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Static | Product | Type | Sets the transaction line type to "Product." |
Field | LineNo | SequenceNumber | Maps the line number to define item sequence. |
Dynamic Formula |
| Status | Normalizes the parent order status into a standardized line-level status. Note: differs from the header formula — "Completed" maps to "Completed" (not "Complete"), and "Cancelled" maps to "Partially Shipped" (not "Shipped"). |
Field | No | Sku | Maps the product/item code (SKU). |
Field | Description | Description | Maps the product description. |
Field | Quantity | Qty | Maps the quantity ordered. |
Field | QtyToShip | QtyShipped | Maps the quantity to ship. |
Field | UnitPrice | UnitPrice | Maps the unit price. |
Field | LineDiscountAmount | DiscountAmount | Maps the line-level discount amount. |
Field | LineDiscountPercent | DiscountPercent | Maps the line-level discount percentage. |
Child 3: Add/Update Order Sales Payment TO iPaaS
Description
This mapping collection transfers payment terms from the parent Business Central Sales Order as a transaction payment in iPaaS.com. It only processes when the record source type is "ParentOnly" and a valid PaymentTermsCode exists.
Mapping Filter
SourceTypeName == "ParentOnly" && !string.IsNullOrEmpty(Parent.PaymentTermsCode)
Description
This filter enables the collection to transfer Sales Order payment terms as a transaction payment, but only when the source type is "ParentOnly" and the parent order has a non-empty PaymentTermsCode.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Dynamic Formula |
| Method | Retrieves the PaymentTermsCode from the parent Sales Order via the API. |
Child 4: Add/Update Order Sales Tracking Number TO iPaaS
Description
This mapping collection maps shipment tracking information from Business Central Sales Order lines to iPaaS.com. It validates that the shipping method exists in iPaaS.com before processing and maps the tracking number, shipping method, and shipment reference details.
Mapping Filter
bool IsExist = await IsShippingMethodExistsInIPaaS(LocationCode); if (!IsExist) throw new Exception($"Shipping Method ({LocationCode}) needs to be created manually in iPaaS.com first"); return true;Description
This filter checks whether the shipping method (based on LocationCode) already exists in iPaaS.com. If it does not, the transfer stops with an error prompting manual creation of the shipping method in iPaaS.com. This ensures only valid shipping methods are processed.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Field | No | Shipment Line No (Custom Field) | Maps the shipment line number. |
Field | DocumentNo | Shipment No (Custom Field) | Maps the shipment document number. |
Field | LocationCode | ShippingMethod | Maps the shipping method code from the location code. |
Field | Description | ShippingMethodDescription | Maps the shipping method description. |
Field | PackageTrackingNo | TrackingNumber | Maps the package tracking number. |
Error Handling
Duplicate Transaction Number
TransactionNumber already exists in iPaaS.com.
Description: A Sales Order with the same transaction number has already been synced.
Resolution: Ensure that the TransactionNumber is unique before syncing. Review existing iPaaS.com transactions for duplicates.
Invalid Email
Email field format is incorrect or missing.
Description: The SellToEMail value does not follow standard email format.
Resolution: Ensure the email is valid and follows the standard format (e.g., user@example.com).
Customer Not Found
CustomerNo not found in iPaaS.com.
Description: The customer or company associated with the Sales Order does not exist in iPaaS.com.
Resolution: Ensure the customer or company record exists in iPaaS.com before syncing the Sales Order. Run a customer sync if needed.
Missing Shipping Method
Shipping Method (LocationCode) needs to be created manually in iPaaS first.
Description: The shipping method referenced in the tracking number collection does not exist in iPaaS.com.
Resolution: Manually create the shipping method in iPaaS.com before processing the Sales Order. The shipping method name must match the LocationCode value from Business Central.
Validation and Testing
Validation Rules
The TransactionNumber must be unique to prevent duplicate orders in iPaaS.com.
EmailAddress must not be null and must follow the standard email format.
The CustomerNo must exist in iPaaS.com customer or company records.
Shipping methods referenced in tracking number lines (via LocationCode) must exist in iPaaS.com before the tracking number collection can process.
Validation Checklist
Sales Order ID is unique and valid.
A valid CustomerNo exists in iPaaS.com.
Email is in a valid format and not null.
Shipping methods exist in iPaaS.com for all LocationCode values referenced in tracking number lines.
The TransactionPollSearchDays preset is configured for the desired polling lookback window.
All required Web Services are enabled in Business Central.
Order_Status custom property is populated in AdditionalProperties.
Test Scenarios
Scenario 1: Valid Sales Order Sync
Sync a Sales Order with Status = "Released" and IsInvoice = false. The transaction should be created in iPaaS.com with the correct header details, addresses, line items, payment terms, and tracking numbers.
Scenario 2: Pending or Cancelled Order
Sync a Sales Order with a non-"Released" status. Verify the mapping filter excludes the order, and the transfer does not occur.
Scenario 3: Invalid Customer ID
Sync a Sales Order for a customer that does not exist in iPaaS.com. Verify the error is logged, and the transaction is not created.
Scenario 4: Invalid Country Name
Sync a Sales Order with an address containing an invalid or unexpected country value. Verify that the error is returned and must be corrected manually.
Scenario 5: Missing Shipping Method
Sync a Sales Order with a LocationCode that does not have a corresponding shipping method in iPaaS.com. Verify that the tracking number collection throws an error with the correct message.
Additional Notes
Only Sales Orders where
IsInvoice = falseandStatus = "Released"are transferred.Polling is limited to recent orders, controlled by the TransactionPollSearchDays preset, to avoid reprocessing older data.
The header-level and line-level status formulas differ: header maps "Completed" → "Complete" while line maps it → "Completed"; header maps "Cancelled" → "Shipped" while line maps it → "Partially Shipped." Review both to ensure alignment with your business requirements.
The address collection returns a static "United States" for the Country field. Update to a dynamic formula if your integration spans multiple countries.
Name parsing in the address collection only captures the first two words of the Name field. Names with middle names or suffixes may not parse correctly.
The status is retrieved from
AdditionalPropertiesusingGetValueFromCustomFieldRather than from a standard field, ensure this custom property is populated on all Sales Orders.Do not use
InvoiceOnly:trueorShipmentOnly:truepolling filters when polling Sales Orders, as these will exclude Sales Order records.