OroCommerce Customer From iPaaS.com Mapping Documentation
This integration transfers iPaaS.com Company records to OroCommerce as B2B Customers, along with their associated addresses, in a single operation. The flow is triggered when a Company is created or updated in iPaaS.com and runs in the From iPaaS.com direction. Its purpose is to keep customer master data, customer group (category) assignments, and address records consistent between iPaaS.com and OroCommerce.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration. The detailed field-level requirements are covered under System Caveats and Setup Requirements below.
iPaaS.com Requirements
Access to iPaaS.com with permissions to create and update Customers and Addresses.
OroCommerce Requirements
A valid OroCommerce account with administrator access.
ID Format
When manually transferring a Customer Company from iPaaS.com, enter the valid iPaaS.com Company (internal ID) into the input field on the iPaaS.com manual sync page.
Example: 145146
External ID Format
The OroCommerce Customer ID is saved as the external ID on the parent record.
Example (parent Customer): 25
For the child address collection, the OroCommerce customer address external ID is saved as the address ID, a pipe separator, and the parent customer ID, in that order.
Example (child Customer Address): 21|25 — where 21 is the OroCommerce customer address ID and 25 is the parent customer ID.
Custom Field Support
This integration supports custom fields on both the parent (Customer) and the child (Customer Address) collections. Custom field values are read from the iPaaS.com record with the GetCustomFieldValue pattern and written to the matching custom field in OroCommerce. For the parent collection, the OroCommerce custom field module must be Customer. For the child collection, the module must be Customer Address.
Creating Custom Fields in OroCommerce
In OroCommerce, click System > Entities > Entity Management.
Locate and select the module (entity) where you want to add the custom field (Customer for the parent, Customer Address for the child).
Click Create Field and create a custom field.
Enter a unique Field Name and select a Storage Type.
Storage Type Notes
Table Column — A schema update is required (mandatory). The custom field is not available until the schema update completes. After creating a Table Column field, a red Update Schema button appears on the page; click Update Schema to apply the changes. Contact your OroCommerce administrator before changing an entity schema to prevent unexpected service downtime.
Serialized Field — No schema update is required; the custom field is added to the schema automatically. This is the recommended storage type, as it avoids manual schema updates.
Set the field type as "string". Other simple data types such as "Number" or "Boolean" are supported when using compatible mappings.
Click Continue.
Edit the field information on the next page if necessary, then click Save and Close.
After creating the field, click Update Schema (if required by the Storage Type).
Creating Custom Fields in iPaaS.com
In iPaaS.com, click Data Management > Custom Fields > Add Custom Field.
Enter a unique Field Name (this name must exactly match the OroCommerce custom field name created above), select the Module (Customer for the parent, Customer Address for the child), and set the Data Type to String.
Populating the Description field is recommended but not required.
Click Save.
After the custom field is created, set its value in iPaaS.com by navigating to the relevant module (for example, Customer Companies), clicking Edit, then clicking Add under the Custom Fields section. Select an existing custom field or create a new one, enter the value in the Value field, and click Apply.
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Both the parent and child collections are enabled and carry no record filter, so every created or updated Company is processed.
Duplicate or Conflicting Mappings
This mapping applies only to Customers transferred from iPaaS.com. To prevent customer data from being overwritten, ensure no other mapping collection targets the same OroCommerce Customer entity. Related collections in the customer family that operate on different entities include OroCommerce Customer User FROM iPaaS.com (which creates contact users rather than the customer company) and OroCommerce Customer Category FROM iPaaS.com (which creates the customer groups referenced by this flow).
Supported Child Collections
This parent mapping collection supports one child collection.
Parent: Add/Update OroCommerce Customer FROM iPaaS.com — creates or updates the OroCommerce B2B customer (company) record, including its customer group assignment.
Child: Add/Update OroCommerce Customer Address FROM iPaaS.com — creates or updates the customer's billing and shipping addresses as part of the same operation.
System Caveats
OroCommerce Caveats
Parent collection (Customer):
Name is required to create the customer in OroCommerce.
Customer Type must be the literal value "customers" (case-sensitive).
Categories: If category assignments from iPaaS.com are transferred, the customer group identifiers Relationships_Group_Id and Relationships_Group_Type must be mapped, and the referenced categories must be transferred to OroCommerce before the company is transferred. Relationships_Group_Type must be set to "customergroups".
Child collection (Customer Address):
Required fields are Country, Region, ZipCode (PostalCode), Street, and City.
Type must be the literal value "customeraddresses" (case-sensitive). The country type must be "countries" and the region type must be "regions".
Country and Region mapping: The country or region name must already exist in OroCommerce to resolve a valid country or region ID.
iPaaS.com Caveats
The Name field is required. Without it, the customer company will not be created.
The Id mapping is required in the customer address update flow so that the existing OroCommerce address is updated rather than duplicated.
Setup Requirements
OroCommerce uses OAuth 2.0 (Authorization Code) authentication to generate an access token, which authorizes all OroCommerce API requests during transfer operations. Store these credentials securely within the iPaaS.com credential manager. Any OroCommerce customer groups, countries, and regions referenced by the transferred data must exist in OroCommerce before the customer is synced.
Integration Flow
The integration processes iPaaS.com customer companies as follows:
A Company is created or updated in iPaaS.com, triggering the integration.
Customer details are mapped and validated against OroCommerce requirements.
If categories are assigned, the integration verifies that the corresponding customer groups have been transferred to OroCommerce.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
The customer record is created or updated in OroCommerce.
Associated addresses are processed through the child collection.
The OroCommerce Customer ID is saved as the external ID in iPaaS.com, and the transfer status and any errors are logged.
Mappings
Parent: Add/Update OroCommerce Customer FROM iPaaS.com
This mapping collection creates or updates the OroCommerce B2B customer (company) record from iPaaS.com Company data. It resolves the customer group assignment, sets the organization and owner relationships, and applies the required record type. The collection has no record filter, so every created or updated Company is processed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (OroCommerce) | Description |
Field | Name | Attributes_Name | (Required) Maps the customer name to OroCommerce. |
Static | customers | Type | (Required) Specifies the record type. OroCommerce expects the literal value "customers" (case-sensitive). |
Dynamic Formula | return await ConvertiPaaSCategoriesToOroCommerceCustomerGroupAsync(Categories); | Relationships_Group_Id | (Recommended) Converts iPaaS.com customer categories into an OroCommerce Customer Group ID. The function first looks for an external ID mapping in iPaaS.com using the category ID. If none exists, it looks up the customer group in OroCommerce by category name and returns the last matched OroCommerce Customer Group ID. |
Static | customergroups | Relationships_Group_Type | (Required when a group is mapped) Specifies the customer group relationship type. |
Static | 1 | Relationships_Organization_Id | (Required) Sets the OroCommerce organization ID that owns the customer. Placeholder value — replace during implementation: "1" is the default organization ID; substitute the organization ID used by your target OroCommerce instance. |
Static | organizations | Relationships_Organization_Type | (Required) Specifies the organization relationship type. |
Static | 1 | Relationships_Owner_Id | (Required) Sets the OroCommerce business unit (owner) ID for the customer. Placeholder value — replace during implementation: "1" is the default business unit ID; substitute the owner ID used by your target OroCommerce instance. |
Static | users | Relationships_Owner_Type | (Required) Specifies the owner (user) relationship type. |
Dynamic Formula | var value = GetCustomFieldValue(CustomFields, "SimTest"); if (string.IsNullOrEmpty(value)){return null;} else {return value;} | SimTest | (Recommended) Reads the value of the "SimTest" custom field from the iPaaS.com record and writes it to the SimTest custom field on the OroCommerce customer. Returns null when the value is empty. Placeholder value — replace during implementation: "SimTest" is an example custom field; replace it with a custom field that exists on the Customer module in your target OroCommerce instance, or remove the mapping if not needed. |
Child: Add/Update OroCommerce Customer Address FROM iPaaS.com
This child mapping collection maps an iPaaS.com company address to an OroCommerce customer address. It resolves the country and region IDs, applies the required address record type, and, on updates, resolves the existing OroCommerce external ID so the correct address record is updated. The collection has no record filter, so every address on a processed Company is mapped.
Mapping Type | Source Field (iPaaS.com) | Destination Field (OroCommerce) | Description |
Field | Address1 | Attributes_Street | (Required) Maps the first address line from iPaaS.com to the OroCommerce customer address. |
Field | Address2 | Attributes_Street2 | (Recommended) Maps the second address line (suite, unit) from iPaaS.com to the OroCommerce customer address. |
Field | City | Attributes_City | (Required) Maps the city from iPaaS.com to the OroCommerce customer address. |
Field | PostalCode | Attributes_PostalCode | (Required) Maps the postal or ZIP code from iPaaS.com to the OroCommerce customer address. |
Field | PhoneNumber | Attributes_Phone | (Recommended) Maps the phone number from iPaaS.com to the OroCommerce customer address. |
Field | Company | Attributes_Organization | (Recommended) Maps the company name from iPaaS.com to the organization field of the OroCommerce customer address. |
Field | FirstName | Attributes_FirstName | (Recommended) Maps the contact first name from iPaaS.com to the OroCommerce customer address. |
Field | LastName | Attributes_LastName | (Recommended) Maps the contact last name from iPaaS.com to the OroCommerce customer address. |
Field | IsPrimaryBilling | IsPrimaryBilling | (Recommended) Maps whether this address is the customer's primary billing address. Provide this flag to mark the address as Default Billing in OroCommerce. |
Field | IsPrimaryShipping | IsPrimaryShipping | (Recommended) Maps whether this address is the customer's primary shipping address. Provide this flag to mark the address as Default Shipping in OroCommerce. |
Dynamic Formula | return await GetCountryIdByNameAsync(Country); | Relationships_Country_Id | (Required) Resolves the OroCommerce Country ID from the iPaaS.com country name; returns null if the name is empty or no match is found. The country must already exist in OroCommerce. |
Static | countries | Relationships_Country_Type | (Required when a country is mapped) Specifies the country relationship type. OroCommerce expects the literal resource type "countries". |
Dynamic Formula | return await GetRegionIdByNameAsync(Region); | Relationships_Region_Id | (Recommended) Resolves the OroCommerce Region ID from the iPaaS.com region name; returns null if the name is empty or no match is found. The region must already exist in OroCommerce. |
Static | regions | Relationships_Region_Type | (Required when a region is mapped) Specifies the region relationship type. OroCommerce expects the literal resource type "regions". |
Static | customeraddresses | Type | (Required) Sets the OroCommerce resource type for the record to "customeraddresses" (case-sensitive). |
Dynamic Formula | return await GetExternalIdAsync(Id, "Company Address", SpaceportSystemId); | Id | (Required for updates) Resolves the existing OroCommerce external ID for this address so that an update targets the correct record rather than creating a duplicate. |
Dynamic Formula | var value = GetCustomFieldValue(CustomFields, "LaneNo"); if (string.IsNullOrEmpty(value)){return null;} else {return value;} | LaneNo | (Recommended) Reads the value of the "LaneNo" custom field from the iPaaS.com record and writes it to the LaneNo custom field on the OroCommerce customer address. Returns null when the value is empty. Placeholder value — replace during implementation: "LaneNo" is an example custom field; replace it with a custom field that exists on the Customer Address module in your target OroCommerce instance, or remove the mapping if not needed. |
Error Handling
Required field is missing. OroCommerce rejected a customer create or update request because one or more required fields were not populated. Ensure all required fields are present: Name for customers; Street, City, PostalCode, and Country for addresses.
Country or Region not found. The country or region name provided does not exist in OroCommerce. Verify that the country and region names match the OroCommerce records exactly, or add the missing country or region to OroCommerce.
Customer group not found. The category assigned to the customer has not been transferred to OroCommerce. Transfer the corresponding category (customer group) to OroCommerce before syncing the customer.
OAuth 2.0 token generation failed. OroCommerce rejected the authentication request. Verify that the OAuth credentials are correctly configured in iPaaS.com.
Testing & Validation
Test Scenarios
Scenario 1 — Create a new customer. Create a new Customer Company in iPaaS.com with a Name and at least one address. Sync to OroCommerce and verify the Customer is created with all addresses. Confirm the OroCommerce Customer ID is saved as the external ID in iPaaS.com.
Scenario 2 — Update an existing customer. Update an existing Customer Company in iPaaS.com (for example, change the Name or an address field). Sync to OroCommerce and verify the changes are reflected without creating duplicate records.
Scenario 3 — Create a customer with a category (failure case). Create a Customer Company in iPaaS.com with an assigned category that has not yet been transferred to OroCommerce. Trigger the sync and verify the integration returns a customer group (category) not found error. Transfer the category first, then re-sync to confirm the customer is created successfully.
Scenario 4 — Missing required fields (failure case). Create a Customer Company in iPaaS.com without the Name field. Verify the integration returns an appropriate error and does not create an incomplete record in OroCommerce.
Scenario 5 — Invalid country or region (failure case). Create an address with a country or region name that does not exist in OroCommerce. Verify the integration returns an error and does not create an incomplete address record.
Validation Checklist
Customer (parent) requirements:
Customer Name is present and not empty.
Customer Type is set to "customers".
Relationships_Group_Type is set to "customergroups".
Relationships_Organization_Type is set to "organizations".
Relationships_Owner_Type is set to "users".
The organization ID and owner ID match the values used by your target OroCommerce instance.
Categories (customer groups) are synced before the customer, where applicable.
Customer Address (child) requirements:
External ID is present for update operations.
Type is set to "customeraddresses" (exact case).
Street (Address1) is present.
City is present.
PostalCode is present.
Country exists in OroCommerce.
Region exists in OroCommerce, where provided.
Additional Notes
Dynamic formulas must return valid references for all dependent entities (customer group, country, region).
Custom fields require the correct module assignment: Customer for the parent collection, Customer Address for the child collection.
Serialized Field is the recommended storage type for custom fields, as it avoids manual schema updates.
The external ID format for addresses includes the parent customer ID to maintain the relationship between the address and its customer.
Categories must be transferred to OroCommerce before any customer that references them.