Overview
When a qualifying transaction is created or updated in iPaaS.com, the corresponding Sales Order record is created or updated in Microsoft Dynamics 365 Business Central. This mapping collection transfers header-level order details — including customer identification, shipping and billing addresses, order status, discount, and location — along with line-item data through a child collection.
Sales Orders can be transferred to Business Central via manual sync or webhooks. Supported webhook scopes include transaction/created and transaction/updated.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
iPaaS.com Requirements
Transaction status must be "Pending"
At least one of CustomerId or CompanyId must be populated
The Customer or Company must have a valid external ID mapped to a Business Central customer
Line item SKUs must exist as items in Business Central
Webhook scopes (
transaction/created,transaction/updated) must be configured if automatic sync is required
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
Customer records must exist with a valid Customer Posting Group assigned
Country codes used in addresses must be valid in Business Central (e.g., "US")
Items referenced in line mappings must exist in Business Central
Custom fields must be exposed through Web Services if extended mappings are used
ID Format
When performing a manual transfer of a Sales Order from iPaaS.com, use the iPaaS.com internal Transaction ID as the identifier.
Example:
17542
This ID uniquely represents each Sales Order record within iPaaS.com and ensures the correct data is transferred to Business Central.
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Supported Child Collections
This flow uses one child collection to create the complete Sales Order record in Business Central:
Data Requirements
The following fields are required for successful Sales Order creation.
Mandatory Header Fields
SellToCustomerNo (resolved from CustomerId or CompanyId)
Status (via lookup translation)
Recommended Header Fields
OrderDate
YourReference (iPaaS.com Transaction ID)
Shipping_Agent_Code
Shipping_Agent_Service_Code
ShippingOptions / BillToOptions
Ship-To address fields
Bill-To address fields
PaymentDiscountPercent
LocationId
Mandatory Line Fields
DocumentType (static: "Order")
Type (static: "Item")
No (SKU)
Quantity
System Caveats
iPaaS.com Caveats
Transaction Qualification: The mapping filter restricts transfers to transactions with Status = "Pending" that have either a CustomerId or CompanyId. Transactions in any other status or without customer/company identification are excluded.
SKU Exclusion Preset: The ExcludeSKUsFromPreprocessing preset accepts a comma-separated list of SKUs to exclude from processing. Line items with SKUs in this list are skipped entirely — they are not mapped, linked, or transferred to Business Central. All other line items are processed normally. This is useful for excluding test, internal, or non-sellable items.
Customer Resolution: The customer resolution formulas use a multi-step fallback: first checking CustomerId for an external ID, then falling back to CompanyId. If neither resolves, the transfer will fail because SellToCustomerNo cannot be populated.
MS Dynamics 365 Caveats
Customer Posting Group: Every customer in Business Central must have a valid Customer Posting Group assigned. If the posting group is missing, the Sales Order creation will fail.
Address Options: Business Central supports two shipping/billing address modes: "Custom Address" (where address fields are mapped individually) and "Default (Sell-to Address)" (where the customer's default address is used via SellToCustomerNo). This template uses "Custom Address" for both shipping and billing.
Static Country/Region Values: The ShipToCounty, ShipToCountryRegionCode, BillToCounty, and BillToCountryRegionCode fields are currently set to static values of "US." If your integration spans multiple countries, these should be changed to dynamic formulas that retrieve the values from the iPaaS.com address collection. See Configuration Examples for the original dynamic formula alternatives.
OrderDate Format: The OrderDate field in Business Central is stored as a string. The mapping converts the iPaaS.com TransactionCreatedDateTime (DateTimeOffset format) to a string using
.ToString().
Integration Caveats
Location ID Resolution: The LocationId mapping uses a two-step conversion:
ConvertLocationCodeToLocationIdretrieves the Business Central location ID from the location code, thenConvertLocationIdToiPaaS.comIdconverts it to the corresponding iPaaS.com location ID. Both conversions must succeed for the field to be populated.Inventory Fields: RemainingQuantity is mapped to both QtyAvailable and QtyOnHand. Review whether both mappings are needed for your implementation.
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 for Sales Order FROM iPaaS.com
NOTE: 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 iPaaS.com to Business Central.
Confirm that the field values are updated appropriately in Business Central.
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 iPaaS.com Transaction records as follows:
The transaction is created or updated in iPaaS.com.
Webhook fires (
transaction/createdortransaction/updated), or a manual sync is triggered using the iPaaS.com Transaction ID.The mapping filter validates that Status = "Pending" and either CustomerId or CompanyId is populated.
iPaaS.com authenticates with Business Central using OAuth 2.0.
The Business Central customer number (SellToCustomerNo) is resolved using the CustomerId or CompanyId external ID.
Shipping agent code and service code are retrieved from the customer record in Business Central.
Order status is mapped via the lookup translation table (Pending → Open; other statuses → Released).
Shipping address fields are populated from the primary shipping address in iPaaS.com.
Billing address fields are populated, with BillToName resolved from the Business Central customer record.
LocationId is resolved via the two-step location code conversion.
Line-item child collection maps each qualifying line with DocumentType, Type, SKU, description, quantity, and shipped quantity.
Sales Order is created or updated in Business Central via the Sales Order API.
Business Central Sales Order ID is saved as the External ID in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: Dynamics Add Sales Order FROM iPaaS
Description
This mapping collection creates or updates Sales Orders in Microsoft Dynamics 365 Business Central from qualifying iPaaS.com transactions. It maps customer identification, order date, status, shipping and billing addresses, discount, and location information. The child collection handles line-item details.
Mapping Filter
Status == "Pending" && (CustomerId != null || CompanyId != null)
Description
This filter restricts transfers to transactions with a status of "Pending" that are associated with either a customer or a company. Transactions in any other status or without customer/company identification are excluded.
Mapping Type | Source (iPaaS.com) | Destination (MSD 365) | Description |
Dynamic Formula |
| Shipping_Agent_Code | Resolves the Business Central customer external ID (via CustomerId, then CompanyId fallback), then retrieves the customer's shipping agent code. |
Dynamic Formula |
| Shipping_Agent_Service_Code | Resolves the Business Central customer external ID, then retrieves the customer's shipping agent service code (e.g., standard, express). |
Dynamic Formula |
| SellToCustomerNo | (Required) Resolves the Business Central customer number using the CustomerId or CompanyId external ID. |
Dynamic Formula |
| OrderDate | Converts the iPaaS.com creation date (DateTimeOffset) to a string for Business Central. |
Field | Id | YourReference | Maps the iPaaS.com Transaction ID as a reference. |
Lookup Translation | Status | Converts iPaaS.com transaction status to Business Central order status. Pending → Open; all other non-cancelled statuses → Released. | |
Field | DiscountAmount | PaymentDiscountPercent | Maps the discount amount. |
Static | Custom Address | ShippingOptions | Sets shipping address mode to "Custom Address" so individual address fields are used. |
Dynamic Formula |
| ShipToName | Concatenates first and last name from the primary shipping address. Returns first name only if last name is null. |
Dynamic Formula |
| ShipToAddress | Maps the first address line from the primary shipping address. |
Dynamic Formula |
| ShipToAddress2 | Maps the second address line from the primary shipping address. |
Dynamic Formula |
| ShipToCity | Maps the city from the primary shipping address. |
Static | US | ShipToCounty | Sets the ship-to county/region. Currently static; see Configuration Examples for a dynamic alternative. |
Dynamic Formula |
| ShipToPostCode | Maps the postal code from the primary shipping address. |
Static | US | ShipToCountryRegionCode | Sets the ship-to country code. Currently static; see Configuration Examples for a dynamic alternative. |
Static | Custom Address | BillToOptions | Sets billing address mode to "Custom Address." |
Dynamic Formula |
| BillToName | Resolves the customer name from Business Central using the CustomerId or CompanyId external ID. See Configuration Examples for an alternative using iPaaS.com address data. |
Dynamic Formula |
| BillToAddress | Maps the first address line from the primary billing address. |
Dynamic Formula |
| BillToAddress2 | Maps the second address line from the primary billing address. |
Dynamic Formula |
| BillToCity | Maps the city from the primary billing address. |
Static | US | BillToCounty | Sets the bill-to county/region. Currently static; see Configuration Examples for a dynamic alternative. |
Dynamic Formula |
| BillToPostCode | Maps the postal code from the primary billing address. |
Static | US | BillToCountryRegionCode | Sets the bill-to country code. Currently static; see Configuration Examples for a dynamic alternative. |
Dynamic Formula |
| LocationId | Converts the Business Central location code to a location ID, then converts that to the corresponding iPaaS.com location ID. |
Field | RemainingQuantity | QtyAvailable | Maps the remaining quantity to the available quantity. |
Field | RemainingQuantity | QtyOnHand | Maps the remaining quantity to the on-hand quantity. |
Lookup Translation Table: Dynamics Order Sales Status From iPaaS
Source (iPaaS.com) | Destination (MSD 365) |
Pending | Open |
Status != "Pending" and Status != "Cancelled" | Released |
Child 1: Dynamics Add Sales Order Line FROM iPaaS
Description
This mapping collection creates Sales Order lines in Business Central from iPaaS.com transaction line items. Each line requires a static DocumentType of "Order" and Type of "Item," along with the product SKU, description, quantity, and shipped quantity.
NOTE: Line items with SKUs listed in the ExcludeSKUsFromPreprocessing preset are excluded during preprocessing, before this collection is evaluated. |
Mapping Type | Source (iPaaS.com) | Destination (MSD 365) | Description |
Static | Order | DocumentType | (Required) Must be set to "Order" for the Sales Order Line API. |
Static | Item | Type | (Required) Must be set to "Item" for product line items. |
Field | Sku | No | (Required) Maps the iPaaS.com product SKU to the Business Central item number. |
Field | Description | Description | Maps the line item description. |
Field | Qty | Quantity | (Required) Maps the ordered quantity. |
Field | QtyShipped | QtyToShip | Maps the shipped quantity from iPaaS.com to the quantity to ship in Business Central. |
Configuration Examples
The following examples provide alternative formulas for fields currently set to static values in the template. Update these as needed for your implementation.
Dynamic Country/Region Mapping
The ShipToCounty, ShipToCountryRegionCode, BillToCounty, and BillToCountryRegionCode fields are currently set to a static value of "US." To support multiple countries, replace the static mappings with dynamic formulas:
ShipToCounty (Region):
FieldFromFirstMatch(Addresses, "IsPrimaryShipping == true", "Region");
ShipToCountryRegionCode:
FieldFromFirstMatch(Addresses, "IsPrimaryShipping == true", "Country");
BillToCounty (Region):
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Region");
BillToCountryRegionCode:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Country");
Alternative BillToName Using iPaaS.com Address Data
The current BillToName formula retrieves the customer name from Business Central. To use iPaaS.com billing address data instead:
var firstName = FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "FirstName"); var lastName = FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "LastName"); return firstName != null ? firstName + (lastName != null ? " " + lastName : "") : null;
Billing Address Fields (Custom Address Mode)
When BillToOptions is set to "Custom Address," the following fields can be mapped:
BillToAddress:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Address1")BillToAddress2:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Address2")BillToCity:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "City")BillToCountryRegionCode:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Country")BillToCounty:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Region")BillToPostCode:
FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "PostalCode")BillToName: (See formula above)
Error Handling
Missing Customer Posting Group
No Customer Posting Group has been assigned to the transaction.
Description: The Business Central customer does not have a valid Customer Posting Group configured.
Resolution: Assign a valid Customer Posting Group to the customer in Business Central before transferring the Sales Order.
Invalid Country Code
The provided country code is not in MSD 365.
Description: A country or region code in the address fields does not match a valid code in Business Central.
Resolution: Use a valid country code that exists in Business Central (e.g., "US"). If using static country values, ensure they match your Business Central configuration.
Customer Not Found
External ID is null — SellToCustomerNo cannot be resolved.
Description: Neither the CustomerId nor CompanyId resolved to a valid external ID in iPaaS.com.
Resolution: Ensure the customer or company record in iPaaS.com has a valid external ID mapped to a Business Central customer. Run a customer sync if needed.
Duplicate Transaction Number
TransactionNumber already exists in Business Central.
Description: A Sales Order with the same reference number already exists.
Resolution: Ensure the TransactionNumber (YourReference) is unique before syncing.
Validation and Testing
ValidationThe Rules
At least one of CustomerId or CompanyId must be present; both cannot be null. The resolved customer must have a valid Customer Posting Group in Business Central.
The TransactionNumber must be unique to prevent duplicate Sales Orders.
Line item SKUs must correspond to valid items in Business Central. SKUs listed in the ExcludeSKUsFromPreprocessing preset are automatically excluded.
Validation Checklist
Transaction status is "Pending", and either CustomerId or CompanyId is populated.
Customer or Company has a valid external ID mapped to a Business Central customer.
The Business Central customer has a valid Customer Posting Group.
Country codes in address fields are valid in Business Central.
Line item SKUs exist as items in Business Central.
The ExcludeSKUsFromPreprocessing preset is configured if specific SKUs need to be excluded.
Webhook scopes are configured if automatic sync is required.
Custom fields in iPaaS.com match Business Central field names and types.
Web Services are enabled for all required entities in Business Central.
Test Scenarios
Scenario 1: Valid Sales Order Creation
Sync a qualifying transaction (Status = "Pending", valid CustomerId) from iPaaS.com. Sales Order should be created in Business Central with correct header details, shipping/billing addresses, and line items.
Scenario 2: Invalid Customer ID
Sync a transaction where neither CustomerId nor CompanyId resolves to a valid Business Central customer. Verify the error is logged and the Sales Order is not created.
Scenario 3: Missing Customer Posting Group
Sync a transaction for a customer without a valid Customer Posting Group in Business Central. Verify that the error is displayed, and the transaction is not created.
Scenario 4: Invalid Country Code
Sync a transaction with an address containing an invalid country code. Verify that the error is returned, and the corrected code is required.
Scenario 5: Excluded SKUs
Sync a transaction containing line items with SKUs in the ExcludeSKUsFromPreprocessing list. Verify that those lines are skipped, and all other lines are processed normally.
Additional Notes
Only transactions with Status = "Pending" and a valid CustomerId or CompanyId are transferred.
The ShipToCounty, ShipToCountryRegionCode, BillToCounty, and BillToCountryRegionCode fields are currently static ("US"). Update these to dynamic formulas if your integration spans multiple countries.
RemainingQuantity is mapped to both QtyAvailable and QtyOnHand — review whether both are needed for your implementation.
The BillToName formula retrieves the customer name from Business Central rather than from iPaaS.com address data. See Configuration Examples for an alternative approach.
The ExcludeSKUsFromPreprocessing preset operates during preprocessing, before mapping filters are evaluated. SKUs in this list are completely excluded from processing.
The LocationId mapping requires two successful conversions (location code → location ID → iPaaS.com ID). If either conversion fails, the field is not populated.
Ensure all customers in Business Central have valid Customer Posting Groups assigned before transferring Sales Orders.
The OrderDate field converts DateTimeOffset to string format — verify the output format meets your Business Central configuration requirements.