How to Define Your Own Procedures

Procedures in Sana are defined in a simple xml format. The following tutorial allows people to easily create their own procedures. This tutorial steps through the creation of a procedure for a post-surgical follow-up.

Creating Procedure Structure and Pages

First we need to define the XML base structure by adding a Procedure title. This is what you want your Procedure called. It is done as follows:

   <Procedure title="Surgery Follow-Up">
   </Procedure>

All opening tags, i.e., <....> need a matching closing tag, i.e., </.....> where the "...." is the name of the element. So in this case the opening tag is: <Procedure> and the closing tag is: </Procedure> and the "...." is Procedure. Note the forward slash "/" in the closing tag.

We can now add a page (via the "Page" element) to our new procedure:

   <Procedure title="Surgery Follow-Up">
         <Page>
         </Page>
   </Procedure>

In the next section we will insert a page element onto the page we just created.

Putting in Page Components

Here we will put page elements into our new procedure. There are several different types of elements we can insert. We will start with a text box element.

 <Procedure title="Surgery Follow-Up">
   <Page>
     <Element type="ENTRY" id="patientId" concept="PATIENT ID" question="Enter the patient's ID number:" answer=""/>
   </Page>
 </Procedure>

We now have a working procedure that can be run in Sana. It is one page long and asks for the patient's ID number and provides the user with a text box for response. Every "element" contains a type (indicating what kind of element type it is), a medical concept, an id that must be unique within the entire procedure, and a question which will be displayed to the user. The answer can be left blank - it allows one to indicate the default response that is filled in automatically.

Sana currently supports the following element types:

* ENTRY: text entry element
* SELECT: drop-box style single-item selection element (good for questions with many possible responses)
* MULTI_SELECT: check-box style multi-item selection element
* RADIO: radio button single-item selection element
* GPS: element to allow the user to grab his/her current coordinates
* SOUND: element to allow the user to make an audio recording
* PICTURE: element to take photo(s)

We can also add multiple elements to a single page (although this is generally not suggested for aesthetic reasons):

 <Procedure title="Surgery Follow-Up">
   <Page>
     <Element type="ENTRY" id="patientId" concept="PATIENT ID" question="Enter the patient's ID number:" answer=""/>
     <Element type="SELECT" id="1" concept="SURGERY SITE" question="Site of surgery" answer="" choices="Head and Neck,Chest,Abdomen,Pelvis,Extremities,Others"/>
   </Page>
 </Procedure>

Elements that have multiple choices (select, multi-select, and radio elements) require a comma-separated "choices" parameter as shown above.

We can also (and usually do) add multiple pages to a single Procedure:

 <Procedure title="Surgery Follow-Up">
   <Page>
     <Element type="ENTRY" id="patientId" concept="PATIENT ID" question="Enter the patient's ID number:" answer=""/>
   </Page>
   <Page>
     <Element type="SELECT" id="1" concept="SURGERY SITE" question="Site of surgery" answer="" choices="Head and Neck,Chest,Abdomen,Pelvis,Extremities,Others"/>
   </Page>
   <Page>
     <Element type="SELECT" id="2" concept="ORGAN" question="Organ" answer="" choices="Stomach,Intestines,Gallbladder,Appendix,Liver,Kidney,Spleen,Pancreas"/>
   </Page>
 </Procedure>

Make sure that each page element has a concept tag such as "SURGERY SITE" or "ORGAN," which will become the concept category of the answer to the question. Feel free to pick any name for the concept tag as long as it is pretty short, summarizes the question, and is in all capital letters.

Adding Branching

Sana Procedures support page-entry branching, meaning pages can be shown on a conditional basis, based on responses to previous questions. Branching is indicated in the Procedure XML by adding the "ShowIf" tag. Within a ShowIf block, a criteria statement must be contained. For example, we can conditionally show the given one element page using the following XML:

 <Page>
   <ShowIf>
     <Criteria type="EQUALS" id="1" value="Abdomen"/>
   </ShowIf>
   <Element type="ENTRY" id="patientId" concept="PATIENT ID" question="Enter the patient's ID number:" answer=""/>
 </Page>

This conditional has type EQUALS, which means it will check that the user answer to element id equal to "1" has value equal to "Abdomen." The type EQUALS will check for a string match, whereas some of the other valid Criteria types expect values to be numbers. Valid types include:

* EQUALS: check if two strings or numbers are equal
* GREATER: check if the answer to the given element (specified by id) is greater than the given value.
* LESS: check if the answer to the given element (specified by id) is less than the given value.

Multiple Criteria can be logically combined in a ShowIf statement through the use of boolean operators. Here is an example

 <ShowIf>
   <and>
     <Criteria type="EQUALS" id="1" value="Abdomen"/>
     <Criteria type="GREATER" id="2" value="5"/>
   </and>
 </ShowIf>

This checks that both element id equal to "1" EQUALS "Abdomen" AND element id equal to "2" is GREATER than 5.

The possible boolean operators are:

* <and> checks if all the Criteria in the statement are true
* <or> checks if any Criteria in the statement is true
* <not> checks if the single Criteria in the statement is not true

Multiple statements can be composed within one another. For example:

 <ShowIf>
   <and>
     <Criteria type="EQUALS" id="1" value="Abdomen"/>
     <or>
       <Criteria type="GREATER" id="2" value="5"/>
       <Criteria type="LESS" id="3" value="2"/>
     </or>
   </and>
 </ShowIf>

checks if element "1" EQUALS "Abdomen" AND either element "2" is GREATER than 5 OR element "3" is LESS than 2.

Installing New Procedures in Sana

Sana 1.1 currently compile and run time installation of new Procedure files into the application. Earlier versions only support compile time installation.

1. Compile time. Place your new XML file into the /res/raw/ directory and add a reference to it in org.moca.util.MocaUtil.java under the loadDefaultDatabase() method. When running Sana for the first time, you will need to reload the database with the new file. Click on the menu button on the phone while in Sana and click "reload database."
2. Run time. The files need to be copied onto the Android device SD card and then updated within the application.
   1. Attach the phone with a USB cable and copy the file to:

      /mnt/sdcard/media/sana/resource/procedure/

   2. On the phone with Sana app running, select

      Settings --> Sana Resources --> Manage Procedures

   3. Press to install (Or use Menu --> Load All Procedures).

If there any errors parsing the procedure xml, an error message will be displayed and it will not be loaded.

Updating Concept Definitions in OpenMRS

As of Sana version 1.1, any new Concepts will not be automatically added to OpenMRS on upload. You will need to log into OpenMRS and manually add them through the "Concept Dictionary" page. This was done as a security and QA measure due to the addition of run time procedure updating.

A Complete Procedure

Here is a more complete Procedure that uses all of the available element types and demonstrates branching.

 <Procedure title="Surgery Follow-Up" author="Sana">
   <Page>
     <Element type="SELECT" concept="SURGERY SITE" id="1" question="Site of surgery" answer="" choices="Head and Neck,Chest,Abdomen,Pelvis,Extremities,Others"/>
   </Page>
   <Page>
     <ShowIf>
       <Criteria type="EQUALS" id="1" value="Abdomen"/>
     </ShowIf>
     <Element type="SELECT" concept="ORGAN" id="2" question="Organ" answer="" choices="Stomach,Intestines,Gallbladder,Appendix,Liver,Kidney,Spleen,Pancreas"/>
   </Page>
   <Page>
     <ShowIf>
       <and>
         <Criteria type="EQUALS" id="1" value="Abdomen"/>
         <Criteria type="EQUALS" id="2" value="Intestines"/>
       </and>
     </ShowIf>
     <Element type="MULTI_SELECT" concept="SYMPTOMS" id="3" question="Check all that apply:" answer="" choices="Fever,Diarrhea,Constipation,Wound drainage,Pain surrounding wound"/>
   </Page>
   <Page>
     <ShowIf>
       <and>
         <Criteria type="EQUALS" id="1" value="Abdomen"/>
         <Criteria type="EQUALS" id="2" value="Intestines"/>
         <Criteria type="EQUALS" id="3" value="Wound drainage"/>
       </and>
     </ShowIf>
     <Element type="RADIO" concept="WOUND DRAINAGE" id="4" question="Is the wound drainage:" answer="" choices="Clear,Pus,Bloody"/>
   </Page>
   <Page>
     <ShowIf>
       <and>
         <Criteria type="EQUALS" id="1" value="Abdomen"/>
         <Criteria type="EQUALS" id="2" value="Intestines"/>
         <Criteria type="EQUALS" id="3" value="Pain surrounding wound"/>
       </and>
     </ShowIf>
     <Element type="RADIO" concept="PAIN LEVEL" id="5" question="How bad is the pain?" answer="" choices="Mild,Moderate,Severe"/>  
   </Page>
   <Page>
     <Element type="RADIO" id="6" concept="INITIAL DIAGNOSIS" question="Diagnosis" answer="" choices="No evidence of infection,Suspect infection"/>
   </Page>
   <Page>
     <Element type="MULTI_SELECT" concept="RECOMMENDATION" id="7" question="Recommendation" answer="" choices="Refer to University Hospital,Antibiotics,Follow-up"/>
   </Page>
   <Page>
     <ShowIf>
       <Criteria type="EQUALS" id="7" value="Follow-up"/>
     </ShowIf>
     <Element type="SELECT" id="8" concept="FOLLOW UP PERIOD" question="Follow-up in:" answer="" choices="3 days,1 week,2 weeks,1 month"/>
     <Element type="ENTRY" id="9" concept="FOLLOW UP PERIOD" question="Other duration:" answer=""/>
   </Page>
   <Page>
     <Element type="ENTRY" id="11" concept="COMMENTS" question="Other comments:" answer=""/>
   </Page>
   <Page>
     <Element type="GPS" id="12" concept="GPS" question="Record Your Position" answer=""/>
   </Page> 
   <Page>
     <Element type="PICTURE" id="13" concept="SURGERY SITE IMAGE" question="Take Picture of Surgery Site" answer=""/>
   </Page> 
 </Procedure>

Form Validation Tool

There is an on-line form validation utility available here:

http://demo.sana.csail.mit.edu/xml