Revision as of 13:18, 20 September 2009

Summary

In this page, I will walk through the steps to deploy replication on ADempiere.

Overview

I am trying to achieve a basic scenario where customers and orders captured at a branch or store are replicated to a central store and where changes made at the central store (via a web portal) may be replicated back to the branch or store.

Discovering Replication Terms

The Type of data Replication determines the direction of the data replication.

• Reference means that the data in this system is read only
• Local means that the data in this system is not replicated to other systems
• Merge means that the data in this system is synchronised with the other system

Apache ActiveMQ

Apache ActiveMQ handles the replication. You can find out more about the project here: http://activemq.apache.org

Role of ActiveMQ

ActiveMQ resides on the server you export from (in order to ensure there is no communication link failure between the export system and this application. ADempiere exports changes to records as defined by you when these records are change by capturing the change via a special model validator and then sending xml as defined by you to the ActiveMQ server. The ActiveMQ server then keeps hold of the change records and provides them to any authorised client that listens to the specific topic. If the clients link fails, ActiveMQ keeps the change message until the client's connection is restored to the ActiveMQ server.

Configuring ActiveMQ

Please follow the instructions on the ActiveMQ website. I used ActiveMQ v 5.2.0.

ADempiere Configuration Overview

These are the steps to configure ADempiere for replication. The exporting system is the system we wish to export record changes from. The importing system is the system we want to import record changes to. You can configure a system to be both an importing and an exporting system.

Exporting System

• Define an Export Processor Type (org.adempiere.process.rpl.exp.TopicExportProcessor)
• Define an Export Processor
  • the host is the hostname or ip address of where you run the ActiveMQ server
  • the port is the port number on which you run ActiveMQ - usually 61616
  • Add the following parameters (search key/parameter value)
    • isDeliveryModePersistent / true - keeps the change message in the queue if a client becomes disconnected
    • timeToLive / 0 (or maybe 10000) - 0 = forever however it would be unusual if a message could not be delivered between ADempiere and a local ActiveMQ service within 10000ms - I have been advised to set this to 0.
    • protocol / tcp
    • clientID / example - the main point is that the client ID for each connection must be different (however, I have also been told it must be the same)
    • topicName / exampleTopic - this need to be the same on the ImportProcessor
• Define a replication strategy incorporating the export processor define above
  • Under Replication Table, select the tables you wish to replicate including the replication type
• Select the replication strategy in Client window

Testing Export

Now you can test to see if your replication export is running

• Open up the ActiveMQ monitor on http://yourhost:8161/admin
• Check the topics do not include your exampleTopic
• fire up ADempiere and make a change to one of the tables you defined as a replication table under replication strategy
• check the topics again and see if your topic has been added to the list of topics in ActiveMQ and that there is 1 message sent n the topic. cYou will not have any consumers registered at this point - but we are ready to move on to Import Processors

If you have a problem, then check the following:

• attach a debugger and set a break point in xxxx to see if the export is triggered

Importing System

NOTE: Changes to the import processor do not take effect until you restart the ADempiere server.

• Configure an Import Processor Type using the class org.adempiere.server.rpl.imp.TopicImportProcessor
• Configure an Import Processor with the following parameters
  • host = the remote hostname or ip address (of the Apache ActiveMQ server)
  • port = the port on the activeMQ server (usually 61616)
  • account = system, password info = manager
    • topicName =
    • protocol = tcp
    • isDurableSubscription = ture (this means you can disconnect and then reconnect - and the messages will be stored for you)
    • subscriptionName = Do not know - still looking at what this does
    • clientID = hostname

Current Issues

• Replication only works point to point - I believe Victor is working on some changes to make the Replication work multicast
• You currently need to specify the ExportProcesser explicitly as an additional client model validator however imho this should be automatically loaded when you associate a replication strategy with a client
• The version number is currently hard coded as 3.2.0
• The application server has to be rebooted when you make changes to the export format.