Administering FormEntry

Owned by Former user (Deleted)
Last updated: Jan 11, 2017 by Hillary Bagiire

Overview

The OpenMRS FormEntry module uses Microsoft® InfoPath™ to gather data for the repository.

  • You must have dictionary concepts defined for each question and answer on your form.
  • The form definition is created by defining a hierarchy of fields that will be used on the form.
    • The layout of the form hierarchy currently has some restrictions imposed by how the forms are eventually translated into the database
      • Form hierarchies should have the following sections (in order)
      • *PATIENT — as a section field
      • *ENCOUNTER — as a section field
      • *OBS — as a concept field with the concept MEDICAL OBSERVATIONS
      • *ORDERS — as a section field
      • There are certain fields that are required for an encounter and these must be present within the form hierarchy under the appropriate section.
      • We have created the "Basic Form" as a starting point. The basic form contains all of the required fields to get a form working. You should always start a new form by making a copy of the Basic Form and giving your copy a new name.

Design Form

  1. If you have not just finished designing the schema...
    1. Log into OpenMRS as an administrator
    2. Navigate to Administration ? Forms
    3. Click on the <u>Edit Metadata</u> link next to your form name
  2. Click on the <u>Download XSN</u> link
  3. Do not open the file with InfoPath (the default action); rather, save the file to disk
  4. Right mouse click the saved XSN file and click 'Design' to open it in Microsoft Infopath in design view

To add form controls:

  1. Select Data Source from the right navigation menu.
  2. Right-click a form element from the Data Source menu.
  3. Drag-and-drop the form element into the main content section.
  4. : NOTE: for typical observations, you may want to drag the child "value" element instead of the entire observation element
  5. : NOTE: For nicely-formatted form elements such as selection boxes and check boxes, use a coded item from your schema, and make sure that it is not set to Multi. Drag the value over to where you want. Afterwards, you can use the Properties dialog to give the form display values of your choosing.
  6. Select a form control from the context menu that is displayed.

To add layout elements:

  1. Move the blinking cursor to the content area where you would like to add a new layout element
  2. Select Layout from the right navigation menu.
  3. Select a layout option from the Layout menu.

To get just the concept name displayed you need to use some xpath scripting:

  1. Right click on the input box in design mode and select "Expression Box Properties"

  2. On the "General" tab, in the "Data Source" section, in the "XPath:" textbox, paste:

    substring-before(substring-after(., "^"), "^")

Publish Form

To publish your form to the web (general instructions):

  1. Save XSN to filesystem (assuming you are still working within InfoPath).
  2. Close InfoPath.
  3. Log into OpenMRS as an administrator and go to Administration ? Forms
  4. Click on the <u>Upload XSN</u> link
  5. Browse to your XSN and upload it

Editing a Form

DO NOT design the XSN that the server uses. The folder specified in the runtime properties for OpenMRS (via the formentry.infopath.output_dir property) is for use ONLY by OpenMRS. You should never manipulate these files directly. In order to get files into that folder, use the "Upload XSN" function. In order to get files out of that folder, use the "Download XSN" function.

Duplicating a Form

Duplication of form is now easily accomplished using the Manage Forms page. Simply select the form you wish to duplicate using the drop down box and then press duplicate. You will be taken to the meta data screen to allow you to change the name and the version. Of note, you have to change the build number in the database directly if you require (form table). It is important to note that XSNs have database form IDs incorporated, so one form cannot be used on another system unless you use the new Import/Export module (which requires identical Concept dictionaries). Occasionally it is necessary to change the ID of an XSN after it has been exported. This can be done using the old method of duplicating form (adapated from Andy's message):

  1. Open the XSN of the form in Design mode (right mouse click the file and choose design) and select File ? Extract form files from the menu to save the form as separate files. Then close infopath.
  2. You will now see a folder with the name of your duplicate form. Inside this folder you will see some files. Edit the FormEntry.xsd file with a text editor (wordpad or notepad) and find the line:

  3. :

    <xs:attribute name="id" type="xs:positiveInteger" fixed="n" use="required" />
  4. : where n is the id of the form.
  5. Change the n within <tt>fixed="n"</tt> to the form id of the form in the database with which you want to import the XSN(the new form id can be found by (a) examining the URL for the new form within OpenMRS' Admin ? Form screen, e.g. hovering over the "metadata" link for the new form and looking at the end of the URL in the browser's status bar at the bottom) OR (b) looking up the form table in the MySQL back end. Save and close FormEntry.xsd
  6. In the same folder, right-click on the Manifest.xsf file and selected Design.
  7. Choose File, Save As and save the form to disk with another name to get the second version of the modified form. You can delete the first version of the form. Upload the second version of the form into OpenMRS.

OpenMRS uses the form id within the FormEntry.xsd file (compressed within the XSN) to determine the form to which the XSN belongs.

Moving Forms Between Servers

OpenMRS does not currently support the transfer of FormEntry forms between servers using different dictionaries or different form definitions

Assuming the two servers are using the same dictionary concepts and form and field definitions (all internal identifiers aligned), you need only upload the XSN to the destination server. If there are subtle differences (different answers to a concept on the desintation server or an additional field in the schema), you might be able to get the form working by uploading the XSN to the destination server, then downloading it and uploading it again – we plan to add a "Rebuild XSN" link to simplify this process.

  • Uploading an XSN (also known as "publishing an XSN")
    updates the URLs and advances the build number (the last number in the InfoPath solution version inside the XSN files). Uploading does not change the schema or templates.
  • Downloading an XSN
    refreshes the schema and templates with the latest data from the form schema definition and the concept dictionary. Downloading does not change the build number and does not mess with the URLs since editing in InfoPath resets the URLs anyway.
  • Editing with InfoPath
    changes the internal URLs anytime you save the file. Anytime an XSN is saved from InfoPath, it must be uploaded ("published") to correct the URLs before it can be used to collect data within an OpenMRS system.

Issues with long Infopath Forms

If your users are spending more than 15 minutes on a form, there is a possibility that their authenticated user session may time out. If this is the case, when the form is submitted, an undetected "403 Forbidden" error may occur and Infopath will close.

There are two settings you can set to keep this from happening: formentry.infopath_taskpane_refresh_sec and formentry.infopath_taskpane_keepalive_min. The "refresh seconds" are "how often (in seconds) the taskpane should "ping" the server to keep the user's session alive". The "keepalive min" is "for how many minutes this should be repeated".

Workable values would be 300 seconds ("ping" server every five minutes) and 45 mins ("if they haven't submitted the form in 45 mins, stop pinging the server).

Other Resources