Remote Data Transfer Module
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.
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.
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 (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.
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).
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.
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).
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)
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.
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 TestModule
Listener 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.
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");
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 size in mysql.