Overview
When an invoice is updated in Microsoft Dynamics 365 Business Central, the corresponding transaction record is updated in iPaaS.com. This mapping collection transfers invoice header data, addresses, line items, payment terms, tracking numbers, and partially shipped line items. Only records where IsInvoice = true are transferred.
Invoice records can be transferred to iPaaS.com through both manual sync and polling. Polling automatically triggers the transfer of invoices from Business Central, limited to recent invoices 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, Sales Order Lines, and Sales Invoices
Invoice records must have IsInvoice = true to qualify for transfer
Contact your MiSP for assistance customizing Business Central Web Services if additional custom fields are needed
iPaaS.com Requirements
Shipping methods referenced in invoice lines must exist in iPaaS.com before transfer
Custom fields must be created in the iPaaS.com subscription if extended field mappings are used
The TransactionPollSearchDays preset must be configured to define the polling lookback window
ID Format
When performing a manual transfer of a MS Dynamics 365 Invoice to iPaaS.com, use the following identifier format: Invoice|{{invoiceId}}
The Invoice ID, prefixed with Invoice|, serves as the primary identifier in the MS Dynamics 365 Invoice API.
Example:
Invoice|72f2e4b9-9b71-4f23-8d8c-bf3c876d3c1a
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Supported Child Collections
This flow uses five child collections to transfer the complete invoice 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.
Supported Boolean Filters
InvoiceOnly: true Polls only invoices. Sales orders and shipments are excluded.
Invoice :true Includes invoices in the polling results. Sales orders are also included unless explicitly excluded.
Combined Filter Examples
InvoiceOnly:true, Your_Reference ne '' Polls only invoices where Your_Reference is not empty. Sales orders and shipments are excluded.
Invoice:true, Your_Reference ne '' Includes invoices where Your_Reference is not empty. Sales orders are also included unless explicitly excluded.
Data Requirements
The following fields are required for a successful invoice transfer.
Mandatory Header Fields:
TransactionNumber (mapped from No)
Type (static: "Invoice")
Status (mapped from Invoice_OrderStatus)
SystemId (mapped from SpaceportSystemId)
Recommended Header Fields:
EmailAddress
DiscountAmount
TaxAmount
Subtotal
Total
TotalQty
System Caveats
MS Dynamics 365 Caveats
Invoice Status Mapping: Business Central invoice statuses are normalized to iPaaS.com statuses using conditional logic. The mapping consolidates multiple statuses: "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."
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.
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.
Partially Shipped Invoice Lines: Partially shipped lines are handled by a separate child collection (Child 5) and are only added when the UpdateNonExistingInvoiceLines preset is enabled. These lines set QtyShipped to 0 by default.
Integration Caveats
Line Type Filtering: The standard line-item collection excludes records where Type = "PartiallyShippedInvoiceLine". The partially shipped collection includes only those records. This ensures each line is processed by exactly one child collection.
Total Quantity Calculation: TotalQty is calculated by summing quantities across all line items where Type = "Item". Non-item line types (e.g., comments, charges) are excluded from the count.
Custom Fields Support
This integration supports extended custom fields for both header-level and line-level data. The following custom fields are mapped in this template.
Header Custom Fields
Invoice No: Maps the Business Central invoice number (Invoice_Invoice_No) for reference and traceability.
Invoiced By: Maps the user or system that generated the invoice (Invoice_InvoicedBy).
Invoice Document Exchange Status: Maps the document exchange status (Invoice_DocumentExchangeStatus) for tracking and auditing purposes.
Line-Item Custom Fields
Unit of Measure: Maps the unit of measure for the item (UnitOfMeasure), e.g., pcs, kg.
Location Code: Maps the inventory or warehouse location code (LocationCode).
Invoice Line Item UPC: Maps the UPC or barcode of the item (InvoiceLine_ItemUPC) for tracking purposes.
Tax Area Code: Maps the tax area code associated with the line item (TaxAreaCode).
Tax Group Code: Maps the tax group code for the line item (TaxGroupCode) to determine applicable tax rules.
Shipment Custom Fields
Shipment Line No: Maps the shipment line number (No).
Shipment No: Maps the shipment document number (DocumentNo).
Adding Custom Fields
In MS Dynamics 365, customize the Web Services to accept the desired custom field in the invoice request. Contact your MiSP for assistance customizing Business Central Web Services.
In iPaaS.com, create a custom field in the iPaaS.com 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.
Setup Requirements
MS Dynamics 365 Configuration
Enable Web Services for all required entities (Sales Invoices, Sales Orders, Sales Order Lines, Items, etc.)
Ensure custom fields are exposed through Web Services if extended mappings are used
Configure invoice statuses to align with expected mapping values
iPaaS.com Configuration
Configure the TransactionPollSearchDays preset to define the polling lookback window
Create shipping methods in iPaaS.com for all LocationCode values used in invoice lines
Create subscription custom fields matching Business Central field names and types
Configure the UpdateNonExistingInvoiceLines preset if partial invoice support is needed
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 invoice records as follows:
The invoice is created or updated in Business Central.
Polling detects the invoice within the TransactionPollSearchDays window, or a manual sync is triggered using the
Invoice|{{invoiceId}}format.The mapping filter validates that IsInvoice = true.
iPaaS.com authenticates with Business Central using OAuth 2.0.
Header fields are mapped: transaction number, type ("Invoice"), status, email, totals, discount, and tax amounts.
TotalQty is calculated by summing quantities of all line items where Type = "Item".
Custom header fields are populated (Invoice No, Invoiced By, Document Exchange Status).
Address child collection maps, billing, and shipping addresses with name parsing.
Line-item child collection maps non-partially-shipped lines with SKU, quantity, pricing, discounts, and custom fields.
Payment child collection maps payment terms from the parent invoice's PaymentTermsCode.
Tracking number child collection validates shipping method existence in iPaaS.com and maps tracking numbers and shipment details.
Partially shipped line-item child collection maps remaining lines where Type = "PartiallyShippedInvoiceLine" with QtyShipped = 0.
The transaction is created or updated in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: Dynamics Update Sales Invoice To iPaaS
Description
This mapping collection transfers invoice header data from Microsoft Dynamics 365 Business Central to iPaaS.com. It maps system identification, transaction details, status, financial totals, and custom fields. Child collections handle addresses, line items, payments, tracking numbers, and partially shipped lines.
Mapping Filter
IsInvoice
Description
This filter transfers only Sales Invoice records from Business Central where the IsInvoice field is set to true. Non-invoice records (e.g., sales orders, credit memos) are excluded.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Dynamically sets the system identifier to uniquely represent the source Business Central system in iPaaS.com. |
Field | No | TransactionNumber | Maps the invoice number as the transaction number. |
Static | Invoice | Type | Sets the transaction type to "Invoice." |
Dynamic Formula |
| Status | Translates Business Central invoice statuses into standardized iPaaS.com statuses (Shipped, Complete, Pending). |
Field | SellToEMail | EmailAddress | Maps the customer's sell-to email address. |
Field | DiscountAmount | DiscountAmount | Maps the total discount amount applied to the invoice. |
Field | TotalTaxAmount | TaxAmount | Maps the total tax amount. |
Field | TotalAmountExcludingTax | Subtotal | Maps the invoice subtotal excluding tax. |
Field | TotalAmountIncludingTax | Total | Maps the invoice total including tax. |
Dynamic 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; | TotalQty | Calculates total quantity by summing quantities of all line items where Type = "Item." |
Dynamic Formula | DestinationValue.TransactionCreatedDateTime | TransactionCreatedDateTime | Preserves the original iPaaS.com transaction creation timestamp. |
Field | Invoice_Invoice_No | Invoice No (Custom Field) | Maps the Business Central invoice number for reference. |
Field | Invoice_InvoicedBy | Invoiced By (Custom Field) | Maps the user or system that generated the invoice. |
Field | Invoice_DocumentExchangeStatus | Invoice Document Exchange Status (Custom Field) | Maps the document exchange status for tracking and auditing. |
Child 1: Dynamics Update Sales Invoice Address To iPaaS
Description
This mapping collection maps Business Central invoice 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. |
Field | CountryRegionCode | Country | Maps the country or region code. |
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 Sales Invoice Line-Item Update To iPaaS.com
Description
This mapping collection maps standard invoice line items from Business Central to iPaaS.com transaction lines. It excludes partially shipped lines, which are handled by a separate child collection (Child 5). Each line maps product details, quantities, pricing, discounts, and custom fields including tax codes and location information.
Mapping Filter
string.IsNullOrWhiteSpace(Type) || Type != "PartiallyShippedInvoiceLine" ? true : false;
Description
This filter includes only records where the Type field is either empty or not equal to "PartiallyShippedInvoiceLine", ensuring that partially shipped invoice lines are excluded from this collection and processed separately.
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 | var orderStatus = Parent.Invoice_OrderStatus; if (orderStatus == null) return null; orderStatus = orderStatus.ToString(); if (orderStatus == "Shipped") { return "Shipped"; } else if (orderStatus == "Completed") { return "Completed"; } else if (orderStatus == "Pending" || orderStatus == "In Progress") { return "Pending"; } else if (orderStatus == "Submitted") { return "Submitted"; } else if (orderStatus == "Partially Shipped") { return "Partially Shipped"; } else if (orderStatus == "Cancelled") { return "Partially Shipped"; }The line-level status formula differs slightly from the header-level formula. At the line level, "Completed" maps to "Completed" (not "Complete"), and "Cancelled" maps to "Partially Shipped" (not "Shipped"). | Status | Normalizes the parent invoice status into a standardized line-level status (Shipped, Completed, Pending, Submitted, Partially 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 | QuantityShipped | QtyShipped | Maps the quantity shipped. |
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. |
Field | UnitOfMeasure | Unit of Measure (Custom Field) | Maps the unit of measure (e.g., pcs, kg). |
Field | LocationCode | Location Code (Custom Field) | Maps the inventory or warehouse location code. |
Field | InvoiceLine_ItemUPC | Invoice Line Item UPC (Custom Field) | Maps the item UPC/barcode for tracking. |
Field | TaxAreaCode | Tax Area Code (Custom Field) | Maps the tax area code. |
Field | TaxGroupCode | Tax Group Code (Custom Field) | Maps the tax group code for applicable tax rules. |
Child 3: Dynamics Update Sales Invoice Tracking Number To iPaaS
Description
This mapping collection maps shipment tracking information from Business Central invoice 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 | LocationCode | ShippingMethod | Maps the shipping method code from the location code. |
Field | Description | ShippingMethodDescription | Maps the shipping method description. |
Dynamic Formula |
| TrackingNumber | Populates the shipment tracking number. Uses PackageTrackingNo if available; falls back to SalesShipment.PackageTrackingNo. |
Field | No | Shipment Line No (Custom Field) | Maps the shipment line number. |
Field | DocumentNo | Shipment No (Custom Field) | Maps the shipment document number. |
Child 4: Dynamics Update Sales Invoice Payment To iPaaS
Description
This mapping collection transfers payment terms from the parent Business Central invoice 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 invoice payment terms as a transaction payment, but only when the source type is "ParentOnly" and the parent invoice has a non-empty PaymentTermsCode.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Dynamic Formula |
| Method | Retrieves the PaymentTermsCode from the parent invoice via the Invoice API. |
Child 5: Dynamics Update Partially Shipped Sales Invoice Line-Item To iPaaS
Description
This mapping collection handles invoice lines that represent partially shipped items. It processes only records where Type = "PartiallyShippedInvoiceLine" and sets QtyShipped to 0 by default. This collection works in conjunction with the UpdateNonExistingInvoiceLines preset to add missing lines to existing iPaaS.com transactions.
Mapping Filter
!string.IsNullOrWhiteSpace(Type) && Type == "PartiallyShippedInvoiceLine" ? true : false;
Description
This filter includes only records where the Type field is not empty and equals "PartiallyShippedInvoiceLine", ensuring that only partially shipped invoice lines are processed in this collection.
Mapping Type | Source (MSD 365) | Destination (iPaaS.com) | Description |
Static | Product | Type | Sets the line type to "Product." |
Field | LineNo | SequenceNumber | Maps the line number to define item sequence. |
Dynamic Formula | var orderStatus = Parent.Invoice_OrderStatus; if (orderStatus == null) return null; orderStatus = orderStatus.ToString(); if (orderStatus == "Shipped") { return "Shipped"; } else if (orderStatus == "Completed") { return "Completed"; } else if (orderStatus == "Pending" || orderStatus == "In Progress") { return "Pending"; } else if (orderStatus == "Submitted") { return "Submitted"; } else if (orderStatus == "Partially Shipped") { return "Partially Shipped"; } else if (orderStatus == "Cancelled") { return "Partially Shipped"; } | Status | Normalizes the parent invoice status into a standardized line-level status. Uses the same formula as the standard line-item collection. |
Field | No | Sku | Maps the product/item code (SKU). |
Field | Description | Description | Maps the product description. |
Field | Quantity | Qty | Maps the quantity ordered. |
Static | 0 | QtyShipped | Sets shipped quantity to 0 by default (shipment data not available for partially shipped lines). |
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. |
Error Handling
Duplicate Transaction Number
TransactionNumber already exists in iPaaS.com.
Description: An invoice 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).
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 invoice. The shipping method name must match the LocationCode value from Business Central.
Invalid Country Code
Country code is invalid or missing.
Description: The CountryRegionCode in the address collection does not match a valid country.
Resolution: Correct the country code in Business Central and re-sync.
Validation and Testing
Validation Rules
Transaction Number Uniqueness: TransactionNumber must be unique to prevent duplicate invoices in iPaaS.com.
Email Validation: EmailAddress must not be null and must follow the standard email format.
Shipping Method Existence: Shipping methods referenced in invoice lines (via LocationCode) must exist in iPaaS.com before the tracking number collection can process.
Partially Shipped Line Handling: Partial invoice lines are only added when the UpdateNonExistingInvoiceLines preset is enabled.
Validation Checklist
Sales Invoice ID is unique and valid.
Email is in a valid format and not null.
Shipping methods exist in iPaaS.com for all LocationCode values referenced in invoice lines.
UpdateNonExistingInvoiceLines preset is enabled if partial invoice support is needed.
TransactionPollSearchDays preset is configured for the desired polling lookback window.
All required Web Services are enabled in Business Central.
Custom fields in iPaaS.com match Business Central field names and types.
Payment terms codes are populated on invoices if payment mapping is active.
Test Scenarios
Scenario 1: Valid Invoice Sync
Sync a complete invoice with all required fields populated. The invoice should be created in iPaaS.com with the correct header details, addresses, line items, payment terms, and tracking numbers.
Scenario 2: Pending or Cancelled Invoice
Sync an invoice with a Pending or Cancelled status. Verify the status is correctly normalized to the iPaaS.com equivalent ("Pending" or "Shipped" respectively).
Scenario 3: Invalid Country Code
Sync an invoice with an invalid or missing CountryRegionCode. Verify that the error is returned and must be corrected manually in Business Central.
Scenario 4: Duplicate Transaction Number
Attempt to sync an invoice with a TransactionNumber that already exists in iPaaS.com. Verify that the error is logged, and the duplicate invoice is not created.
Scenario 5: Missing Shipping Method
Sync an invoice with a LocationCode that does not have a corresponding shipping method in iPaaS.com. Verify the tracking number collection throws an error with the correct message.
Scenario 6: Partially Shipped Lines
Sync an invoice containing lines with Type = "PartiallyShippedInvoiceLine". Verify these lines are processed by Child 5 with QtyShipped = 0, and that they only appear when UpdateNonExistingInvoiceLines is enabled.
Additional Notes
Only invoices where IsInvoice = true are transferred.
Polling is limited to recent invoices, controlled by the TransactionPollSearchDays preset, to avoid reprocessing older data.
Invoice ID format for manual sync:
Invoice|{{invoiceId}}. Example:Invoice|72f2e4b9-9b71-4f23-8d8c-bf3c876d3c1a.Partial invoices are supported via the UpdateNonExistingInvoiceLines preset, which adds missing lines from iPaaS.com to the current invoice.
The header-level and line-level status formulas differ slightly in their mapping of "Completed" and "Cancelled" statuses — review both formulas to ensure alignment with your business requirements.
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.
Custom fields such as QtyShipped, InvoiceLine_ItemUPC, and UnitOfMeasure are mapped for traceability and accurate reporting.
All mappings (Header, Address, Line Items, Payments, Shipment) follow strict field validations to ensure data consistency in iPaaS.com.