Difference between revisions of "A Step by Step Guide to Replication"

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.
m (Mode of Delivery)
m (Step 2: Setup Export Processor (AD_SOURCE))
Line 44: Line 44:
 
*'''Export Format:''' Define what data columns of the tables (from Replication Strategy window) will be exported. ADempeire use information here to generate XML file for export. Note that, the same Export Format must be defined in TARGET as well, as ADempiere will use it to convert from XML back to raw data for import.
 
*'''Export Format:''' Define what data columns of the tables (from Replication Strategy window) will be exported. ADempeire use information here to generate XML file for export. Note that, the same Export Format must be defined in TARGET as well, as ADempiere will use it to convert from XML back to raw data for import.
 
*'''Client's Model Validator:''' Define the Export Model Validator and Replication Strategy. This is required only for SOURCE machine, as we want CRUD action to trigger export to ActiveMQ process.  
 
*'''Client's Model Validator:''' Define the Export Model Validator and Replication Strategy. This is required only for SOURCE machine, as we want CRUD action to trigger export to ActiveMQ process.  
=== Define Replication Strategy ===
+
==== Step 2.1 Define Replication Strategy ====
*
+
A SOURCE can have only one working Replication Strategy (to be defined in Client window), but can have multiple table and document to replicate. In this sample, we only export want to export one data, M_Product.
=== Define Export Processor ===
+
*Open Replication Strategy window
 +
*Create new Replication Strategy
 +
**Search Key: MyReplicationStrategy
 +
**Name: My Replication Strategy
 +
**Entity Type: User maintained
 +
**Export Processor: Human Readable name for - JMS Topic Export Processor
 +
*Create new Replication Table
 +
**Replication Strategy: My Replication Strategy
 +
**Table: M_Product
 +
**Replication Type: Merge
 +
**Entity Type: User maintained
 +
{{Note|Replication Type
 +
*Broadcast:
 +
*Local:
 +
*Merge:
 +
*Reference:
 +
}}
 +
==== Step 2.2 Define Export Processor ====
 +
From previous step, we already define the Export Processor as '''Human Readable name for - JMS Topic Export Processor'''. Let's go through its configuration.
 +
*Open Export Processor window
 +
*On Export Process tab, select record as Human Readable name for - JMS Topic Export Processor
 +
**Search Key: JMS Topic Export Processor
 +
**Name: Human Readable name for - JMS Topic Export Processor
 +
**Human Readable name for - JMS Topic Export Processor Type
 +
**Host: localhost (host machine for ActiveMQ)
 +
**Port: 61616 (default port for tcp)
 +
**Account: system
 +
**Password Info: manager
 +
'''Note:''' We do not touch on security yet, let's use the default Account/Password for now. More information please see [http://activemq.apache.org/security.html ActiveMQ Security]
 +
==== Step 2.3 Define Export Processor Type ====
  
=== Define Export Processor Type ===
+
==== Step 2.4 Define Export Format ====
  
=== Define Export Format ===
+
==== Step 2.5 Define Client's Model Validator ====
 
+
=== Define Client's Model Validator ===
+
  
 
== Step 3: Setup Import Processor (AD_TARGET) ==
 
== Step 3: Setup Import Processor (AD_TARGET) ==

Revision as of 00:42, 15 April 2011

Note.gif Note:

DISCLAIMER - This is an implementation guide written by Kittiu, from Ecosoft Bangkok, Thailand for the purpose of teaching himself while doing his own project. It is not an official guide nor meant to be comprehensive yet. Other contributors are welcome to discuss on improving it.

Overview

This page is based on the attempt to make sense of ADempiere Replication module of the author. It will be illustrated as a step by step guide for the reader to have the FEEL of what how to setup a simple Replication case between a SOURCE and the TARGET machine.

Note: This guide is based on Adempeire 360LTS and GardenWorld

Message Queue

ADempiere use Message Queue (JMS - Java Message Service Protocal) technique to integrate between systems. Using message queue has many advantage versus direct integration or webservice call. In a short word, new data from SOURCE machine will be sent to the Message Queue Server in XML format and reside there waiting for the TARGET machine to pick up. This is a more loosely couple way of integration which can guarantee data delivery regardless of the TARGET machine status during the time of delivery. And by using Message Queue Server and XML as medium, integration between different system become more simple.

Mode of Delivery

To be a bit more specific, JMS support 2 modes of delivery

  1. Queue: This mode is good for point to point, where there is only 1 target machine. SOURCE send message to a specified queue. TARGET receive message from that queue (and dequeue message), whenever it become available.
  2. Topic: This mode is good for multi cast, where there are more than 1 target machine receiving the same message. This about when we subscribe to a magazine (topic). In this approach, TARGET machines must first subscribe to a Topic. Once SOURCE send a message to that Topic, it will be boardcast to all the TARGETs. Note that, the TARGET machine must be listening during the message sending, otherwise it miss that message. The example in this page is based on Topic (Publish and Subscribe) only.

Message Protocol

Replication Type

Before we move on, check out more information about ActiveMQ here

Note.gif Note:

While there are many implementation of JMS Message Queue Server out there in the market, ADempeire is adoption Apache ActiveMQ. Apache ActiveMQ is the most popular and powerful open source messaging and Integration Patterns provider. It is fast, supports many Cross Language Clients and Protocols, comes with easy to use Enterprise Integration Patterns and many advanced features while fully supporting JMS 1.1 and J2EE 1.4. Apache ActiveMQ is released under the Apache 2.0 License

Step by Step Replication Setup in ADempiere

Step 1: Prepare Environment

  1. Prepare 2 ADempiere 360LTS Environment, we will call it AD_SOURCE and AD_TARGET (we won't discuss how to install Adempeire here).
  2. Install ActiveMQ Server (See Getting Start Guide)
    • Download Binary Distribution, apache-activemq-5.5.0-bin.zip from [1]
    • Unzip and place the folder to C:/apache-activemq-5.5.0-bin
    • That's it for installation, now start ActiveMQ server by running C:/apache-activemq-5.5.0-bin/bin/activemq.bat

Activemq start.png

Note.gif Note:

From the console, you will see that ActiveMQ

  • Listening for connections at: tcp://localhost:61616 (tcp / openwire connector).
  • Admin Console is at http://localhost:8161/admin. Here, we can view / manage, connection, queue, topic and etc.
  • Web demo is at http://localhost:8161/demo. A good place to start off understanding ActiveMQ. And also, please check out examples code at C:/apache-activemq-5.5.0-bin/example

Step 2: Setup Export Processor (AD_SOURCE)

As mentioned earlier, the message will be sent in XML format (i.e., when a new product item is created). Beside writing your own code to generate XML file of product data and put it on the queue, ADempeire Replication Module provides windows / process to help you do just that.

Configurations for Export
  • Replication Strategy: Define what (table/document) and how, data (boardcast/reference/local/merge) will be exported. And using what Export Processor.
  • Export Processor: Define where (i.e., host/port) and how (connection parameters) to connect to the ActiveMQ server. Using what Export Process Type (delivery mode).
  • Export Processor Type: Define the java class that do the real connection to ActiveMQ server. This is where the action take place. Out of the package, ADempeire only provide the connection class for Topic delivery mode, org.adempiere.process.rpl.exp.TopicExportProcessor. (once you understand more about how ActiveMQ works, you can write your own class).
  • Export Format: Define what data columns of the tables (from Replication Strategy window) will be exported. ADempeire use information here to generate XML file for export. Note that, the same Export Format must be defined in TARGET as well, as ADempiere will use it to convert from XML back to raw data for import.
  • Client's Model Validator: Define the Export Model Validator and Replication Strategy. This is required only for SOURCE machine, as we want CRUD action to trigger export to ActiveMQ process.

Step 2.1 Define Replication Strategy

A SOURCE can have only one working Replication Strategy (to be defined in Client window), but can have multiple table and document to replicate. In this sample, we only export want to export one data, M_Product.

  • Open Replication Strategy window
  • Create new Replication Strategy
    • Search Key: MyReplicationStrategy
    • Name: My Replication Strategy
    • Entity Type: User maintained
    • Export Processor: Human Readable name for - JMS Topic Export Processor
  • Create new Replication Table
    • Replication Strategy: My Replication Strategy
    • Table: M_Product
    • Replication Type: Merge
    • Entity Type: User maintained
Note.gif Note:

Replication Type

  • Broadcast:
  • Local:
  • Merge:
  • Reference:

Step 2.2 Define Export Processor

From previous step, we already define the Export Processor as Human Readable name for - JMS Topic Export Processor. Let's go through its configuration.

  • Open Export Processor window
  • On Export Process tab, select record as Human Readable name for - JMS Topic Export Processor
    • Search Key: JMS Topic Export Processor
    • Name: Human Readable name for - JMS Topic Export Processor
    • Human Readable name for - JMS Topic Export Processor Type
    • Host: localhost (host machine for ActiveMQ)
    • Port: 61616 (default port for tcp)
    • Account: system
    • Password Info: manager

Note: We do not touch on security yet, let's use the default Account/Password for now. More information please see ActiveMQ Security

Step 2.3 Define Export Processor Type

Step 2.4 Define Export Format

Step 2.5 Define Client's Model Validator

Step 3: Setup Import Processor (AD_TARGET)

Step 4: Validate Export & Import XML File

Step 5: Test Replication

Exploring Java Codes for Replication Module

Debugging Import Process Job

Summary

Some Issues

See Also