Introduction

The purpose of this document is to explain how to use the SAP connector infrastructure to:

• Configure the communication between Openbravo and the SAP ECC Server
• Define the mappings between SAP ECC and Openbravo entities
• Extend existing mappings to customize them

How to Install

The following modules must be installed in order to install the Sap ECC connector with the standard mappings:

• org.openbravo.externaldata.integration: this module implements the external data integration infrastructure, that is used by the connector to integrate data asynchronously.
• org.openbravo.service.external.integration: this module implements the global connector infrastructure.
• org.openbravo.service.integration.sap.ecc.core: this module includes the components that allow to create the mappings to the SAP ECC iDocs
• org.openbravo.service.integration.sap.ecc.mappings: this module includes the actual standard mappings between Openbravo entities and SAP ECC iDocs. Those mappings can be found in the window “Entity Mapping”.
• org.openbravo.service.integration.sapecc.ftp.communication: includes the component needed to enable the communication between Openbravo and a SAP server via FTP or SFTP.

The modules modules listed above will all be included in a pack named ”Openbravo connector with SAP ECC Retail”.

EDL Configuration

Because the import and export processes create relevant log (the contents of the imported/exported idocs), they must be configured in the EDL Configuration window. The processes are named:

• Business Object Export Process
• SAP ECC Object Import Process

For both of them an entry in the Ouput subtab must be added, picking one of the following Output Types:

• Debug: It will write the output in the standard log.
• DebugAndStore: On top of writing the output in the log, it will also store it in database. That log will be available as a subtab in the EDL Request window.

Overview of the SAP ECC Connector Infrastructure

The SAP ECC connector allows the transfer of information between an Openbravo and a SAP ECC server by exchanging iDocs. The exchange of information can happen in both directions: from Openbravo to SAP ECC and vice versa.

The SAP ECC Connector infrastructure provides the means to do the actual exchange of iDocs between the two servers, and some tools to ease the process of working with iDocs. The content of an iDoc is stored in memory in an instance of the SynchronizableBusinessObject (SBO) class. The connector infrastructure will automatically create the SBO instances based on the defined functional mappings.

This is a graphic summary of the process to export an iDoc from SAP ECC to Openbravo:

And is a graphic summary of the process to import an iDoc from SAP ECC to Openbravo:

Communication Between Openbravo and a SAP ECC Server

The SAP ECC Connector offers several methods to synchronize iDocs between the SAP ECC server and Openbravo: via a FTP/SFTP server or using the SAP Java Connector (JCo).

It also offers a debug mode, where the iDocs are read from / written to a folder in the local filesystem.

Shared Folder

If the iDoc exchange is done through a FTP/SFTP server:

• From SAP ECC to Openbravo: Whenever there is a change in the SAP ECC server in one of the SAP entities configured to be exported to Openbravo, SAP will create an iDoc and will place it in the outgoing folder (if defined) of the configured FTP/SFTP directory. Openbravo will check this folder periodically, and will import the iDocs left there by SAP by applying the defined entity mappings.
• From Openbravo to SAP ECC: Openbravo will check periodically for changes done in the tables configured to be exported to SAP. From this data the Openbravo SAP ECC connector will create iDoc files by applying the defined mappings, and will place it in the incoming folder (if defined) of the FTP server. SAP ECC will check this folder periodically to import the iDocs left there in SAP.

JCo

The SAP Java Connector is a middleware component that enables the development of SAP-compatible components and applications in Java. When configured both in the SAP ECC server and in Openbravo, the iDoc exchange will work like this:

• From SAP ECC to Openbravo: Whenever there is a change in the SAP ECC server in one of the SAP entities configured to be exported to Openbravo, SAP will create an iDoc and will use JCo to send the iDoc to the Openbravo server, where a class implementing the JCoIDocHandler will receive it and pass it to the Openbravo SAP ECC Connector so that the defined mappings are applied and the iDoc is imported in Openbravo.
• From Openbravo to SAP ECC: Openbravo will check periodically for changes done in the tables configured to be exported to SAP. From this dada the Openbravo SAP ECC connector will create iDofewxc files by applying the defined mappings, and will send them to the SAP ECC server through JCo using the JCoIDoc API.

Configuration in Application Dictionary

The means of communication between Openbravo and the SAP ECC Server is defined in the Communication with SAP ECC Server.

The communication method is defined in the header tab. If FTP, SFTP or JCo is selected, a subtab will be shown where the user can enter the connection parameters. If the Debug method is selected, a text field will be shown in the header tab where the user can define the local filesystem folder that will be used for the iDoc interchange.

If the SFTP, FTP or Debug communication protocols are selected, the Post Idoc Import Action field will be displayed. This field offers two options regarding what to do with an iDoc imported in Openbravo once the import process finishes:

• Delete: The file will be deleted from the FTP/SFTP server, or from the local filesystem
• Archive: The file will be archived to another folder. The path to the archived folder is specified per entity in the Entity Mapping folder.

How to Define Mappings Between Openbravo and SAP ECC Entities

The manual on how to define the property mappings can be found in this link.

How to Synchronize Data Between Openbravo and SAP ECC

Import

Initializing Properties not Contained in Imported Idocs

When importing a record from SAP, there can be properties in the Openbravo entity to be imported that are not modeled in the iDoc, and whose values should be different than the default value defined in the database.

To initialize those properties, the ImportedOBObjectInitializer<BaseOBObject> interface must be implemented:

/**
 * Interface to be implemented when there is a need to initialize the properties of an entity that
 * are not mapped in the Entity Mapping definition in the AD.
 * 
 * The initialize method will be invoked by the {@link SynchronizableBusinessObjectImporter} when
 * the imported record does not exist in Openbravo yet
 * 
 * Classes that implement this interface should declare the {@link EntityMappingId} qualifier to
 * define the target SystemType and EntityMapping name
 */
public interface ImportedOBObjectInitializer<T> extends Prioritizable {
 
  /**
   * Initializes the properties that are not defined in the Entity Mapping in the AD
   * 
   * @param bob
   *          The entry to be initialized
   */
  public void initialize(T bob);
 
}

Classes implementing this interface must include the @EntityMappingId annotation, and must specify the ID of the entity mapping the initializer refers to.

@EntityMappingId(IMPORT_TAX_RATE_ENTITY_MAPPING_ID)
public class TaxRateOBObjectInitializer implements ImportedOBObjectInitializer<BaseOBObject> {
 
  private static final String SALES_TAX = "S";
 
  @Override
  public void initialize(BaseOBObject bob) {
    TaxRate taxRate = (TaxRate) bob;
    taxRate.setSalesPurchaseType(SALES_TAX);
  }
 
  @Override 
  public int getPriority() {
    return 100;
  }
}

Mapping the contents of an idoc with an existing records in the database

When an Idoc is imported, the synchronization process must be able to know if it contains a new data entry, or an update on a data entry that is already present in the Openbravo database.

In most cases it is possible to xxxxxxxx by checking the Identifies Record Univocally flag of the mapping of a unique property (for instance, the searchKey property of products). When it is not possible to use this flag for this purpose, the ImportedBaseOBObjectAfterFlushHook hook allows to do it programatically:

/**
 * Interface to be implemented when there is a custom way to find a match for the imported record in
 * the database. This is only needed when it is not possible to define property mappings that
 * identify univocally the mapped record in the database
 * 
 * Classes that implement this interface should declare the {@link EntityMappingId} qualifier to
 * define entity mapping it should be applied to
 * 
 */
public interface ImportedBaseOBObjectFetcher {
 
  /**
   * Given a SynchronizableBusinessObject, uses its properties to try to fetch the mapped record
   * from the database. If the records exists it will be returned, if it does not exist, the method
   * will return null
   * 
   * @param item
   *          the SynchronizableBusinessObject whose properties will be used to fetch a record from
   *          the database
   * @return the BaseOBObject extracted from the database or null if no mapped records exists
   */
  public <T extends BaseOBObject> T fetch(SynchronizableBusinessObject item);
 
}

Export

There are two main steps in the process to export data from Openbravo to SAP:

• Retrieving the records to be exported
• Converting them to iDocs

The next two sections describe how to implement the components that carry out those tasks.

The Exporter class

For each entity configured to be exported from Openbravo to SAP ECC, developers must implement a class that extends the SapEccExporterSynchronizableBusinessObjectExporter abstract class.

The class header

The exporter class must extend the SapEccExporterSynchronizableBusinessObjectExporter. It also has to declare a @MappedEntity interface, specifying the system type and the entity name of the entity whose export behaviour is being defined.

Methods to override

The following methods must be overriden:

• exportedEntityName: returns the name of the entity being exported
• getIdocType: returns the iDoc type that will be used to export this entity.
• getSynchronizationQuery: returns an string that represents the HQL query that will be executed to retrieve the records to be exported. It can use placeholder (check [www.TODOlink.com this link] to learn about all the placeholders available).

The next screenshot shows how this methods are implemented for the Invoice entity:

Process Requests

This section explains how to schedule the synchronization background processes. It is done using the standard Process Request window, the main difference being that for synchronization processes it is possible to specify the list of entities the process should synchronize.

How to Create iDocs

This document explains how to create iDocs based on templates.

Attaching iDocs to Exported Records

It is possible to automatically attach an exported iDoc to the record that was going exported by defining the Attach Exported Idocs preference. That preference must be defined as System Admin, and the Visible at Client/Organization/User/Role fields must be left empty.

The attachments will be available from the ERP windows. For instance, this is how the attachments will look like for a business partner that has been exported four times: