Overview

A Procedure is a translation of a medical decision tree into a machine readable document which effectively control the appearance and flow of the user interface presented to mobile users. The remainder of this reference contains the complete XML document specification along with hints for authors. For a table summarizing the Procedure schema, see the Quick Reference at the bottom of this page.

Procedure XML Specification

The Procedure document format is a simple XML based schema with a single root Procedure node having one or more child Page nodes. The root Procedure node also contains metadata about the Procedure itself such as the author, version, and version represented as XML attributes. Input and display prompts are represented as child Element nodes for each Page. Additional metadata representing context, visual hints, constraints, and other information relevant to the prompt as XML attributes. Each Page may also contain simple, or compound, conditional statements that applies to any child Element nodes. The document structure, without the full XML syntax, is illustrrated below

Procedure ...metadata
    Page
        [Optional] 
            Conditional Statement ...simple or componund
        Element ...metadata
        [Optional]
          ... additional Element(s)
    [Optional]
        ...additional Page(s)

The full syntax for the specification-i.e. the XML node tags and attributes, follows.

Procedure

The Procedure tag marks the beginning of procedure.

Procedure
title Yes String A descriptive name.
author Yes String The author of the document.
uuid Yes String The id of the document.
version Yes String Distinguishes different versions of a protocol.
Allowed Child Nodes Page

Page

A Page groups one or more Element objects along with optional conditional logic. On the mobile client, all Element objects will be displayed as a single screen. The inclusion of conditional logic will require that the conditional evaluates to True for the Page to be visible. Marks a set of one or more instructions which are viewed collectively on a single page.

Page
-- no attributes --
Allowed Child Nodes ShowIf, Element

Conditional Logic - Show IF

The conditional logic available in the Sana Procedure mark up allows for the introduction of branching logic as required by many decision trees. When required, it must be included as the first child node for a Page within the XML. Conditional statements that evaluate to False will prevent the Page from being visible, or executed. The conditional statements apply to all Elements on a page.

ShowIf
-- no attributes --
Allowed Child Nodes and, or, not, Criteria

Criteria

An expression which will yield a logical truth value when evaluated.

Criteria
type Yes GREATER
LESS
EQUALS
The comparison operator to apply.
id Yes
value Yes Numeric or String The value to compare against.Note String comparisons are only meaningful for EQUALS.
Allowed Child Nodes -- NA --

Examples:

<Criteria type="EQUALS" id="1" value="Yes"/>
<Criteria type="LESS" id="1" value="1"/>
<Criteria type="GREATER" id="1" value="1"/>

and

Logical conjunction between any combination of two or more Criteria and compound statements. All child nodes must evaluate to True for the statement to be True.

and
Allowed Child Nodes and, or, not, Criteria

Example:

<ShowIf>
  <and>
    <Criteria type="EQUALS" id="1" value="Yes"/>
    <Criteria type="EQUALS" id="2" value="No"/>
  </and>
<ShowIf>

or

Logical disjunction between any combination of two or more Criteria and compound statements. At least one child node must evaluate to True for the statement to be True.

or
-- no attributes --
Allowed Child Nodes and, or, not, Criteria

Example:

<ShowIf>
  <or>
    <Criteria type="EQUALS" id="1" value="Yes"/>
    <Criteria type="EQUALS" id="2" value="No"/>
  </or>
<ShowIf>
not

Logical negation of the result of a simple or compound Criteria.

not
-- no attributes --
Allowed Child Nodes and, or, not, Criteria

Example

<ShowIf>
  <not>
    <Criteria type="EQUALS" id="1" value="Yes"/>
  </not>
<ShowIf>

Compound Statements

The conditional logic available in the Procedure scheme allows for nesting a number of statements in order to significantly more complex logic. As is visible in the individual The following conditional is provided to give some idea of the complexity that can be achieved but is by no means the limit of what can be constructed.

Example:

<ShowIf>
  <and>
    <not>
      <Criteria .../>
    </not>
    <Criteria .../>
    <or>
      <Criteria .../>
      <Criteria .../>
    </or>
  ... etc.
  </and>
</ShowIf>

Element

The elements are the individual instructions which prompt the end user for input or can be used to display information.

Element
id String Yes Must be unique within the page
type Yes DATE
ENTRY
SELECT
MULTI_SELECT
RADIO
PICTURE
PLUGIN
ENTRY_PLUGIN
Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No If true, input is required before the procedure will progress past a page containing the Element

Default: false

image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
choices String Yes The options presented to the user in the prompt. Applies to SELECT,MULTI_SELECT,RADIO
action String Yes A string which identifies which application to launch. Applies to PLUGIN,ENTRY_PLUGIN
mimeType String Yes The type of data collected. Applies to PLUGIN,ENTRY_PLUGIN

[xml example]

More on the type attribute

The following list gives a brief description of the elements available within a Procedure. Additional details, screenshots, and sample mark-up for each are provided. The value for the type attribute must be one of the element types defined by the Sana application. As presented in the summary table above, the core element types are:

The following sections will present additional details on each of the allowed values for the type attribute including additional optional attributes that apply to an Element of that type.

DATE

Element
id String Yes Must be unique within the page
type Yes DATE Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.

[screen shot]

Example

<Element id="1"
type="DATE"
concept="DATE"
question="Entry a date value"
answer=""/>

ENTRY

Presents a simple text box and collects text entered through the device keyboard.

Element
id String Yes Must be unique within the page
type Yes ENTRY Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.

[screen shot]

Example:

<Element id="2"
  type="ENTRY"
  concept="TEXT"
  question="Enter text"
  answer=""/>

SELECT

Presents a dropdown box and collects a single-item from a list.

Element
id String Yes Must be unique within the page
type Yes SELECT Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
choices String Yes The options presented to the user in the prompt.

[screen shot]

Example:

<Element id="3"
type="SELECT"
concept="TEXT"
question="Select a single value"
choices="1,2,3,4"
answer=""/>

MULTI_SELECT

Collects one or more items from a list as a set of checkboxes.

Element
id String Yes Must be unique within the page
type Yes MULTI_SELECT Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
choices String Yes The options presented to the user in the prompt.

[screen shot]

Example:

<Element id="4"
type="MULTI_SELECT"
concept="MULTIVALUE TEXT"
question="Select one or more values"
choices="1,2,3,4"
answer=""/>

RADIO

Collects a single-item from a list as a set of radio buttons.

Element
id String Yes Must be unique within the page
type Yes RADIO Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
choices String Yes The options presented to the user in the prompt.

[screen shot]

Example:

<Element id="5"
type="RADIO"
concept="TEXT"
question="Select a single value"
choices="1,2,3,4"
answer="1"/>

PICTURE

Collects one or more images using the device camera.

Element
id String Yes Must be unique within the page
type Yes PICTURE Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value. The answer attribute is meaningless for this type
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.

[screen shot]

Example:

<Element id="6"
type="PICTURE"
concept="IMAGE"
question="Take a picture"
answer=""/>

PLUGIN

Will capture and return a file object through an external application.

Element
id String Yes Must be unique within the page
type Yes PLUGIN Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value. The answer attribute is meaningless for this type
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
action String Yes A string which identifies which application to launch.
mimeType String Yes The type of data collected.

screen shot

Example:

<Element type="PLUGIN" id="7"
  concept="FILE"
  question="Demonstrate capturing to a file"
  action="org.sana.plugin.CAPTURE_FILE"
  mimeType="application/xml"/>

ENTRY_PLUGIN

Will capture and return an alphanumeric character sequence through an external application.

Element
id String Yes Must be unique within the page
type Yes ENTRY_PLUGIN Controls the UI of the prompt presented to the user
concept String Yes MUST correspond to the definition on the server.
question String Yes The text prompt that will be displayed to the user.
answer String No The default value.
required true or false No Default: false
image String No Name of a drawable resource within the compiled application. Will be displayed to the user on the screen.
audio String No Name of a raw resource within the compiled application. Will be played when the Page containing the Element is displayed.
action String Yes A string which identifies which application to launch.
mimeType String No The type of data collected. This type implies that the mimeType value is text/plain. Including a value will be meaningless since it will be overriden with text/plain

[screen shot]

Example:

<Element type="ENTRY_PLUGIN" id="8"
concept="TEXT"
question="Demonstrate plugin text capture"
action="org.sana.plugin.CAPTURE_CHARS"
mimeType="text/plain"/>

Concepts-providing context

Sana requires each Element to have a a concept attribute which provides the context for the data collection. Prior to execution, all concepts used within a new Procedure must be defined on the server where the data will ultimately be stored. If you would like to introduce new terms, please consult your system administrator regarding local policies for doing so.

Quick Reference

Tag Attribute Required Format Description
Procedure
title Yes String A descriptive name.
author Yes String The author of the document.
uuid Yes String The id of the document.
version Yes String Distinguishes different versions of a protocol.
Page
-- no attributes --
ShowIf
-- no attributes --
and
-- no attributes --
or
-- no attributes --
not
-- no attributes --
Criteria
type Yes GREATER
LESS
EQUALS
The comparison operator to apply.
id Yes
value Yes Numeric or String The value to compare against.Note String comparisons are only meaningful for EQUALS.
Element
id String Yes Must be unique within the page
type DATE
ENTRY
SELECT
MULTI_SELECT
RADIO
PICTURE
PLUGIN
ENTRY_PLUGIN
Yes Controls the UI of the prompt presented to the user
concept String Yes
question String Yes
answer String No
image String No Name of a drawable resource within the compiled application
audio String No Name of a raw resource within the compiled application
choices String Yes Applies to SELECT,MULTI_SELECT,RADIO
action String Yes Applies to PLUGIN,ENTRY_PLUGIN
mimeType String Yes Applies to PLUGIN,ENTRY_PLUGIN