Projects:Magento Connector Core Infrastructure Developers Guide

Contents 1 Introduction 2 Performing Magento Requests 3 Export to Magento 3.1 The Export Requests 3.1.1 MagentoEndpointRequester 3.1.2 DefaultMagentoEndpointRequester 3.2 Post-Export Actions 4 Property Format 5 External Instance Identifier Provider 6 Synchronization Processes

Introduction

The following guide describes some of the basic components of the Magento Connector - Core Infrastructure module. It also explains how to extend some of its components in order to add custom behavior.

Before starting with this guide, it is strongly recommended to read the External Integration Infrastructure User Guide where some of the concepts mentioned along this guide are explained in detail.

Performing Magento Requests

The MagentoRequestHelper is the class that helps to build request to fetch/send data from/to a Magento server. It is both directly when importing records from Magento and by the BaseMagentoExport class when exporting records.

This class extends the RequestHelper interface that defines the different methods that should be implemented to communicate with Magento:

 
public interface RequestHelper {
 
  /**
   * Fires a request to add elements in Magento.
   * 
   * @param endpoint
   *          the URL of the endpoint where the request should be done.
   * @param body
   *          the content of the request.
   * @return a String containing the response of the request.
   * @throws MagentoRequestException
   *           if the request could not be successfully completed
   */
  public String add(String endpoint, String body) throws MagentoRequestException;
 
  /**
   * Fires an update request Magento.
   * 
   * @param endpoint
   *          the URL of the endpoint where the request should be done.
   * @param body
   *          the content of the request.
   * @return a String containing the response of the request.
   * @throws MagentoRequestException
   *           if the request could not be successfully completed
   */
  public String update(String endpoint, String body) throws MagentoRequestException;
 
  /**
   * Fires request to retrieve information from Magento.
   * 
   * @param endpoint
   *          the URL of the endpoint where the request should be done.
   * @return a String containing the response of the request.
   * @throws MagentoRequestException
   *           if the request could not be successfully completed
   */
  public String get(String endpoint) throws MagentoRequestException;
 
  /**
   * Fires request to retrieve information from Magento.
   * 
   * @param endpoint
   *          the URL of the endpoint where the request should be done.
   * @param filter
   *          a {@code MagentoFilter} to specify the filtering of the data to be retrieved.
   * @return a String containing the response of the request.
   * @throws MagentoRequestException
   *           if the request could not be successfully completed
   */
  public String get(String endpoint, MagentoFilter filter) throws MagentoRequestException;
}
 

Export to Magento

The BaseMagentoExporter class is the class in charge of exporting records from Openbravo to Magento. It defines the behavior to export records to Magento by following these steps:

1. Builds the Magento endpoint URL with the mapping information, using the MagentoEndpointBuilder class.
2. It checks if the record to be exported exists or not in Magento. Depending on that the request to be fired against Magento will vary.
3. If the record does not exist in Magento, then a request to add the new record is fired. Otherwise, a request to update the record in Magento is fired. By default, the requests are done with the DefaultMagentoEndpointRequester class for all endpoints.
4. For the records exported for the first time, the related Magento ID is inserted in the Table of IDs.
5. Finally, additional post export actions can be executed.

This export process allows to extend parts of its behavior so developers can include custom behavior. The extensible parts of this process are explained below.

The Export Requests

MagentoEndpointRequester

The MagentoEndpointRequester is the base class to perform requests to a Magento endpoint. It provides some abstract methods:

 
  /**
   * Fires a request to create a new record in Magento.
   * 
   * @param magentoInstance
   *          the identifier of the Magento instance.
   * @param endPoint
   *          the Magento endpoint.
   * @param body
   *          the body of the request used to create the record.
   * @param entityMapping
   *          the entity mapping associated to the newly created record.
   * @return an OptionalLong that contains the ID of the newly created element if present.
   */
  protected abstract OptionalLong addRecordToMagento(String magentoInstance, String endpoint,
      String body, EntityMapping entityMapping) throws Exception;
 
  /**
   * Fires a request to update a record in Magento.
   * 
   * @param magentoInstance
   *          the identifier of the Magento instance.
   * @param endPoint
   *          the Magento endpoint.
   * @param body
   *          the body of the request used to updated the record.
   * @param entityMapping
   *          the entity mapping associated to the updated record.
   */
  protected abstract void updateRecordInMagento(String magentoInstance, String endpoint,
      String body, EntityMapping entityMapping) throws Exception;

As commented in the previous section, by default all the requests to export records to Magento are done with the DefaultMagentoEndpointRequester class which indeed extends MagentoEndpointRequester.

In case custom behavior is desired for a particular Magento endpoint, a class extending MagentoEndpointRequester can be implemented and annotated with the @EntityMappingId qualifier in order to define the Entity Mapping associated to the class. Note that every Entity Mapping is linked to a Magento endpoint with its Application Dictionary definition.

The mentioned qualifier must include the ID of the Entity Mapping:

 
@EntityMappingId("B4B3F0646C534B57A1E5F202B1CF13B5")
public class MyMagentoEndpointRequester extends MagentoEndpointRequester {
 ...
}

DefaultMagentoEndpointRequester

The DefaultMagentoEndpointRequester class is the default MagentoEndpointRequester to make requests for all the Magento endpoints.

As shown above, when adding new records to Magento, the Magento ID of the newly created element should be returned by the addRecordToMagento method using an OptionalLong. The DefaultMagentoEndpointRequester tries to find a property named ID within the Magento response. If not found an empty Optional is returned.

This behavior can be extended by creating a MagentoIdProvider where custom logic can be implemented to specify the way of retrieving the ID of the exported records for an Entity Mapping.

Thus, this kind of classes should be annotated as @ApplicationScoped beans and also with the @EntityMappingId qualifier:

 
@ApplicationScoped
@EntityMappingId("B4B3F0646C534B57A1E5F202B1CF13B5")
public class MyIdProvider implements MagentoIdProvider {
 
  private static final Logger log = LogManager.getLogger();
  private static final String CUSTOM_ID = "magento_id";
 
  @Override
  public OptionalLong getId(final String magentoInstance, final String endPoint, final String body,
      final String response) {
    try {
      return OptionalLong.of(new JSONObject(response).getLong(CUSTOM_ID));
    } catch (Exception e) {
      log.warn("Could not retrieve record ID from Magento response {}", response);
      return OptionalLong.empty();
    }
  }
}
 

Post-Export Actions

It is also possible to execute additional actions once the request to export a record has been completed. This can done by creating a class that implements the PostExportHook interface which exposes the following method:

 
  /**
   * Executes the required actions after exporting an element generated with the export entity
   * mapping associated to this hook.
   * 
   * @param RequestType
   *          the type of request done to the Magento endpoint
   * @param requestContent
   *          the body of the request sent to the Magento endpoint.
   */
  public void execute(RequestType requestType, String requestContent);
 

This kind of classes should be annotated as @ApplicationScoped beans and also with the @EntityMappingId qualifier in order to associate the additional export actions with an Entity Mapping in particular.

Property Format

Some of the mapped properties need to be transformed to the format required by the external system, in this case Magento. The MagentoPropertyFormatter class defines the format to be used for the boolean, date and date-time properties.

External Instance Identifier Provider

The Magento Connector - Core Infrastrucuture module supports the synchronization with multiple Magento instances. For this reason, it needs to provide an External Instance Identifier Provider.

In this module, it is the MagentoExternalInstanceIdentifierProvider the provider that has the logic to retrieve the identifiers of the Magento instances registered in Openbravo.

Synchronization Processes

The Magento Connector module provides two background processes which are responsible of synchronizing the records between Openbravo and Magento:

• Export To Magento Synchronization Process: export records from Openbravo to Magento.
• Import From Magento Synchronization Process: import records from Magento to Openbravo.

In both cases, the synchronization is done for all the Magento Touchpoints whose organization belongs to the natural tree of the organization defined in the process request used to schedule the process.