Skip to main content

OroCommerce Add/Update Kit Product FROM iPaaS

Map Kit product data from iPaaS.com to OroCommerce

Updated over a week ago

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:

  1. Parent: OroCommerce Add/Update Kit Product FROM iPaaS.com

  2. Child: OroCommerce Add/Update Kit Item FROM iPaaS.com

  3. 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:

  1. Add OroCommerce Add/Update Simple Product FROM iPaaS.com

  2. Add OroCommerce Add/Update Configurable Product FROM iPaaS.com

  3. 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.

  1. Navigate to Entity Management: Go to System → Entities → Entity Management.

  2. Select the Target Module: Locate and select the module (entity) where you want to add the custom field (e.g., Product).

  3. 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".

  4. 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.

  5. 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:

  1. Product is created or updated in iPaaS.com with TrackingMethod = "Product" and at least one valid kit component.

  2. Mapping filter validates product qualifies as a Kit product.

  3. Kit component SKUs are validated against existing OroCommerce products during preprocessing.

  4. iPaaS.com authenticates with OroCommerce using OAuth 2.0.

  5. Required relationship entities (Organization, Owner, Attribute Family, etc.) are resolved via dynamic lookups.

  6. Product attributes are mapped (SKU, Status, ProductType = "kit", Featured, NewArrival, KitShippingCalculationMethod).

  7. Related entities (Names, Descriptions, Shipping Options, etc.) are prepared for the included object.

  8. The Kit product is created or updated via the OroCommerce Product API.

  9. 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

  10. If default pricing mappings are provided, pricing validation and creation occur.

  11. OroCommerce Product ID is saved as External ID in iPaaS.com.

  12. 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
(custom field)

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

if(Status == "Active" || Status == "Preorder") return "enabled"; else return "disabled";

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

return await GetBusinessUnitIdByNameAsync("Acme, General");

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

return await GetOrganizationIdByNameAsync("iPaaS.com");

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

return await GetAttributeFamilyIdByCodeAsync("default_family_custom");

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

return new List<string> { Name };

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

if(!string.IsNullOrWhiteSpace(Unit)) { string unitId = await GetProductUnitIdByLabelAsync(Unit); if(!string.IsNullOrWhiteSpace(unitId)) return unitId; } return "each";

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

return new List<string> { "short desc: " + Description };

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

return new List<string> { Description };

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

return await GetWeightUnitIdByShortCodeAsync("kg");

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

return await GetLengthUnitIdByShortCodeAsync("m");

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

return await GetProductTaxCodeIdByTaxCodeAsync("TAXABLE_ITEMS");

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

return await GetProductBrandIdByNameAsync("Default ltd.");

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

if(Categories?.Count > 0) return await GetCatalogCategoryIdByTitleAsync(Categories.LastOrDefault().CategoryName);

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

string normalizedSlug = Regex.Replace(Name, @"[^a-zA-Z0-9\-._~]", "_"); return new List<string> { normalizedSlug };

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

return new List<string> { "Meta Title: " + Name };

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

return new List<string> { "Meta Desc: " + Description };

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

return new List<string> { "Meta Keyword: " + TrackingMethod + " " + Name.Split()[0] };

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

InStockThreshold ?? 1;

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

string priceListId = await GetPriceListIdByNameAsync("Default Price List"); if(!string.IsNullOrWhiteSpace(priceListId)) return priceListId; throw new Exception("Product cannot be updated because incorrect price list name is provided");

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

if(!string.IsNullOrWhiteSpace(Unit)) { string unitId = await GetProductUnitIdByLabelAsync(Unit); if(!string.IsNullOrWhiteSpace(unitId)) return unitId; } return "each";

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

string labelId = null;

string kitLabel = GetCustomFieldValue(CustomFields, "Kit Label");

if(!string.IsNullOrWhiteSpace(kitLabel))

labelId = kitLabel;

else

labelId = Parent.Type;

string productId = await GetProductIdBySkuAsync(Sku);

string productUnitId = await GetOroCommerceProductUnitIdByProductIdAsync(productId);

if (!string.IsNullOrWhiteSpace(productUnitId))

labelId += " " + productUnitId;

labelId += " " + Quantity;

return labelId;

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

return await GetProductIdBySkuAsync(Sku);

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

  1. All mandatory fields are mapped (Type, Attributes_Sku, Attributes_Status, Attributes_ProductType).

  2. All required relationship fields have both ID and Type mapped.

  3. Referenced entities exist in OroCommerce (Organization, Owner, Attribute Family, etc.).

  4. At least one kit component has a SKU that exists in OroCommerce.

  5. Kit Item mandatory fields are mapped (Type, Label_Id, Label_Type, kitItemProducts_Id, kitItemProducts_Type).

  6. Custom fields exist in OroCommerce with matching names and types.

  7. Price List exists for default pricing operations.

  8. Product unit exists or defaults to "each".

  9. 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.

Did this answer your question?