How to Define Your Own Procedures

From MoCa Development Wiki

Procedures in Moca 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 Moca. 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.

Moca 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

Moca 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 Moca

Moca currently only supports manual placing of Procedure files into the application. To do this, put your new XML file into the /res/raw/ directory and add a reference to it in Moca.java under the loadDatabase() method. When running Moca 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 Moca and click "reload database."

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="Moca">
  <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>