Remote FormEntry User Guide

Owned by Former user (Deleted)
Last updated: Mar 16, 2011 by Jeremy KeiperVersion comment
6 min read

Initial Setup

  • Install the RemoteFormEntry module on both the remote server and the central server.

Central Server Setup

  • The runtimeproperty "remoteformentry.server_type" must be set to "central" (webapp restart required to read runtime properties again): remoteformentry.server_type=central
  • Visit the "Setup Forms" page in the "Remote Form Entry" section on the Administration screen
    • Choose the forms you want to use as remote forms. These forms can be used by both remote and central at the same time. This setup operation simply adds a few fields to the form so that most patient data can be passed from remote to central
  • Visit the "Edit Properties" page in the "Remote Form Entry" section.
    • Set the Encounter Types that you assign to initial forms.
      • When one of these forms are imported to central and the patient in them doesn't exist yet, they are automatically created from the data in the form.
      • If a different type of encounter is submitted and the patient doesn't exist yet, it is either because an identifying attribute was keyed in incorrectly at remote/central previously, or the patient never had an initial visit. Either way, the form is put in the error queue stack and must be reviewed manually by a data manager.
    • Save the properties
  • The OpenMRS scheduled task "Process Central Server Imported Queue Items" should be turned on
  • The OpenMRS scheduled task "Generate Remote Return Data" should be turned on
    • Optionally, remote return data can be filtered to generate data for only specific locations.
      • This option is defined in the global property: remoteformentry.remote_locations
      • Add location id's to this global property to generate remote data for those locations.
      • Location id's separated by a comma will have their remote data generated separately.
      • Locations id's separated by a space will generate remote data for those locations all together.
      • Example: remoteformentry.remote_locations="19 26 27,4,2,3 35,7 24 25,8"
        • Remote data will be generated into six groups:
          1. remote data for locations 19 26 and 27
          2. remote data for location 4
          3. remote data for location 2
          4. remote data for locations 3 35
          5. remote data for locations 7 24 25
          6. remote data for location 8

Remote Server Setup

  • Setup openmrs normally
  • Copy the central server database to the remote server's database. Note: If you have a large database, you might want to skip exporting the (large) number of rows in the "obs" and "encounter" tables to save time. RemoteFormEntry will copy just the right encounters/obs the first time data is taken out the site. (Be sure to copy the database after setting up your forms for remote entry.)
  • The runtimeproperty "remoteformentry.server_type" must be set to "remote": remoteformentry.server_type=remote
  • Now set the global properties for the remote server. (formenty.* and remoteformentry.*)
  • VERY IMPORTANT The OpenMRS scheduled task "Process Form Entry Queue" should always always always be turned off
    • If this task is turned on, forms submitted by infopath will be parsed and placed into the remote server database and never transferred back to central
    • Set both the "Start on Startup" to false and select "Stop" for the task
  • The OpenMRS scheduled task "Process HL7 Task" should always be turned off
  • The OpenMRS scheduled task "Process Central Server Imported Queue Items" should always be turned off
  • The OpenMRS scheduled task "Generate Remote Return Data" should always be turned off
  • Visit the "Edit Properties" page in the "Remote Form Entry" section.
    • Set the location of this remote server. The values in the drop down are taken from the locations table
    • Save the properties.

Workflow

  1. Infopath forms are filled out in the remote site (is ongoing throughout this workflow)
    • Behind the scenes: The xml forms that infopath submits back to OpenMRS are stored in the formentry queue table
  2. The user transporting data from remote to central visits the "Export Forms" page (linked from the Administration screen)
  3. Using that page, the user downloads a zip file to a usb key, cdr, or cdrw
    • Behind the scenes: The xml forms are zipped and timestamped.
    • The xml forms are moved from the formentry queue to the remoteformentry pending queue.
  4. ...User walks/jogs/drives/flies to central with the usb key to the central server...
  5. User visits the "Import Forms" page (linked from the central server's Administration screen)
  6. Using that page, the user uploads the zip file on the usb key.
    • Behind the scenes: The xml forms are put into the remoteformentry pending queue. (Note to testers: Both the remote and central server use the pending queue to store data. If your server is both remote and central, you'll have parsing issues)
    • This upload was tagged as from a certain location. A list is kept for "forms received successfully" from this location.
  7. The transport user is done for now. He/she can leave for the day or jump to #9
  8. The openmrs scheduled task "Process Central Server Imported Queue Items" processes items in the remoteformentry pending queue
    • Behind the scenes: When an xml form is processed it is attempted to be matched to a current patient.
    • Patient matching is done on the patient's "Identifiers", aka Medical record numbers. (NOT on patient.patient_id)
      • If the patient is found, the patient's patient_id is put into the xml form and the form is moved from remoteformentry pending queue to the formentry pending queue.
      • If the patient is not found and this form is marked as an "initial" form, the patient is created from the data in the form
      • If the patient is not found and this form is NOT marked as an "initial" form, the xml form is put into the formentry error queue to be analyzed later by a data manager
  9. The user transporting data from central to remote visits the "Download Data for Remote Server" page (linked from the Administration screen)
  10. Using that page, the user downloads a zip file onto a usb key, cdr, or cdrw to be taken to a specific remote server
    • Behind the scenes: The zip file contains two things:
      • A backup of the entire central database (made overnight by the OpenMRS scheduled task "Generate Remote Return Data")
        • This backup is simply a sql file made by the mysqldump program. The obs table data is not included.
      • A list of all xml forms received from this remote server.
  11. ...User walks/jogs/drivers/flies to the remote server...
  12. User visits the "Receive Data from Central" page (linked from the remote server's Administration screen)
  13. Using that page, the user uploads the zip file from central off the usb key
    • Behind the scenes: The items in the remote server's remoteformentry pending queue that the central server says it has received are moved to the formentry archive
    • The database backup from the zip file is run immediately on the remote server. All data and tables in the remote server's database are overwritten with what came from the central server's database.
  14. (Repeat, starting at #2)

Upgrading

Upgrading should be a relatively easy process for central and remote servers.  The remote server is only storing the xml schema of the submitted forms, so those should be both backwards and forwards compatible with openmrs versions.  The only time you need to be careful is when the form schema changes drastically in either the formentry module or in core (which would be very rare)

Upgrade workflow:

  1. Be sure all forms are processed on central
  2. Upgrade central's openmrs/war file to the desired version
    1. (meanwhile filling out of forms at remote sites can continue)
  3. Take central data to remote along with the new war file upgrade
  4. Perform a 'receive from central' on the remote server
    1. (this may or may not complete successfully due to db+code differences
  5. Shut down this remote server
  6. Upgrade this remote server's war file.
  7. Start remote server again and everything should be good to go
  8. Perform a 'send to central' to move the forms back to the central

Troubleshooting

java.io.IOException: Cannot run program "mysqldump"

This can happen if the MySQL bin folder is not on your path. Remote FormEntry depends on running the mysqldump utility. You can confirm the problem by opening up a command prompt and typing "mysqldump" to see if the program is found. Adding the MySQL bin folder to your path should solve the problem. See this conversation for more details.

org.springframework.web.multipart.MaxUploadSizeExceededExceptionMaximum upload size of 75000000 bytes exceeded; nested exception is org.apache.commons.fileupload.FileUploadBase$SizeLimitExceededException: the request was rejected because its size (100604040) exceeds the configured maximum (75000000).

There's a quick way to fix this, but I wouldn't advise that you do things like this too often. But because Tomcat nicely deploys your webapp in exploded format, you *can* make the following change.

  1. Stop tomcat
  2. Change the following line in openmrs-servlet.xml under TOMCAT_HOME/webapps/openmrs/WEB-INF. <property name="maxUploadSize"><value>75000000</value></property>to be something like this<property name="maxUploadSize"><value>100000000</value></property>
  3. Start tomcat
java.lang.IllegalStateException: setAttribute: Session already invalidated

When you have a large amount of data to "receive from central" you might encounter this error before the page is finished loading. This will be fixed in the latest version of remoteformentry, but until then, the workaround is to change the web.xml in your openmrs installation:

  1. Stop tomcat
  2. go to tomcathome/webapps/openms/WEB-INF
  3. edit web.xml and add this after </display-name>: <session-config><session-timeout>3600</session-timeout></session-config>
  4. Start tomcat again Note: This change will disappear when you deploy a new openmrs war file and will have to be re-done.
Generating the Return Data File Does Not Produce Output

The mysql user must have the RELOAD privilege.