Overview
This integration transfers iPaaS customer records to OroCommerce as Customer Users. When a customer is created or updated in iPaaS, the Customer User data syncs to OroCommerce along with associated addresses as a single operation.
ID Format
When manually transferring a customer from iPaaS, enter the valid iPaaS customer ID (internal ID) into the iPaaS input field on the manual sync page. For example, use: 145146.
External ID Format: Customer User (Parent)
The OroCommerce Customer User ID is saved as the External ID. For example: 25.
External ID Format: Customer User Address (Child)
The OroCommerce Customer User Address External ID is saved as the address ID concatenated with a pipe (|) and the parent Customer User ID. For example: 21|25 (where 21 is the Customer User Address ID and 25 is the parent Customer User ID).
Custom Field Support
This integration supports custom fields for both the parent (Customer User) and child collection (Customer User Address).
NOTE: For Parent collections, the custom field module must be Customer User. For Child collections, the custom field module must be Customer User 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 User or Customer User Address).
Click Create Field and create a custom field.
Enter a unique Field Name and select a Storage Type. We recommend selecting Serialized Field as the Storage Type to avoid manual schema updates.
Table Column: Requires a schema update. The custom field is not available until the schema update completes. Contact your OroCommerce administrator before changing an entity schema to prevent unexpected service downtime. After creating a table column field, a red Update Schema button will appear on the page. Click Update Schema to apply the changes.
Serialized Field: The custom field is added to the schema automatically.
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.
After creating the field, click Update Schema (if required by Storage Type).
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.
Select the Module (Customer or 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 Customer or Address, depending on the module where you want to set the custom field.
Click Edit, then click Add under the Custom Fields section.
Select an existing custom field in iPaaS, or create a new one if needed, and enter the value in the Value field.
Click Apply.
Mapping Collection Status
Mapping Status: Enabled
Trigger Events: Create, Update
Duplicate or 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.
System Caveats
OroCommerce Caveats
Parent collection
Name: Required for creating customer in OroCommerce.
If categories are not null during company creation, they should be transferred before the company is transferred.
Customer Type: The record type must be customerusers.
Categories: If categories from iPaaS are not null, they must be transferred before the customer is transferred.
Child Collection
Required fields: Country, Region, ZipCode, Street and.
Type: The type must be customeraddresses.
Country and Region Mapping: The country or region name must exist in OroCommerce to retrieve a valid country or region ID.
iPaaS Caveats
The Name field is required; without it, the customer company will not be created in iPaaS.com
The Id mapping id required in the customer address update flow to update the customer address in OroCommerce.
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 records as follows:
The integration is triggered when a customer is created or updated in iPaaS.
Customer details are mapped and validated against OroCommerce requirements.
Dependent entities (Customer, Website, Role) are resolved via lookup functions.
The Customer User 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.
Mappings
Parent: OroCommerce Customer User Add/Update From iPaaS
Description
This mapping collection transfers customer data from iPaaS to OroCommerce as Customer User records. The flow maps identity fields, assigns a Customer, Website, and Role, and enables the Customer User account.
Mapping Type | Source (iPaaS) | Destination (OroCommerce) | Description |
Dynamic Formula |
| TestCustomField | Retrieves the value of a custom field from iPaaS. Returns null if empty. Example uses the SimTest custom field. Recommended. |
Field | Id | Id | Maps the iPaaS Id to the OroCommerce Id. Optional for create; required for update. |
Static | customerusers | Type | Sets the OroCommerce Type to the static value customerusers. Required. |
Field | EmailAddress | Attributes_Email | Maps the iPaaS EmailAddress to the OroCommerce Attributes_Email. Recommended. |
Field | FirstName | Attributes_FirstName | Maps the iPaaS FirstName to the OroCommerce Attributes_FirstName. Required. |
Field | LastName | Attributes_LastName | Maps the iPaaS LastName to the OroCommerce Attributes_LastName. Required. |
Static | name | Attributes_MiddleName | Sets the OroCommerce Attributes_MiddleName to the static value. Recommended. NOTE: This is placeholder data; customize per implementation. |
Dynamic Formula |
| Attributes_Birthday | Returns the current date in yyyy-MM-dd format. Recommended. NOTE: This is placeholder logic; customize per implementation. |
Static |
| Attributes_Password | If a static password value is provided, it is updated. If no value is provided, the existing password remains unchanged. |
Static | true | Attributes_Enabled | Sets the OroCommerce Attributes_Enabled to true. When disabled, the Customer User cannot log into OroCommerce. Default is true. |
Dynamic Formula |
| Relationships_Customer_Id | Returns the OroCommerce Customer ID by looking up the customer name. Required. |
Dynamic Formula |
| Relationships_Website_Id | Returns the OroCommerce Website ID by looking up the website name. Required. |
Dynamic Formula |
| Relationships_Role_Id | Returns the OroCommerce Role ID by looking up the role name. Conditionally required when Enabled is true. |
Child: OroCommerce Customer User Address Add/Update From iPaaS
Description
This mapping collection transfers address data from iPaaS to OroCommerce Customer User Address records.
Mapping Type | Source (iPaaS) | Destination (OroCommerce) | Description |
Dynamic Formula |
| Id | Retrieves the OroCommerce address External ID for update operations. Required for updates. |
Static | customeraddresses | Type | Sets the OroCommerce Type to the static value customeraddresses. Required. |
Field | Address1 | Attributes_Street | Maps the iPaaS Address1 to the OroCommerce Attributes_Street. Required. |
Field | PhoneNumber | Attributes_Phone | Maps the iPaaS PhoneNumber to the OroCommerce Attributes_Phone. Recommended. |
Field | City | Attributes_City | Maps the iPaaS City to the OroCommerce Attributes_City. Required. |
Field | PostalCode | Attributes_PostalCode | Maps the iPaaS PostalCode to the OroCommerce Attributes_PostalCode. Required. |
Field | Company | Attributes_Organization | Maps the iPaaS Company to the OroCommerce Attributes_Organization. Conditionally required: either Organization or FirstName and LastName must be defined. |
Field | FirstName | Attributes_FirstName | Maps the iPaaS FirstName to the OroCommerce Attributes_FirstName. Recommended. |
Field | LastName | Attributes_LastName | Maps the iPaaS LastName to the OroCommerce Attributes_LastName. Recommended. |
Field | IsPrimaryBilling | IsPrimaryBilling | Maps the iPaaS IsPrimaryBilling to the OroCommerce IsPrimaryBilling. Recommended. |
Field | IsPrimaryShipping | IsPrimaryShipping | Maps the iPaaS IsPrimaryShipping to the OroCommerce IsPrimaryShipping. Recommended. |
Static | countries | Relationships_Country_Type | Sets the OroCommerce Relationships_Country_Type to the static value countries. Required. |
Static | regions | Relationships_Region_Type | Sets the OroCommerce Relationships_Region_Type to the static value regions. Recommended. |
Dynamic Formula |
| Relationships_Country_ID | Converts an iPaaS country name into an OroCommerce Country ID. Recommended. |
Dynamic Formula |
| Relationships_Region_Id | Converts an iPaaS region name into an OroCommerce region Id. Recommended. |
Error Handling
Missing Required Field
Required field is missing.
Description: OroCommerce rejected a Customer User create or update request due to missing required fields.
Resolution: Ensure all required fields are populated: FirstName and LastName for Customer Users; 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.
Customer Not Found
Customer name lookup returned null.
Description: The GetCustomerIdByNameAsync function could not find a matching customer in OroCommerce.
Resolution: Ensure the customer exists in OroCommerce before syncing the Customer User.
Website Not Found
Website name lookup returned null.
Description: The GetWebsiteIdByNameAsync function could not find a matching website in OroCommerce.
Resolution: Verify the website name matches exactly with OroCommerce records.
Role Not Found
Role name lookup returned null.
Description: The GetCustomerRoleIdByNameAsync function could not find a matching role in OroCommerce.
Resolution: Verify the role name matches exactly with OroCommerce records. The Role field is conditionally required when Enabled is true.
Validation & Testing
Before deploying this integration, verify the following configuration items and run the test scenarios to confirm proper operation.
Validation Checklist
Customer User (Parent) Requirements
FirstName and LastName are present.
Customer Type is set to customerusers.
Customer, Website, and Role lookups return valid IDs.
Categories are synced before Customer (if applicable).
EmailAddress is populated (recommended).
Customer User Address (Child) Requirements
External ID is present for update operations.
Type is set to customeraddresses.
Street (Address1) is present.
City is present.
PostalCode is present.
Country exists in OroCommerce.
Region exists in OroCommerce (if provided).
Either Organization or FirstName and LastName is defined.
Test Scenarios
Scenario 1: Create New Customer User
Create a new Customer in iPaaS with Name and at least one address. Sync to OroCommerce and verify the Customer User is created with all addresses. Confirm the OroCommerce Customer User ID is saved as External ID in iPaaS.
Scenario 2: Update Existing Customer User
Update an existing Customer in iPaaS (change Name or other fields). Sync to OroCommerce and verify changes are reflected without creating duplicate records.
Scenario 3: Create Customer User with Address
Create a Customer in iPaaS with at least one address, including all required fields (Street, City, PostalCode, Country). Sync and verify that both the Customer User and Address child records are created in OroCommerce. Verify the Address External ID format includes the parent Customer User ID.
Scenario 4: Missing Required Fields (Failure Case)
Create a Customer in iPaaS without FirstName or LastName. 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.
Scenario 6: Custom Field Transfer
Create matching custom fields in OroCommerce and iPaaS with the same name and module. Assign a value and sync. Verify the custom field value transfers correctly and is stored using the appropriate storage type (Serialized or Table Column).
Additional Notes
Ensure dynamic formulas return valid references for all dependent entities (Customer, Website, Role).
Custom fields require the correct module assignment: Customer User for parent, Customer User 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 User ID to maintain the relationship (e.g., 21|25).
The MiddleName and Birthday mappings contain placeholder values; customize these per implementation.
The GetCustomerIdByNameAsync function uses a hardcoded customer name; replace it with the appropriate field or variable.