From b943def8b368e603f9af30308d111646b31dc986 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Fri, 6 Feb 2026 19:39:17 +0100 Subject: [PATCH 1/7] Renaming - part one --- composer.json | 4 +- docs/ai_actions/ai_actions_guide.md | 2 +- docs/content_management/content_model.md | 4 +- .../productspecificationfield.md | 2 +- docs/discounts/discounts_guide.md | 6 +- docs/discounts/extend_discounts.md | 2 +- docs/ibexa_products/editions.md | 2 +- docs/ibexa_products/ibexa_commerce.md | 2 +- docs/ibexa_products/ibexa_headless.md | 4 +- docs/index.md | 15 +- docs/permissions/policies.md | 2 +- docs/pim/customize_pim.md | 15 -- docs/pim/pim.md | 17 -- .../add_remote_pim_support.md | 11 +- .../attributes/date_and_time.md | 2 +- .../attributes/img/datetime.png | Bin .../attributes/symbol_attribute_type.md | 2 +- docs/{pim => product_catalog}/catalog_api.md | 0 docs/{pim => product_catalog}/catalogs.md | 0 .../create_custom_attribute_type.md | 0 .../create_custom_catalog_filter.md | 0 .../create_custom_name_schema_strategy.md | 0 .../create_product_code_generator.md | 4 +- .../customize_product_catalog.md | 15 ++ .../enable_purchasing_products.md | 0 .../img/catalog_custom_attribute_type.png | Bin .../img/catalog_vat_rates.png | Bin .../img/catalogs_filters.png | Bin .../img/custom_catalog_filter.png | Bin .../diagrams_source/remote_pim_support.xml | 0 .../img/general_assets.png | Bin .../img/group_base_pricing.png | Bin .../img/grouping_products.png | Bin .../img/how_pim_works.png | Bin .../img/multilevel_variants.png | Bin .../img/product_assets.png | Bin .../img/product_attribute_types.png | Bin .../img/product_attributes.png | Bin .../img/product_categories.png | Bin .../img/regional_vat.png | Bin .../img/remote_pim_support.png | Bin docs/{pim => product_catalog}/price_api.md | 0 docs/{pim => product_catalog}/prices.md | 4 +- docs/{pim => product_catalog}/product_api.md | 0 docs/product_catalog/product_catalog.md | 20 +++ .../product_catalog_configuration.md} | 6 +- .../product_catalog_guide.md} | 33 ++-- docs/{pim => product_catalog}/products.md | 4 +- docs/product_catalog/quable_integration.md | 155 ++++++++++++++++++ docs/product_guides/product_guides.md | 2 +- docs/release_notes/ibexa_dxp_v4.1.md | 2 +- docs/release_notes/ibexa_dxp_v4.2.md | 2 +- docs/release_notes/ibexa_dxp_v4.3.md | 10 +- docs/release_notes/ibexa_dxp_v4.4.md | 4 +- docs/release_notes/ibexa_dxp_v4.5.md | 2 +- docs/release_notes/ibexa_dxp_v4.6.md | 12 +- docs/release_notes/ibexa_dxp_v5.0.md | 8 +- mkdocs.yml | 41 ++--- plugins.yml | 39 ++++- 59 files changed, 323 insertions(+), 132 deletions(-) delete mode 100644 docs/pim/customize_pim.md delete mode 100644 docs/pim/pim.md rename docs/{pim => product_catalog}/add_remote_pim_support.md (72%) rename docs/{pim => product_catalog}/attributes/date_and_time.md (94%) rename docs/{pim => product_catalog}/attributes/img/datetime.png (100%) rename docs/{pim => product_catalog}/attributes/symbol_attribute_type.md (97%) rename docs/{pim => product_catalog}/catalog_api.md (100%) rename docs/{pim => product_catalog}/catalogs.md (100%) rename docs/{pim => product_catalog}/create_custom_attribute_type.md (100%) rename docs/{pim => product_catalog}/create_custom_catalog_filter.md (100%) rename docs/{pim => product_catalog}/create_custom_name_schema_strategy.md (100%) rename docs/{pim => product_catalog}/create_product_code_generator.md (78%) create mode 100644 docs/product_catalog/customize_product_catalog.md rename docs/{pim => product_catalog}/enable_purchasing_products.md (100%) rename docs/{pim => product_catalog}/img/catalog_custom_attribute_type.png (100%) rename docs/{pim => product_catalog}/img/catalog_vat_rates.png (100%) rename docs/{pim => product_catalog}/img/catalogs_filters.png (100%) rename docs/{pim => product_catalog}/img/custom_catalog_filter.png (100%) rename docs/{pim => product_catalog}/img/diagrams_source/remote_pim_support.xml (100%) rename docs/{pim => product_catalog}/img/general_assets.png (100%) rename docs/{pim => product_catalog}/img/group_base_pricing.png (100%) rename docs/{pim => product_catalog}/img/grouping_products.png (100%) rename docs/{pim => product_catalog}/img/how_pim_works.png (100%) rename docs/{pim => product_catalog}/img/multilevel_variants.png (100%) rename docs/{pim => product_catalog}/img/product_assets.png (100%) rename docs/{pim => product_catalog}/img/product_attribute_types.png (100%) rename docs/{pim => product_catalog}/img/product_attributes.png (100%) rename docs/{pim => product_catalog}/img/product_categories.png (100%) rename docs/{pim => product_catalog}/img/regional_vat.png (100%) rename docs/{pim => product_catalog}/img/remote_pim_support.png (100%) rename docs/{pim => product_catalog}/price_api.md (100%) rename docs/{pim => product_catalog}/prices.md (87%) rename docs/{pim => product_catalog}/product_api.md (100%) create mode 100644 docs/product_catalog/product_catalog.md rename docs/{pim/pim_configuration.md => product_catalog/product_catalog_configuration.md} (94%) rename docs/{pim/pim_guide.md => product_catalog/product_catalog_guide.md} (87%) rename docs/{pim => product_catalog}/products.md (94%) create mode 100644 docs/product_catalog/quable_integration.md diff --git a/composer.json b/composer.json index 116cbb26cf..834bc60df9 100644 --- a/composer.json +++ b/composer.json @@ -78,7 +78,9 @@ "ibexa/messenger": "~5.0.x-dev", "ibexa/collaboration": "~5.0.x-dev", "ibexa/share": "~5.0.x-dev", - "ibexa/phpstan": "~5.0.-dev" + "ibexa/phpstan": "~5.0.-dev", + "ibexa/connector-quable": "5.0.x-dev", + "ibexa/quable-client": "dev-reverted-open-api as 5.0.x-dev" }, "scripts": { "fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots", diff --git a/docs/ai_actions/ai_actions_guide.md b/docs/ai_actions/ai_actions_guide.md index 8fe4a6377b..a73b7c01b9 100644 --- a/docs/ai_actions/ai_actions_guide.md +++ b/docs/ai_actions/ai_actions_guide.md @@ -168,7 +168,7 @@ Instead of manually browsing through extensive taxonomy trees, editors can reque ### Performing advanced image to text analysis -With some additional customization, store managers could benefit from automating part of product management by integrating their [[= product_name =]] with Google Cloud Vision and [PIM](pim_guide.md) by using [[= product_name_connect =]]. +With some additional customization, store managers could benefit from automating part of product management by integrating their [[= product_name =]] with Google Cloud Vision and the [product catalog](product_catalog_guide.md) by using [[= product_name_connect =]]. Instead of manually selecting and linking images stored in a [DAM](add_image_asset_from_dam.md) solution to their products, they could use of a no-code workflow where an AI service, for example, Google Cloud Vision, extracts text and attributes from product images, which are then matched with existing items in a product catalog. This would enable automatic product identification, tagging, and catalog updates, resulting in less manual work and more efficient product management. diff --git a/docs/content_management/content_model.md b/docs/content_management/content_model.md index 0a3e436202..9dc1c6029b 100644 --- a/docs/content_management/content_model.md +++ b/docs/content_management/content_model.md @@ -139,6 +139,6 @@ A new version is also created when a new [language](languages.md) is added to th ## Products -Products are a special type of content that holds products you can manage in the built-in PIM system. +Products are a special type of content that holds products you can manage with the product catalog capabilities. -For more information, see [PIM](pim.md). +For more information, see [Product catalog](../product_catalog/product_catalog.md). diff --git a/docs/content_management/field_types/field_type_reference/productspecificationfield.md b/docs/content_management/field_types/field_type_reference/productspecificationfield.md index 4a988312bd..ddea872a1b 100644 --- a/docs/content_management/field_types/field_type_reference/productspecificationfield.md +++ b/docs/content_management/field_types/field_type_reference/productspecificationfield.md @@ -6,7 +6,7 @@ month_change: false # Product specification field type This field represents and handles [product attributes](products.md#product-attributes) and [VAT](prices.md#vat). -Consider it as internal to the [PIM](pim.md). +Consider it as internal to the [product catalog](product_catalog.md). | Name | Internal name | Expected input | |------------------------|-------------------------------|----------------| diff --git a/docs/discounts/discounts_guide.md b/docs/discounts/discounts_guide.md index b33e73a428..0b9a7d26a9 100644 --- a/docs/discounts/discounts_guide.md +++ b/docs/discounts/discounts_guide.md @@ -71,7 +71,7 @@ After choosing where the discount applies (catalog or cart), you can choose the - **Fixed amount** - where a specified amount of money, for example, 5 Euro, is deducted from the base price of the product - **Percentage** - where a specified percentage, for example, 10%, is used to calculate the deducted amount from the product's base price -Discounts are translatable and you can limit them to specific [regions](pim_guide.md#regions) or a single currency. +Discounts are translatable and you can limit them to specific [regions](product_catalog_guide.md#regions) or a single currency. They can be permanent or be active only in a specified time frame. Regardless of the specified dates, you can disable a discount at any time to prevent customers from using it. @@ -86,10 +86,10 @@ With discounts, you can target your entire customer base or only a subset of it #### Product selection -All products, including [product variants](pim_guide.md#product-variants), can be selected when creating a discount. +All products, including [product variants](product_catalog_guide.md#product-variants), can be selected when creating a discount. You can also limit this choice to a subset of products: -- belonging to selected [product categories](pim_guide.md#product-categories) +- belonging to selected [product categories](product_catalog_guide.md#product-categories) - hand-picked manually for special cases #### Conditions diff --git a/docs/discounts/extend_discounts.md b/docs/discounts/extend_discounts.md index e81d4f22e4..604aa069c6 100644 --- a/docs/discounts/extend_discounts.md +++ b/docs/discounts/extend_discounts.md @@ -32,7 +32,7 @@ You can also [create your own](#custom-expressions). | Type | Name | Value | Available for | | --- | --- | --- | --- | | Function | `get_current_region()` | [Region object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-RegionInterface.html) of the current siteaccess.| Conditions, rules | -| Function | `is_in_category()` | `true/false`, depending if a product belongs to given [product categories](pim_guide.md#product-categories).| Conditions, rules | +| Function | `is_in_category()` | `true/false`, depending if a product belongs to given [product categories](product_catalog_guide.md#product-categories).| Conditions, rules | | Function | `is_user_in_customer_group()` | `true/false`, depending if an user belongs to given [customer groups](customer_groups.md). | Conditions, rules | | Function | `calculate_purchase_amount()` | Purchase amount, calculated for all products in the cart before the discounts are applied.| Conditions, rules | | Function | `is_product_in_product_codes()` | Parameters:
- [Product object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-ProductInterface.html)
- array of product codes
Returns `true` if the product is part of the given list.| Conditions, rules | diff --git a/docs/ibexa_products/editions.md b/docs/ibexa_products/editions.md index bbc686efa5..c085cdefcc 100644 --- a/docs/ibexa_products/editions.md +++ b/docs/ibexa_products/editions.md @@ -30,7 +30,7 @@ Compare all features available in [[= product_name_headless =]], [[= product_nam | [Search]([[= user_doc =]]/search/search_for_content/) | ✔ | ✔ | ✔ | | [Editorial workflow]([[= user_doc =]]/content_management/workflow_management/editorial_workflow/) | ✔ | ✔ | ✔ | | [Digital Asset Management]([[= user_doc =]]/dam/ibexa_dam/) | ✔ | ✔ | ✔ | -| [Product Information Management]([[= user_doc =]]/pim/pim/) | ✔ | ✔ | ✔ | +| [Product catalog capabilities]([[= user_doc =]]/pim/pim/) | ✔ | ✔ | ✔ | | [Date and time attribute type](date_and_time.md) | ✔ | ✔ | ✔ | | [Symbol attribute type](symbol_attribute_type.md) | ✔ | ✔ | ✔ | | [Personalization](personalization_guide.md) | ✔ | ✔ | ✔ | diff --git a/docs/ibexa_products/ibexa_commerce.md b/docs/ibexa_products/ibexa_commerce.md index 2a99fc715c..d0088d0d9b 100644 --- a/docs/ibexa_products/ibexa_commerce.md +++ b/docs/ibexa_products/ibexa_commerce.md @@ -84,7 +84,7 @@ You can set up your search engine using [[= product_name_com =]] to help clients #### Catalog management -[[= product_name_com =]] gives you the ability to manage your product repository - [PIM](pim_guide.md), and construct an infinite number of product catalogs, each with unique prices, to further customize the experience for your customers. +[[= product_name_com =]] gives you the ability to manage your product repository - [Product Catalog](product_catalog_guide.md), and construct an infinite number of product catalogs, each with unique prices, to further customize the experience for your customers. #### Transactional emails diff --git a/docs/ibexa_products/ibexa_headless.md b/docs/ibexa_products/ibexa_headless.md index f1285f5a2e..8f7fd51d9b 100644 --- a/docs/ibexa_products/ibexa_headless.md +++ b/docs/ibexa_products/ibexa_headless.md @@ -10,7 +10,7 @@ description: Get to know Ibexa Headless - an edition that focuses on content man The Headless edition of [[= product_name =]] focuses on content management. It provides tools to collaboratively create content, and interfaces (API) to distribute this content. -Multilingual, multichannel, extensible, [[= product_name_headless =]] is an advanced Content Management Framework (CMF), a Product Information Management (PIM) platform, and a Digital Asset Management (DAM) repository. +Multilingual, multichannel, extensible, [[= product_name_headless =]] is an advanced Content Management Framework (CMF) with product catalog capabilities, and a Digital Asset Management (DAM) repository. It's provided without a default front office, but with a complete back office and several APIs to manage and access content. ![Ibexa Headless](ibexa_headless.png) @@ -118,7 +118,7 @@ Like everything in the back office, the calendar is extendable: you can add an e #### Many ways to structure and organize content -[Product Information Management](pim_guide.md) (PIM) helps organize complex products and their catalogs: +[Product catalog](product_catalog_guide.md) helps organize complex products and their catalogs: - Products are organized by using product types, variants, catalogs, categories, and tags. - Product attributes are grouped and factorized among product types. For example, fabric + color + size can be shared by many clothing product types. diff --git a/docs/index.md b/docs/index.md index 27abcc3a47..70c5aa1314 100644 --- a/docs/index.md +++ b/docs/index.md @@ -122,8 +122,8 @@
@@ -185,15 +185,16 @@

- + - Product + Product catalog

diff --git a/docs/permissions/policies.md b/docs/permissions/policies.md index d86eece772..aca145f639 100644 --- a/docs/permissions/policies.md +++ b/docs/permissions/policies.md @@ -280,7 +280,7 @@ The [discount](discounts.md) policies decide which actions can be executed by gi | `comparison` | `view` | view version comparison | | `workflow` | `change_stage` | change stage in the specified workflow | [Workflow Transition](limitation_reference.md#workflow-transition-limitation) | -### PIM +### Product Catalog #### Catalogs diff --git a/docs/pim/customize_pim.md b/docs/pim/customize_pim.md deleted file mode 100644 index 877e1daebc..0000000000 --- a/docs/pim/customize_pim.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Customize PIM to the needs of your organization. -page_type: landing_page ---- - -# Customize PIM - -You can customize various areas of the Product Information Management solution to adjust it to the specific requirements of your organization. - -[[= cards([ - "pim/create_custom_attribute_type", - "pim/create_product_code_generator", - "pim/create_custom_catalog_filter", - "pim/create_custom_name_schema_strategy", -], columns=4) =]] diff --git a/docs/pim/pim.md b/docs/pim/pim.md deleted file mode 100644 index 2fd55d49f9..0000000000 --- a/docs/pim/pim.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: Ibexa DXP offers PIM functionalities, with product, product type, product variant and attribute management capabilities to manage complex products. -page_type: landing_page ---- - -# PIM (Product management) - -PIM (Product Information Management) enables handling of products offered in the shop, -including their specifications and pricing. - -[[= cards([ - "pim/pim_guide", - "pim/products", - "pim/catalogs", - "pim/pim_configuration", - "pim/prices", -], columns=3) =]] diff --git a/docs/pim/add_remote_pim_support.md b/docs/product_catalog/add_remote_pim_support.md similarity index 72% rename from docs/pim/add_remote_pim_support.md rename to docs/product_catalog/add_remote_pim_support.md index ef537b0273..96258b60e8 100644 --- a/docs/pim/add_remote_pim_support.md +++ b/docs/product_catalog/add_remote_pim_support.md @@ -4,7 +4,10 @@ description: Install and configure the Remote PIM example package. # Add Remote PIM support -To implement [Remote PIM support](pim_guide.md#remote-pim-support) you can build upon a foundation provided by [[= product_name_base =]]. +[[= product_name =]] provides flexible product catalog infrastructure that works with external Product Information Management (PIM) systems. +For advanced product data management, you can use the existing [Quable PIM integration](quable_integration.md) with [[= product_name =]]. + +To implement [Remote PIM support](product_catalog_guide.md#remote-pim-support) for a custom integration, you can build upon a foundation provided by [[= product_name_base =]]. While doing so, you must implement services that process data coming from the remote PIM. @@ -22,7 +25,7 @@ To connect to your remote PIM, provide your implementation of the following serv ## Switch to the new product catalog engine -To inform the application that the local PIM engine has been replaced by an external one, in `config/packages/ibexa_product_catalog.yaml`, set the new product catalog engine, for example: +To inform the application that the product catalog engine has been replaced by an external one, in `config/packages/ibexa_product_catalog.yaml`, set the new product catalog engine, for example: ``` yaml ibexa_product_catalog: @@ -46,12 +49,12 @@ ibexa: !!! note "Enabling the remote PIM support" - By default, the `ibexa.repositories..product_catalog.engine.type` key is set to `local`, which informs [[= product_name =]] that the built-in PIM solution is used. + By default, the `ibexa.repositories..product_catalog.engine.type` key is set to `local`, which informs [[= product_name =]] that the built-in product catalog capabilities are used. By changing this setting and the `ibexa.repositories..product_catalog.engine` setting from `default` to your custom value, you inform [[= product_name =]] that you're using a remote PIM. ## Install Remote PIM example package -The example implementation provides services that take over the role of services provided by the local PIM package. +The example implementation provides services that take over the role of services provided by the product catalog package. You can modify them to suit your needs. Install the `ibexa/example-in-memory-product-catalog` package: diff --git a/docs/pim/attributes/date_and_time.md b/docs/product_catalog/attributes/date_and_time.md similarity index 94% rename from docs/pim/attributes/date_and_time.md rename to docs/product_catalog/attributes/date_and_time.md index f01446bb98..bb84b66976 100644 --- a/docs/pim/attributes/date_and_time.md +++ b/docs/product_catalog/attributes/date_and_time.md @@ -4,7 +4,7 @@ description: Date and time attribute type allows you to store product informatio # Date and time attributes -The date and time [attribute type](products.md#product-attributes) allows you to represent date and time values as part of the product specification in the [Product Information Management](pim_guide.md) system. +The date and time [attribute type](products.md#product-attributes) allows you to represent date and time values as part of the product specification in the [product_catalog](product_catalog_guide.md). You can use it to store, for example, manufacturing dates, expiration dates, or event dates, all with specified accuracy. diff --git a/docs/pim/attributes/img/datetime.png b/docs/product_catalog/attributes/img/datetime.png similarity index 100% rename from docs/pim/attributes/img/datetime.png rename to docs/product_catalog/attributes/img/datetime.png diff --git a/docs/pim/attributes/symbol_attribute_type.md b/docs/product_catalog/attributes/symbol_attribute_type.md similarity index 97% rename from docs/pim/attributes/symbol_attribute_type.md rename to docs/product_catalog/attributes/symbol_attribute_type.md index d29643f537..1401b911bc 100644 --- a/docs/pim/attributes/symbol_attribute_type.md +++ b/docs/product_catalog/attributes/symbol_attribute_type.md @@ -6,7 +6,7 @@ description: Create a symbol attribute type that enables for the efficient repre In product specifications, the symbol attribute type enables the efficient representation of string-based data and enforces their format. -This feature allows you to store standard product identifiers (such as EAN or ISBN) in the [Product Information Management](pim_guide.md) system. +This feature allows you to store standard product identifiers (such as EAN or ISBN) in the [product catalog](product_catalog_guide.md). ## Build-in symbol attribute formats diff --git a/docs/pim/catalog_api.md b/docs/product_catalog/catalog_api.md similarity index 100% rename from docs/pim/catalog_api.md rename to docs/product_catalog/catalog_api.md diff --git a/docs/pim/catalogs.md b/docs/product_catalog/catalogs.md similarity index 100% rename from docs/pim/catalogs.md rename to docs/product_catalog/catalogs.md diff --git a/docs/pim/create_custom_attribute_type.md b/docs/product_catalog/create_custom_attribute_type.md similarity index 100% rename from docs/pim/create_custom_attribute_type.md rename to docs/product_catalog/create_custom_attribute_type.md diff --git a/docs/pim/create_custom_catalog_filter.md b/docs/product_catalog/create_custom_catalog_filter.md similarity index 100% rename from docs/pim/create_custom_catalog_filter.md rename to docs/product_catalog/create_custom_catalog_filter.md diff --git a/docs/pim/create_custom_name_schema_strategy.md b/docs/product_catalog/create_custom_name_schema_strategy.md similarity index 100% rename from docs/pim/create_custom_name_schema_strategy.md rename to docs/product_catalog/create_custom_name_schema_strategy.md diff --git a/docs/pim/create_product_code_generator.md b/docs/product_catalog/create_product_code_generator.md similarity index 78% rename from docs/pim/create_product_code_generator.md rename to docs/product_catalog/create_product_code_generator.md index 05ef3379ce..e7c000604a 100644 --- a/docs/pim/create_product_code_generator.md +++ b/docs/product_catalog/create_product_code_generator.md @@ -6,7 +6,7 @@ description: A custom product code generator enables you to control how product Product code generator strategies control what product variant codes are generated. -Besides the [built-in](pim_configuration.md#code-generation-strategy) strategies, you can create your own ones. +Besides the [built-in](product_catalog_configuration.md#code-generation-strategy) strategies, you can create your own ones. A code generator strategy must implement `Ibexa\Contracts\ProductCatalog\Local\CodeGenerator\CodeGeneratorInterface`. @@ -26,4 +26,4 @@ Then, register the strategy generator as a service and tag it with `ibexa.produc [[= include_file('code_samples/catalog/custom_code_generator_strategy/config/custom_services.yaml') =]] ``` -Use the defined `type` in [catalog configuration](pim_configuration.md#code-generation-strategy) to apply codes generated by this strategy to new product variants. +Use the defined `type` in [catalog configuration](product_catalog_configuration.md#code-generation-strategy) to apply codes generated by this strategy to new product variants. diff --git a/docs/product_catalog/customize_product_catalog.md b/docs/product_catalog/customize_product_catalog.md new file mode 100644 index 0000000000..744af90e36 --- /dev/null +++ b/docs/product_catalog/customize_product_catalog.md @@ -0,0 +1,15 @@ +--- +description: Customize the Product catalog to the needs of your organization. +page_type: landing_page +--- + +# Customize Product catalog + +You can customize various areas of the product catalog capabilities to adjust it to the specific requirements of your organization. + +[[= cards([ + "product_catalog/create_custom_attribute_type", + "product_catalog/create_product_code_generator", + "product_catalog/create_custom_catalog_filter", + "product_catalog/create_custom_name_schema_strategy", +], columns=4) =]] diff --git a/docs/pim/enable_purchasing_products.md b/docs/product_catalog/enable_purchasing_products.md similarity index 100% rename from docs/pim/enable_purchasing_products.md rename to docs/product_catalog/enable_purchasing_products.md diff --git a/docs/pim/img/catalog_custom_attribute_type.png b/docs/product_catalog/img/catalog_custom_attribute_type.png similarity index 100% rename from docs/pim/img/catalog_custom_attribute_type.png rename to docs/product_catalog/img/catalog_custom_attribute_type.png diff --git a/docs/pim/img/catalog_vat_rates.png b/docs/product_catalog/img/catalog_vat_rates.png similarity index 100% rename from docs/pim/img/catalog_vat_rates.png rename to docs/product_catalog/img/catalog_vat_rates.png diff --git a/docs/pim/img/catalogs_filters.png b/docs/product_catalog/img/catalogs_filters.png similarity index 100% rename from docs/pim/img/catalogs_filters.png rename to docs/product_catalog/img/catalogs_filters.png diff --git a/docs/pim/img/custom_catalog_filter.png b/docs/product_catalog/img/custom_catalog_filter.png similarity index 100% rename from docs/pim/img/custom_catalog_filter.png rename to docs/product_catalog/img/custom_catalog_filter.png diff --git a/docs/pim/img/diagrams_source/remote_pim_support.xml b/docs/product_catalog/img/diagrams_source/remote_pim_support.xml similarity index 100% rename from docs/pim/img/diagrams_source/remote_pim_support.xml rename to docs/product_catalog/img/diagrams_source/remote_pim_support.xml diff --git a/docs/pim/img/general_assets.png b/docs/product_catalog/img/general_assets.png similarity index 100% rename from docs/pim/img/general_assets.png rename to docs/product_catalog/img/general_assets.png diff --git a/docs/pim/img/group_base_pricing.png b/docs/product_catalog/img/group_base_pricing.png similarity index 100% rename from docs/pim/img/group_base_pricing.png rename to docs/product_catalog/img/group_base_pricing.png diff --git a/docs/pim/img/grouping_products.png b/docs/product_catalog/img/grouping_products.png similarity index 100% rename from docs/pim/img/grouping_products.png rename to docs/product_catalog/img/grouping_products.png diff --git a/docs/pim/img/how_pim_works.png b/docs/product_catalog/img/how_pim_works.png similarity index 100% rename from docs/pim/img/how_pim_works.png rename to docs/product_catalog/img/how_pim_works.png diff --git a/docs/pim/img/multilevel_variants.png b/docs/product_catalog/img/multilevel_variants.png similarity index 100% rename from docs/pim/img/multilevel_variants.png rename to docs/product_catalog/img/multilevel_variants.png diff --git a/docs/pim/img/product_assets.png b/docs/product_catalog/img/product_assets.png similarity index 100% rename from docs/pim/img/product_assets.png rename to docs/product_catalog/img/product_assets.png diff --git a/docs/pim/img/product_attribute_types.png b/docs/product_catalog/img/product_attribute_types.png similarity index 100% rename from docs/pim/img/product_attribute_types.png rename to docs/product_catalog/img/product_attribute_types.png diff --git a/docs/pim/img/product_attributes.png b/docs/product_catalog/img/product_attributes.png similarity index 100% rename from docs/pim/img/product_attributes.png rename to docs/product_catalog/img/product_attributes.png diff --git a/docs/pim/img/product_categories.png b/docs/product_catalog/img/product_categories.png similarity index 100% rename from docs/pim/img/product_categories.png rename to docs/product_catalog/img/product_categories.png diff --git a/docs/pim/img/regional_vat.png b/docs/product_catalog/img/regional_vat.png similarity index 100% rename from docs/pim/img/regional_vat.png rename to docs/product_catalog/img/regional_vat.png diff --git a/docs/pim/img/remote_pim_support.png b/docs/product_catalog/img/remote_pim_support.png similarity index 100% rename from docs/pim/img/remote_pim_support.png rename to docs/product_catalog/img/remote_pim_support.png diff --git a/docs/pim/price_api.md b/docs/product_catalog/price_api.md similarity index 100% rename from docs/pim/price_api.md rename to docs/product_catalog/price_api.md diff --git a/docs/pim/prices.md b/docs/product_catalog/prices.md similarity index 87% rename from docs/pim/prices.md rename to docs/product_catalog/prices.md index 6c9a906c3e..6109093886 100644 --- a/docs/pim/prices.md +++ b/docs/product_catalog/prices.md @@ -4,7 +4,7 @@ description: The price engine calculates product prices taking into account cust # Prices -The price engine is responsible for calculating prices for products in the [catalog](pim.md). +The price engine is responsible for calculating prices for products in the [product catalog](product_catalog.md). ## Custom pricing @@ -30,4 +30,4 @@ To use currencies in your shop, you need to first enable them in the back office ## VAT -You can [configure VAT rate globally](pim_configuration.md#vat-rates) (per SiteAccess), or set it individually for each product type and product. +You can [configure VAT rate globally](product_catalog_configuration.md#vat-rates) (per SiteAccess), or set it individually for each product type and product. diff --git a/docs/pim/product_api.md b/docs/product_catalog/product_api.md similarity index 100% rename from docs/pim/product_api.md rename to docs/product_catalog/product_api.md diff --git a/docs/product_catalog/product_catalog.md b/docs/product_catalog/product_catalog.md new file mode 100644 index 0000000000..f9fd65217e --- /dev/null +++ b/docs/product_catalog/product_catalog.md @@ -0,0 +1,20 @@ +--- +description: Ibexa DXP provides product catalog capabilities for managing products, product types, variants, attributes, pricing, and catalogs. +page_type: landing_page +--- + +# Product Catalog + +The Product Catalog provides comprehensive capabilities for managing products offered in your digital commerce experience, including their specifications, pricing, and organization. + +[[= product_name =]] offers robust product catalog infrastructure that can be used standalone. +You can also use [Quable PIM](quable_integration.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. + +[[= cards([ + "product_catalog/product_catalog_guide", + "product_catalog/quable_integration", + "product_catalog/products", + "product_catalog/catalogs", + "product_catalog/product_catalog_configuration", + "product_catalog/prices", +], columns=3) =]] diff --git a/docs/pim/pim_configuration.md b/docs/product_catalog/product_catalog_configuration.md similarity index 94% rename from docs/pim/pim_configuration.md rename to docs/product_catalog/product_catalog_configuration.md index e2c1884587..aed61089c1 100644 --- a/docs/pim/pim_configuration.md +++ b/docs/product_catalog/product_catalog_configuration.md @@ -1,10 +1,10 @@ --- -description: Configure PIM settings per Repository, with different catalog engines and VAT configurations. +description: Configure product catalog settings per repository, with different catalog engines and VAT configurations. --- -# PIM configuration +# Product catalog configuration -You can configure PIM per [Repository](repository_configuration.md). +You can configure the product catalog per [Repository](repository_configuration.md). Under `ibexa.repositories..product_catalog` [configuration key](configuration.md#configuration-files), indicate the catalog engine to use: diff --git a/docs/pim/pim_guide.md b/docs/product_catalog/product_catalog_guide.md similarity index 87% rename from docs/pim/pim_guide.md rename to docs/product_catalog/product_catalog_guide.md index 7f3f50ed16..116b36c71f 100644 --- a/docs/pim/pim_guide.md +++ b/docs/product_catalog/product_catalog_guide.md @@ -1,23 +1,26 @@ --- -description: The PIM product guide provides a full description of the features and benefits that this module brings to the clients. +description: The product catalog guide provides a full description of the features and capabilities for managing products, their specifications, variants, pricing, and organization. month_change: false --- -# PIM product guide +# Product catalog guide -## What is PIM +## What is product catalog -PIM is a Product Information Management module that lets you create, configure, and manage products, their specifications, assets, variants, and prices, but also group products into categories and catalogs. +The Product Catalog is a comprehensive set of capabilities for managing products in [[= product_name =]] that can be used standalone. +It lets you create, configure, and manage products, their specifications, assets, variants, and prices, and group products into categories and catalogs. + +You can also use [Quable PIM](quable_integration.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. ## Availability -PIM is available in all [[= product_name =]] editions. +Product Catalog capabilities are available in all [[= product_name =]] editions. -## How does PIM work +## How does Product Catalog work Products in [[= product_name =]]’s PIM have underlying content items enriched with product-specific information such as attributes, assets, prices, and others. -PIM lets you group products into categories and catalogs. +The Product Catalog lets you group products into categories and catalogs. Catalogs are collections of products selected by using configurable filters. They're specific to each of your sites or storefronts and only contain the products in them that you wish to sell in their associated storefronts. @@ -70,7 +73,7 @@ A product can only be ordered when it has either positive stock, or stock set to ### Product categories -Product categories help you to organize your products within PIM and also create relationships between them. +Product categories help you to organize your products within the product catalog and also create relationships between them. Each product can belong to multiple categories of, depending on user’s choice, different or similar character. Category can also be assigned to multiple products. @@ -150,11 +153,13 @@ To have a better overview for a specific group of products, you can filter the l - product category - the date when the product was created -Catalog filters let you narrow down the products from the PIM that are available in the given catalog. +Catalog filters let you narrow down the products from the product catalog that are available in the given catalog. Besides, the built-in catalog filters, you can also [create custom ones](create_custom_catalog_filter.md). ### Remote PIM support +[[= product_name =]] provides flexible product catalog infrastructure that works with external Product Information Management (PIM) systems. For enterprise product data management, we recommend [Quable PIM](quable_integration.md), our trusted integration partner that offers comprehensive PIM capabilities. + In [[= product_name =]], products are created and maintained by using the REST API or the back office, and their data is stored in a local database. However, in your project or organization, you might have an existing product database, or be specifically concerned about product information security. To address such needs, [[= product_name =]] provides a foundation for remote PIM support. @@ -171,7 +176,7 @@ With remote PIM support, you can take advantage of the following capabilities: ##### Purchasing -Remote PIM support ensures that integration with [Commerce features](commerce.md) mirrors the efficiency of the local PIM, even with [quick orders](quick_order.md). +Remote PIM support ensures that integration with [Commerce features](commerce.md) mirrors the efficiency of the product catalog, even with [quick orders](quick_order.md). This versatility allows for a consistent and user-friendly workflow regardless of the product's origin. ##### Pricing, stock and availability @@ -183,14 +188,14 @@ In your specific scenario, you can implement the support for availability and pr ##### Filtering -Filtering and pagination function the same as with the local PIM, relying on product attributes for effective organization of product data. -However, criteria and Sort Clauses within local PIM correspond with [[= product_name =]]'s content model. +Filtering and pagination function the same as with the product catalog, relying on product attributes for effective organization of product data. +However, criteria and Sort Clauses within product catalog correspond with [[= product_name =]]'s content model. Depending on your source of product information, you might need to adjust the implementation to be compatible with your data format. For reference, you could review the `CriterionVisitor.php` file that is part of [Remote PIM example package](add_remote_pim_support.md#install-remote-pim-example-package). ##### Catalogs -Catalogs can be created just like with the local PIM, but the criteria are limited to type, availability, and attributes. +Catalogs can be created just like with the product catalog, but the criteria are limited to type, availability, and attributes. #### Limitations @@ -213,7 +218,7 @@ Therefore, if your specific requirements aren't met, you must extend the applica - Taxonomy - URL aliases -##### Simplified presentation of PIM-related blocks and views +##### Simplified presentation of product-related blocks and views Enabling Remote PIM impacts a number of application views and blocks, such as Product view, Product list, Catalog, and Product Collection. They're simplified, for example, they don't include thumbnails and other assets, or refer to URL aliases. diff --git a/docs/pim/products.md b/docs/product_catalog/products.md similarity index 94% rename from docs/pim/products.md rename to docs/product_catalog/products.md index d4ce2f9edd..f95f4acbbf 100644 --- a/docs/pim/products.md +++ b/docs/product_catalog/products.md @@ -1,5 +1,5 @@ --- -description: Products in the PIM are characterized by attributes describing their characteristics. You can create product variants and add assets to each product and variant. +description: Products are characterized by attributes describing their characteristics. You can create product variants and add assets to each product and variant. month_change: false --- @@ -64,7 +64,7 @@ You can create product variants automatically based on attributes that have the You can create variants for any combination of values of selected attributes. In the back office you can automatically generate all possible variants for a product. -Codes for product variants are generated automatically based on the [selected strategy](pim_configuration.md#code-generation-strategy). +Codes for product variants are generated automatically based on the [selected strategy](product_catalog_configuration.md#code-generation-strategy). Each product variant has separate availability and stock information. Each variant can also have separate price rules. diff --git a/docs/product_catalog/quable_integration.md b/docs/product_catalog/quable_integration.md new file mode 100644 index 0000000000..5fca3dc049 --- /dev/null +++ b/docs/product_catalog/quable_integration.md @@ -0,0 +1,155 @@ +--- +description: Integrate Quable PIM with Ibexa DXP +--- + +# Quable PIM Integration + +[[= product_name =]] integrates with **Quable PIM** to provide enterprise-grade product information management capabilities. + +Quable is Ibexa's recommended PIM solution, offering advanced features for managing complex product catalogs, digital assets, and multi-channel product experiences. + +## Why Quable? + +Quable PIM is a leading Product Information Management solution that seamlessly integrates with [[= product_name =]]'s product catalog capabilities. This partnership enables you to: + +- **Centralize product data** - Manage all product information in one place +- **Streamline workflows** - Coordinate product data across teams and systems +- **Accelerate time-to-market** - Publish product information faster across all channels +- **Ensure data quality** - Maintain consistent, accurate product information +- **Scale globally** - Support multi-language, multi-region product catalogs + +## Integration Approach + +[[= product_name =]] provides robust [product catalog capabilities](product_catalog.md) that work with any PIM system, including: + +- Product types and variants +- Attributes and specifications +- Pricing and availability management +- Catalog organization and filtering +- Product search and discovery + +These capabilities form the foundation that enables seamless integration with Quable PIM through the [remote PIM support](add_remote_pim_support.md) framework. + +## Install Quable connector + +To integrate [[= product_name =]] with Quable PIM, you need to install the Quable connector packages and configure the connection. + +### Install packages + +Run the following commands to install the required packages: + +``` bash +composer require ibexa/quable-client +composer require ibexa/connector-quable +``` + +These commands add the Quable connector code, including services that enable communication with the Quable PIM system. + +### Get API credentials + +To connect to Quable PIM, you need an API token: + +1. Log in to your Quable instance (for example, `https://sandbox-ibexa-connector.quable.com`). + +2. Navigate to the **Tokens** section at `https://sandbox-ibexa-connector.quable.com/#tokens`. + +3. Locate or create a **Read Access Token**. + +4. Copy the token value for use in the configuration. + +!!! note "Instance URL" + + If you're using a different Quable instance, replace the sandbox URL with your organization's Quable instance URL. + +### Configure Quable connector + +In the `config/packages` folder, create a configuration file for the Quable connector, for example, `ibexa_connector_quable.yaml`: + +``` yaml +ibexa_connector_quable: + instance_url: 'https://sandbox-ibexa-connector.quable.com' + api_token: '' + # Cache is enabled by default to improve performance + cache: + enabled: true +``` + +Replace `` with the API token you obtained from Quable. + +## Configure product catalog engine + +To use Quable as the product data source, configure [[= product_name =]]'s Product Catalog to use the Quable engine. + +### Define Quable engine + +In `config/packages/ibexa_product_catalog.yaml`, add a new engine configuration: + +``` yaml +ibexa_product_catalog: + engines: + local: + type: local + options: + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product + quable: + type: quable + options: + taxonomy: quable + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product +``` + +This configuration defines two engines: the default `local` engine and the new `quable` engine. + +### Set Quable as default engine + +In your repository configuration, typically in `config/packages/ibexa.yaml`, configure the Product Catalog to use the Quable engine: + +``` yaml +ibexa: + repositories: + default: + storage: ~ + search: + engine: '%search_engine%' + connection: default + product_catalog: + engine: quable + regions: + default: ~ +``` + +By setting `engine: quable`, you inform [[= product_name =]] to use Quable PIM as the product data source instead of the local product catalog. + +## Synchronize taxonomy + +After configuring the connection, synchronize the product classifications (taxonomy) from Quable to [[= product_name =]]. + +Run the following command to synchronize classifications: + +``` bash +php bin/console ibexa:quable:classification:sync +``` + +This command imports the product classification structure from Quable PIM into [[= product_name =]], ensuring that product categories and taxonomies are aligned. + +!!! tip "Verbose output" + + Add the `-vv` flag to see detailed information about the requests sent to Quable: + + ``` bash + php bin/console ibexa:quable:classification:sync -vv + ``` + +## Next steps + +Once the Quable connector is configured and taxonomy is synchronized, you can: + +- Create and manage products in Quable PIM +- View and present product data in [[= product_name =]] +- Use product catalog features with Quable as the data source +- Build product catalogs and filter products +- Manage product pricing and availability + +For information about working with products in the user interface, see [Product management]([[= user_doc =]]/persona_paths/manage_products/). diff --git a/docs/product_guides/product_guides.md b/docs/product_guides/product_guides.md index da9283de1a..2461f299ea 100644 --- a/docs/product_guides/product_guides.md +++ b/docs/product_guides/product_guides.md @@ -19,7 +19,7 @@ Discover the primary ones with the help of product guides. Condensed content all "content_management/collaborative_editing/collaborative_editing_guide", "customer_management/customer_portal", "personalization/personalization_guide", - "pim/pim_guide", + "product_catalog/product_catalog_guide", "ibexa_cloud/ibexa_cloud_guide", "cdp/cdp_guide", ], columns=4) =]] diff --git a/docs/release_notes/ibexa_dxp_v4.1.md b/docs/release_notes/ibexa_dxp_v4.1.md index 2ceede15e5..d928e8d4f6 100644 --- a/docs/release_notes/ibexa_dxp_v4.1.md +++ b/docs/release_notes/ibexa_dxp_v4.1.md @@ -1,5 +1,5 @@ --- -description: Ibexa DXP v4.1 enhances the PIM capabilities, adds a Measurement field type and attribute and a Dynamic Targeting block for the Page Builder. +description: Ibexa DXP v4.1 enhances the product catalog capabilities, adds a Measurement field type and attribute and a Dynamic Targeting block for the Page Builder. --- diff --git a/docs/release_notes/ibexa_dxp_v4.2.md b/docs/release_notes/ibexa_dxp_v4.2.md index 6317d80b69..ce37151c45 100644 --- a/docs/release_notes/ibexa_dxp_v4.2.md +++ b/docs/release_notes/ibexa_dxp_v4.2.md @@ -1,5 +1,5 @@ --- -description: Ibexa DXP v4.2 adds the Customer Portal and user management capabilities, and enriches PIM with catalogs, product variants and product assets. +description: Ibexa DXP v4.2 adds the Customer Portal and user management capabilities, and enriches the product catalog with catalogs, product variants and product assets. --- diff --git a/docs/release_notes/ibexa_dxp_v4.3.md b/docs/release_notes/ibexa_dxp_v4.3.md index 5c56547022..cd00311c75 100644 --- a/docs/release_notes/ibexa_dxp_v4.3.md +++ b/docs/release_notes/ibexa_dxp_v4.3.md @@ -1,5 +1,5 @@ --- -description: Ibexa DXP v4.3 adds the improvements to the Customer Portal, PIM and SEO. +description: Ibexa DXP v4.3 adds the improvements to the Customer Portal, Product catalog and SEO. --- @@ -49,7 +49,7 @@ For more information, see [Work with SEO](https://doc.ibexa.co/projects/userguid ## Other changes -### PIM improvements +### Product catalog improvements #### Price Sort Clauses @@ -60,7 +60,7 @@ When querying for products, you can now use one of two price-related Sort Clause #### Usability improvements -This release also includes a number of usability improvements in PIM, +This release also includes a number of usability improvements in the product catalog, such as full information about available attribute values or improved display of Selection attributes. You can now move assets between collections by using drag and drop. @@ -94,7 +94,7 @@ For more information, refer to upgrade documentation. ### API improvements -The catalogs functionality in PIM is now covered in REST API, including: +The catalogs functionality in the product catalog is now covered in REST API, including: - [Getting catalog list](https://doc.ibexa.co/en/4.3/api/rest_api/rest_api_reference/rest_api_reference.html#product-catalog-filter-catalogs) - [Creating, modifying, copying and deleting catalogs](https://doc.ibexa.co/en/4.3/api/rest_api/rest_api_reference/rest_api_reference.html#product-catalog-create-catalog) @@ -150,7 +150,7 @@ You can retrieve the defined languages with: The new release adds `Ibexa\Contracts\Rest\Security\AuthorizationHeaderRESTRequestMatcher` service that can be used instead of `Ibexa\AdminUi\REST\Security\NonAdminRESTRequestMatcher`. It allows REST API endpoints to work with cookie-based authentication. -### PIM improvements +### Product catalog improvements #### HTTP cache support for product-related responses diff --git a/docs/release_notes/ibexa_dxp_v4.4.md b/docs/release_notes/ibexa_dxp_v4.4.md index f61078eb30..a5fd4c5e74 100644 --- a/docs/release_notes/ibexa_dxp_v4.4.md +++ b/docs/release_notes/ibexa_dxp_v4.4.md @@ -59,13 +59,13 @@ For example, you can define formats or source path for images. ### New page blocks [[% include 'snippets/experience_badge.md' %]] [[% include 'snippets/commerce_badge.md' %]] -This release introduces new page blocks that rely on Personalization and PIM features to let editors visually organize products on a page: +This release introduces new page blocks that rely on Personalization and product catalog features to let editors visually organize products on a page: - [Catalog block](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#catalog-block) displays products from a specific catalog to a selected customer group. - [Last purchased](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#last-purchased-block) displays a list of products that were recently purchased, either generally, or by a specific user. - [Last viewed](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#last-viewed-block) displays a list of products that were recently viewed. - [Product collection](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#product-collection-block) displays a collection of specifically selected products. -- [Recently added](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#recently-added-block) displays a list of products that were recently added to PIM. +- [Recently added](https://doc.ibexa.co/projects/userguide/en/4.4/content_management/block_reference/#recently-added-block) displays a list of products that were recently added to the product catalog. ### Personalization improvements diff --git a/docs/release_notes/ibexa_dxp_v4.5.md b/docs/release_notes/ibexa_dxp_v4.5.md index 38d0f80037..02fb5edb6c 100644 --- a/docs/release_notes/ibexa_dxp_v4.5.md +++ b/docs/release_notes/ibexa_dxp_v4.5.md @@ -60,7 +60,7 @@ For more information, see [Commerce](https://doc.ibexa.co/en/4.5/commerce/commer This release introduces new page blocks: -- [Bestsellers block](https://doc.ibexa.co/projects/userguide/en/4.5/content_management/block_reference/#bestsellers-block) displays a list of products from PIM that were recently a bestseller. +- [Bestsellers block](https://doc.ibexa.co/projects/userguide/en/4.5/content_management/block_reference/#bestsellers-block) displays a list of products from the product catalog that were recently a bestseller. ![Bestsellers block](img/4.5_bestsellers_block.png "Bestsellers block") diff --git a/docs/release_notes/ibexa_dxp_v4.6.md b/docs/release_notes/ibexa_dxp_v4.6.md index ba7630fd93..9eef5130e7 100644 --- a/docs/release_notes/ibexa_dxp_v4.6.md +++ b/docs/release_notes/ibexa_dxp_v4.6.md @@ -1,5 +1,5 @@ --- -description: Ibexa DXP v4.6 brings improvements to Commerce, PIM and Personalization offerings, and a number of changes in CDP and Ibexa Connect. +description: Ibexa DXP v4.6 brings improvements to Commerce, Product Catalog and Personalization offerings, and a number of changes in CDP and Ibexa Connect. title: Ibexa DXP v4.6 LTS month_change: false --- @@ -361,7 +361,7 @@ The Product Picker tool that, for example, lets you [select products eligible fo [[% set version = 'v4.6.22' %]] [[= release_note_entry_begin("Symbol attribute", '2025-08-05', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]] -The Symbol attribute allows you to store standardized identifiers of your products in the [Product Information Management](pim_guide.md) system. +The Symbol attribute allows you to store standardized identifiers of your products in the [product catalog](product_catalog_guide.md). For more information, see [Symbol attribute type](symbol_attribute_type.md). @@ -644,7 +644,7 @@ The PHP API has been enhanced with the following new classes: [[= release_note_entry_begin("Date and time attribute", '2025-03-04', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]] -The Date and time attributes allow you to represent date and time values as part of the product specification in the [Product Information Management](pim_guide.md) system. +The Date and time attributes allow you to represent date and time values as part of the product specification in the [product catalog](product_catalog_guide.md). For more information, see [Date and time attributes](date_and_time.md). @@ -1221,11 +1221,11 @@ Editors can now use a Digital Asset Management platform that enables storing med For more information, see [Ibexa DAM](https://doc.ibexa.co/projects/userguide/en/master/dam/ibexa_dam/). -#### New features and improvements in PIM +#### New features and improvements in Product Catalog ##### Remote PIM support -This release introduces a foundation for connecting [[= product_name =]] to other sources of product data. +This release introduces a foundation for connecting [[= product_name =]]'s product catalog capabilities to external Product Information Management (PIM) systems. You can use it to implement a custom solution and connect to external PIM or ERP systems, import product data, and present it side-by-side with your organization's existing content, while managing product data in a remote system of your choice. Here are the most important benefits of Remote PIM support: @@ -1244,7 +1244,7 @@ Among other things, the Remote PIM support feature allows [[= product_name =]] c - use Customer Groups to apply different prices to products, - define and use currencies. -For more information about Remote PIM support and the solution's limitations, see [PIM product guide](https://doc.ibexa.co/en/master/pim/pim_guide/#limitations). +For more information about Remote PIM support and the solution's limitations, see [Product catalog](https://doc.ibexa.co/en/5.0/product_catalog/product_catalog_guide/#limitations). ##### Virtual products diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 074b312180..144f7a6b1a 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -457,13 +457,13 @@ For more information, see [Discounts product guide](discounts_guide.md). #### Date and time attribute -The Date and time attributes allow you to represent date and time values as part of the product specification in the [Product Information Management](pim_guide.md) system. +The Date and time attributes allow you to represent date and time values as part of the product specification in the [product catalog](product_catalog_guide.md). For more information, see [Date and time attributes](date_and_time.md). #### Symbol attribute -The Symbol attributes allow you to efficiently represent the string-based data as part of the product specification in the [Product Information Management](pim_guide.md) system. +The Symbol attributes allow you to efficiently represent the string-based data as part of the product specification in the [product catalog](product_catalog_guide.md). For more information, see [Symbol attributes](symbol_attribute_type.md). @@ -635,7 +635,7 @@ The PHP API has been expanded with the following classes and interfaces: - [`Ibexa\Contracts\DiscountsCodes\Value\Struct\DiscountCodeCreateStruct `](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-DiscountsCodes-Value-Struct-DiscountCodeCreateStruct.html) - [`Ibexa\Contracts\DiscountsCodes\Value\StructDiscountCodeUpdateStruct `](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-DiscountsCodes-Value-Struct-DiscountCodeUpdateStruct.html) -??? note "PIM Attributes" +??? note "Product Catalog Attributes" - [`Ibexa\Contracts\ProductCatalogDateTimeAttribute`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/namespaces/ibexa-contracts-productcatalogdatetimeattribute.html) - [`Ibexa\Contracts\ProductCatalogSymbolAttribute`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/namespaces/ibexa-contracts-productcatalogsymbolattribute.html) @@ -667,7 +667,7 @@ The following search criteria have been added in the v5.0 release: - [`Ibexa\Contracts\Discounts\Value\Query\Criterion\StartDateCriterion`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Query-Criterion-StartDateCriterion.html) - [`Ibexa\Contracts\Discounts\Value\Query\Criterion\TypeCriterion`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Query-Criterion-TypeCriterion.html) -??? note "PIM Attributes" +??? note "Product Catalog Attributes" - [`Ibexa\Contracts\ProductCatalogDateTimeAttribute\Search\Criterion\DateTimeAttribute`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalogDateTimeAttribute-Search-Criterion-DateTimeAttribute.html) - [`Ibexa\Contracts\ProductCatalogDateTimeAttribute\Search\Criterion\DateTimeAttributeRange`](https://doc.ibexa.co/en/5.0/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalogDateTimeAttribute-Search-Criterion-DateTimeAttributeRange.html) diff --git a/mkdocs.yml b/mkdocs.yml index d6f04328b2..48a47abcb1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -348,27 +348,28 @@ nav: - AI Actions guide: ai_actions/ai_actions_guide.md - Configure AI Actions: ai_actions/configure_ai_actions.md - Extend AI Actions: ai_actions/extend_ai_actions.md - - PIM (Product management): - - PIM (Product management): pim/pim.md - - PIM guide: pim/pim_guide.md - - PIM configuration: pim/pim_configuration.md - - Products: pim/products.md + - Product catalog: + - Product catalog: product_catalog/product_catalog.md + - Product catalog guide: product_catalog/product_catalog_guide.md + - Quable PIM Integration: product_catalog/quable_integration.md + - Product catalog configuration: product_catalog/product_catalog_configuration.md + - Products: product_catalog/products.md - Attributes: - - Date and Time attribute: pim/attributes/date_and_time.md - - Symbol attribute type: pim/attributes/symbol_attribute_type.md - - Product API: pim/product_api.md - - Catalogs: pim/catalogs.md - - Catalog API: pim/catalog_api.md - - Enable purchasing products: pim/enable_purchasing_products.md - - Prices: pim/prices.md - - Price API: pim/price_api.md - - Customize PIM: - - Customize PIM: pim/customize_pim.md - - Create custom attribute type: pim/create_custom_attribute_type.md - - Create product code generator: pim/create_product_code_generator.md - - Create custom catalog filter: pim/create_custom_catalog_filter.md - - Create custom name schema: pim/create_custom_name_schema_strategy.md - - Add remote PIM support: pim/add_remote_pim_support.md + - Date and Time attribute: product_catalog/attributes/date_and_time.md + - Symbol attribute type: product_catalog/attributes/symbol_attribute_type.md + - Product API: product_catalog/product_api.md + - Catalogs: product_catalog/catalogs.md + - Catalog API: product_catalog/catalog_api.md + - Enable purchasing products: product_catalog/enable_purchasing_products.md + - Prices: product_catalog/prices.md + - Price API: product_catalog/price_api.md + - Customize product catalog: + - Customize product catalog: product_catalog/customize_product_catalog.md + - Create custom attribute type: product_catalog/create_custom_attribute_type.md + - Create product code generator: product_catalog/create_product_code_generator.md + - Create custom catalog filter: product_catalog/create_custom_catalog_filter.md + - Create custom name schema: product_catalog/create_custom_name_schema_strategy.md + - Add remote PIM support: product_catalog/add_remote_pim_support.md - Commerce: - Commerce: commerce/commerce.md - Cart: diff --git a/plugins.yml b/plugins.yml index 32e5e94c06..c3a0431fb4 100644 --- a/plugins.yml +++ b/plugins.yml @@ -217,15 +217,36 @@ plugins: 'guide/content_rendering/layout/add_register_user_template.md': 'customer_management/create_user_registration_form.md' 'guide/content_rendering/layout/customize_basket.md': 'templating/layout/add_search_form.md' - 'guide/catalog/catalog.md': 'pim/pim.md' - 'guide/catalog/catalog_configuration.md': 'pim/pim_configuration.md' - 'api/public_php_api_managing_catalog.md': 'pim/product_api.md' - 'guide/catalog/enable_purchasing_products.md': 'pim/enable_purchasing_products.md' - 'guide/catalog/create_custom_attribute_type.md': 'pim/create_custom_attribute_type.md' - 'guide/pricing/price_engine.md': 'pim/prices.md' - 'api/public_php_api_managing_prices.md': 'pim/price_api.md' - 'guide/bestsellers.md': 'pim/pim.md' - 'pim/bestsellers.md': 'pim/pim.md' + 'guide/catalog/catalog.md': 'product_catalog/product_catalog.md' + 'guide/catalog/catalog_configuration.md': 'product_catalog/product_catalog_configuration.md' + 'api/public_php_api_managing_catalog.md': 'product_catalog/product_api.md' + 'guide/catalog/enable_purchasing_products.md': 'product_catalog/enable_purchasing_products.md' + 'guide/catalog/create_custom_attribute_type.md': 'product_catalog/create_custom_attribute_type.md' + 'guide/pricing/price_engine.md': 'product_catalog/prices.md' + 'api/public_php_api_managing_prices.md': 'product_catalog/price_api.md' + 'guide/bestsellers.md': 'product_catalog/product_catalog.md' + 'pim/bestsellers.md': 'product_catalog/product_catalog.md' + + 'pim/pim.md': 'product_catalog/product_catalog.md' + 'pim/pim_guide.md': 'product_catalog/product_catalog_guide.md' + 'pim/pim_configuration.md': 'product_catalog/product_catalog_configuration.md' + 'pim/products.md': 'product_catalog/products.md' + 'pim/attributes/date_and_time.md': 'product_catalog/attributes/date_and_time.md' + 'pim/attributes/symbol_attribute_type.md': 'product_catalog/attributes/symbol_attribute_type.md' + 'pim/product_api.md': 'product_catalog/product_api.md' + 'pim/catalogs.md': 'product_catalog/catalogs.md' + 'pim/catalog_api.md': 'product_catalog/catalog_api.md' + 'pim/enable_purchasing_products.md': 'product_catalog/enable_purchasing_products.md' + 'pim/prices.md': 'product_catalog/prices.md' + 'pim/price_api.md': 'product_catalog/price_api.md' + 'pim/customize_pim.md': 'product_catalog/customize_product_catalog.md' + 'pim/create_custom_attribute_type.md': 'product_catalog/create_custom_attribute_type.md' + 'pim/create_product_code_generator.md': 'product_catalog/create_product_code_generator.md' + 'pim/create_custom_catalog_filter.md': 'product_catalog/create_custom_catalog_filter.md' + 'pim/create_custom_name_schema_strategy.md': 'product_catalog/create_custom_name_schema_strategy.md' + 'pim/add_remote_pim_support.md': 'product_catalog/add_remote_pim_support.md' + 'pim/quable_integration.md': 'product_catalog/quable_integration.md' + 'guide/basket/basket.md': 'commerce/commerce.md' 'guide/basket/wishlist_and_stored_baskets.md': 'commerce/commerce.md' 'commerce/wishlist_and_stored_baskets.md': 'commerce/commerce.md' From 8ad264fe5c729c041cdf8dff551c263c600cee21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Mar 2026 16:21:43 +0100 Subject: [PATCH 2/7] Current status --- TODO.md | 10 + .../product_catalog/add_remote_pim_support.md | 2 +- docs/product_catalog/product_catalog.md | 4 +- docs/product_catalog/product_catalog_guide.md | 4 +- docs/product_catalog/quable/install_quable.md | 137 ++++++++ docs/product_catalog/quable/quable.md | 30 ++ .../quable/quable_configuration.md | 242 ++++++++++++++ docs/product_catalog/quable/quable_other.md | 296 ++++++++++++++++++ docs/product_catalog/quable_integration.md | 155 --------- mkdocs.yml | 6 +- 10 files changed, 725 insertions(+), 161 deletions(-) create mode 100644 TODO.md create mode 100644 docs/product_catalog/quable/install_quable.md create mode 100644 docs/product_catalog/quable/quable.md create mode 100644 docs/product_catalog/quable/quable_configuration.md create mode 100644 docs/product_catalog/quable/quable_other.md delete mode 100644 docs/product_catalog/quable_integration.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000000..14dc1eb63e --- /dev/null +++ b/TODO.md @@ -0,0 +1,10 @@ +TODO: + +1) Command `ibexa:quable:languages:check` +2) Wspieramy wszystkie atrybuty - ale co z ich wyszukiwaniem? +3) Dodanie "Manage in Quable" na poziomie product view też, nie tylko product list view? +4) Regenrate API key +5) Firewall do connectora +6) Integracja z messengerem +7) Search integration +8) Embedding products diff --git a/docs/product_catalog/add_remote_pim_support.md b/docs/product_catalog/add_remote_pim_support.md index 96258b60e8..bca6330fa9 100644 --- a/docs/product_catalog/add_remote_pim_support.md +++ b/docs/product_catalog/add_remote_pim_support.md @@ -5,7 +5,7 @@ description: Install and configure the Remote PIM example package. # Add Remote PIM support [[= product_name =]] provides flexible product catalog infrastructure that works with external Product Information Management (PIM) systems. -For advanced product data management, you can use the existing [Quable PIM integration](quable_integration.md) with [[= product_name =]]. +For advanced product data management, you can use the existing [Quable PIM integration](quable/quable.md) with [[= product_name =]]. To implement [Remote PIM support](product_catalog_guide.md#remote-pim-support) for a custom integration, you can build upon a foundation provided by [[= product_name_base =]]. diff --git a/docs/product_catalog/product_catalog.md b/docs/product_catalog/product_catalog.md index f9fd65217e..7972821b97 100644 --- a/docs/product_catalog/product_catalog.md +++ b/docs/product_catalog/product_catalog.md @@ -8,11 +8,11 @@ page_type: landing_page The Product Catalog provides comprehensive capabilities for managing products offered in your digital commerce experience, including their specifications, pricing, and organization. [[= product_name =]] offers robust product catalog infrastructure that can be used standalone. -You can also use [Quable PIM](quable_integration.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. +You can also use [Quable PIM](quable/quable.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. [[= cards([ "product_catalog/product_catalog_guide", - "product_catalog/quable_integration", + "product_catalog/quable/quable", "product_catalog/products", "product_catalog/catalogs", "product_catalog/product_catalog_configuration", diff --git a/docs/product_catalog/product_catalog_guide.md b/docs/product_catalog/product_catalog_guide.md index 116b36c71f..d2edf73496 100644 --- a/docs/product_catalog/product_catalog_guide.md +++ b/docs/product_catalog/product_catalog_guide.md @@ -10,7 +10,7 @@ month_change: false The Product Catalog is a comprehensive set of capabilities for managing products in [[= product_name =]] that can be used standalone. It lets you create, configure, and manage products, their specifications, assets, variants, and prices, and group products into categories and catalogs. -You can also use [Quable PIM](quable_integration.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. +You can also use [Quable PIM](quable/quable.md) that's fully integrated into the [[= product_name_base =]] ecosystem, or the [Remote PIM](add_remote_pim_support.md) to add integration with any Product Information Management (PIM) system. ## Availability @@ -158,7 +158,7 @@ Besides, the built-in catalog filters, you can also [create custom ones](create_ ### Remote PIM support -[[= product_name =]] provides flexible product catalog infrastructure that works with external Product Information Management (PIM) systems. For enterprise product data management, we recommend [Quable PIM](quable_integration.md), our trusted integration partner that offers comprehensive PIM capabilities. +[[= product_name =]] provides flexible product catalog infrastructure that works with external Product Information Management (PIM) systems. For enterprise product data management, we recommend [Quable PIM](quable/quable.md), our trusted integration partner that offers comprehensive PIM capabilities. In [[= product_name =]], products are created and maintained by using the REST API or the back office, and their data is stored in a local database. However, in your project or organization, you might have an existing product database, or be specifically concerned about product information security. diff --git a/docs/product_catalog/quable/install_quable.md b/docs/product_catalog/quable/install_quable.md new file mode 100644 index 0000000000..9688f721cc --- /dev/null +++ b/docs/product_catalog/quable/install_quable.md @@ -0,0 +1,137 @@ +--- +description: Install and configure Quable PIM connector for Ibexa DXP +--- + +# Install Quable connector + +To integrate [[= product_name =]] with Quable PIM, you need to install the Quable connector packages, configure the connection, and set up synchronization. + +## Install packages + +Before installing the Quable connector, ensure you have access to a [Quable PIM instance](https://quable.com). + +Run the following commands to install the required packages: + +``` bash +composer require ibexa/quable-client +composer require ibexa/connector-quable +``` + +These commands add the Quable connector code, including services that enable communication with the Quable PIM system. + +## Get API credentials + +To connect to Quable PIM, you need an API token: + +1. Log in to your Quable instance (for example, `https:/example.quable.com`). +2. Navigate to the [API Tokens](https://docs.quable.com/v5-EN/docs/system-api-tokens) section +3. Copy the **Read Access Token** value for use in the configuration. + +## Configure Quable connector + +In the `config/packages` folder, create a configuration file for the Quable connector, for example, `ibexa_connector_quable.yaml`: + +``` yaml +ibexa_connector_quable: + instance_url: 'https://example.quable.com' + api_token: '' + channel_code: '' +``` + +Replace `` with the Read Access API token you obtained from Quable. + +[Quable's channels](https://docs.quable.com/v5-EN/docs/content-channels) allow you to distribute your product information to defined recipients, for example e-commerce platforms. +Select the Quable channel you want to integrate with [[= product_name =]]. + +## Configure product catalog engine + +To use Quable as the product data source, configure [[= product_name =]]'s product catalog to use the Quable engine. + +### Define Quable engine + +In `config/packages/ibexa_product_catalog.yaml`, add a new engine configuration: + +``` yaml +ibexa_product_catalog: + engines: + local: + type: local + options: + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product + quable: + type: quable + options: + taxonomy: quable + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product +``` + +This configuration defines two engines: the default `local` engine and the new `quable` engine. + +### Set Quable as default engine + +In your repository configuration, typically in `config/packages/ibexa.yaml`, configure the Product Catalog to use the Quable engine as the product data source: + +``` yaml +ibexa: + repositories: + default: + storage: ~ + search: + engine: '%search_engine%' + connection: default + product_catalog: + engine: quable + regions: + default: ~ +``` + +## Set up languages + +When working with Quable products, + +## Synchronize taxonomy + +After configuring the integration, synchronize [product classifications from Quable](https://docs.quable.com/v5-EN/docs/documents-classification-new-version) to [[= product_name =]]'s [taxonomies](taxonomy.md). + +Run the following command to synchronize classifications: + +``` bash +php bin/console ibexa:quable:classification:sync +``` + +This command imports the product classification structure from Quable PIM into [[= product_name =]], ensuring that product categories and taxonomies are aligned. + +!!! note "Verbose output" + + Add the `-vv` flag to see detailed information about the requests sent to Quable: + + ``` bash + php bin/console ibexa:quable:classification:sync -vv + ``` + +## Set up real-time synchronization + +Quable PIM can notify [[= product_name =]] about product data changes in real-time using webhooks. +This ensures that product information stays synchronized automatically without manual intervention. + +Webhook configuration requires setup in both Quable PIM and [[= product_name =]]. + +1. Create a new [webhook in Quable](https://docs.quable.com/v5-EN/docs/webhook). +2. Set the webhook's name and provide the URL to your [[= product_name =]] instance +3. Mark it as **Activated** +4. Enter a secret value for the **Authorization Header** +5. Choose the following scopes: + - Products: created, updated, deleted + - Classifications: created, updated, deleted + +The **Authorization Header** value is a [secret that must be kept secure](security_checklist.md#app-secret-and-other-secrets). + +!!! note + + For local development and testing, consider using one of the avalable [tunnel providers](https://github.com/anderspitman/awesome-tunneling) to make your instance accessible + + + +For information about working with products in the user interface, see [Product management]([[= user_doc =]]/persona_paths/manage_products/). diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md new file mode 100644 index 0000000000..8eb93c7f93 --- /dev/null +++ b/docs/product_catalog/quable/quable.md @@ -0,0 +1,30 @@ +--- +description: Quable PIM integration with Ibexa DXP +--- + +# Quable PIM Integration + +[[= product_name =]] integrates with [Quable](https://www.quable.com/en) to provide product information management as part of the [[= product_name_base =]] orchestration platform. + +## About Quable and Ibexa + +Quable is Ibexa's PIM solution for managing complex product catalogs. +As part of the Ibexa orchestration platform, Quable acts as the source of truth about products that feeds every channel with accurate product data. + +Quable becomes the source that you can use for powerful recommendations, personalized campaigns, and interactive digital experiences across every market. +Teams, partners, and customers have seamless access to product information—details, translations, photographs, videos, PDFs — all validated to meet regional and compliance requirements. + +## Integration documentation + +[[= cards([ + "product_catalog/quable/install_quable", + "product_catalog/quable/quable_configuration", + "product_catalog/quable/quable_other", +], columns=3) =]] + +## User documentation + +For information about working with Quable products in the [[= product_name =]] user interface, see: + +- [Product management]([[= user_doc =]]/persona_paths/manage_products/) +- X - link to Quable doc here? diff --git a/docs/product_catalog/quable/quable_configuration.md b/docs/product_catalog/quable/quable_configuration.md new file mode 100644 index 0000000000..61ef5cedce --- /dev/null +++ b/docs/product_catalog/quable/quable_configuration.md @@ -0,0 +1,242 @@ +--- +description: Quable PIM connector configuration reference for Ibexa DXP +--- + +# Quable configuration reference + +This page provides a complete reference for configuring the Quable PIM connector in [[= product_name =]]. + +## Connector configuration + +The Quable connector is configured in a YAML file in the `config/packages` directory, typically named `ibexa_connector_quable.yaml`. + +### Basic configuration + +``` yaml +ibexa_connector_quable: + instance_url: 'https://your-instance.quable.com' + api_token: '%env(QUABLE_API_TOKEN)%' + webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' + cache: + enabled: true +``` + +### Configuration parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `instance_url` | string | Yes | The URL of your Quable PIM instance (e.g., `https://example.quable.com`) | +| `api_token` | string | Yes | API authentication token from Quable. Use environment variables for security. | +| `webhook_secret` | string | No | Secret key for validating webhook requests from Quable. Required if using real-time synchronization. | +| `cache.enabled` | boolean | No | Enable or disable caching of Quable data. Default: `true`. Recommended for production. | + +!!! tip "Environment variables" + + Store sensitive configuration values like API tokens in environment variables or `.env` files: + + ``` + QUABLE_API_TOKEN=your_read_access_token_here + QUABLE_WEBHOOK_SECRET=your_webhook_secret_here + ``` + +## Product Catalog engine configuration + +Configure [[= product_name =]]'s Product Catalog to use Quable as the data source in `config/packages/ibexa_product_catalog.yaml`. + +### Engine definition + +``` yaml +ibexa_product_catalog: + engines: + local: + type: local + options: + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product + quable: + type: quable + options: + taxonomy: quable + root_location_remote_id: ibexa_product_catalog_root + product_type_group_identifier: product +``` + +### Engine options + +| Option | Description | Default | +|--------|-------------|---------| +| `taxonomy` | Taxonomy identifier for Quable classifications | `quable` | +| `root_location_remote_id` | Remote ID of the root location for product catalog | `ibexa_product_catalog_root` | +| `product_type_group_identifier` | Identifier for the product type group | `product` | + +### Repository configuration + +Set the Quable engine as the default for your repository in `config/packages/ibexa.yaml`: + +``` yaml +ibexa: + repositories: + default: + storage: ~ + search: + engine: '%search_engine%' + connection: default + product_catalog: + engine: quable + regions: + default: ~ +``` + +## Cache configuration + +The Quable connector implements caching to reduce API calls and improve performance. + +### Cache settings + +``` yaml +ibexa_connector_quable: + instance_url: 'https://your-instance.quable.com' + api_token: '%env(QUABLE_API_TOKEN)%' + cache: + enabled: true +``` + +### Cache behavior + +When caching is enabled: + +- Product data is cached after the first request +- Subsequent requests use cached data instead of calling Quable API +- Cache is automatically invalidated when webhooks receive update notifications +- Manual cache clearing: `php bin/console cache:clear` + +!!! note "Production recommendation" + + Always enable caching in production environments to minimize API calls and improve response times. Cache invalidation is handled automatically via webhooks. + +## Language alignment + +[[= product_name =]] and Quable must have matching language configurations for proper data synchronization. + +### Language configuration requirements + +Ensure that: + +1. All languages enabled in [[= product_name =]] exist in Quable PIM +2. Language codes match between systems (e.g., `eng-GB`, `fre-FR`) +3. Default language is consistent across both systems + +### Example language configuration + +In [[= product_name =]] (`config/packages/ibexa.yaml`): + +``` yaml +ibexa: + system: + default: + languages: + - eng-GB + - fre-FR + - ger-DE +``` + +Verify these language codes exist in your Quable PIM instance. + +!!! warning "Mismatched languages" + + If languages don't match between systems, product translations may not display correctly or may be missing entirely. + +## Channel selection + +For multi-channel Quable setups, you can configure which channel's data to display in [[= product_name =]]. + +!!! note "Channel configuration" + + Channel selection configuration varies by deployment. Consult Ibexa support for channel-specific configuration options. + +## Synchronization configuration + +### Taxonomy synchronization + +Taxonomy (classification) synchronization is triggered manually via console command: + +``` bash +php bin/console ibexa:quable:classification:sync +``` + +**Command options:** + +- `-vv` - Verbose output showing detailed API requests +- Add to cron for periodic synchronization if not using webhooks + +### Real-time synchronization + +Real-time synchronization uses webhooks configured in Quable PIM. When enabled, product data updates automatically when changes occur in Quable. + +**Webhook configuration:** + +``` yaml +ibexa_connector_quable: + instance_url: 'https://your-instance.quable.com' + api_token: '%env(QUABLE_API_TOKEN)%' + webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' +``` + +The `webhook_secret` validates incoming webhook requests to ensure they originate from your Quable instance. + +### What synchronizes + +| Data Type | Synchronization Method | Notes | +|-----------|----------------------|-------| +| Products | Real-time (webhooks) or API calls | Product details, attributes, variants | +| Product Types | Real-time (webhooks) or API calls | Type definitions and attribute schemas | +| Attributes | Real-time (webhooks) or API calls | Attribute definitions and values | +| Classifications/Categories | Manual command or webhooks | Hierarchical category structure | +| Assets | On-demand | Images, videos, documents linked to products | + +### What doesn't synchronize + +The following data remains independent in each system: + +- [[= product_name =]] content items and content types +- User accounts and permissions +- Site configurations +- Custom prices set in [[= product_name =]] (override Quable prices) +- Local product catalogs + +## Performance optimization + +### Optimize API calls + +1. **Enable caching** - Reduces repeated API calls +2. **Use webhooks** - Avoid polling for updates +3. **Limit verbose logging** - Use `-vv` only for debugging + +### Connection pooling + +The Quable connector uses Symfony's HTTP client with connection pooling enabled by default for optimal performance. + +## Environment-specific configuration + +### Development environment + +``` yaml +# config/packages/dev/ibexa_connector_quable.yaml +ibexa_connector_quable: + instance_url: 'https://example.quable.com' + api_token: '%env(QUABLE_API_TOKEN)%' + cache: + enabled: false # Disable for development to always fetch fresh data +``` + +### Production environment + +``` yaml +# config/packages/prod/ibexa_connector_quable.yaml +ibexa_connector_quable: + instance_url: 'https://production.quable.com' + api_token: '%env(QUABLE_API_TOKEN)%' + webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' + cache: + enabled: true # Always enable in production +``` diff --git a/docs/product_catalog/quable/quable_other.md b/docs/product_catalog/quable/quable_other.md new file mode 100644 index 0000000000..87beb7eb4c --- /dev/null +++ b/docs/product_catalog/quable/quable_other.md @@ -0,0 +1,296 @@ +--- +description: Quable PIM integration - Architecture, features, limitations, and developer reference +--- + +# Additional technical information + +This page contains additional technical information about the Quable PIM integration with [[= product_name =]], including architecture details, supported features, technical limitations, and developer reference materials. + +!!! note + + This page is a collection of technical materials for review. Content may be reorganized into separate pages in the future. + +## Architecture + +### Integration overview + +The Quable integration is built on [[= product_name =]]'s [Remote PIM framework](../add_remote_pim_support.md), which provides a foundation for connecting external Product Information Management systems. + +**Key architectural principles:** + +- **Single source of truth**: Quable PIM owns all product data +- **Read-only in DXP**: Products are displayed and used in [[= product_name =]] but edited in Quable +- **Service-oriented**: Integration uses service interfaces for data access +- **Event-driven sync**: Real-time updates via webhooks keep data synchronized +- **Cached data access**: API responses are cached for performance + +### Data flow + +``` +Quable PIM → Quable API → Quable Connector → Product Catalog Services → DXP Features + ↓ + Cache Layer + ↓ + Storefront Display +``` + +**Data flow steps:** + +1. **Product data originates** in Quable PIM +2. **Quable API** exposes product data via REST endpoints +3. **Quable Connector** fetches and transforms data using object mappers +4. **Product Catalog Services** provide standardized access to product data +5. **DXP Features** (Product Picker, Page Builder blocks, etc.) consume product data +6. **Storefront** displays products to end users + +**Synchronization triggers:** + +- **Manual**: Command-line sync for taxonomy/classifications +- **Automatic**: Webhooks notify DXP of product changes in real-time +- **On-demand**: API calls when specific product data is requested + +### Service layer architecture + +The Quable connector implements the following service interfaces: + +| Service | Purpose | Key Methods | +|---------|---------|-------------| +| `ProductService` | Retrieve product data | `getProduct()`, `findProducts()`, `findProductsByCode()` | +| `ProductTypeService` | Get product type information | `getProductType()`, `findProductTypes()` | +| `AttributeDefinitionService` | Access attribute definitions | `getAttributeDefinition()`, `findAttributeDefinitions()` | +| `AttributeGroupService` | Manage attribute groups | `getAttributeGroup()`, `findAttributeGroups()` | +| `AssetService` | Retrieve product assets | `findAssets()` | + +**Service characteristics:** + +- Services implement standard [[= product_name =]] Product Catalog interfaces +- Responses are cached by default to minimize API calls +- Services transform Quable data structures into [[= product_name =]] value objects + +### Object mapping and transformers + +The connector uses object mappers and transformers to convert Quable API responses into [[= product_name =]] value objects: + +**Value objects:** + +- `Product` - Complete product data including attributes, variants, assets +- `ProductType` - Product type definitions and attribute schemas +- `AttributeDefinition` - Individual attribute definitions +- `AttributeGroup` - Groups of related attributes +- `Attribute` - Attribute values with type information + +**Transformers:** + +- `ProductTypeTransformer` - Maps product types from Quable to DXP format +- `AttributesListTransformer` - Builds attribute lists from raw data +- `Product/NameTransformer` - Derives product names from attributes +- `AttributeDefinition/NameTransformer` - Extracts attribute definition names + +### Permission handling + +Products from Quable are treated as remote objects for permission purposes: + +- Permission context is provided by `Quable\Permissions\ContextProvider` +- Standard [[= product_name =]] permission system applies to product operations +- Create/Edit/Delete operations are disabled for remote products (handled in Quable) +- View permissions can be controlled via [[= product_name =]] roles and policies + +!!! note "Permission limitations" + + Some permission limitations exist for remote products. Product Type limitations for policies require special handling. See [Known Limitations](#technical-limitations) below. + +### Caching strategy + +The Quable connector implements multi-level caching: + +**Service-level caching:** + +- In-memory cache within service instances +- Reduces duplicate API calls within the same request +- Cache lifetime: duration of PHP process + +**Application-level caching:** + +- Symfony cache component stores API responses +- Configured cache pool for Quable connector +- Cache invalidation via webhooks on data changes + +**Cache configuration:** + +```yaml +ibexa_connector_quable: + cache: + enabled: true # Enable/disable caching +``` + +### API communication patterns + +The connector communicates with Quable using: + +- **HTTP Client**: Symfony HTTP client with connection pooling +- **Authentication**: Bearer token authentication using API token +- **Response format**: JSON +- **Error handling**: Graceful degradation with logging + +## Features and limitations + +### Supported features + +#### Product display and viewing + +✅ **Product listing**: View all products from Quable in [[= product_name =]] Product Catalog interface + +✅ **Product details**: Access complete product information including attributes, specifications, and assets + +✅ **Multi-language support**: Display products in multiple languages with localized attribute values + +✅ **Variant handling**: View product variants with their specific attribute combinations + +✅ **Product attributes**: All Quable attribute types are mapped and displayed in [[= product_name =]] + +#### Product Picker integration + +✅ **Product selection**: Use Product Picker to select Quable products in content editing + +✅ **Category filtering**: Filter products by Quable classifications in Product Picker + +✅ **Code search**: Search products by code/SKU + +✅ **Product preview**: Preview product information before selection + +#### Category and classification + +✅ **Category synchronization**: Import Quable classification structure into [[= product_name =]] taxonomy + +✅ **Hierarchical categories**: Maintain parent-child relationships from Quable + +✅ **Category browsing**: Navigate products by category in [[= product_name =]] + +✅ **Category filtering**: Filter product lists by category + +#### Product Catalog management + +✅ **Catalog creation**: Create product catalogs using Quable product data + +✅ **Catalog filters**: Apply filters to include specific Quable products in catalogs + +✅ **Pricing management**: View base prices from Quable, set custom prices in [[= product_name =]] + +✅ **Availability tracking**: Access product availability information + +#### Page Builder blocks + +✅ **Product Collection block**: Display selected Quable products on pages + +✅ **Product Catalog block**: Show full product listings from catalogs + +✅ **Product Embed block**: Embed individual products in content + +✅ **Dashboard blocks**: Use Quable products in dashboard widgets (e.g., Products by categories) + +#### Content integration + +✅ **Product embeds in rich text**: Embed Quable products within text content (requires configuration) + +✅ **Product specification fields**: Add product specification fields to content types + +✅ **Content-product relationships**: Link content items to Quable products + +### Technical limitations + +#### Read-only product access + +❌ **No product creation**: Products cannot be created in [[= product_name =]]. Create products in Quable PIM. + +❌ **No product editing**: Product data is read-only in [[= product_name =]]. Edit products in Quable, changes sync automatically. + +❌ **No variant management**: Variants are managed in Quable only. + +❌ **Edit action redirects**: Clicking "Edit" on a Quable product redirects to Quable PIM interface. + +#### Category management + +❌ **No category creation**: Categories cannot be created in [[= product_name =]]. Manage in Quable. + +❌ **No category editing**: Category structure is synchronized from Quable, cannot be modified in [[= product_name =]]. + +❌ **No manual assignment**: Products cannot be manually assigned to categories in [[= product_name =]]. + +#### REST API restrictions + +❌ **Product CRUD endpoints disabled**: REST API endpoints for creating, editing, and deleting products are disabled for Quable products. + +❌ **Variant API limitations**: Variant management API endpoints are not available for remote products. + +#### Permission and policy + +⚠️ **Policy limitation validation**: Product Type limitations in policies may not validate correctly. This is a known issue being addressed. + +❌ **No content tab for categories**: Content editing tab is not applicable to Quable categories. + +#### User interface + +❌ **Create actions hidden**: "Create Product" and "Create Variant" buttons are hidden when using Quable engine. + +❌ **No inline editing**: Product attributes cannot be edited inline in [[= product_name =]] interface. + +❌ **Special character handling**: Products with codes containing reserved characters may require special handling. + +### Design decisions + +#### Why read-only in DXP? + +**Single source of truth principle**: Keeping product data creation and editing exclusively in Quable ensures: + +- **Data integrity**: No conflicts between systems +- **Clear ownership**: Quable owns product data, [[= product_name =]] displays it +- **Audit trail**: All changes tracked in Quable +- **Workflow consistency**: Product teams work in one system + +#### System boundaries + +**Quable responsibilities:** +- Product creation and editing +- Attribute definition and management +- Category/classification structure +- Product assets (images, documents) +- Product variants +- Core product data + +**[[= product_name =]] responsibilities:** +- Product display and presentation +- Content-product relationships +- Catalog organization for storefronts +- Custom pricing (overrides) +- Product embeds in content +- Storefront experience + +### UI feature integration + +The following UI features work seamlessly with Quable products. Refer to user documentation for detailed workflows: + +#### Product Picker + +- Select Quable products when editing content +- Filter by category, search by name/code +- Preview product details before selection +- **User docs**: [Product management]([[= user_doc =]]/persona_paths/manage_products/) + +#### Page Builder blocks + +- **Product Collection**: Manually select products to display +- **Product Catalog**: Automatically show products from a catalog +- **Product Embed**: Embed individual products in page content +- **User docs**: [Using Page Builder]([[= user_doc =]]/page_builder/) + +#### Dashboard + +- **Products by categories** widget shows product distribution +- Quable categories available for visualization +- **User docs**: [Dashboard management]([[= user_doc =]]/persona_paths/manage_dashboard/) + +#### Product navigation + +- **Edit button**: Redirects to Quable PIM for product editing +- **View in Quable**: Link to source product in Quable interface +- Seamless navigation between systems diff --git a/docs/product_catalog/quable_integration.md b/docs/product_catalog/quable_integration.md deleted file mode 100644 index 5fca3dc049..0000000000 --- a/docs/product_catalog/quable_integration.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -description: Integrate Quable PIM with Ibexa DXP ---- - -# Quable PIM Integration - -[[= product_name =]] integrates with **Quable PIM** to provide enterprise-grade product information management capabilities. - -Quable is Ibexa's recommended PIM solution, offering advanced features for managing complex product catalogs, digital assets, and multi-channel product experiences. - -## Why Quable? - -Quable PIM is a leading Product Information Management solution that seamlessly integrates with [[= product_name =]]'s product catalog capabilities. This partnership enables you to: - -- **Centralize product data** - Manage all product information in one place -- **Streamline workflows** - Coordinate product data across teams and systems -- **Accelerate time-to-market** - Publish product information faster across all channels -- **Ensure data quality** - Maintain consistent, accurate product information -- **Scale globally** - Support multi-language, multi-region product catalogs - -## Integration Approach - -[[= product_name =]] provides robust [product catalog capabilities](product_catalog.md) that work with any PIM system, including: - -- Product types and variants -- Attributes and specifications -- Pricing and availability management -- Catalog organization and filtering -- Product search and discovery - -These capabilities form the foundation that enables seamless integration with Quable PIM through the [remote PIM support](add_remote_pim_support.md) framework. - -## Install Quable connector - -To integrate [[= product_name =]] with Quable PIM, you need to install the Quable connector packages and configure the connection. - -### Install packages - -Run the following commands to install the required packages: - -``` bash -composer require ibexa/quable-client -composer require ibexa/connector-quable -``` - -These commands add the Quable connector code, including services that enable communication with the Quable PIM system. - -### Get API credentials - -To connect to Quable PIM, you need an API token: - -1. Log in to your Quable instance (for example, `https://sandbox-ibexa-connector.quable.com`). - -2. Navigate to the **Tokens** section at `https://sandbox-ibexa-connector.quable.com/#tokens`. - -3. Locate or create a **Read Access Token**. - -4. Copy the token value for use in the configuration. - -!!! note "Instance URL" - - If you're using a different Quable instance, replace the sandbox URL with your organization's Quable instance URL. - -### Configure Quable connector - -In the `config/packages` folder, create a configuration file for the Quable connector, for example, `ibexa_connector_quable.yaml`: - -``` yaml -ibexa_connector_quable: - instance_url: 'https://sandbox-ibexa-connector.quable.com' - api_token: '' - # Cache is enabled by default to improve performance - cache: - enabled: true -``` - -Replace `` with the API token you obtained from Quable. - -## Configure product catalog engine - -To use Quable as the product data source, configure [[= product_name =]]'s Product Catalog to use the Quable engine. - -### Define Quable engine - -In `config/packages/ibexa_product_catalog.yaml`, add a new engine configuration: - -``` yaml -ibexa_product_catalog: - engines: - local: - type: local - options: - root_location_remote_id: ibexa_product_catalog_root - product_type_group_identifier: product - quable: - type: quable - options: - taxonomy: quable - root_location_remote_id: ibexa_product_catalog_root - product_type_group_identifier: product -``` - -This configuration defines two engines: the default `local` engine and the new `quable` engine. - -### Set Quable as default engine - -In your repository configuration, typically in `config/packages/ibexa.yaml`, configure the Product Catalog to use the Quable engine: - -``` yaml -ibexa: - repositories: - default: - storage: ~ - search: - engine: '%search_engine%' - connection: default - product_catalog: - engine: quable - regions: - default: ~ -``` - -By setting `engine: quable`, you inform [[= product_name =]] to use Quable PIM as the product data source instead of the local product catalog. - -## Synchronize taxonomy - -After configuring the connection, synchronize the product classifications (taxonomy) from Quable to [[= product_name =]]. - -Run the following command to synchronize classifications: - -``` bash -php bin/console ibexa:quable:classification:sync -``` - -This command imports the product classification structure from Quable PIM into [[= product_name =]], ensuring that product categories and taxonomies are aligned. - -!!! tip "Verbose output" - - Add the `-vv` flag to see detailed information about the requests sent to Quable: - - ``` bash - php bin/console ibexa:quable:classification:sync -vv - ``` - -## Next steps - -Once the Quable connector is configured and taxonomy is synchronized, you can: - -- Create and manage products in Quable PIM -- View and present product data in [[= product_name =]] -- Use product catalog features with Quable as the data source -- Build product catalogs and filter products -- Manage product pricing and availability - -For information about working with products in the user interface, see [Product management]([[= user_doc =]]/persona_paths/manage_products/). diff --git a/mkdocs.yml b/mkdocs.yml index 48a47abcb1..4e575dd41d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -351,7 +351,11 @@ nav: - Product catalog: - Product catalog: product_catalog/product_catalog.md - Product catalog guide: product_catalog/product_catalog_guide.md - - Quable PIM Integration: product_catalog/quable_integration.md + - Quable PIM integration: + - Quable overview: product_catalog/quable/quable.md + - Install Quable: product_catalog/quable/install_quable.md + - Quable configuration: product_catalog/quable/quable_configuration.md + - Additional information: product_catalog/quable/quable_other.md - Product catalog configuration: product_catalog/product_catalog_configuration.md - Products: product_catalog/products.md - Attributes: From 9263e01187d72c31c2ff0be859e6234ea5e47bc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 12 Mar 2026 12:52:29 +0100 Subject: [PATCH 3/7] Install doc ready? --- ...e_configuration.md => configure_quable.md} | 31 +++++- docs/product_catalog/quable/install_quable.md | 105 ++++++++++++------ docs/product_catalog/quable/quable.md | 25 ++--- mkdocs.yml | 3 +- 4 files changed, 107 insertions(+), 57 deletions(-) rename docs/product_catalog/quable/{quable_configuration.md => configure_quable.md} (77%) diff --git a/docs/product_catalog/quable/quable_configuration.md b/docs/product_catalog/quable/configure_quable.md similarity index 77% rename from docs/product_catalog/quable/quable_configuration.md rename to docs/product_catalog/quable/configure_quable.md index 61ef5cedce..a57c5b82dc 100644 --- a/docs/product_catalog/quable/quable_configuration.md +++ b/docs/product_catalog/quable/configure_quable.md @@ -2,7 +2,7 @@ description: Quable PIM connector configuration reference for Ibexa DXP --- -# Quable configuration reference +# Configure Quable This page provides a complete reference for configuring the Quable PIM connector in [[= product_name =]]. @@ -25,10 +25,14 @@ ibexa_connector_quable: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `instance_url` | string | Yes | The URL of your Quable PIM instance (e.g., `https://example.quable.com`) | -| `api_token` | string | Yes | API authentication token from Quable. Use environment variables for security. | +| `instance_url` | string | Yes | The URL of your Quable PIM instance (for example, `https://example.quable.com`) | +| `api_token` | string | Yes | API authentication token from Quable. For security, using environment variables is recommended | | `webhook_secret` | string | No | Secret key for validating webhook requests from Quable. Required if using real-time synchronization. | -| `cache.enabled` | boolean | No | Enable or disable caching of Quable data. Default: `true`. Recommended for production. | +| `cache.enabled` | boolean | No | Globally enable or disable all Quable caches. Default: `true`. Set to `false` to bypass all service caches at once. | +| `cache.attribute` | boolean | No | Enable or disable caching for attribute definitions. Default: `true`. | +| `cache.attribute_group` | boolean | No | Enable or disable caching for attribute group definitions. Default: `true`. | +| `cache.product` | boolean | No | Enable or disable caching for product data. Default: `true`. | +| `cache.product_type` | boolean | No | Enable or disable caching for product type definitions. Default: `true`. | !!! tip "Environment variables" @@ -99,6 +103,10 @@ ibexa_connector_quable: api_token: '%env(QUABLE_API_TOKEN)%' cache: enabled: true + attribute: true + attribute_group: true + product: true + product_type: true ``` ### Cache behavior @@ -110,6 +118,12 @@ When caching is enabled: - Cache is automatically invalidated when webhooks receive update notifications - Manual cache clearing: `php bin/console cache:clear` +Each of the four service caches (`attribute`, `attribute_group`, `product`, `product_type`) can be disabled independently while the others remain active. When a service cache is disabled, it falls back to an in-memory adapter that is not shared between requests (effectively bypassing persistence while still avoiding unbounded API call loops within a single request). + +!!! tip "Granular cache control" + + Use per-service cache flags instead of globally disabling all caches. For example, when debugging product queries you can disable only the `product` cache while keeping `attribute` and `attribute_group` caches enabled. This avoids flooding Quable's API with redundant attribute definition requests (which can reach 80+ extra calls per product list request when fully uncached). + !!! note "Production recommendation" Always enable caching in production environments to minimize API calls and improve response times. Cache invalidation is handled automatically via webhooks. @@ -226,9 +240,16 @@ ibexa_connector_quable: instance_url: 'https://example.quable.com' api_token: '%env(QUABLE_API_TOKEN)%' cache: - enabled: false # Disable for development to always fetch fresh data + enabled: true + product: false # Disable only product cache to see live query effects + # attribute, attribute_group, and product_type remain cached + # to avoid excessive API calls for definition data ``` +!!! note "Disabling all caches" + + Setting `enabled: false` disables all service caches at once. Use this only when you need to debug the full pipeline without any caching, as it significantly increases the number of API calls to Quable. + ### Production environment ``` yaml diff --git a/docs/product_catalog/quable/install_quable.md b/docs/product_catalog/quable/install_quable.md index 9688f721cc..34ee62912c 100644 --- a/docs/product_catalog/quable/install_quable.md +++ b/docs/product_catalog/quable/install_quable.md @@ -4,11 +4,13 @@ description: Install and configure Quable PIM connector for Ibexa DXP # Install Quable connector -To integrate [[= product_name =]] with Quable PIM, you need to install the Quable connector packages, configure the connection, and set up synchronization. +To integrate [[= product_name =]] with [[= pim_product_name =]] PIM, you need to install the [[= pim_product_name =]] connector packages, configure the connection, and set up synchronization. -## Install packages +## Create [[= pim_product_name =]] instance + +Before installing the [[= pim_product_name =]] connector, ensure you have access to a [[[= pim_product_name =]] PIM instance](https://quable.com). -Before installing the Quable connector, ensure you have access to a [Quable PIM instance](https://quable.com). +## Install packages Run the following commands to install the required packages: @@ -17,19 +19,19 @@ composer require ibexa/quable-client composer require ibexa/connector-quable ``` -These commands add the Quable connector code, including services that enable communication with the Quable PIM system. +These commands add the [[= pim_product_name =]] connector code, including services that enable communication with [[= pim_product_name =]] PIM. ## Get API credentials -To connect to Quable PIM, you need an API token: +To connect to [[= pim_product_name =]] PIM, you need an API token: -1. Log in to your Quable instance (for example, `https:/example.quable.com`). +1. Log in to your [[= pim_product_name =]] instance (for example, `https:/example.quable.com`). 2. Navigate to the [API Tokens](https://docs.quable.com/v5-EN/docs/system-api-tokens) section 3. Copy the **Read Access Token** value for use in the configuration. -## Configure Quable connector +## Configure [[= pim_product_name =]] connector -In the `config/packages` folder, create a configuration file for the Quable connector, for example, `ibexa_connector_quable.yaml`: +In `config/packages/ibexa_connector_quable.yaml`, specify the configuration for the [[= pim_product_name =]] connector: ``` yaml ibexa_connector_quable: @@ -38,20 +40,22 @@ ibexa_connector_quable: channel_code: '' ``` -Replace `` with the Read Access API token you obtained from Quable. +Replace `` with the Read Access API token you obtained from [[= pim_product_name =]] in the previous step. -[Quable's channels](https://docs.quable.com/v5-EN/docs/content-channels) allow you to distribute your product information to defined recipients, for example e-commerce platforms. -Select the Quable channel you want to integrate with [[= product_name =]]. +[[[= pim_product_name =]]'s channels](https://docs.quable.com/v5-EN/docs/content-channels) allow you to distribute your product information to defined recipients, for example e-commerce platforms. +Select the [[= pim_product_name =]] channel you want to integrate with [[= product_name =]]. + +For all available configuration options, see [Configure [[= pim_product_name =]]](configure_quable.md). ## Configure product catalog engine -To use Quable as the product data source, configure [[= product_name =]]'s product catalog to use the Quable engine. +To use [[= pim_product_name =]] as the product data source, configure [[= product_name =]]'s [product catalog](product_catalog_guide.md) to use the [[= pim_product_name =]] engine. -### Define Quable engine +### Define [[= pim_product_name =]] engine In `config/packages/ibexa_product_catalog.yaml`, add a new engine configuration: -``` yaml +``` yaml hl_lines="8-13" ibexa_product_catalog: engines: local: @@ -67,13 +71,15 @@ ibexa_product_catalog: product_type_group_identifier: product ``` -This configuration defines two engines: the default `local` engine and the new `quable` engine. +This configuration defines two engines: the default `local` engine and the new `quable` engine, allowing you to work with products defined within [[= pim_product_name =]]. -### Set Quable as default engine +To learn more about product catalog configuration, see [Product catalog configuration](product_catalog_configuration.md). -In your repository configuration, typically in `config/packages/ibexa.yaml`, configure the Product Catalog to use the Quable engine as the product data source: +### Set [[= pim_product_name =]] as default engine -``` yaml +In your repository configuration, typically in `config/packages/ibexa.yaml`, configure the product catalog to use the [[= pim_product_name =]] engine as the product data source: + +``` yaml hl_lines="9" ibexa: repositories: default: @@ -89,7 +95,15 @@ ibexa: ## Set up languages -When working with Quable products, +To use the products from [[= pim_product_name =]] within [[= product_name =]] content, make sure the [data languages](https://docs.quable.com/v5-EN/docs/data-languages) in [[= product_pim =]] have corresponding [languages](languages.md) in [[= product_name =]]. + +To preview the current language configuration in both systems, run the following command: + +``` bash +php bin/console ibexa:quable:languages:check +``` + +Based on the returned data, adjust the language configuration as your use case requires. ## Synchronize taxonomy @@ -101,37 +115,56 @@ Run the following command to synchronize classifications: php bin/console ibexa:quable:classification:sync ``` -This command imports the product classification structure from Quable PIM into [[= product_name =]], ensuring that product categories and taxonomies are aligned. +This command imports the product classification structure from [[= pim_product_name =]] PIM into [[= product_name =]], ensuring that product categories are aligned. -!!! note "Verbose output" +!!! tip - Add the `-vv` flag to see detailed information about the requests sent to Quable: - - ``` bash - php bin/console ibexa:quable:classification:sync -vv - ``` + To keep the classifications aligned, we recommended to run the `ibexa:quable:classification:sync` command very night, even when using synchronization with webhooks. ## Set up real-time synchronization -Quable PIM can notify [[= product_name =]] about product data changes in real-time using webhooks. -This ensures that product information stays synchronized automatically without manual intervention. +[[= pim_product_name =]] PIM can notify [[= product_name =]] about product data and classification changes in real-time using webhooks. +This invalidates the [cache](configure_quable.md#cache-behavior) kept in [[= product_name =]] and ensures that product information stays up to date. Webhook configuration requires setup in both Quable PIM and [[= product_name =]]. +### Create webhook in [[= pim_product_name =]] + 1. Create a new [webhook in Quable](https://docs.quable.com/v5-EN/docs/webhook). -2. Set the webhook's name and provide the URL to your [[= product_name =]] instance -3. Mark it as **Activated** -4. Enter a secret value for the **Authorization Header** -5. Choose the following scopes: - - Products: created, updated, deleted - - Classifications: created, updated, deleted +2. Set the webhook's code (used as the webhook's name) +3. Provide the URL to your [[= product_name =]] instance suffixed by `/webhook/quable`, for example: `https://example.com/webhook/quable` +4. Mark it as **Activated** +5. Enter a secret value for the **Authorization Header** +6. Choose the following scopes: + +- Products: created, updated, deleted +- Classifications: created, updated, deleted The **Authorization Header** value is a [secret that must be kept secure](security_checklist.md#app-secret-and-other-secrets). !!! note - For local development and testing, consider using one of the avalable [tunnel providers](https://github.com/anderspitman/awesome-tunneling) to make your instance accessible + For local development and testing, you can consider using one of the avalable [tunnel providers](https://github.com/anderspitman/awesome-tunneling) to make your local instance accessible. + +### Configure webhook in [[= product_name =]] + +In `config/packages/ibexa_connector_quable.yaml`, specify the configuration for the [[= pim_product_name =]] connector: + +``` yaml +ibexa_connector_quable: + + # Existing configuration (...) + + webhook_secret: '' +``` + +!!! warning + + [Quable uses dynamic IP addresses]((https://faq.quable.com/en/articles/8250056-what-are-the-ip-addresses-of-quable-to-add-to-the-whitelist)) to connect to [[= product_name =]]. + If your DXP instance is protected by a firewall, make sure your configuration allows connections from changing IP addresses. +### Configure background task +[[= product_name =]]'s webhook processes Quable's classification change events and queues them to be processed in the background. -For information about working with products in the user interface, see [Product management]([[= user_doc =]]/persona_paths/manage_products/). +To process them, [configure Ibexa Messenger](background_tasks.md) and make sure the `messenger:consume` command is run periodically. diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md index 8eb93c7f93..d1eb5e50b8 100644 --- a/docs/product_catalog/quable/quable.md +++ b/docs/product_catalog/quable/quable.md @@ -4,27 +4,22 @@ description: Quable PIM integration with Ibexa DXP # Quable PIM Integration -[[= product_name =]] integrates with [Quable](https://www.quable.com/en) to provide product information management as part of the [[= product_name_base =]] orchestration platform. +[[= product_name =]] integrates with [[[= pim_product_name =]]](https://www.quable.com/en) to provide product information management as part of the [[= product_name_base =]] orchestration platform. -## About Quable and Ibexa +## About [[= pim_product_name =]] and Ibexa -Quable is Ibexa's PIM solution for managing complex product catalogs. -As part of the Ibexa orchestration platform, Quable acts as the source of truth about products that feeds every channel with accurate product data. +[[= pim_product_name =]] is Ibexa's PIM solution for managing complex product catalogs. +As part of the Ibexa orchestration platform, [[= pim_product_name =]] acts as the source of truth about products that feeds every channel with accurate product data. -Quable becomes the source that you can use for powerful recommendations, personalized campaigns, and interactive digital experiences across every market. +[[= pim_product_name =]] becomes the source that you can use for recommendations, personalized campaigns, and interactive digital experiences across every market. Teams, partners, and customers have seamless access to product information—details, translations, photographs, videos, PDFs — all validated to meet regional and compliance requirements. -## Integration documentation +// TODO: Describe here what you can do with the products in DXP + +## Learn more [[= cards([ "product_catalog/quable/install_quable", - "product_catalog/quable/quable_configuration", - "product_catalog/quable/quable_other", + "product_catalog/quable/configure_quable", + "product_catalog/quable/work_with_quable", ], columns=3) =]] - -## User documentation - -For information about working with Quable products in the [[= product_name =]] user interface, see: - -- [Product management]([[= user_doc =]]/persona_paths/manage_products/) -- X - link to Quable doc here? diff --git a/mkdocs.yml b/mkdocs.yml index 1581dcf454..26bbd44a2c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -356,7 +356,7 @@ nav: - Quable PIM integration: - Quable overview: product_catalog/quable/quable.md - Install Quable: product_catalog/quable/install_quable.md - - Quable configuration: product_catalog/quable/quable_configuration.md + - Configure Quable: product_catalog/quable/configure_quable.md - Additional information: product_catalog/quable/quable_other.md - Product catalog configuration: product_catalog/product_catalog_configuration.md - Products: product_catalog/products.md @@ -990,6 +990,7 @@ extra: product_name_cloud: 'Ibexa Cloud' product_name_oss: 'Ibexa OSS' product_name_engage: 'Ibexa Engage' + pim_product_name: 'Quable' eol_versions: ['2.5'] From aebdc8b8b492b85c5f2015b9e4e6c69db290af53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 12 Mar 2026 12:56:02 +0100 Subject: [PATCH 4/7] Fixed build --- docs/product_catalog/quable/install_quable.md | 4 ++-- docs/product_catalog/quable/quable.md | 3 ++- plugins.yml | 1 - 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/product_catalog/quable/install_quable.md b/docs/product_catalog/quable/install_quable.md index 34ee62912c..a085992be9 100644 --- a/docs/product_catalog/quable/install_quable.md +++ b/docs/product_catalog/quable/install_quable.md @@ -140,7 +140,7 @@ Webhook configuration requires setup in both Quable PIM and [[= product_name =]] - Products: created, updated, deleted - Classifications: created, updated, deleted -The **Authorization Header** value is a [secret that must be kept secure](security_checklist.md#app-secret-and-other-secrets). +The **Authorization Header** value is a [secret that must be kept secure](security_checklist.md#app_secret-and-other-secrets). !!! note @@ -160,7 +160,7 @@ ibexa_connector_quable: !!! warning - [Quable uses dynamic IP addresses]((https://faq.quable.com/en/articles/8250056-what-are-the-ip-addresses-of-quable-to-add-to-the-whitelist)) to connect to [[= product_name =]]. + [Quable uses dynamic IP addresses](https://faq.quable.com/en/articles/8250056-what-are-the-ip-addresses-of-quable-to-add-to-the-whitelist)) to connect to [[= product_name =]]. If your DXP instance is protected by a firewall, make sure your configuration allows connections from changing IP addresses. ### Configure background task diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md index d1eb5e50b8..5c100b353c 100644 --- a/docs/product_catalog/quable/quable.md +++ b/docs/product_catalog/quable/quable.md @@ -18,8 +18,9 @@ Teams, partners, and customers have seamless access to product information—det ## Learn more +// TODO: Update this when complete + [[= cards([ "product_catalog/quable/install_quable", "product_catalog/quable/configure_quable", - "product_catalog/quable/work_with_quable", ], columns=3) =]] diff --git a/plugins.yml b/plugins.yml index c3a0431fb4..4baee6ddfc 100644 --- a/plugins.yml +++ b/plugins.yml @@ -245,7 +245,6 @@ plugins: 'pim/create_custom_catalog_filter.md': 'product_catalog/create_custom_catalog_filter.md' 'pim/create_custom_name_schema_strategy.md': 'product_catalog/create_custom_name_schema_strategy.md' 'pim/add_remote_pim_support.md': 'product_catalog/add_remote_pim_support.md' - 'pim/quable_integration.md': 'product_catalog/quable_integration.md' 'guide/basket/basket.md': 'commerce/commerce.md' 'guide/basket/wishlist_and_stored_baskets.md': 'commerce/commerce.md' From 78fc1954792f11dee06329d4834dde44d729bb27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 12 Mar 2026 14:51:50 +0100 Subject: [PATCH 5/7] Configuration doc --- .../quable/configure_quable.md | 263 ------------------ .../quable/configure_quable_connector.md | 50 ++++ docs/product_catalog/quable/install_quable.md | 4 +- docs/product_catalog/quable/quable.md | 2 +- mkdocs.yml | 2 +- 5 files changed, 54 insertions(+), 267 deletions(-) delete mode 100644 docs/product_catalog/quable/configure_quable.md create mode 100644 docs/product_catalog/quable/configure_quable_connector.md diff --git a/docs/product_catalog/quable/configure_quable.md b/docs/product_catalog/quable/configure_quable.md deleted file mode 100644 index a57c5b82dc..0000000000 --- a/docs/product_catalog/quable/configure_quable.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -description: Quable PIM connector configuration reference for Ibexa DXP ---- - -# Configure Quable - -This page provides a complete reference for configuring the Quable PIM connector in [[= product_name =]]. - -## Connector configuration - -The Quable connector is configured in a YAML file in the `config/packages` directory, typically named `ibexa_connector_quable.yaml`. - -### Basic configuration - -``` yaml -ibexa_connector_quable: - instance_url: 'https://your-instance.quable.com' - api_token: '%env(QUABLE_API_TOKEN)%' - webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' - cache: - enabled: true -``` - -### Configuration parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `instance_url` | string | Yes | The URL of your Quable PIM instance (for example, `https://example.quable.com`) | -| `api_token` | string | Yes | API authentication token from Quable. For security, using environment variables is recommended | -| `webhook_secret` | string | No | Secret key for validating webhook requests from Quable. Required if using real-time synchronization. | -| `cache.enabled` | boolean | No | Globally enable or disable all Quable caches. Default: `true`. Set to `false` to bypass all service caches at once. | -| `cache.attribute` | boolean | No | Enable or disable caching for attribute definitions. Default: `true`. | -| `cache.attribute_group` | boolean | No | Enable or disable caching for attribute group definitions. Default: `true`. | -| `cache.product` | boolean | No | Enable or disable caching for product data. Default: `true`. | -| `cache.product_type` | boolean | No | Enable or disable caching for product type definitions. Default: `true`. | - -!!! tip "Environment variables" - - Store sensitive configuration values like API tokens in environment variables or `.env` files: - - ``` - QUABLE_API_TOKEN=your_read_access_token_here - QUABLE_WEBHOOK_SECRET=your_webhook_secret_here - ``` - -## Product Catalog engine configuration - -Configure [[= product_name =]]'s Product Catalog to use Quable as the data source in `config/packages/ibexa_product_catalog.yaml`. - -### Engine definition - -``` yaml -ibexa_product_catalog: - engines: - local: - type: local - options: - root_location_remote_id: ibexa_product_catalog_root - product_type_group_identifier: product - quable: - type: quable - options: - taxonomy: quable - root_location_remote_id: ibexa_product_catalog_root - product_type_group_identifier: product -``` - -### Engine options - -| Option | Description | Default | -|--------|-------------|---------| -| `taxonomy` | Taxonomy identifier for Quable classifications | `quable` | -| `root_location_remote_id` | Remote ID of the root location for product catalog | `ibexa_product_catalog_root` | -| `product_type_group_identifier` | Identifier for the product type group | `product` | - -### Repository configuration - -Set the Quable engine as the default for your repository in `config/packages/ibexa.yaml`: - -``` yaml -ibexa: - repositories: - default: - storage: ~ - search: - engine: '%search_engine%' - connection: default - product_catalog: - engine: quable - regions: - default: ~ -``` - -## Cache configuration - -The Quable connector implements caching to reduce API calls and improve performance. - -### Cache settings - -``` yaml -ibexa_connector_quable: - instance_url: 'https://your-instance.quable.com' - api_token: '%env(QUABLE_API_TOKEN)%' - cache: - enabled: true - attribute: true - attribute_group: true - product: true - product_type: true -``` - -### Cache behavior - -When caching is enabled: - -- Product data is cached after the first request -- Subsequent requests use cached data instead of calling Quable API -- Cache is automatically invalidated when webhooks receive update notifications -- Manual cache clearing: `php bin/console cache:clear` - -Each of the four service caches (`attribute`, `attribute_group`, `product`, `product_type`) can be disabled independently while the others remain active. When a service cache is disabled, it falls back to an in-memory adapter that is not shared between requests (effectively bypassing persistence while still avoiding unbounded API call loops within a single request). - -!!! tip "Granular cache control" - - Use per-service cache flags instead of globally disabling all caches. For example, when debugging product queries you can disable only the `product` cache while keeping `attribute` and `attribute_group` caches enabled. This avoids flooding Quable's API with redundant attribute definition requests (which can reach 80+ extra calls per product list request when fully uncached). - -!!! note "Production recommendation" - - Always enable caching in production environments to minimize API calls and improve response times. Cache invalidation is handled automatically via webhooks. - -## Language alignment - -[[= product_name =]] and Quable must have matching language configurations for proper data synchronization. - -### Language configuration requirements - -Ensure that: - -1. All languages enabled in [[= product_name =]] exist in Quable PIM -2. Language codes match between systems (e.g., `eng-GB`, `fre-FR`) -3. Default language is consistent across both systems - -### Example language configuration - -In [[= product_name =]] (`config/packages/ibexa.yaml`): - -``` yaml -ibexa: - system: - default: - languages: - - eng-GB - - fre-FR - - ger-DE -``` - -Verify these language codes exist in your Quable PIM instance. - -!!! warning "Mismatched languages" - - If languages don't match between systems, product translations may not display correctly or may be missing entirely. - -## Channel selection - -For multi-channel Quable setups, you can configure which channel's data to display in [[= product_name =]]. - -!!! note "Channel configuration" - - Channel selection configuration varies by deployment. Consult Ibexa support for channel-specific configuration options. - -## Synchronization configuration - -### Taxonomy synchronization - -Taxonomy (classification) synchronization is triggered manually via console command: - -``` bash -php bin/console ibexa:quable:classification:sync -``` - -**Command options:** - -- `-vv` - Verbose output showing detailed API requests -- Add to cron for periodic synchronization if not using webhooks - -### Real-time synchronization - -Real-time synchronization uses webhooks configured in Quable PIM. When enabled, product data updates automatically when changes occur in Quable. - -**Webhook configuration:** - -``` yaml -ibexa_connector_quable: - instance_url: 'https://your-instance.quable.com' - api_token: '%env(QUABLE_API_TOKEN)%' - webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' -``` - -The `webhook_secret` validates incoming webhook requests to ensure they originate from your Quable instance. - -### What synchronizes - -| Data Type | Synchronization Method | Notes | -|-----------|----------------------|-------| -| Products | Real-time (webhooks) or API calls | Product details, attributes, variants | -| Product Types | Real-time (webhooks) or API calls | Type definitions and attribute schemas | -| Attributes | Real-time (webhooks) or API calls | Attribute definitions and values | -| Classifications/Categories | Manual command or webhooks | Hierarchical category structure | -| Assets | On-demand | Images, videos, documents linked to products | - -### What doesn't synchronize - -The following data remains independent in each system: - -- [[= product_name =]] content items and content types -- User accounts and permissions -- Site configurations -- Custom prices set in [[= product_name =]] (override Quable prices) -- Local product catalogs - -## Performance optimization - -### Optimize API calls - -1. **Enable caching** - Reduces repeated API calls -2. **Use webhooks** - Avoid polling for updates -3. **Limit verbose logging** - Use `-vv` only for debugging - -### Connection pooling - -The Quable connector uses Symfony's HTTP client with connection pooling enabled by default for optimal performance. - -## Environment-specific configuration - -### Development environment - -``` yaml -# config/packages/dev/ibexa_connector_quable.yaml -ibexa_connector_quable: - instance_url: 'https://example.quable.com' - api_token: '%env(QUABLE_API_TOKEN)%' - cache: - enabled: true - product: false # Disable only product cache to see live query effects - # attribute, attribute_group, and product_type remain cached - # to avoid excessive API calls for definition data -``` - -!!! note "Disabling all caches" - - Setting `enabled: false` disables all service caches at once. Use this only when you need to debug the full pipeline without any caching, as it significantly increases the number of API calls to Quable. - -### Production environment - -``` yaml -# config/packages/prod/ibexa_connector_quable.yaml -ibexa_connector_quable: - instance_url: 'https://production.quable.com' - api_token: '%env(QUABLE_API_TOKEN)%' - webhook_secret: '%env(QUABLE_WEBHOOK_SECRET)%' - cache: - enabled: true # Always enable in production -``` diff --git a/docs/product_catalog/quable/configure_quable_connector.md b/docs/product_catalog/quable/configure_quable_connector.md new file mode 100644 index 0000000000..f6b8e3073c --- /dev/null +++ b/docs/product_catalog/quable/configure_quable_connector.md @@ -0,0 +1,50 @@ +--- +description: Quable PIM connector configuration reference for Ibexa DXP +--- + +# Configure Quable connector + +This page provides a complete reference for configuring the [[= pim_product_name =]] PIM connector in [[= product_name =]]. + +Use the `ibexa_connector_quable` key in `config/packages/ibexa_connector_quable.yaml` to customize [[= pim_product_name =]] behaviour. + +## Configuration + +``` yaml +ibexa_connector_quable: + enabled: true + instance_url: 'https://example.quable.com' + api_token: '' + channel_code: '' + webhook_secret: '' # Needed for webhook authentication + throw_on_invalid_criteria: '%kernel.debug%' + throw_on_invalid_mapping: '%kernel.debug%' + cache: + enabled: true + attribute: true + attribute_group: true + product: true + product_type: true +``` + +## Connector options + +| Parameter | Default value | Description | +|-----------|--------------------------|-------------| +| `enabled` | `false` | Enables the connector bundle configuration. | +| `instance_url` | string | Base URL of your [[= pim_product_name =]] instance, for example `https://example.quable.com`. | +| `api_token` | string | Read Access API token used to authenticate requests to [[= pim_product_name =]]. | +| `channel_code` | string | Code of the [[= pim_product_name =]] channel used as the source of product data. | +| `webhook_secret` | string | Secret expected in the webhook authorization header. | +| `throw_on_invalid_criteria` | `%kernel.debug%` | Controls behavior for unsupported filter/search criteria: `true` throws an exception, `false` ignores unsupported criteria. | +| `throw_on_invalid_mapping` | `%kernel.debug%` | Controls behavior for mapping errors during data transformation: `true` throws an exception, `false` ignores mapping errors. | +| `cache.enabled` | `true` | Global cache switch for the connector. When `false`, cache decorators use only [in-memory cache](persistence_cache.md#in-memory-cache-configuration). | +| `cache.attribute` | `true` | Enables caching for attribute definition requests. | +| `cache.attribute_group` | `true` | Enables caching for attribute group requests. | +| `cache.product` | `true` | Enables caching for product requests. | +| `cache.product_type` | `true` | Enables caching for product type requests. | + +In production environments, it's recommended to: + +- enable caching for better performance, using Redis or Valkey as [persistence cache](persistence_cache.md#redisvalkey) +- disable `throw_on_invalid_criteria` and `throw_on_invalid_mapping` to prevent non-critical errors from causing application crashes diff --git a/docs/product_catalog/quable/install_quable.md b/docs/product_catalog/quable/install_quable.md index a085992be9..b8018fa638 100644 --- a/docs/product_catalog/quable/install_quable.md +++ b/docs/product_catalog/quable/install_quable.md @@ -45,7 +45,7 @@ Replace `` with the Read Access API token you obtained from [[= [[[= pim_product_name =]]'s channels](https://docs.quable.com/v5-EN/docs/content-channels) allow you to distribute your product information to defined recipients, for example e-commerce platforms. Select the [[= pim_product_name =]] channel you want to integrate with [[= product_name =]]. -For all available configuration options, see [Configure [[= pim_product_name =]]](configure_quable.md). +For all available configuration options, see [Configure [[= pim_product_name =]]](configure_quable_connector.md). ## Configure product catalog engine @@ -124,7 +124,7 @@ This command imports the product classification structure from [[= pim_product_n ## Set up real-time synchronization [[= pim_product_name =]] PIM can notify [[= product_name =]] about product data and classification changes in real-time using webhooks. -This invalidates the [cache](configure_quable.md#cache-behavior) kept in [[= product_name =]] and ensures that product information stays up to date. +This invalidates the cache kept in [[= product_name =]] and ensures that product information stays up to date. Webhook configuration requires setup in both Quable PIM and [[= product_name =]]. diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md index 5c100b353c..0c59abd504 100644 --- a/docs/product_catalog/quable/quable.md +++ b/docs/product_catalog/quable/quable.md @@ -22,5 +22,5 @@ Teams, partners, and customers have seamless access to product information—det [[= cards([ "product_catalog/quable/install_quable", - "product_catalog/quable/configure_quable", + "product_catalog/quable/configure_quable_connector", ], columns=3) =]] diff --git a/mkdocs.yml b/mkdocs.yml index 26bbd44a2c..79ed115618 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -356,7 +356,7 @@ nav: - Quable PIM integration: - Quable overview: product_catalog/quable/quable.md - Install Quable: product_catalog/quable/install_quable.md - - Configure Quable: product_catalog/quable/configure_quable.md + - Configure Quable: product_catalog/quable/configure_quable_connector.md - Additional information: product_catalog/quable/quable_other.md - Product catalog configuration: product_catalog/product_catalog_configuration.md - Products: product_catalog/products.md From 934d977a5389712b1b018f7ad07f9bdcc54be86e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 12 Mar 2026 15:22:42 +0100 Subject: [PATCH 6/7] Removed Quable other --- TODO.md | 29 ++ docs/product_catalog/quable/quable_other.md | 296 -------------------- mkdocs.yml | 1 - 3 files changed, 29 insertions(+), 297 deletions(-) delete mode 100644 docs/product_catalog/quable/quable_other.md diff --git a/TODO.md b/TODO.md index 14dc1eb63e..d16708aef5 100644 --- a/TODO.md +++ b/TODO.md @@ -8,3 +8,32 @@ TODO: 6) Integracja z messengerem 7) Search integration 8) Embedding products +9) https://ibexa.atlassian.net/browse/IBX-10990 (edit product redirect) +10) #### Product navigation + +- **Edit button**: Redirects to Quable PIM for product editing +- **View in Quable**: Link to source product in Quable interface +- Seamless navigation between systems + +#### System boundaries + +**Quable responsibilities:** +- Product creation and editing +- Attribute definition and management +- Category/classification structure +- Product assets (images, documents) +- Product variants +- Core product data + +**[[= product_name =]] responsibilities:** +- Product display and presentation +- Content-product relationships +- Catalog organization for storefronts +- Custom pricing (overrides) +- availability +- Product embeds in content +- Storefront experience + +⚠️ **Policy limitation validation**: Product Type limitations in policies may not validate correctly. This is a known issue being addressed. + +Mentiond: The Quable integration is built on [[= product_name =]]'s [Remote PIM framework](../add_remote_pim_support.md), which provides a foundation for connecting external Product Information Management systems. diff --git a/docs/product_catalog/quable/quable_other.md b/docs/product_catalog/quable/quable_other.md deleted file mode 100644 index 87beb7eb4c..0000000000 --- a/docs/product_catalog/quable/quable_other.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -description: Quable PIM integration - Architecture, features, limitations, and developer reference ---- - -# Additional technical information - -This page contains additional technical information about the Quable PIM integration with [[= product_name =]], including architecture details, supported features, technical limitations, and developer reference materials. - -!!! note - - This page is a collection of technical materials for review. Content may be reorganized into separate pages in the future. - -## Architecture - -### Integration overview - -The Quable integration is built on [[= product_name =]]'s [Remote PIM framework](../add_remote_pim_support.md), which provides a foundation for connecting external Product Information Management systems. - -**Key architectural principles:** - -- **Single source of truth**: Quable PIM owns all product data -- **Read-only in DXP**: Products are displayed and used in [[= product_name =]] but edited in Quable -- **Service-oriented**: Integration uses service interfaces for data access -- **Event-driven sync**: Real-time updates via webhooks keep data synchronized -- **Cached data access**: API responses are cached for performance - -### Data flow - -``` -Quable PIM → Quable API → Quable Connector → Product Catalog Services → DXP Features - ↓ - Cache Layer - ↓ - Storefront Display -``` - -**Data flow steps:** - -1. **Product data originates** in Quable PIM -2. **Quable API** exposes product data via REST endpoints -3. **Quable Connector** fetches and transforms data using object mappers -4. **Product Catalog Services** provide standardized access to product data -5. **DXP Features** (Product Picker, Page Builder blocks, etc.) consume product data -6. **Storefront** displays products to end users - -**Synchronization triggers:** - -- **Manual**: Command-line sync for taxonomy/classifications -- **Automatic**: Webhooks notify DXP of product changes in real-time -- **On-demand**: API calls when specific product data is requested - -### Service layer architecture - -The Quable connector implements the following service interfaces: - -| Service | Purpose | Key Methods | -|---------|---------|-------------| -| `ProductService` | Retrieve product data | `getProduct()`, `findProducts()`, `findProductsByCode()` | -| `ProductTypeService` | Get product type information | `getProductType()`, `findProductTypes()` | -| `AttributeDefinitionService` | Access attribute definitions | `getAttributeDefinition()`, `findAttributeDefinitions()` | -| `AttributeGroupService` | Manage attribute groups | `getAttributeGroup()`, `findAttributeGroups()` | -| `AssetService` | Retrieve product assets | `findAssets()` | - -**Service characteristics:** - -- Services implement standard [[= product_name =]] Product Catalog interfaces -- Responses are cached by default to minimize API calls -- Services transform Quable data structures into [[= product_name =]] value objects - -### Object mapping and transformers - -The connector uses object mappers and transformers to convert Quable API responses into [[= product_name =]] value objects: - -**Value objects:** - -- `Product` - Complete product data including attributes, variants, assets -- `ProductType` - Product type definitions and attribute schemas -- `AttributeDefinition` - Individual attribute definitions -- `AttributeGroup` - Groups of related attributes -- `Attribute` - Attribute values with type information - -**Transformers:** - -- `ProductTypeTransformer` - Maps product types from Quable to DXP format -- `AttributesListTransformer` - Builds attribute lists from raw data -- `Product/NameTransformer` - Derives product names from attributes -- `AttributeDefinition/NameTransformer` - Extracts attribute definition names - -### Permission handling - -Products from Quable are treated as remote objects for permission purposes: - -- Permission context is provided by `Quable\Permissions\ContextProvider` -- Standard [[= product_name =]] permission system applies to product operations -- Create/Edit/Delete operations are disabled for remote products (handled in Quable) -- View permissions can be controlled via [[= product_name =]] roles and policies - -!!! note "Permission limitations" - - Some permission limitations exist for remote products. Product Type limitations for policies require special handling. See [Known Limitations](#technical-limitations) below. - -### Caching strategy - -The Quable connector implements multi-level caching: - -**Service-level caching:** - -- In-memory cache within service instances -- Reduces duplicate API calls within the same request -- Cache lifetime: duration of PHP process - -**Application-level caching:** - -- Symfony cache component stores API responses -- Configured cache pool for Quable connector -- Cache invalidation via webhooks on data changes - -**Cache configuration:** - -```yaml -ibexa_connector_quable: - cache: - enabled: true # Enable/disable caching -``` - -### API communication patterns - -The connector communicates with Quable using: - -- **HTTP Client**: Symfony HTTP client with connection pooling -- **Authentication**: Bearer token authentication using API token -- **Response format**: JSON -- **Error handling**: Graceful degradation with logging - -## Features and limitations - -### Supported features - -#### Product display and viewing - -✅ **Product listing**: View all products from Quable in [[= product_name =]] Product Catalog interface - -✅ **Product details**: Access complete product information including attributes, specifications, and assets - -✅ **Multi-language support**: Display products in multiple languages with localized attribute values - -✅ **Variant handling**: View product variants with their specific attribute combinations - -✅ **Product attributes**: All Quable attribute types are mapped and displayed in [[= product_name =]] - -#### Product Picker integration - -✅ **Product selection**: Use Product Picker to select Quable products in content editing - -✅ **Category filtering**: Filter products by Quable classifications in Product Picker - -✅ **Code search**: Search products by code/SKU - -✅ **Product preview**: Preview product information before selection - -#### Category and classification - -✅ **Category synchronization**: Import Quable classification structure into [[= product_name =]] taxonomy - -✅ **Hierarchical categories**: Maintain parent-child relationships from Quable - -✅ **Category browsing**: Navigate products by category in [[= product_name =]] - -✅ **Category filtering**: Filter product lists by category - -#### Product Catalog management - -✅ **Catalog creation**: Create product catalogs using Quable product data - -✅ **Catalog filters**: Apply filters to include specific Quable products in catalogs - -✅ **Pricing management**: View base prices from Quable, set custom prices in [[= product_name =]] - -✅ **Availability tracking**: Access product availability information - -#### Page Builder blocks - -✅ **Product Collection block**: Display selected Quable products on pages - -✅ **Product Catalog block**: Show full product listings from catalogs - -✅ **Product Embed block**: Embed individual products in content - -✅ **Dashboard blocks**: Use Quable products in dashboard widgets (e.g., Products by categories) - -#### Content integration - -✅ **Product embeds in rich text**: Embed Quable products within text content (requires configuration) - -✅ **Product specification fields**: Add product specification fields to content types - -✅ **Content-product relationships**: Link content items to Quable products - -### Technical limitations - -#### Read-only product access - -❌ **No product creation**: Products cannot be created in [[= product_name =]]. Create products in Quable PIM. - -❌ **No product editing**: Product data is read-only in [[= product_name =]]. Edit products in Quable, changes sync automatically. - -❌ **No variant management**: Variants are managed in Quable only. - -❌ **Edit action redirects**: Clicking "Edit" on a Quable product redirects to Quable PIM interface. - -#### Category management - -❌ **No category creation**: Categories cannot be created in [[= product_name =]]. Manage in Quable. - -❌ **No category editing**: Category structure is synchronized from Quable, cannot be modified in [[= product_name =]]. - -❌ **No manual assignment**: Products cannot be manually assigned to categories in [[= product_name =]]. - -#### REST API restrictions - -❌ **Product CRUD endpoints disabled**: REST API endpoints for creating, editing, and deleting products are disabled for Quable products. - -❌ **Variant API limitations**: Variant management API endpoints are not available for remote products. - -#### Permission and policy - -⚠️ **Policy limitation validation**: Product Type limitations in policies may not validate correctly. This is a known issue being addressed. - -❌ **No content tab for categories**: Content editing tab is not applicable to Quable categories. - -#### User interface - -❌ **Create actions hidden**: "Create Product" and "Create Variant" buttons are hidden when using Quable engine. - -❌ **No inline editing**: Product attributes cannot be edited inline in [[= product_name =]] interface. - -❌ **Special character handling**: Products with codes containing reserved characters may require special handling. - -### Design decisions - -#### Why read-only in DXP? - -**Single source of truth principle**: Keeping product data creation and editing exclusively in Quable ensures: - -- **Data integrity**: No conflicts between systems -- **Clear ownership**: Quable owns product data, [[= product_name =]] displays it -- **Audit trail**: All changes tracked in Quable -- **Workflow consistency**: Product teams work in one system - -#### System boundaries - -**Quable responsibilities:** -- Product creation and editing -- Attribute definition and management -- Category/classification structure -- Product assets (images, documents) -- Product variants -- Core product data - -**[[= product_name =]] responsibilities:** -- Product display and presentation -- Content-product relationships -- Catalog organization for storefronts -- Custom pricing (overrides) -- Product embeds in content -- Storefront experience - -### UI feature integration - -The following UI features work seamlessly with Quable products. Refer to user documentation for detailed workflows: - -#### Product Picker - -- Select Quable products when editing content -- Filter by category, search by name/code -- Preview product details before selection -- **User docs**: [Product management]([[= user_doc =]]/persona_paths/manage_products/) - -#### Page Builder blocks - -- **Product Collection**: Manually select products to display -- **Product Catalog**: Automatically show products from a catalog -- **Product Embed**: Embed individual products in page content -- **User docs**: [Using Page Builder]([[= user_doc =]]/page_builder/) - -#### Dashboard - -- **Products by categories** widget shows product distribution -- Quable categories available for visualization -- **User docs**: [Dashboard management]([[= user_doc =]]/persona_paths/manage_dashboard/) - -#### Product navigation - -- **Edit button**: Redirects to Quable PIM for product editing -- **View in Quable**: Link to source product in Quable interface -- Seamless navigation between systems diff --git a/mkdocs.yml b/mkdocs.yml index 79ed115618..ab51eb19bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -357,7 +357,6 @@ nav: - Quable overview: product_catalog/quable/quable.md - Install Quable: product_catalog/quable/install_quable.md - Configure Quable: product_catalog/quable/configure_quable_connector.md - - Additional information: product_catalog/quable/quable_other.md - Product catalog configuration: product_catalog/product_catalog_configuration.md - Products: product_catalog/products.md - Attributes: From 0284c83e7c0e31e00ba1720ff019e9cf34e89e35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 12 Mar 2026 16:40:27 +0100 Subject: [PATCH 7/7] Added product guide skeleton --- .../quable/configure_quable_connector.md | 4 ++-- docs/product_catalog/quable/quable.md | 22 +++++++++++++---- docs/product_catalog/quable/quable_guide.md | 0 docs/product_guides/product_guides.md | 1 + .../quable_twig_functions.md | 24 +++++++++++++++++++ .../twig_function_reference.md | 1 + main.py | 8 +++++-- mkdocs.yml | 10 ++++---- 8 files changed, 58 insertions(+), 12 deletions(-) create mode 100644 docs/product_catalog/quable/quable_guide.md create mode 100644 docs/templating/twig_function_reference/quable_twig_functions.md diff --git a/docs/product_catalog/quable/configure_quable_connector.md b/docs/product_catalog/quable/configure_quable_connector.md index f6b8e3073c..0d86275683 100644 --- a/docs/product_catalog/quable/configure_quable_connector.md +++ b/docs/product_catalog/quable/configure_quable_connector.md @@ -8,7 +8,7 @@ This page provides a complete reference for configuring the [[= pim_product_name Use the `ibexa_connector_quable` key in `config/packages/ibexa_connector_quable.yaml` to customize [[= pim_product_name =]] behaviour. -## Configuration +## Configuration example ``` yaml ibexa_connector_quable: @@ -27,7 +27,7 @@ ibexa_connector_quable: product_type: true ``` -## Connector options +## Configuration options | Parameter | Default value | Description | |-----------|--------------------------|-------------| diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md index 0c59abd504..acff082f98 100644 --- a/docs/product_catalog/quable/quable.md +++ b/docs/product_catalog/quable/quable.md @@ -1,5 +1,6 @@ --- description: Quable PIM integration with Ibexa DXP +page_type: landing_page --- # Quable PIM Integration @@ -14,13 +15,26 @@ As part of the Ibexa orchestration platform, [[= pim_product_name =]] acts as th [[= pim_product_name =]] becomes the source that you can use for recommendations, personalized campaigns, and interactive digital experiences across every market. Teams, partners, and customers have seamless access to product information—details, translations, photographs, videos, PDFs — all validated to meet regional and compliance requirements. -// TODO: Describe here what you can do with the products in DXP +// TODO: Update this when complete -## Learn more +## Getting started -// TODO: Update this when complete +[[= cards([ + "product_catalog/quable/quable_guide", +]) =]] + +## Development [[= cards([ "product_catalog/quable/install_quable", "product_catalog/quable/configure_quable_connector", -], columns=3) =]] + "templating/twig_function_reference/quable_twig_functions", +]) =]] + +## Learn more about Quable + +[[= cards([ + ("https://quable.com/en", "Quable - PIM solution for product data management", "Manage your product data and accelerate sales with Quable. Discover the new PIM platform that revolutionizes the product experience"), + ("https://docs.quable.com/", "Quable Resources", "Find all Quable PIM, DAM, and Portal resources: user guides, training content, product documentation, technical documentation, and the PIM API for developers."), + ("https://developers.quable.com/", "Quable technical documentation", ""), +]) =]] diff --git a/docs/product_catalog/quable/quable_guide.md b/docs/product_catalog/quable/quable_guide.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/product_guides/product_guides.md b/docs/product_guides/product_guides.md index be34a589fa..1a1e554007 100644 --- a/docs/product_guides/product_guides.md +++ b/docs/product_guides/product_guides.md @@ -20,6 +20,7 @@ Discover the primary ones with the help of product guides. Condensed content all "customer_management/customer_portal", "personalization/personalization_guide", "product_catalog/product_catalog_guide", + "product_catalog/quable/quable_guide", "commerce/shopping_list/shopping_list_guide", "ibexa_cloud/ibexa_cloud_guide", "cdp/cdp_guide", diff --git a/docs/templating/twig_function_reference/quable_twig_functions.md b/docs/templating/twig_function_reference/quable_twig_functions.md new file mode 100644 index 0000000000..ef0d652ae5 --- /dev/null +++ b/docs/templating/twig_function_reference/quable_twig_functions.md @@ -0,0 +1,24 @@ +--- +description: Twig functions exposed by Quable connector +page_type: reference +--- + +# Quable Twig functions + +The [Quable connector](quable.md) provides the following Twig functions: + +## `ibexa_quable_instance_url()` + +Returns the [configured Quable instance URL](configure_quable_connector.md#configuration-example) (`ibexa_connector_quable.instance_url`). + +### Example + +``` html+twig + + Manage in Quable + +``` diff --git a/docs/templating/twig_function_reference/twig_function_reference.md b/docs/templating/twig_function_reference/twig_function_reference.md index c9810c8e80..d8ca339c65 100644 --- a/docs/templating/twig_function_reference/twig_function_reference.md +++ b/docs/templating/twig_function_reference/twig_function_reference.md @@ -24,4 +24,5 @@ In addition to the [native functions provided by Twig](https://twig.symfony.com/ "templating/twig_function_reference/date_twig_filters", "templating/twig_function_reference/ai_actions_twig_functions", "templating/twig_function_reference/discounts_twig_functions", + "templating/twig_function_reference/quable_twig_functions" ], columns=4) =]] diff --git a/main.py b/main.py index af2a37be87..8ee770e714 100644 --- a/main.py +++ b/main.py @@ -1,6 +1,7 @@ import os import pprint import re +import urllib.error import urllib.request from mkdocs.structure.pages import Page from mkdocs.utils import meta @@ -69,9 +70,12 @@ def cards(pages, columns=1, style="cards", force_version=False): if hash: hash = '#' + hash - if re.search("^https://[^@/]+.ibexa.co", path): + if re.search(r"^https?://", path): html = True - content = urllib.request.urlopen(path).read().decode('utf-8') + try: + content = urllib.request.urlopen(path).read().decode('utf-8') + except urllib.error.URLError: + content = "" elif re.search(".html$", path): html = True content = open("docs/%s" % path, "r").read() diff --git a/mkdocs.yml b/mkdocs.yml index ab51eb19bf..538645463a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -304,24 +304,25 @@ nav: - Assets: templating/assets.md - Image variations: templating/image_variations.md - Twig function reference: - - Twig function reference: templating/twig_function_reference/twig_function_reference.md + - AI Twig functions: templating/twig_function_reference/ai_actions_twig_functions.md - Cart Twig functions: templating/twig_function_reference/cart_twig_functions.md - Catalog Twig functions: templating/twig_function_reference/catalog_twig_functions.md - Checkout Twig functions: templating/twig_function_reference/checkout_twig_functions.md - Component Twig functions: templating/twig_function_reference/component_twig_functions.md - Content Twig functions: templating/twig_function_reference/content_twig_functions.md - Date Twig filters: templating/twig_function_reference/date_twig_filters.md + - Discounts functions: templating/twig_function_reference/discounts_twig_functions.md - Field Twig functions: templating/twig_function_reference/field_twig_functions.md - - Page Twig functions: templating/twig_function_reference/page_twig_functions.md - Icon Twig functions: templating/twig_function_reference/icon_twig_functions.md - Image Twig functions: templating/twig_function_reference/image_twig_functions.md + - Page Twig functions: templating/twig_function_reference/page_twig_functions.md - Product Twig functions: templating/twig_function_reference/product_twig_functions.md + - Quable functions: templating/twig_function_reference/quable_twig_functions.md - Site context Twig functions: templating/twig_function_reference/site_context_twig_functions.md - Storefront Twig functions: templating/twig_function_reference/storefront_twig_functions.md + - Twig function reference: templating/twig_function_reference/twig_function_reference.md - URL Twig functions: templating/twig_function_reference/url_twig_functions.md - User Twig functions: templating/twig_function_reference/user_twig_functions.md - - AI Twig functions: templating/twig_function_reference/ai_actions_twig_functions.md - - Discounts functions: templating/twig_function_reference/discounts_twig_functions.md - Twig Components: templating/components.md - URLs and routes: - URLs and routes: templating/urls_and_routes/urls_and_routes.md @@ -355,6 +356,7 @@ nav: - Product catalog guide: product_catalog/product_catalog_guide.md - Quable PIM integration: - Quable overview: product_catalog/quable/quable.md + - Quable product guide: product_catalog/quable/quable_guide.md - Install Quable: product_catalog/quable/install_quable.md - Configure Quable: product_catalog/quable/configure_quable_connector.md - Product catalog configuration: product_catalog/product_catalog_configuration.md