This integration transfers iPaaS customer company records to OroCommerce as Customers. When a company is created or updated in iPaaS, the customer data syncs to OroCommerce along with associated addresses as a single operation.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
OroCommerce Requirements
A valid OroCommerce account with administrator access.
The Name field is required for creating a Customer in OroCommerce.
Customer Type must be set to
customers.If categories are assigned to the company in iPaaS, they must be transferred to OroCommerce before the customer is transferred. Map both Relationships_Group_Id and Relationships_Group_Type (set to
customergroups).For address records: Country, Region, ZipCode, and Street are required. Type must be set to
customeraddresses. Country and region names must exist in OroCommerce to retrieve valid IDs.
iPaaS.com Requirements
Access to iPaaS with permissions to create and update Customers and Addresses.
The Name field is required on each customer company record; without it, the record will not be created in iPaaS.
The Id mapping is required in the customer address update flow to update an address in OroCommerce.
OAuth 2.0 credentials must be correctly configured in iPaaS for OroCommerce API access.
ID Format
When manually transferring a customer company from iPaaS, enter the valid iPaaS customer company ID (internal ID) into the iPaaS input field on the manual sync page. For example, use: 145146.
External ID Format: Customer (Parent)
The OroCommerce Customer ID is saved as the External ID in iPaaS. For example: 25.
External ID Format: Customer Address (Child)
The OroCommerce Customer Address External ID is saved as the address ID concatenated with a pipe (|) and the parent customer ID. For example: 21|25 (where 21 is the customer address ID and 25 is the parent customer ID).
Custom Field Support
This integration supports custom fields for both the parent (Customer) and child collection (Customer Address).
Note: For parent collections, the custom field module must be Customer. For child collections, the custom field 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 or Customer Address).
Click Create Field and configure the following:
Field Name: Enter a unique name. The name must start with a letter and contain only letters, underscores, and numbers.
Storage Type: Select Serialized Field or Table Column.
Serialized Field: The custom field is added automatically and does not require a manual schema update. Recommended.
Table Column: Requires a schema update before the custom field becomes available. After creating the field, a red Update Schema button will appear. Click Update Schema to apply the changes. Contact your OroCommerce administrator before updating an entity schema to prevent unexpected service downtime.
Type: Set the field type to 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.
Creating Custom Fields in iPaaS
In iPaaS, click Data Management > Custom Fields > Add Custom Field.
Enter a unique Field Name that exactly matches the OroCommerce custom field name created above.
Select the Module (Customer or Customer Address) and set the Data Type to String.
Add a Description.
Click Save.
Set Up the Custom Field Values in iPaaS
In iPaaS, navigate to the relevant entity (Customer or Address).
Click Edit, then click Add under the Custom Fields section.
Select an existing custom field, or create a new one if needed, and enter the value in the Value field.
Click Apply.
Map the Custom Field in iPaaS
In iPaaS.com, open the relevant mapping collection and add a new mapping by selecting the desired destination custom field. The source can be configured based on the custom field requirements.
Mapping Collection Status
Mapping Status: Enabled
Trigger Events: Create, Update
Conflicting Mappings
This mapping applies only to Customers from iPaaS. Ensure no other mappings target the same OroCommerce Customer entity to prevent data from being overwritten.
Authentication and Security
OroCommerce uses OAuth 2.0 authentication to generate an access token. This token authorizes all OroCommerce API requests during transfer operations.
Integration Flow
The integration processes iPaaS customer companies as follows:
The integration is triggered when a customer company is created or updated in iPaaS.
Customer details are mapped and validated against OroCommerce requirements.
If categories are assigned, the system verifies they have been transferred to OroCommerce.
The customer record is created or updated in OroCommerce.
Associated addresses are processed through the child collection.
Upon successful transfer, the OroCommerce ID is saved as the External ID in iPaaS.
Sync results are logged for troubleshooting.
Supported Child Collections
This parent mapping collection supports the following child collection:
Mappings
Parent Collection: OroCommerce Add/Update Customer FROM iPaaS.com
Mapping Type | Source Field (iPaaS) | Destination Field (OroCommerce) | Description |
Dynamic Formula |
| SimTest | Recommended: Retrieves the value of the custom field "SimTest". Returns null if empty. |
Field | Name | Attributes_Name | Required: Maps iPaaS Name to OroCommerce Attributes_Name. |
Dynamic Formula |
| Relationships_Group_Id | Recommended: Converts iPaaS customer categories into an OroCommerce Customer Group ID. Looks up by CategoryId external ID first; falls back to CategoryName lookup. |
Static | 1 | Relationships_Owner_Id | Recommended: Sets the static owner ID. |
Static | 1 | Relationships_Organization_Id | Recommended: Sets the static organization ID. |
Static | customers | Type | Required: Sets the OroCommerce Type. |
Static | customergroups | Relationships_Group_Type | Recommended: Sets the customer group relationship type. |
Static | organizations | Relationships_Organization_Type | Recommended: Sets the organization relationship type. |
Static | users | Relationships_Owner_Type | Recommended: Sets the owner relationship type. |
Child: OroCommerce Add/Update Customer Address FROM iPaaS.com
Mapping Type | Source Field (iPaaS) | Destination Field (OroCommerce) | Description |
Dynamic Formula |
| LaneNo | Recommended: Retrieves the value of the custom field "LaneNo". Returns null if empty. |
Dynamic Formula |
| Id | Required: Retrieves the OroCommerce address External ID for update operations. |
Field | Address1 | Attributes_Street | Required: Maps Address1 to Attributes_Street. |
Field | PhoneNumber | Attributes_Phone | Recommended: Maps PhoneNumber to Attributes_Phone. |
Field | City | Attributes_City | Required: Maps City to Attributes_City. |
Field | PostalCode | Attributes_PostalCode | Required: Maps PostalCode to Attributes_PostalCode. |
Field | Company | Attributes_Organization | Recommended: Maps Company to Attributes_Organization. |
Field | FirstName | Attributes_FirstName | Recommended: Maps FirstName to Attributes_FirstName. |
Field | LastName | Attributes_LastName | Recommended: Maps LastName to Attributes_LastName. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended: Maps IsPrimaryBilling to IsPrimaryBilling. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended: Maps IsPrimaryShipping to IsPrimaryShipping. |
Dynamic Formula |
| Relationships_Country_Id | Required: Converts an iPaaS country name into an OroCommerce Country ID. |
Dynamic Formula |
| Relationships_Region_Id | Recommended: Converts an iPaaS region name into an OroCommerce Region ID. |
Static | customeraddresses | Type | Required: Sets the OroCommerce Type. |
Static | countries | Relationships_Country_Type | Required: Sets the country relationship type. |
Static | regions | Relationships_Region_Type | Recommended: Sets the region relationship type. |
Error Handling
Missing Required Field
Required field is missing.
Description: OroCommerce rejected a customer create or update request due to missing required fields.
Resolution: Ensure all required fields are populated: Name for customers; Street, City, PostalCode, and Country for addresses.
Invalid Country or Region
Country or Region not found.
Description: The country or region name provided does not exist in OroCommerce.
Resolution: Verify the country and region names match exactly with OroCommerce records, or add the missing country/region to OroCommerce.
Authentication Failure
OAuth 2.0 token generation failed.
Description: The OroCommerce API rejected the authentication request.
Resolution: Verify OAuth credentials are correctly configured in iPaaS.
Category Not Found
Customer group not found.
Description: The category assigned to the customer has not been transferred to OroCommerce.
Resolution: Transfer the category to OroCommerce before syncing the customer.
Validation and Testing
Before deploying this integration, verify the following configuration items and run the test scenarios to confirm proper operation.
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.Categories are synced before the customer (if 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 (if provided).
Test Scenarios
Scenario 1: Create New Customer
Create a new Customer Company in iPaaS with 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 Existing Customer
Update an existing Customer Company in iPaaS.com (change Name or other fields). Sync to OroCommerce and verify changes are reflected without creating duplicate records.
Scenario 3: Create Customer with Category (Failure Case)
Create a Customer Company in iPaaS with an assigned category that has not been transferred to OroCommerce. Trigger the sync and verify that the integration returns a 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.
Additional Notes
Ensure dynamic formulas return valid references for all dependent entities.
Custom fields require the correct module assignment: Customer for parent, Customer Address for child.
Serialized Field storage type is recommended for custom fields to avoid manual schema updates.
The External ID format for addresses includes the parent customer ID to maintain the relationship (for example:
21|25).Categories must be transferred to OroCommerce before customers that reference those categories.