Merge branch 'akeneo:master' into master

Author: alin-plamadeala

.gitleaks.toml

@@ -17,5 +17,5 @@ paths = [
     # Rest API old authentication
     '''content/rest-api/authentication_old.md''',
     # UI Extension documentation
-    '''content/extensions/ui-extensions.md''',
+    '''content/extensions/getting-started.md''',
 ]

content/apps/overview.md

@@ -28,7 +28,7 @@ Apps integrate with Akeneo in the following ways:
     - easily **get a pre-filtered product selection** configured by your users from their PIM interface,
     - push your app requirements and **get mapped product data** calling catalogs endpoints without developing any mapping interface
     - provide a **consistent experience** to users
-- connecting with our **[REST API](/api-reference-index.html)**, **[GraphQL API](/event-platform/overview.html)**, **[Event Platform](/graphql/getting-started.html)** to read and write Akeneo data
+- connecting with our **[REST API](/api-reference-index.html)**, **[GraphQL API](/graphql/getting-started.html)**, **[Event Platform](/event-platform/overview.html)** to read and write Akeneo data
 
 ![App in Akeneo Product Cloud](../img/apps/apps-fit-akeneo.png)
 

content/concepts/catalog-structure.md

@@ -87,6 +87,7 @@ Below is the list of attribute types and their description:
 | Reference data simple select | pim_reference_data_simpleselect | allows you to manage any kind of data that has its own properties, as a single-choice select. |
 | Reference data multi select | pim_reference_data_multiselect | allows you to manage any kind of data that has its own properties, as a multi-choice select. |
 | Table (Growth and Enterprise editions only) | pim_catalog_table | allows you to manage multidimensional data in the form of a table |
+| Product link | pim_catalog_product_link | allow you to create a unidirectional relationship between a product/product model and another.                                                                                                                   |
 
 In the Akeneo UI, you can find the attributes in the `Settings`/`Attributes` menu. Below is an example of one attribute in the UI.
 
@@ -143,7 +144,7 @@ The `group_labels` field is only available since the 5.0.
 _Focus on the table attribute configuration_
 
 The structure of a table attribute is defined in a specific `table_configuration` field, which describes the columns of the table.
-Each column is defined by a data type (select, text, boolean, number), and a unique code. It can hold a collection of labels,
+Each column is defined by a data type (select, text, boolean, number, incremental_number, reference_entity, product_link, measurement, date), and a unique code. It can hold a collection of labels,
 and user-defined validation constraints based on the column data type. A table configuration must define at least two columns, and the first one has to be a `select` data type.
 In order to ensure that the PIM will still be running, we have defined some limits.  
 - You can create up to **10 columns** in a single table.

content/concepts/products.md

@@ -387,6 +387,69 @@ Whenever the attribute's type is `pim_catalog_number`, the `data` field should c
 }
 ```
 
+#### Product link attribute
+::: availability versions=SaaS editions=EE
+:::
+
+Whenever the attribute type is pim_catalog_product_link, the data field must contain:
+- The `type` of the linked entity, with the value `product` or `product_model`
+- The `identifier` or the `id` of the linked entity:
+  - If type is `product`: either the UUID in the id key, or the identifier in the identifier key
+  - If type is `product_model`: the product model code in the id key
+
+##### Examples
+```json
+{
+  "values": {
+    "included_battery": [
+      {
+        "locale": null,
+        "scope": null,
+        "data": {
+          "type": "product",
+          "id": "fc24e6c3-933c-4a93-8a81-e5c703d134d5"
+        },
+        "attribute_type": "pim_catalog_product_link"
+      }
+    ]
+  }
+}
+```
+```json
+{
+  "values": {
+    "included_battery": [
+      {
+        "locale": null,
+        "scope": null,
+        "data": {
+          "type": "product",
+          "identifier": "bl1850b"
+        },
+        "attribute_type": "pim_catalog_product_link"
+      }
+    ]
+  }
+}
+```
+```json
+{
+  "values": {
+    "included_battery": [
+      {
+        "locale": null,
+        "scope": null,
+        "data": {
+          "type": "product_model",
+          "id": "my_super_battery"
+        },
+        "attribute_type": "pim_catalog_product_link"
+      }
+    ]
+  }
+}
+```
+
 #### Metric attribute
 ::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS editions=CE,EE
 :::

content/event-platform/available-events.md

@@ -1171,6 +1171,21 @@ The modifications that can lead to this event include:
                 "scope": "a_scope"
               }
             ],
+            "a_pim_catalog_product_link_attribute": [
+              {
+                "previous": {
+                  "type": "product",
+                  "id": "83413cad-b3aa-4f68-9b4b-7fc90c1ce84a"
+                },
+                "new": {
+                  "type": "product",
+                  "id": "aeabe737-f655-4389-bcc0-d8dd2fc47824"
+                },
+                "type": "pim_catalog_product_link",
+                "locale": "a_locale",
+                "scope": "a_scope"
+              }
+            ],
             "a_pim_catalog_number_attribute": [
               {
                 "previous": 0,

content/event-platform/concepts.md

@@ -51,8 +51,21 @@ The statuses for a subscription are:
 
 ## Subscription types
 
+::: info
+We will consider adding other subscription destinations based on feedback. Please [fill-in this form](https://forms.gle/XsZ7rovRnqfAn4xF9) to propose & upvote new destination types.
+:::
+
+
 ### Pub/Sub subscription
 
+This is the **preferred and most resilient method** for consuming events. It leverages Google Cloud's managed messaging service.
+
+#### Key Advantages
+
+- **Managed Scalability & Reliability:** Google Pub/Sub inherently handles high throughput and traffic bursts, absorbing the complexities of scaling.
+- **Reduced Infrastructure Burden:** Significantly lowers the operational overhead and risk for the customer.
+- **Simplified Integration:** Easier setup and maintenance compared to managing a custom HTTP endpoint.
+
 #### Configuration
 
 For the `pubsub` subscription type, the `config` property needed when creating the subscription requires both the project ID and the topic ID.
@@ -90,6 +103,25 @@ For comprehensive details on managing subscriptions, consult the complete API re
 
 ### HTTPS subscription
 
+This option pushes events directly to a HTTP endpoint. It offers flexibility but requires careful infrastructure planning.
+
+#### Critical Requirements & Considerations
+
+- **Strong Infrastructure:** The endpoint must be highly available and designed to handle variable event loads.
+    - This also depends on the **source PIM's size and activity**. A small PIM with few SKUs won't generate the same volume as a large instance with many jobs. Thus, the **HTTP endpoint** can be adjusted based on the PIM's intended use.
+- **Mandatory Rate Limiting (HTTP 429):**
+    - Our platform **dynamically adjusts its delivery rate from 1 to 100 events per second.**
+    - This adaptive mechanism **relies entirely on the endpoint correctly returning an `HTTP 429 "Too Many Requests"` status** when its capacity is reached. [ref](https://api.akeneo.com/event-platform/key-platform-behaviors.html#optimized-throughput)
+
+::: warning
+Endpoints without proper HTTP 429 handling are at high risk of being overwhelmed, leading to event loss and subscription suspension.
+:::
+
+- **Fast Acknowledgement:** Endpoints must respond with an `HTTP 200 OK` within **5 seconds**. Delays trigger retries and can lead to suspension. [ref](https://api.akeneo.com/event-platform/key-platform-behaviors.html#delivery-timeout)
+    - **Recommendation:** Implement an asynchronous processing model (e.g., using an internal queue) to acknowledge events quickly and process them separately.
+- **Suspension Policy:** Subscriptions may be suspended due to repeated errors (e.g., `4xx`/`5xx` status codes, timeouts, misconfigured SSL). [ref](https://api.akeneo.com/event-platform/key-platform-behaviors.html#suspension-policy)
+
+
 #### Configuration
 
 For the `https` type, the `config` property requires:
@@ -177,6 +209,8 @@ We currently use a static IP address provided by Google Cloud: `34.140.80.128`
 
 When configuring a subscription, you can optionally define a **filter** to receive **only the events that match specific criteria**.
 
+**Regardless of the destination type, we strongly advise to utilize event filters.** This ensures you only subscribe to and receive events that are relevant to your specific integration needs.
+
 You can find the list of currently available filters and the correct syntax to use [here](/event-platform/available-filters.html).
 
 ### Example

content/event-platform/key-platform-behaviors.md

@@ -1,4 +1,3 @@
-
 # Key platform behaviors
 
 Your subscribing service implementation and architecture must deal with the following capabilities and constraints to consume events from the platform at its best.
@@ -14,15 +13,27 @@ To help identify duplicated events and deal with un-ordered events if it's somet
 
 ## Optimized throughput
 
-Our delivery engine will try to deliver events as fast as possible but will adapt the throughput within the limits described in this section.
+If your subscription has an HTTPS destination, our delivery engine adapts the event delivery rate based on your system's capacity, operating within these limits:
+
+**Maximum rate:** `100` events per second
+
+**Minimum rate:** `1` event per second
+
+
+The throughput automatically adjusts between these limits based on your endpoint's responses:
+- `200 OK`: The delivery rate gradually increases up to the maximum rate
+- `429 Too Many Requests`: The delivery rate decreases to prevent system overload
+
+::: warning
+Events that are throttled and remain undelivered for more than one hour will negatively impact your success rate, as it indicates a potential queuing risk. This may trigger the [suspension policy](/event-platform/key-platform-behaviors.html#suspension-policy).
+:::
 
-If your subscription has an HTTPS destination, please respond with `429 Too Many Requests` when your system is overloaded: this way, the delivery engine will slow down, retry undelivered events, and gradually increase the throughput when your system gets back to recovers (i.e., when it responds `200 OK` again).
+Consider using another [subscription type](/event-platform/concepts.html#subscription-types) to get around these limitations.
 
-Please note that if the throughput drops too significantly, the suspension policy will be triggered ([see bellow](/event-platform/key-platform-behaviors.html#suspension-policy)).
 
 ## Delivery timeout
 
-Specifically for the HTTPS destination type, the delivery timeout ensures that messages are processed within a specified  time frame. Your endpoint is expected to handle requests within **`5 seconds`**.  If processing exceeds this duration, the event will enter the retry process ([see bellow](/event-platform/concepts.html#retry-policy-for-transient-failures.html)).
+Specifically for the HTTPS destination type, the delivery timeout ensures that messages are processed within a specified  time frame. Your endpoint is expected to handle requests within **`5 seconds`**.  If processing exceeds this duration, the event will enter the retry process ([see bellow](/event-platform/concepts.html#retry-policy-for-transient-failures)).
 
 Under normal circumstances, your HTTPS endpoint must handle the event as fast as possible.
 **Our recommendation** is to put the message in a `queuing system` or in a `database` for asynchronous processing.
@@ -53,12 +64,12 @@ Your subscription is immediately suspended if you meet one of these conditions:
 
 ### Threshold-Based Suspension:
 
-This type of suspension is based on the success rate of your HTTPS endpoint. If the success rate drops below 95% within the last rolling hour, your subscription will be suspended.
+This type of suspension is based on the success rate of your HTTPS endpoint. If the success rate drops below 90% within the last rolling hour, your subscription will be suspended.
 
 Here are the errors type that decrease the success rate:
 
 - `5XX Server Error` HTTP statuses
-- `429 Too Many Requests` HTTP statuses (while the minimum rate threshold is exceeded)
+- `429 Too Many Requests` HTTP statuses (while the event remains undelivered for more than one hour)
 - `4xx Client Error Response` HTTP status
 - Delivery timeout
 

content/event-platform/limitations.md

@@ -8,9 +8,9 @@
 
 **Event Platform Quotas:**
 
-Our Event platform has specific quotas designed to ensure optimal performance and fair usage for all users.
-- **Weekly Event Limit**: You can distribute up to 5 million events per week for the light payload.
-- **Exceeding Limits**: If you exceed this limit occasionally, your usage will not be interrupted. However, habitual overages may require further discussion to optimize your usage.
+Our event platform does not impose specific quotas.
+
+However, to ensure optimal performance and fair use for all users, heavy usage (millions of events per day) may require further discussion to help you optimise your usage.
 
 ::: panel-link Consult now our FAQ [Next](/event-platform/faq.html)
 :::

content/extensions/faq.md

@@ -0,0 +1,12 @@
+## FAQ
+### Who is responsible for UI extensions?
+Akeneo is responsible for the UI extensions framework itself, including the APIs and administrative interface. We provide support for these components. Your organization or your integrator is responsible for any custom code, iframes, or other custom development built within the UI extensions. Support for this custom code falls to your organization or integrator, not Akeneo.
+
+### How can I add a new UI extension to my PIM?
+Adding a new extension to your organization is easy! Just follow the steps in [this guide](https://api.akeneo.com/extensions/getting-started.html#getting-started).
+
+### The UI extensions entry isn't showing up in my PIM. Could you help me understand why?
+If you don't see the UI extensions entry in your PIM, it's likely due to permission settings. [This guide](https://api.akeneo.com/extensions/getting-started.html#authorization) will help you check and activate the necessary permissions.
+
+### I'd like to see my extension in a position that isn't currently available. What can I do?
+Currently, UI extension placements are limited to those defined by Akeneo. However, we highly value your feedback! Please contact your Customer Success Manager or our Support team to share your specific placement needs. This will help us understand your use case and consider it for future development.

content/extensions/filtering.md

@@ -0,0 +1,23 @@
+# Filter and display UI extensions
+
+You may want to create UI extensions that are only available to certain user groups or for specific products. This can be achieved by filtering UI extensions based on user groups and product selection.
+
+### Filter UI extension by user groups
+
+You can filter the user groups allowed to see and execute an UI extension by using the permissions tab on the UI extensions creation/edition form.
+
+[![ui-extension-permissions.png](../img/extensions/ui-extensions/ui-extension-permissions.png)](../img/extensions/ui-extensions/ui-extension-permissions.png)
+
+### Filter UI extension by product selection
+You can filter the products that can be selected by an UI extension by using the product selection tab on the UI extensions creation/edition form.
+
+[![ui-extension-product-selection.png](../img/extensions/ui-extensions/ui-extension-product-selection.png)](../img/extensions/ui-extensions/ui-extension-product-selection.png)
+
+### Order UI extensions
+
+In addition to the filtering capacity, you can order the UI extension in the UI using the `weight` field on the creation/update form. This will determine the order in which extensions are displayed in the **header** and **tab** positions.
+
+[![ui-extension-product-selection.png](../img/extensions/ui-extensions/weight.png)](../img/extensions/ui-extensions/weight.png)
+
+::: panel-link FAQ [Next](/extensions/faq.html)
+:::