This tutorial shows which steps should be followed in creating an application which allows an user to fill in a questionnaire and store the answers in MedRecord.

Preparatory Work

Before one can add a questionnaire to an application, the developer needs some information about this questionnaire.

MedRecord makes this information available through procedures. Procedures are summaries written by people with a medical background and contain all the information needed by user interface developers to implement the functionality.

Besides the procedure, MedRecord also provides a formbuilder which allows persons with a medical background to layout and format the forms. These forms are stored in MedRecord and can be used, in combination with a suitable library for showing those forms, by the frontend.

Finally MedRecord provides detailed information about what information the user should provide, complete with references to SNOMED and way to validate the answers. The best resource for this information are the JSON schemas or the Javadocs.

This example uses the Asthma Control Questionnaire as an example. Before implementing this questionnaire it is recommended to familliarize oneself with the following:

  • the ACQ procedure
  • the corresponding API
  • the JSON schema or JavaDoc
  • any available form

Login and find an EHR ID

The first step is to find an EHR ID for the user. This EHR ID is used to store the information correctly and can be obtained through the demographics API of MedRecord.

After logging in, the EHR ID is available in the JSON Web Token or in the information returned by the login method.

Find out what the patient should do

In health care the physician creates a care plan which, in this case, can be seen as a todo list with activities the patient has to do.

In this care plan there might be an item telling the patient to fill in a questionnaire on a certain date. This item comes with an activityId which is important to remember and has to be included with the answers send back to MedRecord.

It is also possible to fill in a questionnaire without a care plan and storing the answers in MedRecord.

More information about such todo lists can be found in the documentation on care plans.

Showing the form to the patient

For showing the form to the patient there are two options.

The UI developer can create its own form using the information available in the JSON schema and procedure.

A better approach is to design the form using the formbuilder and then rendering the results using a library handling all the details of displaying and processing these forms.

Such library is currently under construction.

Sending results back to MedRecord

NOTE\ When using the library mentioned in the previous step, sending results back to MedRecord is already handled by this library.

MedRecord will calculate and check the fields which need to be calculated and will return this information. If the results of a calculation are not needed before calling the API method for storing the information it is best not to make those calculations on the client but let MedRecord do this. MedRecord will reject the answers if the calculations done by the client and by MedRecord do not match.

Generic solution

Sending data to MedRecord is as simple as POSTing the data as JSON document to a specific URL.

For the ACQ procedure this method is POST /ehr/{ehrId}/procedure/acq

Detailed information about the body to be included in the method call can be found in the documentation of this method.

A minimal example document would be:

  "applicationInfo": {
    "applicationVersion": "1.1.0",
    "locale": {
      "region": "UK",
      "language": "en"
    "applicationName": "MedSafe"
  "shortnessOfBreath": "NONE",
  "wheezing": "NOT_AT_ALL",
  "time": "2015-01-05T12:55Z",
  "puffsPerDay": "NONE",
  "height": "1.5",
  "fev1": "2",
  "age": "17",
  "wokenByAsthma": "NEVER",
  "gender": "MALE",
  "symptomsOnWakeup": "NO_SYMPTOMS",
  "activityLimiting": "NOT_LIMITED_AT_ALL"

Java solution

For Java there exist a client library which contains a method to store an ACQ result. Information about this method can be found in the JavaDocs

A minimal example using this library would be:

final AcqScore acqScore = new AcqScoreBuilder()
        new ApplicationInfoBuilder()
            .setLocale(new Language("en"))
    .setHeight(new BigDecimal("1.5"))
    .setFev1(new BigDecimal("2"))
    .setAge(new BigDecimal("17"))

final ClientResourceConfig config = getResourceConfig();
final String ehrId = getEhrIdOfUser();
new AcqScoreSetResource(config, ehrId).create(acqScore);