CEXT-5400: Add origData to the event payload and release notes

src/_includes/conditional-event-example.md

@@ -4,5 +4,6 @@ The following example creates and registers a conditional event named `plugin.ma
 *  The `category_id` is either `3`, `4`, or `5`
 *  The product `name` contains `TV`
 *  The `store_id` of product category is either `1` or `2`
+*  The `quantity_and_stock_status.qty` value has changed
 
 These fields are present and declared in the parent event.

src/_includes/conditional-event.md

@@ -25,5 +25,8 @@ Each rule contains the following:
    | `equal`       | Checks whether the payload value matches the specified value. For Boolean data types, use `1` to compare to `true` and `0` to compare to `false`. |
    | `regex`       | A regular expression that checks for matches. The specified value must be compatible with the [regular expression match](https://www.php.net/manual/en/function.preg-match.php). |
    | `in`          | Checks whether the payload value is one of multiple specified values. The value must be a comma-separated list. You do not need to provide additional escape characters. |
+   | `onChange`    | <Edition name="paas" />Checks whether the provided field's value has changed compared to its previous value. The value attribute is optional. If provided, the operator checks whether the field's new value is equal to the specified value field. |
 
 *  The value to compare against. When you assign the `regex` operator, you must delimit the regular expression value with valid characters, such as forward slashes (/). For example, `/^TV .*/i`, which checks whether the string starts with the string `TV`, ignoring the case of the letters.
+
+*  The value in the `onChange` operator is a path to a field to compare against. By default, comparison is done against `field` and `_origData.field` values. In cases where the event payload has a different structure, you can provide a custom path to compare against.

src/data/navigation/sections/events.js

@@ -49,6 +49,10 @@ module.exports = [
     title: "Create event subscriptions in a module",
     path: "/events/module-development.md",
   },
+  {
+    title: "Create event subscriptions with original data",
+    path: "/events/events-original-data.md",
+  },
   {
     title: "Create conditional events",
     path: "/events/conditional-events.md",

src/pages/events/conditional-events.md

@@ -1,7 +1,6 @@
 ---
 title: Create conditional events
 description: Create custom Adobe Commerce conditional events using declarative configuration.
-edition: paas
 keywords:
   - Events
   - Extensibility
@@ -50,11 +49,72 @@ You can create conditional events within your module's or root `io_events.xml` f
               <operator>in</operator>
               <value>1,2</value>
            </rule>
+           <rule>
+               <field>quantity_and_stock_status.qty</field>
+               <operator>onChange</operator>
+               <value />
+           </rule>
         </rules>
     </event>
 </config>
 ```
 
+## Trigger events on specific field changes
+
+<Edition name="paas" />
+
+<InlineAlert variant="warning" slots="text"/>
+
+This rule is possible only for events that include original data [`_origData`](./events-original-data.md) in the payload. If an event does not include original data, the `onChange` operator cannot be used, and such an event will not be triggered.
+
+For events that contain original data [`_origData`](./events-original-data.md) within the payload, you can create conditional events that trigger only when specific fields change. It can reduce the number of events sent to your application when only specific field changes are relevant.
+
+To check if the event payload contains original data, you can visit **System** > Events > **Events List** page or use the [`bin/magento events:info <event_code>`](./commands.md#return-event-details) command.
+
+For example, you want to trigger an event only when the product stock quantity changes:
+
+```xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="...">
+    <event name="plugin.magento.catalog.model.resource_model.product.on_stock_change_event"
+           parent="plugin.magento.catalog.model.resource_model.product.save">
+        <fields>
+            <field name="qty"/>
+            <field name="category_id"/>
+            <field name="name"/>
+        </fields>
+        <rules>
+            <rule>
+                <field>quantity_and_stock_status.qty</field>
+                <operator>onChange</operator>
+                <value />
+            </rule>
+        </rules>
+    </event>
+</config>
+```
+
+In this example the payload value of `quantity_and_stock_status.qty` is compared to its previous value stored in `_origData.quantity_and_stock_status.qty`. The event is triggered only when the quantity value has changed.
+
+For some events the payload structure may differ and the original data [`_origData`](./events-original-data.md) may not be available as a root node. In such cases you can provide a custom path to compare against in the `value` element:
+
+```xml
+<event name="observer.checkout_cart_product_add_before">
+    <fields>
+        <field name="*"/>
+        <field name="_origData"/>
+    </fields>
+    <rules>
+        <rule>
+            <field>product.quantity_and_stock_status.qty</field>
+            <operator>onChange</operator>
+            <value>product._origData.quantity_and_stock_status.qty</value>
+        </rule>
+    </rules>
+</event>
+```
+
+In this example the payload value of `product.quantity_and_stock_status.qty` is compared to the value stored in `product._origData.quantity_and_stock_status.qty`.
+
 ## Command line
 
 The `bin/magento events:subscribe <event_code> --force --fields=<name1> --fields=<name2>` command creates and registers custom and native Commerce events. When you also specify the `--parent <event_code>` and `--rules=<field-name>|<operator>|<value>` options, you create and register a conditional event.

src/pages/events/create-events.md

@@ -121,6 +121,12 @@ Operator: in
 Value: 1,2
 ```
 
+<!--
+Field: quantity_and_stock_status.qty
+Operator: onChange
+Value:
+-->
+
 ## Events Subscriptions grid actions
 
 Click **Select** > **Edit** in the **Action** column of an event subscription's row to display a form for editing the subscription.

src/pages/events/events-original-data.md

@@ -0,0 +1,107 @@
+---
+title: Create event subscriptions with original data
+description: Use original event data in Adobe Commerce events.
+edition: paas
+keywords:
+  - Events
+  - Extensibility
+---
+
+# Create event subscriptions with original data
+
+Events that are based on objects that implement a specific interface in Adobe Commerce can include the original data of the object in the event payload. The original data represents the state of the object before any changes were made. This is particularly useful for events that are triggered by updates to objects, as it allows you to compare the previous state with the new state.
+
+If the object is new (such as when a new product is created), the original data will be empty. Events that support original data also include an `_isNew` field in the payload, which indicates whether the object is new or existing.
+
+To check if an event includes original data in its payload, you can visit **System** > Events > **Events List** page or use the following command [`bin/magento events:info <event_code>`](./commands.md#return-event-details). Keep in mind that that the returned payload for some events, especially those that are dynamically defined, might not include full details.
+
+To include original data in the event payload, the event must be configured to include the `_origData` field even if the wildcard `*` is used to include all fields. For example, if you want to receive the whole payload including original data for the `observer.catalog_product_save_after` event, you can configure it as follows:
+
+<InlineAlert variant="warning" slots="text" />
+
+The `_origData` field is not included by default even when using the wildcard `*`, so you must explicitly add it to the event configuration.
+
+```xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module-commerce-events-client/etc/io_events.xsd">
+    <event name="observer.catalog_product_save_after">
+        <fields>
+            <field name="*"/>
+            <field name="_origData"/>
+        </fields>
+    </event>
+</config>
+```
+
+As a result, the event payload will include the `_origData` field with the original data of the product before it was saved:
+
+```json
+{
+  "sku": "Simple product",
+  "name": "Simple product",
+  "price": "500.000000",
+  "quantity_and_stock_status": {
+    "is_in_stock": "1",
+    "qty": "3126"
+  },
+  .....
+  "_origData": {
+    "sku": "Simple product",
+    "name": "Simple product New Name",
+    "price": "600.000000",
+    "quantity_and_stock_status": {
+      "is_in_stock": true,
+      "qty": 3125
+    },
+    .....
+  },
+  "_isNew": false
+}
+```
+
+For some events with a complex payload structure, the original data might not be available as a root node. In such cases, you can provide a custom path to include the original data. For example, for the `observer.checkout_cart_product_add_before` event, you can configure it as follows:
+
+```xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module-commerce-events-client/etc/io_events.xsd">
+    <event name="observer.checkout_cart_product_add_before">
+        <fields>
+            <field name="*"/>
+            <field name="product._origData"/>
+            <field name="quote_item._origData"/>
+        </fields>
+    </event>
+</config>
+```
+
+You can define specific original and new fields to be included in the event payload. For example, if you want to include only the `sku` and `quantity_and_stock_status.qty` fields, along with their original values, configure the event as follows:
+
+```xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module-commerce-events-client/etc/io_events.xsd">
+    <event name="observer.catalog_product_save_after">
+        <fields>
+            <field name="sku"/>
+            <field name="quantity_and_stock_status.qty"/>
+            <field name="_origData.sku"/>
+            <field name="_origData.quantity_and_stock_status.qty"/>
+        </fields>
+    </event>
+</config>
+```
+
+As a result, the event payload will include only the selected fields and their original values:
+
+```json
+{
+  "sku": "Simple product",
+  "quantity_and_stock_status": {
+    "qty": "3126"
+  },
+  "_origData": {
+    "sku": "Simple product",
+    "quantity_and_stock_status": {
+      "qty": 3125
+    }
+  }
+}
+```
+
+The original data can be used in conditional events using the `onChange` operator to trigger events only when specific fields have changed. For more information, see [Create conditional events](./conditional-events.md#trigger-events-on-specific-field-changes).