Contents
Summary
Customer records can be sent from iPaaS.com into Microsoft Dynamics 365 Business Central through two collections in this family: Add Dynamics 365 Business Central Customer FROM iPaaS.com, which creates a new Business Central customer, and Update Dynamics 365 Business Central Customer FROM iPaaS.com, which updates an existing one. Each collection writes the customer's number and name, email, primary billing address details (address, city, county, post code, country, and phone), the customer price group resolved from the iPaaS.com customer's categories, and the posting groups, payment terms, and tax area that control how the customer's transactions post in Business Central.
Whether an incoming customer is created through the Add collection or updated through the Update collection is decided by whether the iPaaS.com customer is already linked to a Business Central customer record, not by which event fired. The two collections work together: the Add collection establishes the link and creates the record, and the Update collection refreshes an already-linked record while preserving its Business Central customer number. Customer records sent through this family are always created as a person-type customer in Business Central.
ID Format
Manual Sync ID Format
When transferring a customer from the iPaaS.com Manual Sync page, enter the iPaaS.com customer record ID of the customer to transfer.
Example: 153237
External ID Format
After a successful transfer, iPaaS.com saves the Business Central customer number as the external ID on a dedicated external-ID record. The customer is identified in Business Central by its customer number — the No. field on the customer card. This external ID routes every subsequent transfer of the same customer to the existing Business Central customer rather than creating a duplicate. An example customer number value from Business Central is 44552.
As a fallback, when no external-ID record exists yet and the iPaaS.com customer matches an existing Business Central customer by number or by email, the records are linked automatically instead of creating a duplicate — see Duplicate Matching.
Deleted Record Support
Outbound delete is not supported for the customer record. These collections create and update Business Central customers from iPaaS.com; they do not remove Business Central records. Delete mappings are not included in the default templates, and deleting a customer in iPaaS.com does not remove the corresponding Business Central customer. Subscribers who need to retire a Business Central customer should manage that on the Business Central side.
Custom Field Support
Custom fields are supported for both the Add and Update collections in this direction. To set a Business Central customer field that is not already in the standard mapping list:
In Business Central, customize the relevant Web Service so it accepts the field on the customer request. Subscribers or their MiSP can contact iPaaS.com Support for assistance customizing Business Central Web Services.
In iPaaS.com, create a custom field whose name matches the Business Central field name you want to populate.
Map the new custom field to a static or dynamic source.
Each such custom field name and value is included in the customer record sent to Business Central as-is. The name must be a valid customer field in your Business Central environment, or Business Central rejects the request.
Mapping Collection Status
Status: Enabled
Trigger Events: Customer Create, Customer Update. These collections use the customer scope set. In this direction, transfers dispatch automatically once subscribers or their MiSP subscribe to the iPaaS.com customer outbound triggers — enable them in the subscription configuration's Outbound Data Flows section by subscribing to the customer create and update events. Until those subscriptions are enabled, no automatic transfers occur, and a Manual Sync can be run at any time. Whether a transferred customer is created through the Add collection or updated through the Update collection depends on whether the record is already linked to a Business Central customer, not on which event fired.
Duplicate or Conflicting Mappings
Other collections also operate on the Business Central customer and may write the same record:
Add Dynamics 365 Business Central Customer FROM iPaaS.com and Update Dynamics 365 Business Central Customer FROM iPaaS.com are the two collections of this family. The Add collection creates a new Business Central customer; the Update collection refreshes an existing one. They are designed to work together and are partitioned by whether the iPaaS.com customer is already linked to a Business Central record.
Add/Update Dynamics 365 Business Central Customer TO iPaaS.com captures customers from Business Central into iPaaS.com — the opposite direction.
Before enabling these collections together, review their filters and Add/Update settings and decide which system is the source of truth for customer data, so the same customer is not written in conflicting directions.
Collision Handling
This integration does not provide configurable collision-handling methods for the customer collections. There is no subscriber-selectable conflict-resolution option (such as Error, Remap and Link, or Update and No Link) on these collections. Customers are instead matched to their Business Central record by the saved external ID (the customer number), with a number-then-email fallback — see Duplicate Matching. Keep the customer number and email unique so repeated transfers update the same customer rather than creating a duplicate.
Duplicate Matching
Before creating or updating a customer that is not already linked, the integration checks whether the incoming customer already exists in Business Central — first by customer number, then by email — and links the iPaaS.com customer to that existing Business Central record instead of creating a duplicate. When a match is found, an external-ID link is established so all later transfers route to the same Business Central customer. If neither the number nor the email matches an existing Business Central customer, the Add collection creates a new record.
Supported Child Collections
None. The customer's primary billing address values are written directly onto the customer record in Business Central from the iPaaS.com customer's primary billing address; there is no separate address child collection in this direction.
System Caveats
Microsoft Dynamics 365 Business Central Caveats
Posting groups, payment terms, and tax area must already exist: the Customer Posting Group, Gen. Bus. Posting Group, Payment Terms Code, and Tax Area Code values are validated by Business Central against records that must already exist in your company. They ship with example values that will not match your company. Replace each with a value configured in your Business Central setup before the first transfer, or the transfer fails when Business Central rejects the unknown value. See the Mappings section for the per-field replacement guidance.
Customer number length: Business Central limits the customer number to 20 characters. On Add, a longer iPaaS.com customer number is truncated to fit. On Update, the existing Business Central customer number is preserved and must be present and within that limit, or the update is rejected.
Country/region code: the country value must be 10 characters or fewer and match an existing country/region code in your Business Central company, or Business Central rejects the record.
Update target must exist: the Update collection updates an existing Business Central customer. When the customer cannot be found in Business Central, the update is rejected. New customers are created through the Add collection.
Single price group from categories: iPaaS.com supports multiple category assignments whereas Business Central allows only one. The customer price group is set from the first category in the list, and only when that category resolves to a price group configured in Business Central.
Person-type customer: customer records sent through this family are always created as a person-type customer in Business Central.
Name composition: the customer name is composed from the iPaaS.com first and last name. If a different name should appear (for example, a company name), adjust the Name mapping.
iPaaS.com Caveats
Primary billing address required for address fields: the address, city, county, post code, country, and phone fields populate only when the iPaaS.com customer has an address flagged as the primary billing address. Without one, those fields are left unset on a new Business Central customer (Add) or left unchanged on an existing one (Update).
Customer number is the routing key: the customer number must be present for the transfer to link correctly. It is saved as the external ID that routes all subsequent transfers for that customer.
Email must be present and unique: the customer email must be present and unique. It is also used as the secondary key for duplicate matching.
Custom fields must exist first: a mapped custom field's name must already exist as a field in your Business Central environment. If it does not, Business Central rejects the entire customer record for that transfer — none of the record's fields are stored, including standard fields such as email and address, not just the unmatched custom field. Remove or correct any custom-field mapping whose name does not exist in your environment.
Setup Requirements
Microsoft Dynamics 365 Business Central Configuration
Enable Web Services for Customers, Customer Card, Contact Card, and Customer Price Group so the integration can read and write customer records.
Configure valid codes that the mappings reference: Tax Area Code, Gen. Bus. Posting Group, Customer Posting Group, Payment Terms Code, and any Customer Price Group codes the customer's categories resolve to.
Configure country/region codes that match the iPaaS.com country values, each 10 characters or fewer.
If custom fields are mapped, customize the relevant Web Service to accept them.
Authentication uses Business Central API credentials; ensure credentials are stored securely in the iPaaS.com credential manager.
For the full installation walkthrough, see the Installation Instructions.
iPaaS.com Configuration
In the subscription configuration's Outbound Data Flows section, subscribe to the customer create and update events to enable automatic transfers.
Ensure customer records carry a valid customer number, name, email, and primary billing address data.
Configure categories if customer price group mapping is required.
Create custom fields whose names match the Business Central field names for any custom-field mappings in use.
Subscribers or their MiSP can contact iPaaS.com Support for assistance configuring Business Central Web Services.
Integration Flow
A customer is created or updated in iPaaS.com, and the corresponding outbound trigger fires (or a subscriber runs a Manual Sync using the iPaaS.com customer record ID).
The integration determines whether the iPaaS.com customer is already linked to a Business Central customer. If it is not linked, the integration checks Business Central for a match — first by customer number, then by email — and establishes an external-ID link when a match is found.
iPaaS.com authenticates with Business Central.
For an unlinked customer with no match, the Add collection creates a new Business Central customer: it sets the customer number (truncated to the 20-character limit), composes the name from first and last name, writes the email, primary billing address fields, resolved customer price group, and the posting groups, payment terms, and tax area. The record is created as a person-type customer.
For a linked customer, the Update collection refreshes the existing Business Central customer: it preserves the existing customer number and rewrites the name, email, address fields, resolved price group, and the posting groups, payment terms, and tax area.
Transfer status and any errors are recorded in the iPaaS.com Dashboard under Integration Monitoring and the Error Logs.
Mappings
Add Dynamics 365 Business Central Customer FROM iPaaS.com
iPaaS.com data type: Customer
This collection creates a new Business Central customer from iPaaS.com. It has no mapping filter, so every customer record sent through it is processed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Microsoft Dynamics 365 Business Central) | Description |
Dynamic Formula |
| No | Required. Sets the Business Central customer number from the iPaaS.com customer number. It is the key used to match, link, and later update the customer, and is saved as the external ID. Business Central limits the customer number to 20 characters, so a longer iPaaS.com customer number is truncated to fit. |
Dynamic Formula |
| Name | Required. Composes the customer name from the iPaaS.com first and last name; Business Central requires a customer name. To show a different value (for example, a company name), adjust this mapping. |
Field |
| Required. The customer email address, which must be present and unique. | |
Dynamic Formula |
| Address | Recommended. The address line from the customer's primary billing address in iPaaS.com. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| City | Recommended. The city from the customer's primary billing address. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| County | Recommended. The county from the region on the customer's primary billing address. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| PostCode | Recommended. The post code from the customer's primary billing address. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| CountryRegionCode | Recommended. The country/region code from the country on the customer's primary billing address. The code must be 10 characters or fewer and match an existing country/region code in your Business Central company. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| PhoneNo | Recommended. The phone number from the customer's primary billing address. Left unset if the customer has no primary billing address. |
Dynamic Formula |
| CustomerPriceGroup | Recommended. Resolves the iPaaS.com customer's categories to the matching Business Central customer price group code. Set only when the categories resolve to a price group already configured in Business Central. iPaaS.com supports multiple category assignments whereas Business Central allows only one, so the first category in the list is used. By default the price group is cleared when the matching category is removed in iPaaS.com; to keep the existing value when no category code is returned, adjust the formula. |
Static |
| CustomerPostingGroup | Required. Sets the customer posting group, which controls how the customer's transactions post to the general ledger. Pre-install prerequisite — the first transfer fails without it. |
Static |
| GenBusPostingGroup | Required. Sets the general business posting group, which controls how the customer's transactions post. Pre-install prerequisite — the first transfer fails without it. |
Static |
| PaymentTermsCode | Required. Sets the payment terms for the customer. Pre-install prerequisite — the first transfer fails without it. |
Static |
| TaxAreaCode | Required. Sets the tax area for the customer. Pre-install prerequisite — the first transfer fails without it. |
Business Central Gen. Business Posting Groups — confirm the value used by the GenBusPostingGroup mapping exists in your company, or create one and use its code:
Business Central Tax Areas — confirm the value used by the TaxAreaCode mapping exists in your company, or create one and use its code:
Update Dynamics 365 Business Central Customer FROM iPaaS.com
iPaaS.com data type: Customer
This collection updates an existing Business Central customer from iPaaS.com. It has no mapping filter, so every customer record sent through it is processed. The posting groups, payment terms, and tax area are written on every update.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Microsoft Dynamics 365 Business Central) | Description |
Dynamic Formula |
| No | Required. Keeps the existing Business Central customer number on update instead of replacing it with a value from iPaaS.com, so the update is routed to the correct existing customer. The customer number is limited to 20 characters and must be present, or the update is rejected. |
Dynamic Formula |
| Name | Required. Composes the customer name from the iPaaS.com first and last name; Business Central requires a customer name. To show a different value (for example, a company name), adjust this mapping. |
Field |
| Required. The customer email address, which must be present and unique. | |
Dynamic Formula |
| Address | Recommended. The address line from the customer's primary billing address in iPaaS.com. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| City | Recommended. The city from the customer's primary billing address. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| County | Recommended. The county from the region on the customer's primary billing address. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| PostCode | Recommended. The post code from the customer's primary billing address. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| CountryRegionCode | Recommended. The country/region code from the country on the customer's primary billing address. The code must be 10 characters or fewer and match an existing country/region code in your Business Central company. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| PhoneNo | Recommended. The phone number from the customer's primary billing address. Left unchanged if the customer has no primary billing address. |
Dynamic Formula |
| CustomerPriceGroup | Recommended. Resolves the iPaaS.com customer's categories to the matching Business Central customer price group code. Set only when the categories resolve to a price group already configured in Business Central. iPaaS.com supports multiple category assignments whereas Business Central allows only one, so the first category in the list is used. By default the price group is cleared when the matching category is removed in iPaaS.com; to keep the existing value when no category code is returned, use the alternate form shown in the collection's mapping note. |
Static |
| CustomerPostingGroup | Required. Sets the customer posting group, written on every update. Pre-install prerequisite — the update fails without it. |
Static |
| GenBusPostingGroup | Required. Sets the general business posting group, written on every update. Pre-install prerequisite — the update fails without it. |
Static |
| PaymentTermsCode | Required. Sets the payment terms, written on every update. Pre-install prerequisite — the update fails without it. |
Static |
| TaxAreaCode | Required. Sets the tax area, written on every update. Pre-install prerequisite — the update fails without it. |
Business Central Gen. Business Posting Groups — confirm the value used by the GenBusPostingGroup mapping exists in your company, or create one and use its code:
Business Central Tax Areas — confirm the value used by the TaxAreaCode mapping exists in your company, or create one and use its code:
Error Handling
For the complete catalog of error messages this integration can produce, see the Error Messages article. The conditions most relevant to the customer transfer are:
Missing customer number: The Add collection requires a customer number; without one the transfer is rejected. Resolution: ensure each iPaaS.com customer carries a customer number before transferring.
Customer number too long: A customer number longer than 20 characters is truncated on Add, but if a value exceeding the limit reaches the update path the transfer is rejected. Resolution: keep customer numbers within the 20-character Business Central limit.
Missing or invalid email: The customer email must be present and valid (for example,
user@example.com). A missing or malformed email causes the transfer to fail. Resolution: ensure the email field is present and well-formed in iPaaS.com before syncing.Invalid country code: A country/region code that is longer than 10 characters or does not match an existing Business Central country/region code is rejected. Resolution: ensure the country code is 10 characters or fewer and matches a configured Business Central country/region code.
Unknown posting group, payment terms, or tax area: Business Central rejects the record when the Customer Posting Group, Gen. Bus. Posting Group, Payment Terms Code, or Tax Area Code value does not match an existing record in your company. Resolution: replace the shipped example values with codes configured in your Business Central setup before the first transfer.
Update target not found: The Update collection rejects the transfer when the customer does not already exist in Business Central. Resolution: create the customer through the Add collection first, then run the update.
Errors and transfer status for every customer transfer are recorded in the iPaaS.com Dashboard under Integration Monitoring and the Error Logs.
Validation Rules
Customer number: required on Add and used as the match/link key; truncated to the 20-character Business Central limit. Preserved on Update and must be present.
Email: required, must be present and unique, and is used as the secondary duplicate-matching key.
Country/region code: must be 10 characters or fewer and match an existing Business Central country/region code.
Posting groups, payment terms, tax area: must match records that already exist in the Business Central company, or the transfer fails.
Price group: set only when the customer's first category resolves to a price group configured in Business Central.
Update target: the Update collection requires the customer to already exist in Business Central.
Testing and Validation
Test Scenarios
Valid customer create. Send a new iPaaS.com customer with a customer number, name, email, and primary billing address, with the posting groups, payment terms, and tax area set to codes that exist in Business Central. Confirm a new person-type customer is created in Business Central with the expected field values.
Valid customer update. Send an update for a customer already linked to a Business Central record. Confirm the existing Business Central customer is updated with the mapped fields and that its customer number is preserved.
Duplicate matching by number. Send a customer whose customer number matches an existing Business Central customer that is not yet linked. Confirm the records are linked automatically rather than creating a duplicate.
Duplicate matching by email. Send a customer whose number does not match but whose email matches an existing Business Central customer. Confirm the records are linked by email.
Missing email (failure case). Attempt to transfer a customer without an email address. Confirm the transfer fails with an error logged.
Invalid country code (failure case). Attempt to transfer a customer with a country code that is too long or not configured in Business Central. Confirm the transfer fails with the country-code error.
Unknown posting group (failure case). Transfer a customer while the shipped example posting group, payment terms, or tax area values are still in place and do not exist in your company. Confirm the transfer fails, then replace the values with existing codes and confirm the transfer succeeds.
Update target missing (failure case). Attempt an update for a customer that does not exist in Business Central. Confirm the update is rejected.
Validation Checklist
The iPaaS.com customer carries a customer number that is present, unique, and 20 characters or fewer.
The customer email is present, valid, and unique.
The country/region code is 10 characters or fewer and exists in Business Central.
The Customer Posting Group, Gen. Bus. Posting Group, Payment Terms Code, and Tax Area Code values have been replaced with codes that exist in your Business Central company.
Categories are configured in iPaaS.com if customer price group mapping is required, and the resolved price group exists in Business Central.
Web Services are enabled in Business Central for Customers, Customer Card, Contact Card, and Customer Price Group.
Custom fields exist with matching names for every custom-field mapping in use, and the relevant Web Service is customized to accept them.
The customer outbound triggers are subscribed in Outbound Data Flows if automatic transfers are wanted.
Additional Notes
The Add and Update collections are decided by whether the iPaaS.com customer is already linked to a Business Central record, not by which event fired. The Add collection establishes the link and creates the record; the Update collection refreshes an already-linked record while preserving its Business Central customer number.
At the time this documentation was written, customer records sent through this family are always created as a person-type customer in Business Central.
At the time this documentation was written, the Update collection writes the posting groups, payment terms, and tax area on every update from the values set in these mappings. To keep different values per customer, adjust the mappings or maintain those fields in Business Central directly.
Outbound delete is not supported; deleting a customer in iPaaS.com does not remove the Business Central customer.
Related Documents
Connections and Settings (pending publication)
Known Limitations (pending publication)