MMSyntax

Introduction

Purpose

This document provides a description of the syntax used by the OpenMRS messaging module [archive:1|http://openmrs.org/wiki/Messaging_Module]. The expected audience of this document are the development team of the messaging module, the OpenMRS community, and any parties interested in the development or adoption of this messaging syntax.

This document draws heavily from work that has previously been done on the subject of syntaxes and terminologies as well as specific examples. The authors who contribute herein will make every effort to cite and credit fully. The entries in the References section of this document are particularly formative in its creation and are duly credited.

Scope

The messaging module syntax (MMSX) is the language used to communicate between an OpenMRS installation and a user via a character limited messaging service. Popular examples of character limited messaging services include short message service (SMS) or Twitter. This syntax follows the codes and conventions defined by the Open Mobile Health Exchange microsyntax (OMHE).

Some important examples of those conventions:

Message strings are limited to 160 characters or less.
Commands are separated by whitespace or asterisks.

Definitions, Acronyms, Abbreviations

MMSX - messaging module syntax, see scope of this document.
SMS - short message service.
Twitter - a web based short message service.
OMHE - Open Mobile Health Exchange microsyntax.
LOINC - Logical Observation Identifiers and Name Codes.

References

Desiderata for Controlled Medical Vocabularies in the Twenty-First Century. JJ Cimino. [PDF]
LOINC - Logical Observation Identifiers and Name Codes.
ChildCount+ - Empowering communities to improve child and maternal health.

Document Overview

Section Two - Major Parts of a Message. Defines the structure of MMSX messages.
Section Three -

Major Parts of a Message

There are four major constructions for MMSX messages:

A standalone MMSX command.
A pairing of an MMSX command and a value.
An MMSX command qualified by the use of one or more tags.
An MMSX command paired with a value and qualified by one or more tags.

Some examples:* help would return a implementation defined help message.

wt155 would execute the command 'wt' with a value of '155'.
getbg#6m would execute the command 'getbg' with the tag '6mo'.
bg120#prebreakfast#accucheck would execute the command 'bg' with a value of '120' and the tags 'pre-breakfast' and 'accucheck'.
These constructions can be combined with the use of whitespaces to separate multiple commands in a single message. For example:* MUAC105 id28 E V D would execute the command 'MUAC' with a value of '105', the command 'id' with a value of 28, and the commands 'E', 'V', and 'D'.
Special commands can override the behavior of whitespaces. For example:* msg28 Hello, John! would send the message 'Hello, John!' to the user with id 28.
ptobs id27 cid314 The patient appears ill would record 'The patient appears ill' into an observation of concept id 314 for the user with id 27.

General Naming Conventions

Reserved Characters

Reserved characters in MMSX are " "(white space), "="(equals), "#"(pound), "|"(pipe), "*"(asterisk), "@"(at), "^"(karat), "+"(plus), and "-"(minus). The symbols have the following meanings:

" " separates commands. (This can be over-ridden by individual commands).
"=" assigns a value to a command. This command is inferred if no space exists between a command and a value.
"#" denotes a tag. The tag is always assigned to the immediately preceding command.
"*" also separates commands. This symbol serves as an alternate way to separate commands in a single message if the " " value has been over-ridden.
"@" is a shortcut to the 'msg' command. For example, @jdoe Hello, John! would also send the message 'Hello, John!' to the user JDoe.
"+" has two different meanings depending on where it occurs in relation to a string of characters.
- "+" is a shortcut to the 'id' command when it precedes a string. For example, MUAC105 +28 E V D would also execute the 'MUAC' command with a value of '105' as well as the commands 'E', 'V', and 'D' for the user with the id number 28.
- "+" is a shortcut to the 'yes' command when it succeeds a string. For example, BS+ executes the 'BS' command with an affirmative response.
"-" has two different meanings depending on where it occurs in relation to a string of characters.
- "-" is a shortcut to the 'icn' command when it precedes a string. For example, D +28 -084 -900 BS+ would execute the 'D' command (enter new diagnosis) on the user with id 28. The diagnosis codes '084' and '900' would be applied. Finally, the 'BS' command with a value of '+' would be executed.
- "-" is a shortcut to the 'no' command when it succeeds a string. "For example, BS- executes the 'BS' command with a negative response.

Appendix: Codes to Implement and Functionality

This section will be used to maintain a list of codes to be implemented in MMSX. Implemented codes will be placed on a separate wiki page, and a link to that page will be placed here. Please follow the format.

ptobs

Command: ptobs[archive:value] [archive:idXXX] <cidXXX>

Name: Patient Observation

Known Aliases: po

Status: Proposal

Options:

id (if no patient id is specified, will default to the user id assigned to the mobile device)
cid (must be specified)
[archive:value]

Details: This command will interact with an observation in an OpenMRS database. If no value is specified, it will return the last known value of the specified concept id cid for the patient id id and the date of that value's entry. If a value is specified, it will write a new observation of the specified concept id cid for the patient id id with a value of value and a comment 'Entered via <messaging modality>' where <messaging modality> is the method in which the message was received (such as SMS, Email, Twitter, and so on).

Examples:

ptobs cid120 returns the last value of concept id 120 for the patient assigned to the address from which the message was received. For example (if concept id 120 is CD4 count): PTOBS> Your last CD4 count was 327 on 07 May 10..
ptobs +50 cid120 returns the last value of concept id 120 for the patient with id 50. For example: PTOBS> DOE, John last CD4 count was 327 on 07 May 10.
potenofovir id50 cid4037 assigns the value 'tenofovir' to a new observation as concept id 4037 for patient id 91. The observation also has a comment 'Entered via <messaging modality>'. For example (if concept id 4037 is current antiretroviral regimen): PTOBS> "Tenofovir" added to Current Antiretroviral Regimen for DOE, John.

msg

Command: msg<id or username or groupname> <string>

Name: Message

Known Aliases: @

Status: Proposal

Options:

id or username (required) - identifies the recipient of the message. Can be a UUID, a group designation, or a user name.
string (required) - the message to be sent.

Details: This command will deliver a a string to a specified user or group of users. The string will be delivered to the preferred address of each user. If the user does not exist or does not have a specified messaging address, an error will be delivered to the sender.

Examples:

@bob Jambo! delivers joe> Jambo! to Bob's preferred messaging address.
msg yndour Great concert last night! delivers skeita> Great concert last night! to Yndour's preferred messaging address.
@chw please come to Yala Clinic for a meeting this Friday. delivers doc> please come to Yala Clinic for a meeting this Friday. to all users specified in the 'chw' group.

Appendix: Examples of Currently Existing Syntaxes to Study or Include

This section will be used to maintain a list of examples of syntax to include in MMSX. Please expand this section liberally, but also please be aware that not all codes may be incorporated into MMSX (for example, some conventions or codes may conflict with others).