CEXT-1699 Draft version

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,142 @@
+---
+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 following arguments. The method returns a `mixed` data type. Individual converter classes must be created for each field when aiming to convert multiple fields within a payload. Conversely, the same class can be reused 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. You want to 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 '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 using the CLI while subscribing 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
+
+```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 defines the converter class that updates the event data field value for the specified event. Only one converter class can be used per field
+
+Attribute | Required | Description
+--- | --- | ---
+`converter` | No | The fully-qualified class name.
+
+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: