Skip to main content

Microsoft Dynamics 365 Business Central Contact TO iPaaS Mapping Documentation

Field-by-field mapping reference for syncing contacts from Microsoft Dynamics 365 Business Central to iPaaS.com, including the contact filter and address child.

Contents

Summary

Microsoft Dynamics 365 Business Central contacts can be transferred to iPaaS.com through the integration's polling schedule or through Manual Sync. Each Business Central contact is captured into iPaaS.com as a Customer with a contact record type — the integration models contacts through the Customer model and distinguishes a contact from a customer by a contact marker on its identifier. The parent collection records the contact's header detail (number, email address, first and last name, company, and several classification values held as custom fields), and a single child collection captures the contact's address within the same transfer.

This family captures the contact side of a Business Central person record. A mapping filter routes only person records classified as contacts through this collection; person records classified as customers are handled by the Add/Update Dynamics 365 Business Central Customer TO iPaaS.com collection, and company records are handled by the Add/Update Dynamics 365 Business Central Company TO iPaaS.com collection. The contact's first, middle, and last name, its web user role, and its active web user status are captured as extended values on the iPaaS.com customer so the contact can be linked and kept in sync across the subscriber's connected systems.

ID Format

Manual Sync ID Format

When transferring a Business Central contact from the iPaaS.com Manual Sync page, enter the contact identifier followed by a contact marker. Either the contact's internal record ID or the contact number resolves the record:

{{Id}}|contact
{{customer_no}}|contact

The contact marker distinguishes a contact record from a customer record that shares the same number.

  • Example (internal ID): 3f2504e0-4f89-11d3-9a0c-0305e82c3301|contact

  • Example (contact number): 44552|contact

External ID Format

After a successful transfer, iPaaS.com saves the Business Central contact number as the external ID on a dedicated external-ID record. This external ID links every subsequent transfer of the same contact to the same iPaaS.com customer rather than creating a duplicate. Keep the contact number unique so repeated transfers update the existing customer.

Deleted Record Support

Outbound delete is not supported for the contact customer or for its address child record. This family captures and updates contacts into iPaaS.com; it does not remove iPaaS.com records. Delete mappings are not included in the default templates, and deleting a contact in Business Central does not remove the corresponding iPaaS.com customer or address. Subscribers who need to retire an iPaaS.com customer should manage that on the iPaaS.com side.

Custom Field Support

Custom fields are supported on the parent contact customer. This collection captures four contact classification values — Customer Type, Record Type, Role, and Active — into iPaaS.com custom fields; these are listed in the parent field mapping table below. The address child collection does not support custom fields.

To capture a Business Central contact value that is not already in the standard mapping list:

  1. In Business Central, customize the relevant Web Service so the value is exposed in the contact response. Subscribers or their MiSP can contact iPaaS.com Support for assistance customizing Business Central Web Services.

  2. In iPaaS.com, create a custom field on the subscription that matches the field name and data type.

  3. Map the new iPaaS.com custom field to the Business Central value on the parent contact 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. The Customer Type, Record Type, Role, and Active custom fields must be created in iPaaS.com before contacts are captured, or those values are not stored.

Mapping Collection Status

  • Status: Enabled

  • Trigger Events: Customer Create, Customer Update, Customer Poll. Contacts share the customer 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 contacts — and a Manual Sync can be run at any time. Whether a detected contact creates a new iPaaS.com customer or updates an existing one depends on the external-ID link (the saved contact number), not on the change type — see ID Format.

Duplicate or Conflicting Mappings

Other collections operate on the same Business Central person source and may write the same kinds of records:

  • Add/Update Dynamics 365 Business Central Customer TO iPaaS.com captures the same Business Central person source, filtered to records classified as customers rather than contacts. Both collections write customer records to iPaaS.com.

  • Add Dynamics 365 Business Central Customer FROM iPaaS.com and Update Dynamics 365 Business Central Customer FROM iPaaS.com write in the opposite direction (from iPaaS.com into Business Central).

Before enabling these collections together, review their filters and Add/Update settings and decide which system is the source of truth for contact data, so the same record is not written in conflicting directions.

Collision Handling

This integration does not provide configurable collision-handling methods for the contact collections. There is no subscriber-selectable conflict-resolution option (such as Error, Remap and Link, or Update and No Link) on these collections. A contact is matched to its iPaaS.com customer by the saved external ID (the contact number), and, when no external ID exists yet, by email — see Duplicate Matching. Keep the contact number and email unique so repeated transfers update the same customer rather than creating a duplicate.

Duplicate Matching

To avoid creating duplicate customers in iPaaS.com, when a contact has no external-ID link yet the integration looks up an existing iPaaS.com customer by email address before recording a new one. If a match is found, the integration links the contact to that existing customer; if the link cannot be established, the transfer stops with an error and the contact may be recorded as a duplicate. Because of this, email addresses must be present and unique. The address child collection does not perform a separate lookup; instead its PreventDuplicate setting reuses the customer's existing address rather than adding a second copy when the same address is transferred again. Neither collection auto-transfers a related record as a prerequisite.

Supported Child Collections

The parent Add/Update Dynamics 365 Business Central Contact TO iPaaS.com collection captures the contact header. One child collection captures the contact's address within the same dispatch:

Child Collection

Purpose

Add/Update Dynamics 365 Business Central Contact Address TO iPaaS.com

Captures the contact's address, read from the parent contact record, on the matching iPaaS.com customer.

The address child collection captures its record as part of the parent contact's transfer; it is not synced on its own.

System Caveats

Microsoft Dynamics 365 Business Central Caveats

  • Source classification: only Business Central person records classified as contacts are captured by this family. A record's type and record-type classification in Business Central determine whether it flows through this collection, the customer collection, or the company collection. A record passes this collection's filter only when its type is Person and its record type is Contact.

  • Contact identifier: a contact is identified by its number with a contact marker so it is not confused with a customer record that shares the same number.

  • Address read from the parent: the contact's address values are read from the parent Business Central contact record and reflect the contact's address as held in Business Central. The integration captures a single contact address per contact transfer through the child collection.

iPaaS.com Caveats

  • Contact number is the routing key: the contact 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 contact.

  • Email matching and uniqueness: before recording a new customer, iPaaS.com checks for an existing customer by email address to avoid duplicates. Customer email addresses must be present and unique in iPaaS.com; duplicate email addresses can cause sync failures.

  • Captured as a customer: the contact is recorded as an iPaaS.com customer with a contact record type; its address is recorded on that customer rather than as an independent record.

  • Custom fields must exist first: the iPaaS.com custom fields for Customer Type, Record Type, Role, and Active must be created in iPaaS.com before contacts are captured, or those values are not stored.

Setup Requirements

Microsoft Dynamics 365 Business Central Configuration

  • Enable Web Services for Customers, Customer Card, and Contact Card so the integration can read contact records and their addresses.

  • Customize the Contact Card Web Service to expose the contact's First Name and Last Name (or a Company Name). A contact is captured into iPaaS.com only when at least one of First Name, Last Name, or Company Name is present; until one is exposed, Person contacts cannot be created in iPaaS.com.

  • If custom fields are mapped, 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

  • Create the custom fields for Customer Type, Record Type, Role, and Active on the iPaaS.com subscription so the contact's extended values can be stored.

  • Ensure each Business Central contact carries a present, unique email address before transferring.

Subscribers or their MiSP can contact iPaaS.com Support for assistance configuring Business Central Web Services.

Integration Flow

  1. A contact is created or updated in Business Central.

  2. The integration detects the contact on its polling schedule, or a subscriber triggers a Manual Sync using the {{Id}}|contact or {{customer_no}}|contact format.

  3. The parent mapping filter confirms the record is a person classified as a contact; person records classified as customers and company records are skipped.

  4. iPaaS.com authenticates with Business Central using OAuth 2.0 and reads the contact.

  5. The parent collection records the contact header: customer number, email address, first and last name, company, and the Customer Type, Record Type, Role, and Active custom field values.

  6. If the contact has no external-ID link yet, the integration looks up an existing iPaaS.com customer by email and links to it when a match is found, so an existing customer is not duplicated.

  7. The address child collection records the contact's address — address lines, city, region, country, postal code, and phone number — read from the parent contact record, and prevents a duplicate address on the customer.

  8. The iPaaS.com customer is created on the first transfer or updated on subsequent transfers, matched by the saved external ID (the contact number).

  9. 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 Contact TO iPaaS.com (Parent)

iPaaS.com data type: Customer

Mapping Filter

Type == "Person" && RecordType == "Contact"

Filter Description. Only Business Central records whose Type is Person and whose RecordType is Contact pass this filter. Person records classified as customers, and company records, are rejected here and are handled by the Add/Update Dynamics 365 Business Central Customer TO iPaaS.com and Add/Update Dynamics 365 Business Central Company TO iPaaS.com collections respectively. This ensures only contacts are captured as contact customers.

This collection captures the contact header and is the parent of the address child collection below.

Mapping Type

Source Field (Microsoft Dynamics 365 Business Central)

Destination Field (iPaaS.com)

Description

Field

No

CustomerNumber

Required. The iPaaS.com customer number, taken from the Business Central contact number. It is saved as the external ID and is the key used to match the contact to its iPaaS.com customer on every transfer. Keep the contact number unique.

Field

EMail

EmailAddress

Required. The contact's email address. It must be present and unique, and it is used to match the contact to an existing iPaaS.com customer when no external-ID link exists yet.

Field

FirstName_Contact

FirstName

Required. The contact's first name on the iPaaS.com customer record.

Field

LastName_Contact

LastName

Recommended. The contact's last name. Left unset when the Business Central contact has no last name.

Field

CompanyName_Contact

Company

Recommended. The contact's company name from Business Central. Left unset when the Business Central contact has no company name.

Field

Type

Customer Type (Custom Field)

Optional. The Business Central record type classification, stored on the iPaaS.com Customer Type custom field. The custom field must exist on the subscription; left unset when the source value is absent.

Field

RecordType

Record Type (Custom Field)

Optional. The Business Central record type, stored on the iPaaS.com Record Type custom field, identifying the captured record as a contact. The custom field must exist on the subscription; left unset when the source value is absent.

Field

WebUserRole_Contact

Role (Custom Field)

Optional. The contact's web user role from Business Central, stored on the iPaaS.com Role custom field. The custom field must exist on the subscription; left unset when the source value is absent.

Dynamic Formula

GetValueFromCustomField(AdditionalProperties, "Active_Web_User");

Active (Custom Field)

Optional. The contact's active web user status, read by name from the contact's extended Business Central properties and stored on the iPaaS.com Active custom field. A value is stored only when the Business Central contact carries that property, and the custom field must exist on the subscription.

Add/Update Dynamics 365 Business Central Contact Address TO iPaaS.com (Child)

iPaaS.com data type: Customer Address

This collection is a parent-only child of the Contact parent. It records the contact's address on the matching iPaaS.com customer, reading each value from the parent contact record. It has no independent transfer — the address is captured whenever its parent contact is captured.

Mapping Filter

if(Parent != null && !string.IsNullOrEmpty(Parent.Address) && SourceTypeName == "ParentOnly")
    return true;
return false;

Filter Description. The address is captured only when the parent contact exists, the parent contact has a street address, and the source is the parent-only address built from that contact. A contact with no street address does not produce an address record, and the collection does not run for other source types. Because the address is read from the parent contact, additional address collections can be built the same way to represent different contact addresses.

Mapping Type

Source Field (Microsoft Dynamics 365 Business Central)

Destination Field (iPaaS.com)

Description

Dynamic Formula

Parent.Address

Address1

Recommended. The first line of the contact's street address. Left unset when the parent contact has no address line.

Dynamic Formula

Parent.Address2

Address2

Recommended. The second line of the contact's street address. Left unset when the parent contact has no second address line.

Dynamic Formula

Parent.City

City

Recommended. The contact's city. Left unset when the parent contact has no city.

Dynamic Formula

Parent.County

Region

Recommended. The contact's county, mapped to the iPaaS.com region. Left unset when the parent contact has no county.

Dynamic Formula

Parent.CountryRegionCode

Country

Recommended. The contact's 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.

Dynamic Formula

Parent.PostCode

PostalCode

Recommended. The contact's postal code. Left unset when the parent contact has no post code.

Dynamic Formula

Parent.PhoneNo

PhoneNumber

Recommended. The contact's phone number. Left unset when the parent contact has no phone number.

Static

true

PreventDuplicate

Required (designed constant). Prevents a duplicate address from being added to the iPaaS.com customer. When the same contact address is transferred again, the existing iPaaS.com address is reused instead of adding a second copy. This is a designed constant and should remain set to true.

Error Handling

For the complete catalog of error messages this integration can produce, see the Error Messages article. The errors most relevant to the contact transfer are:

  • Missing or duplicate email: The contact's email address is used to match the contact to an existing iPaaS.com customer when no external-ID link exists, and a present, unique email is required for the customer. A contact with no email cannot be matched, and a duplicate email can cause a sync failure. Resolution: ensure each Business Central contact carries a present, unique email address before transferring.

  • Unable to link an existing customer by email: When the integration finds an existing iPaaS.com customer by email but cannot establish the external-ID link, the transfer stops and the contact may be recorded as a duplicate. Resolution: confirm the matching iPaaS.com customer's email and external IDs, then re-transfer the contact.

  • Missing or duplicate contact number: The contact number is saved as the external ID and is the key that links each transfer to its iPaaS.com customer. A contact with no number cannot be linked, and a non-unique contact number can cause a transfer to update an unintended customer. Resolution: ensure each Business Central contact carries a unique contact number before transferring.

Errors and transfer status for every contact transfer are recorded in the iPaaS.com Dashboard under Integration Monitoring and the Error Logs.

Validation Rules

  • Contact qualification: only person records whose record type is contact are processed; person records classified as customers and company records are skipped by the parent filter.

  • Email presence and uniqueness: the email address must be present and unique; it is the fallback match key when no external-ID link exists.

  • Address condition: the address child collection captures a record only when the parent contact exists and has a street address, and the source is the parent-only address.

  • Custom field existence: the Customer Type, Record Type, Role, and Active custom fields must exist on the iPaaS.com subscription for their values to be stored.

Testing and Validation

Test Scenarios

  1. Valid contact transfer. Transfer a Business Central contact (Type Person, RecordType Contact) with a number, email, first and last name, company, and an address (by polling or Manual Sync). Confirm the iPaaS.com customer is created with the correct header, custom field values, and address.

  2. Filter routing. Transfer a person record classified as a customer and a company record. Confirm neither is captured by the contact collection and that each is handled by its own collection.

  3. Email duplicate matching. Transfer a contact whose email matches an existing iPaaS.com customer that has no external-ID link to this contact. Confirm the contact links to the existing customer instead of creating a duplicate.

  4. Missing email. Transfer a contact with no email address. Confirm the transfer fails and the error is logged.

  5. ID format. From the Manual Sync page, transfer a specific contact using {{Id}}|contact and {{customer_no}}|contact. Confirm the correct contact is captured.

  6. Parent-child transfer. Transfer a contact that has an address. Confirm the address is captured under the same iPaaS.com customer in a single dispatch.

  7. Repeat transfer / external ID. Transfer the same contact twice. Confirm the second transfer updates the existing iPaaS.com customer (matched by contact number) rather than creating a duplicate, and that the address is reused rather than duplicated.

Validation Checklist

  • The Business Central contact is Type Person and RecordType Contact.

  • The contact carries a unique, non-empty contact number and a present, unique email address.

  • All required Web Services are enabled in Business Central (Customers, Customer Card, Contact Card).

  • Custom fields exist on the iPaaS.com subscription for Customer Type, Record Type, Role, and Active.

  • The contact's address values are populated on the Business Central contact record if address capture is in use.

Additional Notes

  • Contacts are captured into iPaaS.com as customers with a contact record type; the integration models contacts through the Customer model and distinguishes them by a contact marker on the identifier.

  • The address child collection captures a single contact address per contact transfer, read from the parent contact record, and is provided as a starting point for the initial release that subscribers or their MiSP adjust to their address use case.

  • Outbound delete is not supported for the contact customer or its address; deletions in Business Central do not propagate to iPaaS.com.

Related Documents

Related Articles
Microsoft Dynamics 365 Business Central Company TO iPaaS Mapping Documentation
Microsoft Dynamics 365 Business Central Customer TO iPaaS Mapping Documentation
Microsoft Dynamics 365 Business Central Location TO iPaaS Mapping Documentation
Microsoft Dynamics 365 Business Central Product TO iPaaS Mapping Documentation
Microsoft Dynamics 365 Business Central Product Category TO iPaaS Mapping Documentation
Did this answer your question?