diff --git a/src/data/navigation/sections/events.js b/src/data/navigation/sections/events.js index 9edd6641..32754d65 100644 --- a/src/data/navigation/sections/events.js +++ b/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", diff --git a/src/pages/events/commands.md b/src/pages/events/commands.md index 86bad2a3..c749cbcb 100644 --- a/src/pages/events/commands.md +++ b/src/pages/events/commands.md @@ -193,7 +193,7 @@ If you are implementing eventing in a performance testing environment, run the ` ### Options -`--fields=` 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='{"":"", "converter":""}'` 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=||` 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='{"":"", "converter":""}'` Applies the converter class to the given field. + ### Example To subscribe to a native event: diff --git a/src/pages/events/convert-field-values.md b/src/pages/events/convert-field-values.md new file mode 100644 index 00000000..ca271fdc --- /dev/null +++ b/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 + '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 + + + + + + + +``` diff --git a/src/pages/events/module-development.md b/src/pages/events/module-development.md index 6ccdd69b..58531709 100644 --- a/src/pages/events/module-development.md +++ b/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 `` 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: diff --git a/src/pages/events/release-notes.md b/src/pages/events/release-notes.md index 189eba90..b47a88ec 100644 --- a/src/pages/events/release-notes.md +++ b/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. + +* Added an event tracking ID field for better tracking of the event delivery process. + +* Increased test coverage of eventing modules. + ## Version 1.4.1 ### Release date