The Remote Data Transfer Module provides a platform for other modules to transmit data between OpenMRS installations with ease. It also provides stand-alone functionality for transmitting user selected files to other OpenMRS installations via the web interface.
After installing the latest version of the Remote Data Transfer (RDT) Module .omod file into your OpenMRS via the standard module installation procedure, links to following pages will appear on the OpenMRS Adminstration page.
This page allows you to configure the current server and any destination servers that you wish to send data to.
This server: Server ID should be set here. The Server ID is a unique ID string (up to 40 characters) that uniquely identifies the current server in the group of servers that Remote Data Transfer is intended to be used. It is therefore up to the system administrator to ensure that the Server ID is unique.
Remote Servers: Destination servers can be added by clicking the Add Server button. Any existing servers can be edited by clicking on their Server ID.
New Server/Edit Server: After clicking on the Add Server button or on the Server ID link a server edit page will appear. The details of the new server can be added through the form on this page or existing server details edited. Here is a run through of the fields on this page:
This page is used for sending single files of any type to a specific server.
Clicking Add will add the file to the queue. The to initiate the actual sending process either one of the Online or Offline methods should be used (described below).
Online transfer will immediately send all queue items to the selected servers. The transmitting and receiving servers must be connected by a network for this to work. Where no network connection is available offline transfer can be used.
Here data for selected servers can be downloaded as a single file and transferred manually to the remote server (via USB Pen or equivalent). Simply select the server to download items for in “Download Transfer Data File” and choose where you want to save the file. On the receiving end the file can be uploaded by clicking browse, selecting the transfer file, and then clicking upload. It is necessary to make a return trip with data from the remote server to the local server before the data can be confirmed as sent (See “Status”below).
This page keeps a track of all data sent or waiting to be sent, as well as data received from other servers. The columns in the table are self explanatory but there are a few things to note.
Clicking on the data link for any item will allow you to download that data.
Status - This will either read “Queued”, “Sent, Awaiting Acknowledgement”, or “Transfer Complete”.
-note: when data is received from a server that is not configured it will automatically be created as a server. (only serverId will be recorded, other information can be filled out later manually)
The following information will guide you through setting up and getting started with using Remote Data Transfer (RDT) Module within your own module.
Prerequisites – The latest version of the RDT Module .omod file should be downloaded and included in the classpath of your module.
Require Module – The following code should be placed in yours config.xml file to insure that RDT is always loaded before your module can be installed in the OpenMRS system. This will insure that you are always able to register listeners with the module when the system is started (see below for registering listeners).<require_modules>
Implement RemoteDataTransferListener – To be informed of when new data arrives for your module it is necessary to implement a listener. This is a class that inplements the RemoteDataTransferListener interface. An example of what this class might look like is below. The main function of this class is to allow code from within your module to be executed when data arrives that has been tagged with the tags that your module is setup to listen for. These tags are also specified in your implementation of this interface:
dataReceived – This method is executed when data is received that has been taggeed with any of the tags in getSupportedTags. The appropriate RemoteDataTransferReceivedItem is made available via a parameter. Some of the most useful properties of this object are listed:
getSupportedTags – This method should return a List<String> object containing the tags that should be listened for.
Register Listener – In order for the listener that has been implemented to be registered with RDT the following code must be added in yours module's moduleApplicationContext.xml.
note - ModuleListener should be replaced by the name of your implemented module listener class.
After setting up the module API functions are made available by starting the RDT service. This is done as follows:
Now service methods can be called using the newly created service object. For example to send data:
Out of memory error
When dealing with large files you might sometimes encounter out of memory errors. These can usually be resolved by adjusting the memory assigned to your java virtual machine. The command line parameter -Xmx512m can be used on launch (In this case to assign 512 MB to the jvm).
An Internal Error has Occurred org.hibernate.exception.GenericJDBCException could not insert: [archive:org.openmrs.module.remotedatatransfer.RemoteDataTransferQueueItem]
If you are receiving this error message when trying to send files you will need to increase the max_allowed_packet size in mysql.