OroCommerce Customer User From iPaaS.com Mapping Documentation
This integration transfers iPaaS.com Customer records to OroCommerce as Customer Users, along with their associated addresses, in a single operation. The flow is triggered when a Customer is created or updated in iPaaS.com and runs in the From iPaaS.com direction. Its purpose is to keep customer user account data, the customer (company) and website assignments, and address records consistent between iPaaS.com and OroCommerce.
Before You Begin
Complete the following prerequisites before enabling this integration.
iPaaS.com Requirements
A configured OroCommerce connection in iPaaS.com with valid OAuth 2.0 (Authorization Code) credentials stored securely in the iPaaS.com credential manager.
The source iPaaS.com Customer record must have FirstName, LastName, and EmailAddress populated, as the customer user cannot be created in OroCommerce without them.
If custom fields are used, create the matching custom field in iPaaS.com with a name that exactly matches the OroCommerce custom field, assigned to the correct module (Customer User for the parent, Customer User Address for the child).
OroCommerce Requirements
The customer (company), website, customer user role, country, and region referenced by the transferred data must already exist in OroCommerce so their IDs can be resolved during the transfer.
If customer categories (groups) are used, transfer them to OroCommerce before the customer user is synced.
If custom fields are used, create the matching custom field in OroCommerce on the correct entity (Customer User for the parent, Customer User Address for the child) before syncing.
ID Format
When manually transferring a Customer from iPaaS.com, enter the valid iPaaS.com Customer (internal ID) into the input field on the iPaaS.com manual sync page.
Example: 145146
External ID Format
The OroCommerce Customer User ID is saved as the external ID on the parent record.
Example (parent Customer User): 25
For the child address collection, the OroCommerce customer user address external ID is saved as the address ID, a pipe separator, and the parent customer user ID, in that order.
Example (child Customer User Address): 21|25 — where 21 is the OroCommerce customer user address ID and 25 is the parent customer user ID.
Custom Field Support
This integration supports custom fields on both the parent (Customer User) and the child (Customer User 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 User. For the child collection, the 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 for the parent, Customer User 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 User for the parent, Customer User 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), 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 Customer is processed.
Duplicate or Conflicting Mappings
This mapping applies only to Customer Users transferred from iPaaS.com. To prevent customer user data from being overwritten, ensure no other mapping collection targets the same OroCommerce Customer User entity. Related collections in the customer family that operate on different entities include OroCommerce Customer FROM iPaaS.com (which creates the customer company that this flow assigns users to) and OroCommerce Customer Category FROM iPaaS.com (which creates the customer groups). Because those collections target different OroCommerce entities, they do not conflict with this flow.
Supported Child Collections
This parent mapping collection supports one child collection.
Parent: Add/Update OroCommerce Customer User FROM iPaaS.com — creates or updates the OroCommerce customer user account, including its customer (company), website, and role assignments.
Child: Add/Update OroCommerce Customer User Address FROM iPaaS.com — creates or updates the customer user's billing and shipping addresses as part of the same operation.
System Caveats
OroCommerce Caveats
Parent collection (Customer User):
Type must be the literal value "customerusers" (case-sensitive).
Email is required.
First Name is required.
Last Name is required.
Customer (the company the user belongs to) is required.
Website is required.
Role is required.
The customer, website, and role referenced by the mappings must already exist in OroCommerce so their IDs can be resolved.
Child collection (Customer User Address):
Type must be the literal value "customeruseraddresses" (case-sensitive). The country type must be "countries" and the region type must be "regions".
Required fields are Country, Region, ZipCode (PostalCode), Street, and City.
Country and Region mapping: The country or region name must already exist in OroCommerce to resolve a valid country or region ID.
To mark an address as Default Billing or Default Shipping in OroCommerce, provide the IsPrimaryBilling or IsPrimaryShipping flag.
iPaaS.com Caveats
FirstName, LastName, and EmailAddress must be present on the iPaaS.com Customer record for the customer user to be created in OroCommerce.
The Id mapping is required in the customer user 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 (company), website, customer user role, country, and region referenced by the transferred data must exist in OroCommerce before the customer user is synced.
Integration Flow
The integration processes iPaaS.com customers as follows:
A Customer is created or updated in iPaaS.com, triggering the integration.
Customer user details are mapped and validated against OroCommerce requirements.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
The customer (company), website, and role relationships are resolved to their OroCommerce IDs.
The customer user record is created or updated in OroCommerce.
Associated addresses are processed through the child collection.
The OroCommerce Customer User 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 User FROM iPaaS.com
This mapping collection creates or updates the OroCommerce customer user account from iPaaS.com Customer data. It maps the account identity fields (email, first and last name), resolves the customer (company), website, and role relationships to their OroCommerce IDs, and applies the required record type and account-status defaults. The collection has no record filter, so every created or updated Customer is processed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (OroCommerce) | Description |
Static | customerusers | Type | (Required) Specifies the record type. OroCommerce expects the literal value "customerusers" (case-sensitive). |
Field | EmailAddress | Attributes_Email | (Required) Maps the customer user email address from iPaaS.com to OroCommerce. |
Field | FirstName | Attributes_FirstName | (Required) Maps the customer user first name from iPaaS.com to OroCommerce. |
Field | LastName | Attributes_LastName | (Required) Maps the customer user last name from iPaaS.com to OroCommerce. |
Static |
| Attributes_Password | Sets the customer user password when a new customer user is created. The static value is a single space; replace it with the password value appropriate for your implementation. |
Dynamic Formula | return await GetWebsiteIdByNameAsync("Default") | Relationships_Website_Id | (Required) Resolves the OroCommerce Website ID from the website name; returns null if the name is empty or no match is found. The website is the customer user's registration website and the default website for that user's outgoing email notifications. Placeholder value — replace during implementation: "Default" is an example website name; substitute the website name used by your target OroCommerce instance. |
Static | true | Attributes_Enabled | (Recommended) Sets whether the customer user account is enabled. When a customer user is disabled, that user cannot log into OroCommerce. The default value is "true". |
Dynamic Formula | return await GetCustomerIdByNameAsync("Alex"); | Relationships_Customer_Id | (Required) Resolves the OroCommerce Customer ID from the customer (company) name; returns null if the name is empty or no match is found. The customer must already exist in OroCommerce. Placeholder value — replace during implementation: "Alex" is an example customer name; substitute the customer (company) name that the user should belong to in your target OroCommerce instance. |
Dynamic Formula | string roleId = await GetCustomerRoleIdByNameAsync("Administrator"); if(string.IsNullOrEmpty(roleId)){ return null; } return roleId; | Relationships_Role_Id | (Conditionally required) Resolves the OroCommerce customer user Role ID from the role name; returns null if the name is empty or no match is found. The role is required when the account is enabled. Placeholder value — replace during implementation: "Administrator" is an example role name; substitute the customer user role used by your target OroCommerce instance. |
Static | reset | Relationships_AuthStatus_Id | (Recommended) Sets the authentication status, which defines whether the customer user can use the current password to log in. Supported values are "active", "reset", and "expired". |
Dynamic Formula | var value = GetCustomFieldValue(CustomFields, "TabindaTestCustomField"); if (string.IsNullOrEmpty(value)){return null;} else {return value;} | TabindaTestCustomField | Reads the value of the "TabindaTestCustomField" custom field from the iPaaS.com record and writes it to the matching custom field on the OroCommerce customer user. Returns null when the value is empty. Placeholder value — replace during implementation: "TabindaTestCustomField" is an example custom field; replace it with a custom field that exists on the Customer User module in your target OroCommerce instance, or remove the mapping if not needed. |
Child: Add/Update OroCommerce Customer User Address FROM iPaaS.com
This child mapping collection maps an iPaaS.com customer address to an OroCommerce customer user address. It maps the postal address parts and contact details, 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 Customer is mapped.
Mapping Type | Source Field (iPaaS.com) | Destination Field (OroCommerce) | Description |
Field | Address1 | Attributes_Street | (Required) Maps the street (iPaaS.com Address1) portion of the customer user postal address. |
Field | Address2 | Attributes_Street2 | (Recommended) Maps the second address line (suite, unit) from iPaaS.com to the OroCommerce customer user address. |
Field | City | Attributes_City | (Required) Maps the city portion of the customer user postal address. |
Field | PostalCode | Attributes_PostalCode | (Required) Maps the ZIP/postal code for the billing or shipping address. |
Field | PhoneNumber | Attributes_Phone | (Recommended) Maps the customer user phone number, which may be used for shipping or payment related communication. |
Field | Company | Attributes_Organization | (Conditionally required) Maps the customer user organization name for the billing or shipping address. Either organization, or both first name and last name, must be provided. |
Field | FirstName | Attributes_FirstName | (Conditionally required) Maps the customer user first name for the billing or shipping address. Either organization, or both first name and last name, must be provided. |
Field | LastName | Attributes_LastName | (Conditionally required) Maps the customer user last name for the billing or shipping address. Either organization, or both first name and last name, must be provided. |
Field | IsPrimaryBilling | IsPrimaryBilling | (Recommended) Maps whether this address is the customer user'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 user'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 | (Conditionally required) Resolves the OroCommerce Region ID from the iPaaS.com region name; returns null if the name is empty or no match is found. A state or region is required for some countries, and 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, "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. |
Field | CustomMoney | CustomMoney | Maps the value of the iPaaS.com "CustomMoney" custom field directly to the matching custom field on the OroCommerce customer user address. Placeholder value — replace during implementation: "CustomMoney" is an example custom field; replace it with a custom field that exists on the Customer User Address module in your target OroCommerce instance, or remove the mapping if not needed. |
Error Handling
Required field is missing. OroCommerce rejected a customer user create or update request because one or more required fields were not populated. Ensure all required fields are present: Email, First Name, Last Name, Customer, Website, and Role for the customer user; 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.
Authentication failure. OroCommerce rejected the OAuth 2.0 token request, so no transfer could be made. Verify that the OAuth 2.0 credentials are configured correctly in the iPaaS.com OroCommerce connection.
Customer not found. The customer (company) name used to resolve the customer relationship does not exist in OroCommerce. Transfer the corresponding customer (company) to OroCommerce before syncing the customer user.
Website not found. The website name used to resolve the website relationship does not exist in OroCommerce. Verify that the website name matches an existing OroCommerce website exactly.
Role not found. The role name used to resolve the role relationship does not exist in OroCommerce. Verify that the role name matches an existing OroCommerce customer user role.
Testing & Validation
Test Scenarios
Scenario 1 — Create a new customer user. Create a new Customer in iPaaS.com with a first name, last name, email address, and at least one address. Sync to OroCommerce and verify the Customer User is created with all addresses and the correct customer (company), website, and role assignments. Confirm the OroCommerce Customer User ID is saved as the external ID in iPaaS.com.
Scenario 2 — Update an existing customer user. Update an existing Customer in iPaaS.com (for example, change the email address or an address field). Sync to OroCommerce and verify the changes are reflected without creating duplicate records.
Scenario 3 — Create a customer user with an address. Create a Customer in iPaaS.com with at least one address that includes all required fields (Street, City, PostalCode, and Country). Sync and verify that both the Customer User and the Address child records are created in OroCommerce. Confirm that the address external ID follows the format that includes the parent customer user ID.
Scenario 4 — Missing required fields (failure case). Create a Customer in iPaaS.com without a first name or last name. 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.com with the same name and module, assign a value, and sync. Verify the custom field value transfers correctly and is stored using the configured storage type (Serialized Field or Table Column).
Validation Checklist
Customer User (parent) requirements:
Email, First Name, and Last Name are present.
Type is set to "customerusers" (exact case).
The customer (company), website, and role names resolve to existing OroCommerce records.
The role is provided when the account is enabled.
The website, customer, and role placeholder values are replaced with the values used by your target OroCommerce instance.
Customer User 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.
Either the organization, or both first name and last name, is provided.
Additional Notes
Dynamic formulas must return valid references for all dependent entities (customer, website, role, country, region).
Custom fields require the correct module assignment: Customer User for the parent collection, Customer User 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 user ID to maintain the relationship between the address and its customer user.