Contents
Summary
Microsoft Dynamics 365 Business Central sales orders can be transferred to iPaaS.com as transactions through the integration's polling schedule or through Manual Sync. Each order is captured as an iPaaS.com transaction with its header detail, and four child collections capture the order's addresses, line items, tracking number, and payment terms within the same transfer.
Only Business Central sales orders whose status is Released are processed. Orders in any other status are skipped until they reach Released. This sales order family captures the open-order stage of a Business Central sales document; once a sales order is posted it becomes a sales invoice, which is captured separately by the sales invoice family. The parent Add/Update Dynamics 365 Business Central Sales Order TO iPaaS.com collection records the order header, then dispatches its four child collections so that the addresses, line items, tracking number, and payment travel with the same iPaaS.com transaction.
ID Format
Manual Sync ID Format
When transferring a Business Central sales order from the iPaaS.com Manual Sync page, enter the order in either of these formats:
{{salesorder_no}}The {{salesorder_no}} value is the Business Central sales order number — the No. field on the sales order.
Example:
SO1001
{{orderId}}The {{orderId}} value is the sales order's unique ID (a GUID).
Example:
9b6f77f2-15db-4c56-94a0-d8b8c6762b8e
External ID Format
After a successful transfer, iPaaS.com saves the Business Central sales order number as the external ID on a dedicated external-ID record. This external ID links every subsequent transfer of the same order to the same iPaaS.com transaction rather than creating a duplicate. Keep the sales order number unique so repeated transfers update the existing transaction.
The child records are linked to the same order through their own external IDs derived from the order:
The tracking number child saves an external ID based on the sales order number with a tracking suffix — for example,
SO1001|tracking.The payment child saves an external ID combining the sales order identifier with the mapping collection identifier — for example,
SO1542|1564.
Deleted Record Support
Outbound delete is not supported for the sales order transaction or for any of its child records (addresses, line items, tracking number, and payment). This family captures and updates sales orders into iPaaS.com; it does not remove iPaaS.com records. Delete mappings are not included in the default templates, and deleting a sales order or any of its child records in Business Central does not remove the corresponding iPaaS.com transaction or child record. Subscribers who need to retire an iPaaS.com transaction should manage that on the iPaaS.com side.
Custom Field Support
Custom fields are supported on the parent sales order transaction and on the line-item collection. They are not supported on the address, tracking number, or payment collections.
The default templates do not ship any custom-field mappings for this family. To capture a Business Central sales order or line value that is not already in the standard mapping list:
In Business Central, customize the relevant Web Service so the value is exposed in the sales order or line response. Subscribers or their MiSP can contact iPaaS.com Support for assistance customizing Business Central Web Services.
In iPaaS.com, create a custom field on the subscription that matches the field name and data type.
Map the new iPaaS.com custom field to the Business Central value in the parent sales order collection or the line-item collection.
A custom field must exist on the iPaaS.com subscription before its mapping can store a value; an unmatched custom field is left unset.
Mapping Collection Status
Status: Enabled
Trigger Events: Transaction Create, Transaction Update, Transaction Poll. These collections use the transaction scope set. Transfers happen automatically on the integration's polling schedule — there are no webhooks for this integration, so the integration periodically checks Business Central for new and changed sales orders within the Transaction Poll Search Days window — and a Manual Sync can be run at any time. Whether a detected order creates a new iPaaS.com transaction or updates an existing one depends on the external-ID link (the saved sales order number), not on the change type — see ID Format.
Polling Filters
The sales order polling endpoint accepts optional polling filters that control which record types are retrieved and allow additional filtering. Filters are passed as a single string and may be combined using commas. When polling sales orders:
Do not use
InvoiceOnly:trueorShipmentOnly:true— these exclude sales order records from the results.Shipment:trueorInvoice:truestill returns sales orders alongside the respective record type.An additional filter such as
Your_Reference ne ''can be added to include only sales orders whose Your Reference field is not empty.
Duplicate or Conflicting Mappings
Other collections operate on Business Central order and invoice data and may write the same kinds of records:
Dynamics Sales Order Add/Update from iPaaS and its child write sales orders in the opposite direction — from iPaaS.com into Business Central — rather than capturing them.
The Business Central invoice collections capture posted invoices and sales invoices, which are handled separately from open sales orders but also write transaction records to iPaaS.com.
Before enabling these collections together, review their filters and Add/Update settings and decide which system is the source of truth for order data, so the same record is not written in conflicting directions.
Collision Handling
This integration does not provide configurable collision-handling methods for the sales order collections. There is no subscriber-selectable conflict-resolution option (such as Error, Remap and Link, or Update and No Link) on these collections. Orders are instead matched to their iPaaS.com transaction by the saved external ID (the sales order number) — see ID Format. Keep the sales order number unique so repeated transfers update the same transaction rather than creating a duplicate.
Duplicate Matching
None of the five sales order collections perform duplicate matching against existing iPaaS.com records, and none auto-transfer a related record as a prerequisite. The order transaction is linked to iPaaS.com solely by its external ID; the child records are captured within the parent order's transfer and associated with that order's transaction.
Supported Child Collections
The parent Add/Update Dynamics 365 Business Central Sales Order TO iPaaS.com collection captures the order header. Four child collections capture the rest of the order within the same dispatch:
Child Collection | Purpose |
Add/Update Dynamics 365 Business Central Sales Order Address TO iPaaS.com | Captures the order's billing and shipping addresses. |
Add/Update Dynamics 365 Business Central Sales Order Line Item TO iPaaS.com | Captures each order line as a transaction line. |
Add/Update Dynamics 365 Business Central Sales Order Tracking Number TO iPaaS.com | Captures the order's package tracking number and shipping method. |
Add/Update Dynamics 365 Business Central Sales Order Payment TO iPaaS.com | Captures the order's payment terms as a transaction payment. |
Each child collection captures its records as part of the parent order's transfer; the children are not synced on their own.
System Caveats
Microsoft Dynamics 365 Business Central Caveats
Order qualification: only sales orders whose status is Released are processed. Orders in any other status are skipped until they reach Released, and they are not captured as transactions before then.
Status translation: Business Central order statuses are translated to standardized iPaaS.com statuses through a status lookup. Open, Pending Approval, and Pending Prepayment map to Pending; Released maps to Shipped; Completed maps to Complete. A Business Central status not covered by the lookup is not translated. Review the lookup if orders use statuses beyond these.
Line-level status differs from the header: the line-item collection sets each line's status from whether the parent order is Released — Released becomes Shipped and any other status becomes Pending. This is a simpler rule than the header's status lookup, so the line status reflects only whether the parent order is Released.
Order date conversion: the transaction creation date is converted from the Business Central order date. When the order date is missing or cannot be parsed on the Business Central record, the conversion does not produce a value.
Total quantity: the order's total quantity is calculated by summing the quantities of the order's item lines only. Non-item line types are excluded from the count, and the total is zero when the order has no lines or none of its lines are item lines.
Name parsing on addresses: the address collection derives the first and last name by splitting the address name on spaces — the first word becomes the first name and the second word becomes the last name. A name with only one word leaves the last name empty, and a name with more than two words contributes only its first two words.
Country source: the address country is taken from the Business Central country/region code on the order address. Where downstream systems expect a full country name rather than a code, confirm the value meets their needs.
iPaaS.com Caveats
Sales order number is the routing key: the sales order number must be present on the Business Central record for the transfer to link correctly. It is saved as the external ID that routes all subsequent transfers for that order.
Primary address designations: the primary billing and primary shipping flags determine how each address is classified on the iPaaS.com transaction. Confirm the Business Central order carries the expected billing and shipping address designations.
Line sequence: the line sequence number is taken from the Business Central line number and defines the order of lines on the iPaaS.com transaction. Confirm Business Central line numbering reflects the intended sequence.
Tracking number is the routing key for tracking: a tracking record is captured only when the Business Central order carries a package tracking number. Orders without a tracking number are still captured by the parent order collection and its other children.
Payment terms condition: a payment record is captured only when the parent order carries a payment terms code. Orders without a payment terms code are still captured by the parent order collection and its other children.
Setup Requirements
Microsoft Dynamics 365 Business Central Configuration
Enable Web Services for the customer, item, and sales order data the integration reads — including Sales Order, Sales Orders, and Sales Order Lines, along with Items, Item Card, Item Categories, Items By Location, and Customer Price Groups.
Enable and customize the Sales Shipments Web Service (and Sales Shipment Lines) to expose the originating Order No. on each shipment — the order's tracking-number child reads shipments by that field. Until Order No. is exposed, sales order transfers to iPaaS.com do not complete.
If custom fields are mapped on the parent order or line-item collection, customize the relevant Web Service to expose them.
Authentication uses OAuth 2.0; ensure credentials are stored securely in the iPaaS.com credential manager.
For the full installation walkthrough, see the Installation Instructions.
iPaaS.com Configuration
Configure the Transaction Poll Search Days preset to define the polling lookback window for automatic transfers.
Create custom fields on the iPaaS.com subscription that match the Business Central field names and data types for any custom-field mappings added to the parent order or line-item collection.
Confirm the status lookup entries match the Business Central order statuses in use, so each order status translates to the intended iPaaS.com status.
Subscribers or their MiSP can contact iPaaS.com Support for assistance configuring Business Central Web Services.
Integration Flow
A sales order is created or updated in Business Central and reaches the Released status.
The integration detects the order on its polling schedule within the Transaction Poll Search Days window, or a subscriber triggers a Manual Sync using the
{{salesorder_no}}or{{orderId}}format.The parent mapping filter confirms the order status is Released; orders in any other status are skipped.
iPaaS.com authenticates with Business Central using OAuth 2.0 and reads the order.
The parent collection records the order header: source system identifier, transaction number, type, translated status, customer email, financial totals, total quantity, and order date.
The address child collection records the order's billing and shipping addresses, deriving first and last name from the address name.
The line-item child collection records each order line as a transaction line with SKU, quantity, quantity shipped, pricing, discounts, sequence, and a line-level status.
The payment child collection records the order's payment terms as a transaction payment when the parent order has a payment terms code.
The tracking number child collection records the package tracking number and shipping method when the order carries a package tracking number.
The iPaaS.com transaction is created on the first transfer or updated on subsequent transfers, matched by the saved external ID (the sales order number).
Transfer status and any errors are recorded in the iPaaS.com Dashboard under Integration Monitoring and the Error Logs.
Mappings
Add/Update Dynamics 365 Business Central Sales Order TO iPaaS.com (Parent)
iPaaS.com data type: Transaction
Mapping Filter
Status == "Released"
Filter Description. Only Business Central sales orders whose status is Released pass this filter. Orders in any other status are skipped by this collection and are not captured as transactions until they reach Released.
This collection captures the order header and is the parent of the four child collections below.
Mapping Type | Source Field (Microsoft Dynamics 365 Business Central) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Identifies the source Business Central system on the iPaaS.com transaction so the order is attributed to the correct connected system. The value is resolved automatically by the platform and should not be changed. |
Field |
| TransactionNumber | Required. The iPaaS.com transaction number, taken from the Business Central sales order number. It is saved as the external ID and is the key used to match the order to its iPaaS.com transaction on every transfer. Keep the sales order number unique. |
Static |
| Type | Required (designed constant). Sets the transaction type to a fixed |
Lookup Translation |
| Status | Recommended. Translates the Business Central order status into a standardized iPaaS.com status. Open, Pending Approval, and Pending Prepayment map to Pending; Released maps to Shipped; Completed maps to Complete. A status not listed in the lookup is not translated. See the lookup table below. |
Field |
| EmailAddress | Recommended. The customer's sell-to email address from the order. Left unset when the order has no sell-to email. |
Field |
| DiscountAmount | Recommended. The order's overall discount amount. Left unset when the order has no discount amount. |
Field |
| TaxAmount | Recommended. The total tax amount. In Business Central this value is read-only and is calculated from the order's lines and tax setup. |
Field |
| Subtotal | Recommended. The order subtotal excluding tax. In Business Central this value is read-only and is calculated from the order's lines. |
Field |
| Total | Recommended. The order total including tax. In Business Central this value is read-only and is calculated from the order's lines and tax setup. |
Dynamic Formula | (total-quantity sum — see formula below) | TotalQty | Recommended. The order's total quantity, calculated by summing the quantities of item lines only. Non-item line types are excluded, and the total is zero when the order has no item lines. |
Dynamic Formula | (order-date conversion — see formula below) | TransactionCreatedDateTime | Recommended. Sets the transaction creation date from the Business Central order date, converting it to a date-and-time value. A value is produced only when the order has an order date that can be parsed. |
The Status lookup translates the Business Central order status as follows:
Business Central Status | iPaaS.com Status |
Open, Pending Approval, Pending Prepayment | Pending |
Released | Shipped |
Completed | Complete |
The TotalQty formula:
var sum = 0;
if (LineItems != null && LineItems.count > 0) {
foreach (var item in LineItems){
if (item.Type == "Item")
sum = sum + item.Quantity;
}
}
return sum;The TransactionCreatedDateTime formula:
DateTimeOffset dateTimeOffset = DateTimeOffset.Parse(OrderDate); return dateTimeOffset;
Add/Update Dynamics 365 Business Central Sales Order Address TO iPaaS.com (Child)
iPaaS.com data type: Transaction Address
This collection is a child of the Sales Order parent. It has no mapping filter, so every address on a captured order is processed. It records the order's billing and shipping addresses on the iPaaS.com transaction and derives a first and last name from the address name.
Mapping Type | Source Field (Microsoft Dynamics 365 Business Central) | Destination Field (iPaaS.com) | Description |
Field |
| IsPrimaryBilling | Recommended. Flags whether this is the order's primary billing address, classifying the address on the transaction. |
Field |
| IsPrimaryShipping | Recommended. Flags whether this is the order's primary shipping address, classifying the address on the transaction. |
Field |
| Address1 | Recommended. The first line of the street address. Left unset when the order address has no first line. |
Field |
| Address2 | Recommended. The second line of the street address. Left unset when the order address has no second line. |
Field |
| City | Recommended. The city. Left unset when the order address has no city. |
Field |
| Region | Recommended. The county, mapped to the iPaaS.com region. Left unset when the order address has no county. |
Field |
| Country | Recommended. The country, taken from the Business Central country/region code. Where downstream systems expect a full country name rather than a code, confirm the value meets their needs. Left unset when there is no country/region code. |
Field |
| PostalCode | Recommended. The postal code. Left unset when the order address has no post code. |
Dynamic Formula |
| FirstName | Recommended. Derives the first name by taking the first word of the address name. A name with no spaces contributes its whole value. |
Dynamic Formula |
| LastName | Recommended. Derives the last name by taking the second word of the address name. A one-word name leaves the last name empty; a name with more than two words contributes only its second word. |
Add/Update Dynamics 365 Business Central Sales Order Line Item TO iPaaS.com (Child)
iPaaS.com data type: Transaction Line
This collection is a child of the Sales Order parent. It has no mapping filter, so every line on a captured order is processed. It captures each order line as a transaction line and supports custom fields.
Mapping Type | Source Field (Microsoft Dynamics 365 Business Central) | Destination Field (iPaaS.com) | Description |
Static |
| Type | Required (designed constant). Sets the transaction line type to a fixed |
Field |
| SequenceNumber | Recommended. The line number, defining the order of lines on the transaction. Confirm Business Central line numbering reflects the intended sequence. |
Dynamic Formula |
| Status | Recommended. Derives the line status from the parent order's status — Released becomes Shipped, and any other status becomes Pending. This is a simpler rule than the header's status lookup. |
Field |
| Sku | Recommended. The product/item code (SKU). Left unset when the line has no item code. |
Field |
| Description | Recommended. The line description. Left unset when the line has no description. |
Field |
| Qty | Recommended. The line quantity. Left unset when the line has no quantity. |
Field |
| QtyShipped | Recommended. The line quantity to ship. Left unset when the line has no quantity to ship. |
Field |
| UnitPrice | Recommended. The line unit price. Left unset when the line has no unit price. |
Field |
| DiscountAmount | Recommended. The line-level discount amount. Left unset when the line has no discount amount. |
Field |
| DiscountPercent | Recommended. The line-level discount percentage. Left unset when the line has no discount percentage. |
Add/Update Dynamics 365 Business Central Sales Order Tracking Number TO iPaaS.com (Child)
iPaaS.com data type: Transaction Tracking Number
This collection is a child of the Sales Order parent. It captures the order's package tracking number and shipping method. It records a tracking number; it does not write the order header or its line items.
Mapping Filter
!string.IsNullOrEmpty(PackageTrackingNo)
Filter Description. A tracking record is captured only when the Business Central order carries a package tracking number. When the package tracking number is empty, no tracking record is captured for that order — orders without tracking information do not produce a tracking record, but they are still captured by the parent order collection and its other children.
Mapping Type | Source Field (Microsoft Dynamics 365 Business Central) | Destination Field (iPaaS.com) | Description |
Field |
| TrackingNumber | Required. The package tracking number. It must be present for this collection to capture a tracking record; an order with no package tracking number does not produce one. |
Field |
| ShippingMethod | Recommended. The shipping method, taken from the Business Central shipping agent code. Left unset when the order has no shipping agent code. Confirm the value matches the shipping method downstream systems expect. |
Field |
| ShippingMethodDescription | Recommended. The shipping method description, taken from the Business Central shipment method code. Left unset when the order has no shipment method code. |
Add/Update Dynamics 365 Business Central Sales Order Payment TO iPaaS.com (Child)
iPaaS.com data type: Transaction Payment
This collection is a child of the Sales Order parent. It captures the order's payment terms as a transaction payment, reading its value from the parent order.
Mapping Filter
SourceTypeName == "ParentOnly" && !string.IsNullOrEmpty(Parent.PaymentTermsCode)
Filter Description. A payment record is captured only when the source type is ParentOnly and the parent order has a non-empty PaymentTermsCode. An order with no payment terms code does not produce a payment record, and the collection does not run for non-parent source types.
Mapping Type | Source Field (Microsoft Dynamics 365 Business Central) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. The payment method, taken from the parent order's payment terms code. The payment record is captured only when the parent order has a payment terms code. Confirm the payment terms code matches what downstream systems expect for the payment method. |
Error Handling
For the complete catalog of error messages this integration can produce, see the Error Messages article. The conditions most relevant to the sales order transfer are:
Missing or duplicate sales order number: The sales order number is saved as the external ID and is the key that links each transfer to its iPaaS.com transaction. An order with no number cannot be linked, and a non-unique order number can cause a transfer to update an unintended transaction. Resolution: ensure each Business Central sales order carries a unique sales order number before transferring.
Customer or company not found: If the customer or company associated with the sales order does not exist in iPaaS.com, the order cannot be associated correctly. Resolution: ensure the customer or company record exists in iPaaS.com before transferring the order, running a customer sync first if needed.
Invalid email format: If the sell-to email on the order is not a valid email format, it may be rejected downstream. Resolution: ensure the email follows a standard format (for example, user@example.com).
Errors and transfer status for every order transfer are recorded in the iPaaS.com Dashboard under Integration Monitoring and the Error Logs.
Validation Rules
Order qualification: only sales orders whose status is Released are processed; orders in any other status are skipped by the parent filter.
Tracking condition: a tracking record is captured only when the order carries a package tracking number.
Payment condition: a payment record is captured only when the source type is
ParentOnlyand the parent order has a payment terms code.Status translation: the order status is translated through the status lookup; a status not listed in the lookup is not translated.
Testing and Validation
Test Scenarios
Valid order transfer. Release a complete Business Central sales order with header detail, addresses, line items, payment terms, and a tracking number, then transfer it (by polling or Manual Sync). Confirm the iPaaS.com transaction is created with the correct header, addresses, lines, payment, and tracking number.
Status filter. Transfer a sales order whose status is not Released. Confirm the parent filter excludes it and no transaction is created until the order reaches Released.
Status translation. Transfer Released and Completed orders. Confirm the header status is translated to the expected iPaaS.com value (Shipped and Complete, respectively) and that the line-level status follows the line rule (Shipped when the order is Released, otherwise Pending).
ID format. From the Manual Sync page, transfer a specific order using
{{salesorder_no}}(for example, SO1001) and confirm the correct order is captured. Repeat using the order's GUID.Parent-child transfer. Transfer an order that has multiple lines, billing and shipping addresses, payment terms, and tracking data. Confirm all child records are captured under the same iPaaS.com transaction in a single dispatch.
Tracking condition. Transfer one order with a package tracking number and one without. Confirm a tracking record is captured only for the order that carries a tracking number.
Repeat transfer / external ID. Transfer the same order twice. Confirm the second transfer updates the existing iPaaS.com transaction (matched by sales order number) rather than creating a duplicate.
Validation Checklist
The Business Central sales order carries a unique, non-empty sales order number.
The order status is Released so the parent filter captures it.
All required Web Services are enabled in Business Central.
The status lookup entries match the Business Central order statuses in use.
Custom fields exist on the iPaaS.com subscription for any custom-field mappings added to the parent order or line-item collection, matching the Business Central field names and types.
The Transaction Poll Search Days preset is configured for the desired polling lookback window.
Payment terms codes are populated on orders if payment mapping is in use.
Package tracking numbers are populated on orders if tracking mapping is in use.
Additional Notes
This family captures only sales orders in the Released status; orders in other statuses are not captured until they reach Released.
The header-level status uses a lookup translation, while the line-level status reflects only whether the parent order is Released — review both if order status fidelity matters downstream.
Address name parsing captures only the first two words of the address name, so names with middle names or suffixes may not separate as intended.
The order date conversion produces a value only when the Business Central order has an order date that can be parsed; an empty or unparseable order date leaves the transaction creation date unset.
Outbound delete is not supported for the order transaction or any child record; deletions in Business Central do not propagate to iPaaS.com.
Related Documents
Connections and Settings (pending publication)
Known Limitations (pending publication)