Page Comparison

h2. Overview

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.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=2]\]

h2. How to use the modules user interface (UI)

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.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=3]\]

h3. Configuration

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:
* _Server ID:_ This is the only required information to  create a server. As mentioned above, this has to be unique in the system  of servers that RDT Module is intended to be used with.

* _URL (Optional):_ This is the URL of the server's OpenMRS  installation. For example, if the official OpenMRS demo was being  configured as a server it's url would be: [http://demo.openmrs.org/openmrs|http://demo.openmrs.org/openmrs] (This is only required for online transfers)

* _Username (Optional):_ The username of the account on the  remote server that will be used to login and complete the transfer.   This is only required for online transfers.

* _Password (Optional):_ The password of the account specified above.  This is only required for online transfers.

* _Description (Optional):_ A short description of the remote server.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=4]\]

h3. Send File

This page is used for sending single files of any type to a specific server.
* _File:_ The browse button can be used to select a file from your system.

* _Destination:_ A remote server should be selected here (Servers have to be configured first, see above).

* _Tag (Optional):_ This is used to tag the file for use  with a specific module. This can left blank if the file is not intended  to be used by any particular module.

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).

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=5]\]

h3. Online Transfer

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.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=6]\]

h3. Offline Transfer

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).

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=7]\]

h3. View Transfers

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”.
* _Queued:_ Data is waiting to be sent by one of the methods mentioned above.

* _Sent, Awaiting Acknowledgement:_ Data has been sent but no  confirmation has been received. This usually only applies to Offline  Transfer, where a return trip is required from remote to local server  for data to be verified as sent.  While an item is marked with this  status, it will continually be resent with any future transmissions  until confirmation of it's transfer has been given.

* _Transfer Complete:_ Transfers that have been confirmed as processed will be marked with this status.

\-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)

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=8]\]

h2. How to use the application programming interface (API)

The following information will guide you through setting up and  getting started with using Remote Data Transfer (RDT) Module  within  your own module.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=9]\]

h3. Setup

*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>
	<require_module>org.openmrs.module.remotedatatransfer</require_module>
</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:public class TestModuleListener implements RemoteDataTransferListener {
 
	protected final Log log = LogFactory.getLog(getClass());
 
	@Override
	public void dataReceived(RemoteDataTransferReceivedItem receivedItem) {         //PERFORM ACTIONS HERE 	}
 
	@Override
	public List<String> getSupportedTags() {
		String[] list = {"kdmtestmodule1","kdmtestmodule2"};
		return Arrays.asList(list);
	}
}
*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:
* _textData:_ This is the textual data payload ff binaryData  is null.  If binaryData is not null then this is the filename for the  binary data. This means that you can read in text data as a string or if  binaryData is present it can be assumed that textData contains the  filename of the binaryData.

* _binaryData:_ This is java.sql.Blob object from which  binary data can be read.  If this parameter is not null then it can be  assumed that textData contains the filename of the binaryData.

* _fromServer:_ The server object that represents where the data originated from.

* _tag:_ The tag that was given to the data to determine it's purpose.

*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.<bean class="org.openmrs.module.remotedatatransfer.impl.RemoteDataTransferServiceImpl">
	    <property name="listener">
	    	<bean id="moduleListener" class="@MODULE_PACKAGE@.ModuleListener"/>
	    </property>
</bean>
note -  ModuleListener should be replaced by the name of your implemented module listener class.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=10]\]

h3. Service/API Methods

After setting up the module API functions are made available by starting the RDT service. This is done as follows:RemoteDataTransferService service = Context.getService(RemoteDataTransferService.class);
Now service methods can be called using the newly created service object.  For example to send data:service.sendData("DATA0101", service.getServer("SERVER001"),"TAG1");\\

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=11]\]

h2. Known Issues

*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|http://dev.mysql.com/doc/refman/5.1/en/packet-too-large.html] size in mysql.

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=12]\]

h2. Resources

\[[edit|http://archive.openmrs.org/index.php?title=Remote_Data_Transfer_Module&action=edit&section=13]\]

h3. Blog

[Kennymac's devBlog|http://dev.xeerotee.net/]