11.1 Using the OpenRosa API in OpenClinica (experimental)

Starting with version 3.5, OpenClinica will begin to support the OpenRosa API, which will let you run Enketo, ODK Collect, or any of a number of OpenRosa-compliant data capture clients. If you're not familiar with Enketo, ODK, or OpenRosa, here's a primer. You can also see this blog post on how OpenClinica LLC is using Enketo and the OpenRosa API in its products. 

To try it yourself:

    1. Build/install the latest OpenClinica code from github or distros

    2. Install an OpenRosa client, such as enketo or ODK Collect
    3. Add the property 'PortalURL' to datainfo.properties with the URL of the OpenRosa Client
      PortalURL = http://www.example.com
    4. Issue a /formList request from the client to the OpenClinica:
      GET /OpenClinica-web/rest2/openrosa/{studyOID}/formList

    5. Currently supported methods include
      GET /OpenClinica-web/rest2/openrosa/{studyOID}/formList
      GET /OpenClinica-web/rest2/openrosa/{studyOID}/formXml
      POST /OpenClinica-web/rest2/openrosa/{studyOID}/submission

Note: These APIs are still experimental, may not work at all, and are certainly not suitable for production use. OpenClinica Participate uses them but the hosted environment includes tools to ensure network security and robustness for production use that are not in the enketo package. We aim to eventually support OpenRosa API as part of the standard OpenClinica API and welcome feedback, testing, and code contriutions. In particular, this is still experimental because:

  • Form submission will not really work because it does not create a study subject and study event where the data can go. This will be added in the near future.
  • The API is not particularly secure. There is no production-quality authentication mechanism, other than to secure network access to known safe clients. 

Alternative CRF design model using XForm

Starting with OpenClinica 3.8, you can use an alternative model for CRF Design based on the OpenRosa XForm specification, instead of the spreadsheet-based OpenClinica CRF Template. To enable:

  • Configure your OpenClinica datainfo.properties to activate the Xform feature
    • If you will be uploading images, the default size limit for total images uploaded is 5MB
    • If you will be uploading a large number of images or particularly large images, you should add the following to datainfo.properties:
      • pformMaxSubmissionSize=100000000
      • This maximum submission size setting is a safe bet to cover most image upload needs (this specific setting allowed for 15 files of 4.72MB each to be loaded. Feel free to adjust the number as needed to meet your needs.)
  • When adding a CRF or CRF version, select the 'Upload as Xform' tab
  • Paste your OpenRosa-compliant XForm code into the textarea (you can use an OpenRosa-compliant form design tool such as XLSForm to generate the XML from a spreadsheet)
  • Upload any media files (images, videos, audio, etc) that you want to be embedded in the form

The primary use case right now is to support having images & video embedded in participant forms. It also enables you to use a growing list of features available in the enketo form engine that are not available in the traditional OpenClinica CRF engine. Your CRFs should still function in the traditional OpenClinica CRF engine, though they may not look as pretty or support all the features of a typical OpenClinica CRF because only a minimal amount of required metadata is parsed from the XForm into the OpenClinica form metadata model. Most of the display/layout information as well as any edit checks and skip logic is left only in the XForm.

 

 

 


Functional approval by Laura Keita (lkeita), Director of Training and Compliance. Signed on 2016-05-12 4:37PM

Approved for publication by Cal Collins (ccollins), Chief Executive Officer. Signed on 2016-05-13 9:13AM

Not valid unless obtained from the OpenClinica document management system on the day of use.