Merge pull request #149 from AdobeDocs/events-develop

Merge events-develop branch into main

src/data/navigation/sections/events.js

@@ -27,6 +27,10 @@ module.exports = [
     title: "Add custom fields",
     path: "/events/custom-event-fields.md"
   },
+  {
+    title: "Convert payload field values",
+    path: "/events/convert-field-values.md"
+  },
   {
     title: "Command reference",
     path: "/events/commands.md",

src/pages/events/commands.md

@@ -193,7 +193,7 @@ If you are implementing eventing in a performance testing environment, run the `
 
 ### Options
 
-`--fields=<field_name>` Required. An event field to transmit to the Adobe App Builder application. You can specify this option multiple times. Each instance can contain only one field name.
+`--fields='{"<name>":"<field-name>", "converter":"<path\to\converterclass>"}'` Required, but the `converter` argument is optional. Specifies an event field to transmit to the Adobe App Builder application. You can specify this option multiple times. Each instance can contain only one field name. The `converter` argument applies the [converter class](convert-field-values.md) to the specified field.
 
 `--force`, `-f` Forces subscription to the event, even if it hasn't been defined locally.
 
@@ -203,6 +203,8 @@ If you are implementing eventing in a performance testing environment, run the `
 
 `--rules=<field-name>|<operator>|<value>` Defines a rule that will be applied to the subscribed event. You can apply multiple rules to an event, but each rule must be defined separately. A rule definition must specify the field to be evaluated, an operator, and the value to be evaluated, in that order. The field name in a rule definition does not have to match a field specified with the `--fields` option.
 
+`--fields='{"<name>":"<field-name>", "converter":"<path\to\converterclass>"}'` Applies the converter class to the given field.
+
 ### Example
 
 To subscribe to a native event:

src/pages/events/convert-field-values.md

@@ -0,0 +1,147 @@
+---
+title: Convert payload field values
+description: Learn how to convert a field value based on a condition
+keywords:
+  - Events
+  - Extensibility
+---
+
+# Convert payload field values
+
+The payload of an event often includes field values that are not easily interpretable for third-party implementations. For example, a value might be stored in the Commerce database as an integer, but the external system stores the same information as a string. Alternatively, instead of transforming data types, you might want to change a Commerce-supplied string to a string defined in the external system. To address this issue, you can implement a converter, enabling custom values for any field in the payload.
+
+## Converter definition
+
+Your converter class must implement `FieldConverterInterface`. This interface contains the `convert` method, which accepts `mixed` and `Event` arguments. The method returns a `mixed` data type. You must create individual converter classes for each field when converting multiple fields within a payload. You can reuse a class to replace a specific field across multiple events.
+
+```php
+interface FieldConverterInterface
+{
+    /**
+     * Converts a field value
+     *
+     * @param mixed $value
+     * @param Event $event
+     * @return mixed
+     */
+    public function convert(mixed $value, Event $event);
+}
+```
+
+As an example, the `observer.catalog_product_save_after` event contains a top-level `visibility` field, which must contain an integer value. Convert these values to strings that match values on the external system. The following table describes these values.
+
+Commerce value | Converted value | Description
+--- | --- | ---
+1 | NOT_VISIBLE_INDIVIDUALLY | This product should not be displayed if it is part of a configurable product.
+2 | CATALOG_ONLY | This product appears in catalog listings, but not in searches.
+3 | SEARCH_ONLY | This product appears in searches, but not catalog listings.
+4 | CATALOG_AND_SEARCH | This product appears in catalog listings and searches. For most products, this is the default.
+
+In the following example, the `TestConverterVisibility` converter class updates the value of the `visibility` field to a string.
+
+```php
+<?php
+/**
+ * Copyright &copy; Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+declare(strict_types=1);
+
+namespace Magento\AdobeCommerceEventsClient\Event;
+
+use Magento\AdobeCommerceEventsClient\Event\Filter\FieldConverterInterface;
+
+class TestConverterVisibility implements FieldConverterInterface
+{
+    /**
+     * Method used to convert field value
+     *
+     * @param mixed $value
+     * @return mixed
+     */
+    public function convert(mixed $value, Event $event): mixed
+    {
+        return match ($value) {
+            '1' => 'NOT_VISIBLE_INDIVIDUALLY',
+            '2' => 'CATALOG_ONLY',
+            '3' => 'SEARCH_ONLY',
+            '4' => 'CATALOG_AND_SEARCH'
+        };
+    }
+}
+```
+
+The default payload for this event includes the following:
+
+```json
+{
+   "event":{
+      "data":{
+         "value":{
+            "visibility":"4",
+        }
+      }
+   }
+}
+```
+
+The converter changes the payload to:
+
+```json
+{
+   "event":{
+      "data":{
+         "value":{
+            "visibility":"CATALOG_AND_SEARCH",
+        }
+      }
+   }
+}
+```
+
+## Register the converter
+
+You must configure a module's `io_events.xml` or root `app/etc/io_events.xml` file to update the required fields. You can also declare them in the system `config.php` file or add them when using the CLI to subscribe to an event.
+
+### Command line
+
+The [`bin/magento events:subscribe --fields` command](commands.md#subscribe-to-an-event) defines the fields and converters to include in the payload of a subscribed event. The example command adds the `visibility` field and provides the path to the converter class. You can specify multiple fields in the same request.
+
+```bash
+bin/magento events:subscribe observer.catalog_product_save_after --fields="store_id" --fields='{"name":"visibility", "converter": "Magento\AdobeCommerceEventsClient\Event\TestConverterVisibility"}'`
+```
+
+### `config.php` file
+
+The following example `config.php` is the equivalent of the example `bin/magento events:subscribe` command in the **Command line** example above.
+
+```php
+'io_events' => [
+        'observer.catalog_product_save_after' => [
+            'fields' => [
+                'store_id',
+                [
+                    'name' => 'visibility',
+                    'converter' => 'Magento\\AdobeCommerceEventsClient\\Event\\TestConverterVisibility'
+                ]
+            ],
+            'enabled' => 1
+        ]
+ ]       
+```
+
+### Configure an `io_events.xml` file
+
+The `converter` attribute of the `field` element defines the converter class that updates the event data field value for the specified event. Only one converter class can be defined per field.
+
+The following example updates the value of the field `visibility` present in the `observer.catalog_product_save_after` event payload using the `TestConverterVisibility` converter class.
+
+```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="visibility" converter="Magento\AdobeCommerceEventsClient\Event\TestConverterVisibility"/>
+        </fields>
+    </event>
+</config>
+```

src/pages/events/module-development.md

@@ -223,6 +223,8 @@ The contents of an `observer.catalog_product_save_after` event are similar to th
 }
 ```
 
+The `<field>` element can also contain the `converter` attribute. Use this attribute to change the value of a field in the event payload. [Convert payload field values](./convert-field-values.md) describes its usage.
+
 ### Array of nested objects
 
 When the payload contains an array of objects, use the following construction to register specific fields from that array:

src/pages/events/release-notes.md

@@ -12,6 +12,20 @@ These release notes describe the latest version of Adobe I/O Events for Adobe Co
 
 See [Update Adobe I/O Events for Adobe Commerce](installation.md#update-adobe-io-events-for-adobe-commerce) for upgrade instructions.
 
+## Version 1.5.0
+
+### Release date
+
+February 7, 2024
+
+### Enhancements
+
+* Added support for [field converters](convert-field-values.md). You can now create a converter class that changes the data type or value of fields in an event payload. <!--- CEXT-1699 -->
+
+* Added an event tracking ID field for better tracking of the event delivery process.  <!--- CEXT-2759 -->
+
+* Increased test coverage of eventing modules. <!--- CEXT-2640 -->
+
 ## Version 1.4.1
 
 ### Release date