FormEntry Technical Overview
The OpenMRS FormEntry module uses Microsoft® InfoPath™ to gather data for the repository.
Designing Forms
- The form hierarchy (or schema) created within the OpenMRS web application defines an XML Schema for data collection. Essentially, the form hierarchy defines all of the data points that will be (or could be) gathered on any particular form.
- When you download a form for the first time, the schema your have defined along with an XML template that follows the schema are injected into a starter form that contains the basic layout and plumbing for InfoPath. A downloaded XSN should be saved to disk and opened with InfoPath in design mode — e.g., right-click the XSN file and select "Design" from the context menu.
- During the design process, forms that are saved to disk are automatically altered internally by InfoPath. The URLs in the form are changed to point to the local file system.
- When you upload a form through the OpenMRS web application, the internal URLs are converted to the appropriate value based on the server's URL and the file's location on the server.
Submitting Forms
- When an InfoPath form is submitted to the server, an XML file containing the form data is actually posted to the server (via HTTP POST protocol, just as you were submitting a web-based form)
- The server places the XML file (unchanged) into the formentry_queue table
- A scheduled FormEntry queue processing task scans the formentry_queue table every 30 seconds and, when records are found, process queue entries. The XML is translated using the form's XSLT template to create an HL7 message to be placed in the hl7_in_queue (HL7 inbound message queue)
- If errors occur, the record is transferred to the formentry_error table and processing stops
- If no errors occur, the record is transferred to the formentry_archive table and an entry is made into the hl7_in_queue (HL7 inbound message queue)
- An HL7 processor task scans the hl7_in_queue table every 30 seconds and processes any entries that are found.
- The open source HL7API engine is used to parse the HL7 message and create the appropriate encounter and obs records.
- If any errors occur, they are logged in the hl7_in_error table; otherwise, the entry is moved to the hl7_in_archive> table when processing is completed successfully.
- See HL7 and HL7 Import Process wiki pages
In summary, form data are initially placed in the FormEntry queue, translated into HL7 messages in the HL7 inbound queue, and then parsed into the individual encounter and observational data points. Subsequently, all data operations (other than auditing FormEntry submissions) are performed on data from the encounter and obs tables.
By FormEntry 1.2, we should be translating order data into appropriate HL7 messages to follow the same general flow and generate data within the order tables.
Deployment Notes
- Be sure to set the formentry.infopath_server_url property at openmrs/admin/maintenance/globalProps.form
- As of Formentry version 2.6, the formentry_queue table is not used anymore, the default queue is done on the filesystem at $user/OpenMRS/formentry/queue
- When using FormEntry Module in a non-Windows environment (one that uses cabextract), do not adjust tomcat memory usage to greater than 4GB. See Ticket # 1987.
Database Tables and Columns
formentry_xsn
Once changes to an Infopath form are made, the compressed XSN is stored in the formentry_xsn. Each time a xsn is saved in infopath the build number is incremented. When uploaded to the server or rebuilt on the server the build version is also incremented. The version property is set and determined by a user. Best practices say that when you modify the look of the paper/electronic form you should increment this.
It is possible to delete all old XSNs that are marked as 'archived' and will never be used again.