Event Based eXporter

Installation

1. Copy the contents of the module ZIP file to the root directory of your Magento project
2. Run the following terminal command in the root directory of your Magento project:
   php bin/magento setup:upgrade

Configuration

Profiles

Export functionality of EBX is controlled through so-called profiles. You need to create at least one profile to start the export.

Steps to create a profile:

1. Log in to Magento admin
2. Select System / Oander Event Based eXporter / Profiles in the left menu
3. Click the Add New Profile button
4. Fill in the form as follows:
   • Name - For identification purposes only, not used by the export process. Example: Orders to Kepler
   • Event Based Export Enabled - Enable or disable event based export for this profile. It is advised to enable it only after initialization (see below).
   • Send Directly to Queue - Enable it for slow remote servers or during initialization
   • Type - Magento entity type to be exported, eg. Order
   • HTTP Method - As required by the remote server eg. POST
   • URL - Absolute URL of the remote server's API endpoint eg. https://api.oanderconnect.com/order
   • Authorization Type - As required by the remote server. Currently, only No authorization and Bearer token are supported.
   • Authorization Bearer Token - Token to use if Authorization Type is Bearer token
5. Click Save Profile or Save and Continue Edit

Initialization

To export data that is created before EBX installation and configuration, you need to initialize each profile. Initialization can be skipped in cases like EBX had been installed before the website has gone to production.

Steps to initialize a profile:

1. Create a profile (see above)
2. Click Select in the Action column of the profile grid, then click Initialize, or click the Initialize Profile button on the top button bar of the profile page
3. Enter the starting and ending entity IDs to be exported. Inputs are pre-filled with the first and last IDs in the database, you only need to change them if you want to initialize a part of your entities. Leave them at their default values if you want a full initialization. Please note that these are internal Magento entity IDs that are different from other identifiers such as order increment ID or product SKU.
4. Click the Start initialization button

Initialization is done via cron. You can monitor the progress of initialization by checking the values of Items in PreQueueand Items in Resend Queue counters on the initialization form. Both should be zero when initialization has been finished. Please note that the counters are only refreshed when you reload the page. See below for a more detailed explanation of the PreQueue and the Resend Queue.

To avoid errors on a production website caused by a previous state of an entity overwriting the current state of an entity sent earlier, enable Send Directly to Queue first, start the initialization, let it finish and disable Send Directly to Queue when initialization has been finished.

System config

1. Select Stores / Settings / Configuration in the admin menu on the left
2. Select the OANDER EVENT BASED EXPORTER / Settings tab

Cron is required to be enabled for initialization and resend. Also, the Magento cron job has to be properly configured. See the Magento documentation for information about cron configuration: https://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli-subcommands-cron.html

The resend queue

If the event based export of an entity fails for any reason (eg. remote server downtime or network issues), the data to be exported is inserted to a resend queue and tried to be resent later via cron. This method guarantees that all data will be sent eventually, when normal operation is restored. The resend queue is also used by the initialization process. It is stored in the oander_ebx_resend_queue table in the database.

The PreQueue

The PreQueue is used by the initialization process. Each item in the PreQueue points to an entity to be exported. Entities are first converted to the format needed for export and then inserted to the Resend Queue. The PreQueue is stored in the oander_ebx_pre_queue table in the database.

Adding new entity types to EBX

Thanks to the modular architecture of EBX, it can be extended with any entity type without modifying the original module.

Steps to add EBX functionality to your entity type:

1. Create a type option observer
   Create an observer class that extends Oander\EventBasedExporter\Observer\TypeOption\AbstractTypeOptionObserver, implement the getOptionDataabstract method (please refer to its phpDoc), and attach the observer to the oander_ebx_convert_order event. You should see your entity type in the type selector dropdown of the profile form when done.
2. Create an entry point to access the data being saved
   This is typically an observer attached to a Magento event, but plugins can also be used if no event is available. Use the *_save_commit_after events to ensure the entity has been saved to the Magento database.
3. Call the EventProcessor
   Call Oander\EventBasedExporter\Api\EventProcessorInterface::processEvent in your entry point observer and pass your entity type and entity object to be exported. The EventProcessor will find every matching profile and wil process each of them. Note that disabled profiles will not be used.
4. Create your converter
   Create a class that extends Oander\EventBasedExporter\Observer\Convert\AbstractConvertObserver, implement the accept and convert abstract methods (please refer to the phpDoc of AbstractConverter) and attach your observer to the oander_ebx_convert_* event, where * is your entity type, exactly the same as provided in your type option observer in step 1. The converted data returned by your converter must be an associative array, containing only primitive values eg. int, float, bool and null, and other arrays.

The four steps above are enough for event based export to work. Two more steps are needed for initialization:

1. Create a load observer
   Create an observer that extends Oander\EventBasedExporter\Observer\Load\OrderLoadObserver, implement the loadById abstract method and attach your observer to the oander_ebx_load_* event, where * is your entity type, exactly the same as provided in your type option observer. The sole purpose of this observer is to load an entity by its entity ID.
2. Create an entity ID range observer
   Create an observer that extends Oander\EventBasedExporter\Observer\EntityIdRange\AbstractEntityIdRangeObserver, implement the getIdRangeabstract method (detailed phpDoc is available in the class, please refer to it) and attach your observer to the oander_ebx_entity_id_range_* event where * is your entity type, exactly the same as provided in your type option observer. Note that initialization will still work if this observer is not implemented, but Entity ID From and Entity ID To inputs will not be pre-filled on the initialization form.

See the etc/events.xml file of this module and the referenced classes in it for examples of all of the above steps.