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.

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.

In the following example, the TestConverterVisibility converter class updates the value of the visibility field to a string.

<?php
/**
 * Copyright [first year code created] Adobe
 * All rights reserved.
 */
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:

{
   "event":{
      "data":{
         "value":{
            "visibility":"4",
        }
      }
   }
}

The converter changes the payload to:

{
   "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 env.php or config.php files or add them when using the CLI to subscribe to an event.

Command line

The bin/magento events:subscribe --fields command 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.

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.

'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.

<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>

Field-aware event conversion

data-slots=text

data-backgroundcolor=blue

By default, Commerce builds the entire source object (such as order, quote, or product) before trimming it down to the fields you subscribed to. For large records, this intermediate build can use significantly more memory and processing than the delivered payload requires.

When you enable field-aware event conversion, Commerce collects only the fields you subscribed to, plus any fields used by your event rules, instead of first building the complete source object. The data delivered to your destinations does not change — only how it is built internally.

Field-aware conversion helps most when you subscribe to a narrow set of fields on large records, such as orders or quotes with many items. Subscriptions that use a wildcard (fields:*) still build the full object, but they are protected from producing excessively large payloads by an early size check.

Enable field-aware event conversion

In the Commerce Admin, navigate to Stores > Settings > Configuration > Adobe Services > Adobe I/O Events > Commerce events, and set Field-aware event conversion to Yes. This setting is disabled by default.

You can also enable it from the command line:

bin/magento config:set adobe_io_events/eventing/field_aware_conversion_enabled 1

This setting takes effect immediately for any environment running version 1.22.0 or later of the eventing modules.