Projects:SAP ECC Integration/How to Define Mappings Between Openbravo and SAP ECC Entities

Contents 1 Introduction 2 Using the Application Dictionary 2.1 The Entity Mapping Window 2.1.1 Entity Mapping Header Tab 2.1.2 Property Mapping Instance subtab 3 Programatically 3.1 The class header 3.2 How to specify the properties that will be mapped programatically 3.3 How to define the mapping implementation of imported entities 3.4 How to define the mapping implementation of exported entities

Introduction

Entity mappings are defined in the Entity Mapping window that is available for system admin role. The header tab of that window defines the mapping between entities, and the integration direction of the mapping. Property mappings of a given entity are defined in the Property Mapping Instance subtab.

Not all property mappings can be defined in the Entity Mapping window, some of them will have to be implemented programmatically.

Using the Application Dictionary

The Entity Mapping Window

The entity mapping window is where the mappings between Openbravo and SAP entities are defined. The header tab defines the relations between SAP entities and Openbravo's, along with the direction of the integration, and the Property Mapping Instance subtab allows to define the mappings for some properties.

Entity Mapping Header Tab

Each record in this tab represents the mapping between the Openbravo and SAP entities. It contains the following fields:

• Module: The module where the entity mapping is defined.
• System Type: The name of the external system type. For SAP ECC, SAPECC must be used
• Mapped Entity: The name of the entity in the external system. For SAP ECC, the iDoc type must be used (i.e. WP_PLU for products).
• Mapping Entity: The name of the entity in Openbravo
• Integration Direction: The direction of the integration for this mapping. It can be:
  • From External System to Openbravo
  • From Openbravo to External System
  • Bidirectional
• Is First Level Mapping: Only meaningful for entity mappings defined to export records from Openbravo to SAP ECC. This flag should be checked if the entity mapping represents a SAP iDoc, as opposed to a SAP sub segment (an example is described in section Mappings for entities to be exported from Openbravo to SAP).
• Integration API Type: The Manual BaseOBObject option must be selected

Property Mapping Instance subtab

In this subtab is where the mapping for each property is defined. It contains the following fields:

• Module: The module where the entity mapping is defined
• Sequence number: an auto generated sequence number. It does not have any significance for SAP ECC.
• Mapping name: The name of the property in SAP ECC
• Property Path: The path to the property in Openbravo, starting from the entity set in the Mapping Entity field of the header tab.
• Identifies Record Univocally: Specifies if the current column could be used to identify a record of the given entity univocally. For instance, the product EAN and the business partner searchKey properties should have this flag set to true. It is used by the import iDoc infrastructure to, given an imported iDoc, try to fetch its
• Property Mapping Class: Selector that offers different options to define how the mapping between the SAP ECC and the Openbravo property should be done. The relevant property mapping classes for SAP ECC are divided in two groups, those that represent a 1:1 mapping between the SAP property and Openbravo's (i.e. Product EAN), and those that represent a 1:N (i.e. the property orderLineList of the Order entity). The 1:1 property mapping classes are:
  • DirectPropertyMapping
  • BooleanDirectPropertyMapping
  • DateDirectPropertyMapping
  • LongDirectPropertyMapping
  • BigDecimalPropertyMapping

What property to select depends on the type of the property in Openbravo (DirectPropertyMapping if it is a String, BooleanDirectPropertyMapping if it is a boolean, etc).

And the property class to define a 1:N property is:

• • OneToManyPropertyMapping. An example on how to define a property using this class is shown in section Mappings for entities to be exported from Openbravo to SAP.

Programatically

Sometimes it is not possible to define the property mappings from the Entity Mapping window. For instance, the XML structure of the iDocs is quite complex, and only the properties from the main segment (i.e. the E1WPA01 segment of the WP_PLU iDoc) can be modeled in the Entity Mapping window.

Mappings for those properties that cannot be defined form the Entity Mapping window can be implemented by subclassing the JavaPropertyMappingHandler class. In that subclass, developers can define which SAP ECC fields will be mapped (by overwriting the getPropertySorting method), and can define the implementation of the mappings by overwriting the setPropertyInBaseOBObject method.

The class header

The user must create a subclass of JavaPropertyMappingHandler. Its header must:

• Declare the MappedEntity annotation, specifying the systemType (SAPECC_SAPECC, the SapEccConstants.SYSTEM_TYPE constant can be used instead) and the entityName properties, which should be taken from the Mapping Entity fields of the Entity Mapping window.
• The JavaPropertyMappingHandler class uses generics, so the subclass must specify which Openbravo entity that will be imported.

For instance, the header for a JavaPropertyMappingHandler to define the property mappings of the Product entity would look like this:

How to specify the properties that will be mapped programatically

The getPropertySorting method must be overwritten to specify which properties will be mapped by the JavaPropertyMappingHandler. The properties that must be included for SAP ECC are:

• Those that belong to the header segment but that cannot be defined in the Entity Mapping window.
• All the properties belonging to sub segments. The name of the sub segment must be included in the getPropertySorting returned list.

For instance, to map two properties from the iDoc header segment and the properties of four subsegments for the WP_PLU iDoc, the following implementation could be used:

How to define the mapping implementation of imported entities

To define the mappings of entities that will be imported into Openbravo, the setPropertyInBaseOBObject method must be overwritten. The method has three parameters:

• The BaseOBObject that is being created/updated in Openbravo. The setPropertyInBaseOBObject method must set one of its properties
• The name of the property that is being mapped. The class of this parameter will be determined by the Generics defined in the class header
• The SynchronizableBusinessObject that contains the values of the properties obtained from the iDoc being imported

For instance, an snippet of an implementation to define the import mappings of a product could look like this:

When the property belongs to the segment header (i.e. FILIALE), the value included in the SynchronizableBusinessObject (called itemValue in the snipped showed above) will contain the value itself. For instance, the setOrganization method would look like this:

If the property is included in a segment (i.e. the E1WPA02 segment contains information about the product category), the value included in the SynchronizableBusinessObject will be a list of SynchronizableBusinessObject, and each of those SynchronizableBusinessObjects will contain the properties included in that segment in the iDoc being imported. For instance, the setProductCategory method would look like this:

In that specific case the segment is included only once, so there is no need to iterate over the list of SynchronizableBusinessObjects.

Notice how an Exception is thrown if a condition is not met. When this happens, an entry for this record will be kept in the EDL Request table in ERROR status, so that it can be reprocessed later.

How to define the mapping implementation of exported entities

To define the mappings of entities that will be imported into Openbravo, the setPropertyInBaseOBObject method must be overwritten. The method has two parameters:

• The BaseOBObject that is being exported.
• The name of the property that is being mapped.

The method must return the value to be exported to SAP ECC for the given record being exported and the given mapped property name.

If the property being mapped is a segment (i.e. E1WPP03 in the example above), then the method must return a list of SynchronizableBusinessObject. For instance, an implementation for the getBusinessPartnerContactData could be:

Notice how the returned list contains one SynchronizableBusinessObject per business partner location.

Like in setPropertyInBaseOBObject, it is possible to throw an exception to cancel the synchronization of the record. It will create an error entry in the EDL Request window, which can be reprocessed if needed.