Projects:External Integration Infrastructure/TechnicalDocumentation

Contents 1 Overview 1.1 Import Process 1.2 Export Process 2 High Level Class Overview by Package 2.1 org.openbravo.service.external.integration 2.2 org.openbravo.service.external.integration.base 2.3 org.openbravo.service.external.integration.datasource 2.4 org.openbravo.service.external.integration.edl 2.4.1 Export 2.4.2 Import 2.5 org.openbravo.service.external.integration.export 2.6 org.openbravo.service.external.integration.handler 3 org.openbravo.service.external.integration.importer 4 org.openbravo.service.external.integration.mapping 5 org.openbravo.service.external.integration.process

Overview

Import Process

Export Process

High Level Class Overview by Package

org.openbravo.service.external.integration

This package only contains the SynchronizableBusinessObject class. This class acts as a bridge between the representation of an instance in the external system and a BaseOBObject in Openbravo.

The main attribute of this class is its properties map, that contains a list of property name - property value pairs.

The connector applies the defined property mappings to create a SynchronizableBusinessObject from a BaseOBObject (this is done in the PropertyMapper.createSynchronizableBusinessObject method) and to create/update a BaseOBObject given a SynchronizationBusinessObject (done in the PropertyMapper.createSynchronizableBusinessObject method).

org.openbravo.service.external.integration.base

QueryBaseOBObject?? To be completed by CAR

org.openbravo.service.external.integration.datasource

This package contains two manual datasources, both of them will be used in subtabs of the Entity Mapping window:

• JavaPropertyMappingHandlerDS: Shows the list of JavaPropertyMappingHandler defined for the entity mapping selected in the header tab
• SynchronizableBusinessObjectExporterDS: Shows the list of SynchronizableBusinessObjectExporterDS defined for the entity mapping selected in the header tab

org.openbravo.service.external.integration.edl

The base connector module uses the external data integration module to split the data to be imported/exported in batches and to process it asynchronously, and also to manage errors.

Export

In the export process, the EDL request line data contains the ids of the records to be exported. That makes very simple the implementation of the EDL classes, having to deal with simple strings and lists of strings.

The following EDL classes have been implemented to manage the export of records:

• ExportDataAsyncProcessor: AsynchronousProcessor that fetches the List<String> content of the EDL request and converts it to iterators (IdBatchIterator and IdItemIterator) to be consumed by EDL.
  • IdBatchIterator: Iterator that given a List<String> that contains record IDs, returns in each element a string that contains batchSize ids separated by a line break. It is used to build the content of the EDL request lines.
  • IdItemIterator: Iterator that given an element of IdBatchIterator, returns one record ID per iterator elmement.
• ExportDataProcessor: Returns the raw data of the EDL request as a list of strings. It also adds additional information to the context data.
• ExportItemProcessor: In the processItem method, converts the record it to an instance of SynchronizableBusinessObject using a SynchronizableBusinessObjectExporter and a PropertyMapper. In the writeResponse method, exports all the instances ofSynchronizableBusinessObject created in the processItem method to the external system using the SynchronizableBusinessObjectExporter.export method.
  • ExportResultController: Interface that if implemented by an OutputDataProcessor, will be used by the ExportItemProcessor show log about why an export process failed.
• BasicOutputDebuggerProcessor: Basic OutputDebuggerProcessor that just saves in OBEDLOutputContent the content of the OutputDebuggerProcessor writer.

Import

The following EDL classes have been implemented to manage the import of records. They all reference the OBEI_ImportData EDL Data type. This data type can be used when the data to be imported is formatted as JSON:

• ImportDataAsyncProcessor: An extension of JSONAsynchProcessor.
• ImportDataProcessor: Returns the raw data of the EDL request as a JSONArray. It also adds additional information to the context data.
• ImportItemProcessor: Converts the item to be exported to an SynchronizableBusinessObject, and imports it using a SynchronizableBusinessObjectImporter, passing a PropertyMapper that will map the properties of the imported JSON to the properties of the BaseOBObject that will be created/updated.

org.openbravo.service.external.integration.export

• SynchronizableBusinessObjectExporter: Interface to be implemented in the modules that define specific connectors to external systems. Classes that implement it will be in charge of exporting a list of SynchronizableBusinessObject to the external system. The interface is used by the ExportItemProcessor class.
• BaseSynchronizableBusinessObjectExporter: An abstract classes that implements SynchronizableBusinessObjectExporter and that provides a default implementation for the exportToSynchronizableBusinessObject method.
• SynchronizableBusinessObjectExporterStore: Utility class to obtain the SynchronizableBusinessObjectExporter defined for a given system type and entity mapping.

org.openbravo.service.external.integration.handler

This package contains implementations of EntityPersistenceEventObservers.

• CheckEntityInEntityMappingEventHandler: When defining an entity mapping, it checks that the entity name used is valid.
• CheckPropertyInEntityEventHandler: When defining a property mappings, it checks that the property name used is a property of the entity used in the header tab.
• CircularDependenciesDetector: When defining dependencies between entity mappings, it makes sure that circular dependencies are not created.

org.openbravo.service.external.integration.importer

This package contains the SynchronizableBusinessObjectImporter class, which is the main responsible of importing records from an external system to Openbravo. It also contains some hooks that can be extended to customize the import process

• SynchronizableBusinessObjectImporter: Class in charge of importing a SynchronizableBusinessObject, created as a result of applying the defined entity mappings to a record received to be imported, into Openbravo. Its importFromSynchronizableBusinessObject method is invoked by ImportItemProcessor.processItem. The following hooks can be extended by customization modules to modify the default behaviour or the importer:
  • ImportedBaseOBObjectInitializer: When as a result of the import a new record is imported in Openbravo, the initialize method of this interface will be invoked to initialize it. It is commonly used to initialize fields mandatory in Openbravo but that are not included in the record provided by the external system.
  • ImportedBaseOBObjectAfterFlushHook: It is invoked right after flushing the imported record. It is usually used to do actions that had to be done after some triggers/eventhandlers were invoked.
  • ImportedBaseOBObjectFetcher: When importing a change, specifies how to find the record to be created/updated/deleted in Openbravo. By default this is done by matching a field of the imported change with a unique property of the Openbravo entity to be imported, but it is possible to override this behaviour by implementing this interface.
  • ImportedItemDeletionPolicy: It specifies when an imported change represents a deletion (i.e., in SAP ECC a change is a deletion if the

org.openbravo.service.external.integration.mapping

This package contains all the classes that have a role in building the mappings between an entity in the external system and an entity in Openbravo.

• SynchronizableBusinessObject: In-memory representation of the record being imported/exported.
• EntityMappingUtils: Contains utility methods related with the EntityMapping generated class.
• MappedEntity: Qualifier that customization classes should use to specify the system type and the entity name they apply to.
  • MappedEntitySelector: Selector that is to fetch a class based on its MappedEntity qualifier.

The following classes manage the application of mappings. The classes that extend PropertyMapping are not including in this diagram, they will be described in another diagram later in this section.

• PropertyMapper: It is in charge of applying the defined property mappings. It relies on the PropertyMappingListBuilder interface to obtain the list of mappings to apply. The mappings are applied in different methods depending on if a record is being imported or exported.
  • createSynchronizableBusinessObject: Method invoked to apply the mappings to a record that will be exported. Based on an entity and an ID, retrieves the record from the database and applies the mappings on it to create an instance of SynchronizableBusinessObject.
  • applyMappingToBaseOBObject: Method invoked to, given an SynchronizableBusinessObject and BaseOBObject that represents the record that will be imported, sets in the BaseOBObject the properties defined in the SynchronizableBusinessObject after applying the mappings to the latter.
• PropertyMapping: Represents a mapping between a property in the external system and the equivalent property in the Openbravo entity. They can be defined in the application dictionary or programatically. The end of this section contains a description of all the available PropertyMappings.
• ConditionalPropertyMapping: Hook that can be implemented in customizations to determine if the mapping for a given property should be applied to a BaseOBObject in particular in the export process.
• PropertyMappingListBuilder: Interface to be implemented by the classes in charge of retreving the list of non-programatically-defined PropertyMappings defined for a given EntityMapping.
• ADPropertyMappingListBuilder: Implementation of PropertyMappingListBuilder that reads the mappings from the application dictionary.
• PropertyMappingHandlerStore: Class in charge of obtaining all the JavaPropertyMappingHandler defined for a given system type and entity.
• PropertyMapperFactory: Factory class to create instances of PropertyMapping based on the system type, the entity being exported/imported and the direction of the synchronization.

The following diagram describe the classes used to define PropertyMappings:

• PropertyMapping: Abstract class that represents a mapping between a property in the external system and the equivalent property in the Openbravo entity. It offers two methods, getMappingValue and setMappingValue, to apply a mapping in the export and import process respectively.
  • JavaPropertyMapping: A property mapping that is defined programatically. The implementation of the getMappingValue and setMappingValue methods is delegated to JavaPropertyMappingHandler.
    • JavaPropertyMappingHandler: Class that defines for a given system type and entity all its JavaPropertyMappings.
  • DirectPropertyMapping: Simple PropertyMapping that represents a direct relation between two properties of different entities
    • UUIDPropertyMapping: Subclass of DirectPropertyMapping, intended to map properties that are UUIDs in Openbravo or the external system. The mapping automatically applies a UUIDTransformer to format the UUID.
      • UUIDTransformer: Interface to be implemented by classes to format UUIDs.
      • CanonicalUUIDTransformer: Implementation of UUIDTransformer that formats the UUIDs to their canonical form.
    • EntityPropertyMapping: To be used when a property represents a whole entity whose mapping definition is defined in a separate entity mapping (i.e. the businessPartner field of an order, if several fields of the business partner must be exported to the external system).
      • OneToManyEntityPropertyMapping: To be used when a property represents a list of whole entities whose mapping definition is defined in a separate entity mapping (for instance, the orderLineList property of Order).
    • DateDirectPropertyMapping: DirectPropertyMapping to be used when the target property is a date. It automatically applies a date format, which can be defined by extending DatePropertyFormatter.
      • DatePropertyFormatter: Interface to be implemented by classes to define the date format to be used in a particular system type.
    • NumericDirectPropertyMapping: Abstract class that represent numeric property mappings. It initially has two subclasses:
      • BigDecimalDirectPropertyMapping: To be used when the target property in Openbravo is a BigDecimal
      • LongDirectPropertyMapping: To be used when the target property in Openbravo is a Long
    • BooleanDirectPropertyMapping: To be used when the target property is a boolean. It uses the BooleanPropertyFormatter to determine what values in the external system represent true and false.
      • BooleanPropertyFormatter: Interface to implemented by classes to define what values represent true and false in the external system.
      • PropertyFormatStore: Utility class that given a system type returns the BooleanPropertyFormatter and DatePropertyFormatter defined for it.

org.openbravo.service.external.integration.process

• ExternalSynchronizationProcess: Abstract class that given an iterator of entries to be imported/exported, and some context information, will create EDL Requests that when processed will import into Openbravo / export to the external system those entries. It uses the following classes to help create the EDL Requests:
  • EdlRequestCreator: Class where ExternalSynchronizationProcess delegates the creation of EDL Requests.
  • EdlRequestParamsProvider: Interface to be implemented by classes that wants to add parameters to the EDL Requests. It has two subclasses, ExportEdlRequestParamsProvider and ImportEdlRequestParamsProvider.
  • RequestInfo: Abstract class to represent the request information that will be used to create the EDL Requests. It is subclassed by ExportRequestInfo and ImportRequestInfo.
• ImportExternalSynchronizationProcess: Abstract subclass of ExternalSynchronizationProcess to be extended by the background processes meant to import data from external systems into Openbravo. Ths subclasses must overwrite the getRequestsInformation method, that given an entity and a date, must return an iterator with information about the entries belonging to the given entity that have been modified in the external system since the given date.
• ExportExternalSynchronizationProcess: Abstract subclass of ExternalSynchronizationProcess to be extended by the background processes meant to export data from Openbravo to external systems:
  • HqlQueryBuilder: Helps to build the HQL queries intended to retrieve the IDs of the records pending to be exported.
  • MalformedQueryException: Custom exception that will be thrown when a query returned by the HqlQueryBuilder class cannot be executed.

The following classes help in the definition of HqlQueryBuilders:

• HqlQueryContextInfo: A class used to encapsulate the context information that can be used by the HqlQueryBuilder to replace the values of some parameters of the query.
• HqlQueryBuilderCriteria: A class intended to parse an HQL query by replacing a particular placeholder with the corresponding criteria. It has the following subclasses:
  • ActiveCriteria: Includes an isActive=true criteria.
  • ClientCriteria: Includes a client filter, using as value the client present in the context.
  • OrgCriteria: Includes an organization filter, so that only the records that use the context organization are returned.
  • NaturalOrgCriteria: Includes a natural organization filter, so that only the records that belong to the natural tree of the context organization are returned.
  • ChildOrgCriteria: Includes a child organization filter, so that only the records that belong to the child tree of the context organization are returned.
  • IncrementalRefreshCriteria: Includes a filter to return only the records that whose updated property is a date after the given date
  • IncrementalRefreshCriteriaCreationOnly: Includes a filter to return only the records that whose creationDate property is a date after the given date