Overview
When a product is created or updated in iPaaS.com with TrackingMethod = Product and includes a kit with at least one valid kit component, the corresponding product record is created or updated in OroCommerce as a Kit product. This mapping ensures accurate and consistent synchronization of kit product data between iPaaS.com and OroCommerce.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
iPaaS.com Requirements
Product records must have valid SKU, Name, Default Price, and Status.
TrackingMethod must be set to "Product".
Product must have a Kit with at least one valid Kit Component.
Kit Component SKUs must exist in OroCommerce before kit product creation.
Type field must be populated.
OroCommerce Requirements
The following entities must exist before product creation if referenced:
Organization
Business Unit (Owner)
Attribute Family
Inventory Status
Tax Code
Brand
Category
Price List (for default pricing)
Product Units
Products referenced as Kit Components must already exist in OroCommerce.
API credentials must have permission to create/update products and kit items.
Custom fields must be created in OroCommerce before mapping (schema update may be required).
ID Format
When manually transferring a Product from iPaaS.com, enter the valid iPaaS.com Product (internal ID) into the input field on the iPaaS.com manual sync page.
Example: 197689
External ID Format
The OroCommerce Product ID will be saved as the external ID.
Example: 288
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Supported Child Collections
This flow has one child collection, and that child has another child collection in order to create Kit products in OroCommerce. All attributes and relationships are handled within this single mapping collection except for Kit Items which use the following mapping collections:
Parent: OroCommerce Add/Update Kit Product FROM iPaaS.com
Child: OroCommerce Add/Update Kit Item FROM iPaaS.com
Child: OroCommerce Add/Update Kit Item Product FROM iPaaS.com
Duplicate or Conflicting Mappings
This mapping applies only to Kit Products in OroCommerce. The following mapping collections are in use to update Kit Product and create/update Configurable and Simple Products:
Add OroCommerce Add/Update Simple Product FROM iPaaS.com
Add OroCommerce Add/Update Configurable Product FROM iPaaS.com
Update OroCommerce Configurable Product FROM iPaaS.com
Mandatory Fields
The following fields are required to be mapped in this flow for successful kit product creation:
Mandatory Product Fields
Type
Attributes_Sku
Attributes_Status
Attributes_ProductType (must be "kit")
Relationships_AttributeFamily_Id
Relationships_AttributeFamily_Type
Relationships_InventoryStatus_Id
Relationships_InventoryStatus_Type
Relationships_Names_Ids
Relationships_Names_Type
Relationships_PrimaryUnitPrecision_Id
Relationships_PrimaryUnitPrecision_Type
Relationships_PrimaryUnitPrecision_Precision
Mandatory Kit Item Fields
Type (productkititems)
Relationships_Label_Id
Relationships_Label_Type
Relationships_kitItemProducts_Id
Relationships_kitItemProducts_Type
The system leverages dynamic formula-based mappings using mappable fields and custom helper functions to resolve required internal OroCommerce entity IDs from static labels, configuration values, or other mapped attributes. This approach enables seamless creation and association of both single-valued (to-one) and multi-valued (to-many) related entities during product creation, without requiring pre-existing relationships or manual setup in OroCommerce.
NOTE: These fields are included in the included object only if they are mapped. |
Kit Items Update Behavior
During product updates from iPaaS.com, Kit Item records in OroCommerce are deleted and recreated as part of the standard synchronization process. This occurs on every product update, even when no changes have been made to the kit definition or its components. This behavior is required to ensure consistency of kit configuration, including support for scenarios such as kit component removal or restructuring.
Custom Fields Support
This flow supports the use of custom fields. To map and add data from iPaaS.com into a custom field in OroCommerce, follow the steps outlined below.
Navigate to Entity Management: Go to System → Entities → Entity Management.
Select the Target Module: Locate and select the module (entity) where you want to add the custom field (e.g., Product).
Create a Custom Field: Click Create Field and configure the following required fields:
Field Name: Provide a unique name. This value should start with a letter and contain only alphabetic symbols, underscores, and numbers.
Storage Type: Select "Serialized field" or "Table Column". For Table Column fields, a schema update is required before the custom field becomes available. Serialized Field custom fields are added automatically.
Type: Set field type as "string", "datetime", "integer", "float", "decimal", "boolean", or "enum".
Update the Schema: After creating the field with Table Column storage type, click Update Schema to apply the changes.
Note: Contact your OroCommerce administrator before updating an entity schema to prevent unexpected service downtime.
iPaaS.com Subscription Custom Fields Configuration: Once the schema update is completed (if required), configure the custom field in iPaaS.com:
Go to the OroCommerce subscription > Custom Fields.
Create the custom field with the exact Field Name and Type from OroCommerce.
Select the "Product" Module and click Save.
Open the relevant mapping collection and add a new mapping by selecting the desired destination custom field.
Authentication and Security
OroCommerce uses OAuth 2.0 authentication to generate an access token, which is then used to authorize all OroCommerce API requests in transfer operations. Ensure credentials are stored securely within the iPaaS.com credential manager.
Integration Flow
The integration processes iPaaS.com Kit Product records as follows:
Product is created or updated in iPaaS.com with
TrackingMethod = "Product"and at least one valid kit component.Mapping filter validates product qualifies as a Kit product.
Kit component SKUs are validated against existing OroCommerce products during preprocessing.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
Required relationship entities (Organization, Owner, Attribute Family, etc.) are resolved via dynamic lookups.
Product attributes are mapped (SKU, Status, ProductType = "kit", Featured, NewArrival, KitShippingCalculationMethod).
Related entities (Names, Descriptions, Shipping Options, etc.) are prepared for the included object.
The Kit product is created or updated via the OroCommerce Product API.
For each kit component with a valid SKU in OroCommerce:
Kit Item is created with label grouping
Kit Item Product is associated with the existing OroCommerce product
If default pricing mappings are provided, pricing validation and creation occur.
OroCommerce Product ID is saved as External ID in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: OroCommerce Kit Product Add/Update FROM iPaaS
This mapping collection handles the creation of standalone OroCommerce Kit products from iPaaS.com data. It applies only to products where TrackingMethod = Product and includes a kit with at least one valid kit component. The mapping ensures that kit items, organizational structure, product units, tax code, related financial attributes, and other data are correctly associated, maintaining consistent updates within OroCommerce.
Mapping Filter
if (TrackingMethod == "Product" && Kit?.Components?.Count > 0)
{
return true;
}
return false;
Description
This filter ensures that only kit products eligible for creation in OroCommerce are processed. It validates that the product's TrackingMethod is set to "Product" and that the product contains one or more kit components.
NOTE: Valid iPaaS.com Products that exist as Kit Components are created during preprocessing which ensures that valid kit component SKUs may already exist in OroCommerce |
Mapping Type | Source (iPaaS.com) | Destination (OroCommerce) | Description |
Static | true | Test_bool_2 |
|
Static | products | Type | (Required) Sets the product type in OroCommerce. |
Field | Sku | Attributes_Sku | (Required) Maps the product SKU from iPaaS.com to OroCommerce. |
Dynamic Formula |
| Attributes_Status | (Required) Maps product status. OroCommerce only supports "enabled" or "disabled". Active and Preorder are mapped to enabled; all others to disabled. |
Static | kit | Attributes_ProductType | (Required) Sets the product type to "kit" for kit products. |
Static | true | Attributes_Featured | (Recommended) Sets whether the product is featured. Set to "true" or "false". |
Static | true | Attributes_NewArrival | (Recommended) Sets whether the product is a new arrival. Set to "true" or "false". |
Static | kit_shipping_all | Attributes_KitShippingCalculationMethod | (Recommended) Specifies how to calculate fixed shipping price for product kit. Available values: kit_shipping_all, kit_shipping_product, kit_shipping_items. |
Dynamic Formula |
| Relationships_Owner_Id | (Recommended) Retrieves the business unit ID by name for product ownership. |
Static | businessunits | Relationships_Owner_Type | (Required when Owner_Id is mapped) Specifies the owner relationship type. |
Dynamic Formula |
| Relationships_Organization_Id | (Recommended) Retrieves the organization ID by name. |
Static | organizations | Relationships_Organization_Type | (Required when Organization_Id is mapped) Specifies the organization relationship type. |
Dynamic Formula |
| Relationships_AttributeFamily_Id | (Required) Retrieves the attribute family ID by code. |
Static | attributefamilies | Relationships_AttributeFamily_Type | (Required) Specifies the attribute family relationship type. |
Lookup Translation | Product Inventory Status | Relationships_InventoryStatus_Id | (Required) Maps inventory status using lookup translation table. |
Static | prodinventorystatuses | Relationships_InventoryStatus_Type | (Required) Specifies the inventory status relationship type. |
Dynamic Formula |
| Relationships_Names_Ids | (Required) Returns product name as a list to support OroCommerce's multi-name localized structure. |
Static | productnames | Relationships_Names_Type | (Required) Specifies the names relationship type. |
Dynamic Formula |
| Relationships_PrimaryUnitPrecision_Id | (Required) Resolves product unit by label; defaults to "each" if not found. |
Static | productunitprecisions | Relationships_PrimaryUnitPrecision_Type | (Required) Specifies the primary unit precision relationship type. |
Static | 0 | Relationships_PrimaryUnitPrecision_Precision | (Required) Sets the decimal precision for the primary unit. |
Static | true | Relationships_PrimaryUnitPrecision_Sell | (Recommended) Sets whether the product is sellable. Set to "true" or "false". |
Dynamic Formula |
| Relationships_ShortDescriptions_Ids | (Recommended) Maps short description as a list for localization support. |
Static | productshortdescriptions | Relationships_ShortDescriptions_Type | (Required when ShortDescriptions_Ids is mapped) Specifies the short descriptions relationship type. |
Dynamic Formula |
| Relationships_Descriptions_Ids | (Recommended) Maps description as a list for localization support. |
Static | productdescriptions | Relationships_Descriptions_Type | (Required when Descriptions_Ids is mapped) Specifies the descriptions relationship type. |
Static | productshippingoptions | Relationships_ProductShippingOptions_Type | (Required when any shipping options are mapped) Specifies the shipping options relationship type. |
Dynamic Formula |
| Relationships_ProductShippingOptions_WeightUnit | (Required when WeightValue is mapped) Retrieves weight unit ID by short code. |
Field | Weight | Relationships_ProductShippingOptions_WeightValue | (Recommended) Maps product weight for shipping options. |
Dynamic Formula |
| Relationships_ProductShippingOptions_DimensionUnit | (Required when any dimension is mapped) Retrieves dimension unit ID by short code. |
Field | Depth | Relationships_ProductShippingOptions_DimensionLength | (Recommended) Maps product depth to length for shipping options. |
Field | Width | Relationships_ProductShippingOptions_DimensionWidth | (Recommended) Maps product width for shipping options. |
Field | Height | Relationships_ProductShippingOptions_DimensionHeight | (Recommended) Maps product height for shipping options. |
Dynamic Formula |
| Relationships_TaxCode_Id | (Recommended) Retrieves tax code ID by code. |
Static | producttaxcodes | Relationships_TaxCode_Type | (Required when TaxCode_Id is mapped) Specifies the tax code relationship type. |
Dynamic Formula |
| Relationships_Brand_Id | (Recommended) Retrieves brand ID by name. |
Static | brands | Relationships_Brand_Type | (Required when Brand_Id is mapped) Specifies the brand relationship type. |
Dynamic Formula |
| Relationships_Category_Id | (Recommended) Retrieves category ID using the last category in the collection. |
Static | categories | Relationships_Category_Type | (Required when Category_Id is mapped) Specifies the category relationship type. |
Static | systemConfig | Relationships_PageTemplate_Id | (Recommended) Sets the fallback value for page template. |
Static | entityfieldfallbackvalues | Relationships_PageTemplate_Type | (Required when PageTemplate_Id is mapped) Specifies the page template relationship type. |
Static | entityfieldfallbackvalues | Relationships_ManageInventory_Type | (Required when ManageInventory is mapped) Specifies the manage inventory relationship type. |
Static | 1 | Relationships_ManageInventory_ScalarValue | (Recommended) Sets manage inventory option. "1" = On order submission; "0" = No (custom). |
Static | entityfieldfallbackvalues | Relationships_DecrementQuantity_Type | (Required when DecrementQuantity is mapped) Specifies the decrement quantity relationship type. |
Static | 1 | Relationships_DecrementQuantity_ScalarValue | (Recommended) Sets decrement quantity option. "1" = Yes; "0" = No. |
Static | entityfieldfallbackvalues | Relationships_BackOrder_Type | (Required when BackOrder is mapped) Specifies the backorder relationship type. |
Static | 0 | Relationships_BackOrder_ScalarValue | (Recommended) Sets backorder option. "1" = Yes; "0" = No. |
Dynamic Formula |
| Relationships_SlugPrototypes_Ids | (Recommended) Generates URL-safe slug from product name. |
Static | localizedfallbackvalues | Relationships_SlugPrototypes_Type | (Required when SlugPrototypes_Ids is mapped) Specifies the slug prototypes relationship type. |
Dynamic Formula |
| Relationships_MetaTitles_Ids | (Recommended) Maps meta title for SEO optimization. |
Static | localizedfallbackvalues | Relationships_MetaTitles_Type | (Required when MetaTitles_Ids is mapped) Specifies the meta titles relationship type. |
Dynamic Formula |
| Relationships_MetaDescriptions_Ids | (Recommended) Maps meta description for SEO optimization. |
Static | localizedfallbackvalues | Relationships_MetaDescriptions_Type | (Required when MetaDescriptions_Ids is mapped) Specifies the meta descriptions relationship type. |
Dynamic Formula |
| Relationships_MetaKeywords_Ids | (Recommended) Maps meta keywords for SEO optimization. |
Static | localizedfallbackvalues | Relationships_MetaKeywords_Type | (Required when MetaKeywords_Ids is mapped) Specifies the meta keywords relationship type. |
Static | productprices | DefaultPricing_Type | (Required for default pricing) Specifies the product prices relationship type. |
Static | USD | DefaultPricing_Attributes_Currency | (Required for default pricing) Sets the currency code. |
Dynamic Formula |
| DefaultPricing_Attributes_Quantity | (Required for default pricing) Sets quantity; defaults to 1 if InStockThreshold is null. |
Field | DefaultPrice | DefaultPricing_Attributes_Value | (Required for default pricing) Maps the default price value. |
Dynamic Formula |
| DefaultPricing_Relationships_PriceList_Id | (Required for default pricing) Retrieves price list ID by name; throws exception if not found. |
Static | pricelists | DefaultPricing_Relationships_PriceList_Type | (Required for default pricing) Specifies the price list relationship type. |
Dynamic Formula |
| DefaultPricing_Relationships_Unit_Id | (Required for default pricing) Resolves product unit; defaults to "each". |
Static | productunits | DefaultPricing_Relationships_Unit_Type | (Required for default pricing) Specifies the product units relationship type. |
Child OroCommerce Kit Item Add/Update FROM iPaaS
This mapping collection is responsible for creating Kit Items in OroCommerce based on iPaaS.com Kit and Kit Component data.
It processes a one-to-many relationship, where:
A single iPaaS.com Kit contains multiple Kit Components
And maps it into OroCommerce as:
Multiple Kit Items
Each Kit Item containing multiple Kit Item Products
For each Kit Component, an associated existing OroCommerce product is linked through a child transfer, ensuring that Kit Item Products reference valid product entities.
This collection serves as a base mapping, exposing only the mandatory fields required by OroCommerce to create Kit Items and their related Kit Item Products, while deferring optional and extended mappings to downstream collections.
Mapping Type | Source (iPaaS.com) | Destination (OroCommerce) | Description |
Static | productkititems | Type | (Required) Specifies the kit item type in OroCommerce. |
Child: OroCommerce Kit Item Product Add/Update FROM iPaaS
This mapping collection handles the creation of OroCommerce Kit Items by grouping labels and assigning already existing products from iPaaS.com Kit Component data by creating Kit Item Products in a child transfer. It applies only to kit component SKUs that exist in OroCommerce beforehand. The mapping ensures that kit items are correctly grouped based on labels, products are correctly associated with respective kit items, and maintains consistent updates within OroCommerce.
Mapping Filter
string productId = await GetProductIdBySkuAsync(Sku); if (!string.IsNullOrWhiteSpace(productId)) return true; return false;
Description
This filter validates whether a product already exists in OroCommerce by attempting to find a Product ID using the SKU. If a Product ID is found, the filter evaluates to true; otherwise, it evaluates to false. This filter is typically used to ensure that only the products that exist in OroCommerce are included in the payload of creating Kit Item Product under Kit Item.
Mapping Type | Source (iPaaS.com) | Destination (OroCommerce) | Description |
Field | Type | CustomProductKitItem | (Example) Demonstrates how custom fields are supported within the integration. See the Custom Fields Support section. |
Field | Quantity | Attributes_MinimumQuantity | (Recommended) Used to limit the quantity of this kit item that a customer may purchase as part of the kit. |
Static | true | Attributes_Optional | (Recommended) Indicates whether this kit item is required for purchase, or can be skipped by the customer. |
Dynamic Formula |
| Relationships_Label_Id | (Required) Generates a compounded label for grouping kit components. If "Kit Label" custom field is present, uses that value; otherwise falls back to Parent.Type. Appends product unit and quantity for distinct grouping. |
Static | productkititemlabels | Relationships_Label_Type | (Required) Specifies the kit item labels relationship type. Must be statically mapped to "productkititemlabels". |
Dynamic Formula |
| Relationships_kitItemProducts_Id | (Required) Retrieves the OroCommerce product ID by SKU for kit item product assignment. |
Static | productkititemproducts | Relationships_kitItemProducts_Type | (Required) Specifies the kit item products relationship type. Must be statically mapped to "productkititemproducts". |
Error Handling
Duplicate SKU
Description: This error occurs when trying to create a product in OroCommerce with an existing SKU.
Resolution: Enable collision handling in the mapping collection by configuring the appropriate option in the subscription settings.
No Valid Kit Components
Description: This error occurs when creating a KIT product without any valid product kit components (components whose SKUs exist in OroCommerce).
Resolution: Ensure that at least one kit component has a SKU that already exists in OroCommerce before creating the kit product.
Missing Required Relationship Type
Description: A relationship ID was mapped without its corresponding Type field.
Resolution: Ensure both the ID and Type fields are mapped for all relationships (e.g., Relationships_Owner_Id and Relationships_Owner_Type).
Invalid Price List Name
Description: The Price List name specified in the default pricing mapping does not exist in OroCommerce.
Resolution: Verify the Price List name exists in OroCommerce and update the mapping accordingly.
Kit Component Product Not Found
Description: A kit component's SKU does not exist in OroCommerce.
Resolution: Ensure the kit component product is transferred to OroCommerce before creating the kit product.
Validation and Testing
Validation Rules
Relationship Type Validation
Some fields are validated internally and only become relevant if their dependent fields are also mapped. For instance:
If a Relationships_Owner_Id field is mapped, the corresponding Relationships_Owner_Type must also be mapped to include that relationship in the payload.
If the type field is not provided, the ID field will not be used in the request.
This pattern applies to all similar relationship fields.
Kit Component Validation
iPaaS.com ProductKitComponents are validated and included in the request only if their SKUs already exist in OroCommerce. The kit must contain at least one valid component before creating a Kit product.
Validation Checklist
All mandatory fields are mapped (Type, Attributes_Sku, Attributes_Status, Attributes_ProductType).
All required relationship fields have both ID and Type mapped.
Referenced entities exist in OroCommerce (Organization, Owner, Attribute Family, etc.).
At least one kit component has a SKU that exists in OroCommerce.
Kit Item mandatory fields are mapped (Type, Label_Id, Label_Type, kitItemProducts_Id, kitItemProducts_Type).
Custom fields exist in OroCommerce with matching names and types.
Price List exists for default pricing operations.
Product unit exists or defaults to "each".
Collision handling is configured if SKU conflicts are possible.
Test Scenarios
Scenario 1: Create Kit Product
Sync a new product from iPaaS.com with TrackingMethod = "Product" and at least one valid kit component. The Kit product should be created in OroCommerce with associated Kit Items. OroCommerce Product ID should be saved as External ID in iPaaS.com.
Scenario 2: Update Existing Kit Product
Update an existing kit product in iPaaS.com. Changes should be reflected in OroCommerce without creating duplicates. Kit Items should be deleted and recreated.
Scenario 3: Kit Component SKU Validation
Create a kit product where some component SKUs do not exist in OroCommerce. Only components with valid SKUs should be included in the kit.
Scenario 4: Kit Label Grouping
Create a kit product with multiple components. Components with the same "Kit Label" custom field should be grouped under the same Kit Item.
Scenario 5: No Valid Components (Failure Case)
Attempt to create a kit product where no component SKUs exist in OroCommerce. Transfer should fail with an appropriate error message.
Additional Notes
Ensure dynamic formulas return valid output; null or invalid returns may cause transfer failures.
The mapping filter requires TrackingMethod = "Product" and at least one kit component; products without components are handled by Simple Product mapping collections.
Relationship Type fields are always required when mapping relationship IDs.
Kit Item records are deleted and recreated on every update to ensure consistency.
Kit components are grouped by the "Kit Label" custom field; if not set, the Kit Type is used as the grouping label.
Only kit components with SKUs that exist in OroCommerce are included in the kit creation.
The KitShippingCalculationMethod attribute accepts: "kit_shipping_all", "kit_shipping_product", or "kit_shipping_items".
Custom field names in iPaaS.com must exactly match OroCommerce field names.
Contact your OroCommerce administrator before updating entity schemas to prevent service downtime.
It is recommended to include only 1 item in localized lists (Names, Descriptions, MetaTitles, etc.) unless multiple localizations are required.
