Please note: OASYS is now the 'messaging module'.
Please find the current version of its development on the SVN repository at http://svn.openmrs.org/openmrs-modules/messaging/.

Introduction

Purpose

This requirements specification provides a complete description of all the functions and specifications of a system that will allow OpenMRS to handle asynchronous communications such as SMS or email. The expected audience for this document are the development teams of OpenMRS and Frontline:SMS, as well as parties interested in the development of this technology.  

PLEASE NOTE: For the purpose of a prototype of this module, only a single messaging system (such as SMS) and a few commands should be implemented. The anticipated delivery date of this prototype is 15 Mar 10.

Scope

OASYS will allow for applications built in OpenMRS (modules) to request a message be delivered to a recipient. Those modules will be able to access OASYS' API with a request for a message to be delivered and the recipient(s) to deliver the message to. OASYS will have access all information necessary to deliver that message, including the recipient's preferred delivery medium, message constraints of those media, and so on. OASYS will then prepare the message and submit it to a delivery system for transmission. Those delivery systems will also be able to submit messages to OASYS, which will be aware of the module that the message is intended for and will transport the message to the relevant module. OASYS may use a separate delivery system (such as Frontline:SMS for SMS messages) or integrate its own (for example, by incorporating SMSLib into its design). 

Definitions, Acronyms, Abbreviations 

AMPATH: Academic Model Providing Access to Healthcare. see http://iukenya.org

AMRS: AMPATH Medical Record System. see http://amrs.iukenya.org/

API: Application-Program Interface. see http://en.wikipedia.org/wiki/Application_programming_interface

SMS: Short Messaging Service. see http://en.wikipedia.org/wiki/SMS

OpenMRS: see http://www.openmrs.org  

OASYS: OpenMRS Asynchronous System for Simple Messages. 

FrontlineSMS:see http://medic.frontlinesms.com/

SMSLib: Java library for sending or receiving SMS. see http://smslib.org/

ResultsSMS: see http://www.resultssms.org 

Google Voice API: see http://code.google.com/p/google-voice-java/

OMHE: Open Mobile Health Exchange - A microsyntax for devices, machines, and human. see http://code.google.com/p/omhe/

CHW: Community Health Worker. see http://en.wikipedia.org/wiki/Community_health_worker

Twitter: see http://twitter.com

Java-Twitter: a java wrapper around the Twitter API. see http://code.google.com/p/java-twitter/

JavaMail: a java API for email support. see http://java.sun.com/products/javamail/

Document Overview 

    The remainder of this document is two chapters. Chapter two provides a full description of OASYS and lists all functions performed by the system. The final chapter details each of the system functions and actions in full for the developers' assistance. The two chapters are cross-referenced by topic to increase understanding of all parties.

Overall Description

OASYS will provide support to any OpenMRS module that requires delivery of a message offline (i.e. the message recipient is not using a live interface). OASYS will also provide an interface for delivery systems to access OpenMRS. 

Product Perspective / System Environment 

OASYS will operate as a module within OpenMRS. It will assume that all information necessary for the delivery of that message is available within OpenMRS (i.e. if a recipient specifies SMS is his preferred messaging system, that recipient's mobile device number would be stored within OpenMRS). On receiving a message request, OASYS will access the recipient's information in OpenMRS and obtain their preferred delivery mechanism and address. OASYS will then prepare the message for transport and deliver it to the relevant message delivery system for that mechanism. 

OASYS will also receive messages from message delivery systems it has been configured to accept messages from. On receipt of a message from a message delivery system, it will examine the message to determine the relevant action to perform on the message and call the relevant APIs to perform the action.   

Product Functions 

OASYS is designed to allow messages into and out of OpenMRS. 

Note: In writing the use cases below, I have assumed that you cannot guarantee context other than linking a mobile device number to a particular user or patient. As a result, the prompts guide users to interacting with the system using OMHE-styled syntax that OASYS can interpret out of context 

User Characteristics / Use Cases 

AMPATH Outreach SMS / Pediatric Oncology f/u

Mr. Bonaventura is a patient in Rainbow Clinic's HIV clinic. He has an appointment in two days' time. A process running in an OpenMRS instance is configured to send patients a reminder of their appointment. The process uses OASYS' API tor request that the system deliver Mr. Bonaventura a message. OASYS is aware that Mr. Bonaventura has stated a preference to receive messages via SMS. OASYS verifies that the message meets SMS constraints (160 character limit, for example) and sends the message to an SMS messaging system for delivery along with Mr. Bonaventura's demographics (specifically the mobile telephone number to deliver the message to).

The SMS messaging system sends the message to Mr. Bonaventura, who replies that he will attend the appointment as scheduled. The SMS messaging system receives the reply SMS and forwards that to OASYS along with the mobile device number that the message was received from. OASYS looks up the mobile number and identifies the reply as from Mr. Canonicus. OASYS then examines the message. If it cannot determine what type of message it is, it then examines the context (for example, OASYS is aware that it just sent an appointment reminder to this mobile device). Based on the above, OASYS determines that the appointment reminder process originated the messages and performs the follow-up action defined (in this use case, to register that Mr. Bonaventura has replied that he will attend his appointment).

Example of user interface:

SMS Message to Mr. Bonaventura: Hello. You have an appointment scheduled for Mar 6. Please reply 'app yes' if you will attend, 'app no' if you cannot, or 'app maybe' if you are unsure.

Mr. Bonaventura replies: 'app no'.

SMS Message to Mr. Bonaventura: We understand you will not be able to attend your appointment. We will contact you to reschedule your appointment within 24 hours.

ResultsSMS

As a part of his routine healthcare, Rainbow Clinic performs a laboratory test on Mr. Soranzo. It is now two days later, and the results of the lab test are entered into OpenMRS. Rainbow clinic has specified that all laboratory results should be delivered to patients directly. The laboratory system uses OASYS' API to request that the test results be delivered to Mr. Soranzo. Because this information meets Rainbow Clinic's criteria for protected health information, the laboratory system informs OASYS to use increased security in the delivery of this message. 

OASYS determines that Mr. Soranzo has stated a preference to receive his messages via SMS. Because this message requires increased security, OASYS needs to verify Mr. Soranzo's credentials. OASYS retrieves Mr. Soranzo's previously defined PIN along with his address to the SMS messaging system for delivery. The SMS messaging system will prompt Mr. Soranzo for his PIN, and if it matches the PIN provided by OASYS, then the SMS messaging system will deliver the specified message. The SMS messaging system sends a message to OASYS confirming successful delivery of the message along with the address it delivered to. OASYS examines the address, realizes that the address belongs to Mr. Soranzo, and registers message delivery into the laboratory system. 

Example of user interface:

SMS Message to Mr. Soranzo: Hello. Your blood work from Apr 02 is finished. Please reply 'pin XXXX' where XXXX is your pin number to get your results.

Mr. Soranzo replies: 'pin 1234'

SMS Message to Mr. Soranzo: Your Hgb was 11.2, and your HbA1C was 8.4. Reply 'chw' if you have a question about these results.

Mr. Soranzo replies: 'chw'

SMS Message to Mr. Soranzo: We will contact you about your blood work within 24 hours.

AMPATH-WFP Food Voucher Program

Mr. Donado is a patient at the Rainbow Clinic who meets the clinic's criteria for nutritional supplementation. A nutritionist writes a prescription and enters it into a nutrition module in OpenMRS. The nutrition module calculates the monetary value required for the prescription. The nutrition module deducts the credits from Rainbow Clinic's funds and assigns them to an account tied to Mr. Donado's phone. The nutrition module now needs to inform Mr. Donado that his credits are ready and of the account number. The nutrition module utilizes the OASYS API and provides Mr. Donado's demographics, contact information, and the message to be delivered. OASYS does not currently know how Mr. Donado would like to be contacted, however the API call from the nutrition module notes a mobile telephone number to be used. OASYS recognizes the mobile number and delivers the message to the Rainbow Clinic's SMS messaging system. (If the nutrition module had specified an email address, OASYS would use its email messaging system). 

Mr. Donado is now at a store and wishes to use his nutrition credits to buy food. He sends an SMS message to Rainbow Clinic, requesting a credit transfer to the store's account. OASYS receives the message from the SMS messaging system along with the number of the mobile device the message was sent from. On examining the message, OASYS realizes the message is a credit transfer request to an account.Using the number of the device the message was submitted from, OASYS identifies Mr. Donado's account information. OASYS uses the nutrition module's API to request the credit transfer. The nutrition module carries out the transfer and requests OASYS to send messages to Mr. Donado and the vendor with their new balances. OASYS then submits these messages to the preferred delivery services for both Mr. Donado and the vendor.

The vendor now wishes to exchange his nutrition credits for mPESA credits. He sends an SMS message to the Rainbow Clinic with his request. OASYS receives the request and identifies it as a credit exchange request for the nutrition module. Using the nutrition module's API, OASYS passes along the request for the credit exchange. The nutrition module then carries out the internal transaction and sends OASYS (via its API) a request to send Mr. Donado his new balance. The nutrition module also sends a request to OASYS to notify mPESA of the requested transaction. OASYS realizes the new request is an mPESA request and sends the request to the mPESA messaging service with the relevant account information. 

Example 1: new account

SMS Message to Mr. Donado: Hello. Your nutrition credits have been deposited. You now have 34 credits. Reply 'help nut' for help with the nutrition system.

Mr. Donado replies: 'help nut'

SMS Message to Mr. Donado: Reply 'nut bal' to get your balance, 'nut send XXXX YY' to send YY credits to XXXX account.

Example 2: vendor transaction

Mr. Donado replies: 'nut send 0009 14'.

SMS Message to Mr. Donado: Please reply 'pin XXXX' where XXXX is your pin number to send the credits to Acct 0009.

Mr. Donado replies: 'pin 1111'

SMS Message to Mr. Donado: '14 credits have been transferred to Acct# 0009. You have 20 credits remaining.'

SMS Message to Vendor 0009: '14 credits have been deposited to your account from User Donado. You now have 64 credits. Reply 'help nut vend' for help with the system'

Example 3: vendor credit exchange

Vendor 0009 replies: 'help nut vend'

SMS Message to Vendor 0009: Reply 'nut bal' to get your balance, 'nut send XXXX YY' to send YY credits to XXXX account, 'nut exchg ZZ' to change ZZ credits for mPESA.

Vendor 0009 replies: 'nut exchg 64'.

SMS Message to Vendor 0009: '64 credits have been exchanged. You have 0 credits remaining.'

Patient Phone Registration

Mr. Grimaldi is a new patient to the Rainbow Clinic. At his first appointment, he informs the registration staff that he has a cellular phone. The registration staff borrows his phone and types a short code into the device. The device sends an SMS to the SMS messaging system with a message that corresponds to register a new mobile device. OASYS receives the message from the SMS messaging system and recognizes the message as a request to register a new mobile device. OASYS registers the mobile number and sends a new message to the SMS messaging system to obtain Mr. Grimaldi's ID number. The SMS messaging system obtains the ID number from Mr. Grimaldi. OASYS then registers the mobile number as Mr. Grimaldi's in OpenMRS.

Example of user interface

Registration staff on Mr. Grimaldi's mobile: 'sta'.

--- Registration staff returns Mr. Grimaldi's mobile to him ---

SMS Message to Mr. Grimaldi: Welcome to Rainbow Clinic's mobile messaging system! Please reply 'id XXXXXX' where XXXXXX is your Rainbow Clinic ID number to get started.

Mr. Grimaldi replies: 'id 987654'

SMS Message to Mr. Grimaldi: Are you Ms. WrongPerson? Reply 'id yes' if you are, 'id no' if you are not.

Mr. Grimaldi replies: 'id no'

SMS Message to Mr. Grimaldi: We're sorry. Please reply 'id XXXXXX' where XXXXXX is your ID number to get started.

Mr. Grimaldi replies: 'id 987655'

SMS Message to Mr. Grimaldi: Are you Mr. Grimaldi? Reply 'id yes' if you are, 'id no' if you are not.

Mr. Grimaldi replies: 'id yes'.

SMS Message to Mr. Grimaldi: Hello, Mr. Grimaldi. Please reply 'pin YYYY' where YYYY is the pin number you will use for this system.

Mr. Grimaldi replies: 'pin 2222'

SMS Message to Mr. Grimaldi: Thank you. Please don't share your PIN with anyone else! If you forget your PIN, please call us at 123-456-7890 to change it.

SMS Message to Mr. Grimaldi: Rainbow Clinic would like to send you messages. These messages are free, and we will ask for your PIN before we send any personal messages.

SMS Message to Mr. Grimaldi: May we send you messages on this phone? Reply 'auth yes' if we can, 'auth no' if we cannot.

Mr. Grimaldi replies: 'yes'.

SMS Message to Mr. Grimaldi: Thank you! Mobile number 254-555-1212 is now registered to Mr. Grimaldi. We will send you messages at this number. Have a nice day!

Sick Patient / Pregnant + HIV / Pregnant + no ante-natal care f/u

Mr. Bergetto is a CHW for Rainbow Clinic assigned to the Ocean Village area. Last week, Rainbow Clinic identified Mr.SickPerson in Ocean Village that looked unwell at the time. Rainbow Clinic also identified Ms.NoHealthcare as a pregnant mother with HIV. Rainbow Clinic asked both patients to come into the clinic for follow-up, but neither patient did. Rainbow clinic specifies that these kinds of patients need to be followed up by a CHW in 7 days if they don't come in to the clinic.

The patient follow-up module recognizes that both Mr. SickPerson and Ms. NoHealthcare have not been seen in Rainbow Clinic and that their 7 day grace period has expired. The patient follow-up module uses OASYS' API to request a message be sent to Mr. Bergetto with the contact information for each patient. Mr. Bergetto has requested that OASYS use email for contact.

Example of User Interface

Email Message to Mr. Bergetto: Hello. Mr. SickPerson (ID 1231-2), Ms. NoHealthcare (ID 2342-3) in your area need follow-up. Reply 'fu XXXXX' where XXXXX is the patient's ID to start their follow-up.

Mr. Bergetto replies: fu 12312

Email message to Mr. Bergetto: Mr. SickPerson (ID 1231-2) was identified on 3 Mar as a sick patient. He has not followed up in 7 days. He lives at http://gps.coods.com/12x23. No phone number is available. Reply 'fu 1231-2 report' when your follow-up is complete.

--- Mr. Bergetto visits Mr. Sickperson and convinces him to go to clinic ---

Mr. Bergetto replies: fu 12312 report

Email Message to Mr. Bergetto: Follow-up Report for Mr. SickPerson. Reply 'fu 12312 app yes' if Mr. Sickperson will go to clinic, 'fu 12312 app no' if he will not, 'fu 12312 app maybe' if he is unsure, 'fu 12312 more' for other reports.

Mr. Bergetto replies: fu 12312 app yes

Email Message to Mr. Bergetto: Mr. Sickperson has until Mar 17 to come to clinic. 

Example 2 of User Interface

Mr. Bergetto replies: fu 23423

Email message to Mr. Bergetto: Ms. Nohealthcare (ID 2342-3) was identified on 3 Mar as a pregnant mother with HIV. She has not followed up in 7 days. No location is available. Her mobile number is 222-333-4444. Reply 'fu 23423 report' when your follow-up is complete.

--- Mr. Bergetto calls Ms.Nohealthcare and learns she can't afford transportation to her visit --- 

Mr. Bergetto replies: 'fu 23423 report'

Email message to Mr. Bergetto: Follow-up Report for Ms. Nohealthcare. 'fu 23423 app yes' if Mr. Sickperson will go to clinic, 'fu 23423 app no' if he will not, 'fu 23423 app maybe' if he is unsure, 'fu 23423 more' for other reports.

Mr. Bergetto replies: 'fu 23423 more'

Email message to Mr. Bergetto: Reply 'fu 23423 dead' if patient has died, 'fu 23423 nothome' if not at home, 'fu 23423 badloc' if the location is wrong, 'fu 23423 funds' if cant afford to come to clinic.

Mr. Bergetto replies: 'fu 23423 funds'

Email message to Mr. Bergetto: 100 Ksh has been transferred to Ms. Nohealthcare via mPESA. She has until 17 Mar to come to clinic. 

ART Adherence / Medication refill reminder

Mr. Ricbardetto is a patient with HIV who receives care at Rainbow Clinic. He has been placed on an anti-retroviral regimen that involves him taking his pills three times a day. Rainbow Clinic has specified that these patients receive a reminder every week about their medications. The medication adherence module uses OASYS' API and requests delivery of a medication reminder message to Mr. Ricbardetto. OASYS recognizes that Mr. Ricbardetto wants to receive messages using Twitter's direct message feature. (Note: this message may require increased security because it reveals Mr. Ricbardetto's HIV status. However, Rainbow Clinic may choose to consider Twitter direct messages to be secure because Mr. Ricbardetto has to log into Twitter to receive the message.)

Example of User Interface

Twitter message to Mr. Ricbardetto: 'd ricbardetto This is your weekly reminder to take your HIV medication. You should have 14 pills of Atripla (Rx #3b217) remaining. Reply 'did 3b217' if you were able to take your medication or 'med help' for more responses.

Mr. Ricbardetto replies: 'd RainbowClinic med help'

Twitter message to Mr. Ricbardetto: 'd ricbardetto Reply 'med 3b127 out' if you do not have any more pills, 'med 3b217 cost' if you could not pay for your medications, or 'med 3b127 stop' if you will not take this medication .'

Mr. Ricbardetto replies: 'd RainbowClinic med 3b127 stop'

Twitter message to Mr. Ricbardetto: 'd ricbardetto We note you have stopped taking this medication. We will be in touch with you within 24 hours.

Patient - system inquiry (lab value, next appointment)

Ms. Vasquez is a patient at Rainbow Clinic and wants to find out when her next appointment is. She sends an SMS message asking for help to the Rainbow Clinic. The SMS messaging system delivers the message to OASYS. OASYS recognizes the mobile number as that of Ms. Vasquez, an enrolled patient. OASYS sends a list of options to Ms. Vasquez via SMS. Ms. Vasquez then sends the command to find her next appointment. OASYS looks up the patient's return visit date concept in OpenMRS and returns the value to Ms. Vasquez via the SMS messaging system. 

Example of User Interface

Ms. Vasquez replies: 'help'

SMS Message to Ms. Vasquez: Reply 'med list' to get a list of your medications, 'app next' to get your next appointment, 'help lab' for information on the lab system, or 'help more' for more commands.

Ms. Vasquez replies: 'app next'

SMS Message to Ms. Vasquez: Your next appointment is 6 Jun. Reply 'app no' if you need to change this appointment, otherwise we will see you on 6 Jun.

Blast SMS - Bulletin to Patients for a new service

Ms. Poggio is a clinic administrator at Rainbow Clinic. The clinic is implementing a new service for its HIV patients, and Ms. Poggio is in charge of advertising the new service. Using the cohort builder in OpenMRS, she identifies a group of patients who should receive the message. She then specifies that this list of patients should receive a message and enters the message. Cohort builder utilizes OASYS' API, which then sequentially moves through the list of patients provided by Cohort Builder and uses each patient's communication preference to select the right messaging service and deliver the message to them. 

SMS Reminder to perform daily survey

Ms. Annabella is a 20 year old woman who is pregnant and is a patient of Rainbow Clinic. Rainbow Clinic specifies that these kinds of patients should complete a survey each day. If they do not complete the survey by a specified time, Rainbow Clinic sends the patient a prompt to remind the patient to complete their survey. At that appointed time, the survey module uses the OASYS API and specifies the patients to send the message to and the message to be sent. OASYS checks each patient's communication preference and sends the specified message via their preferred mechanism. 

Point of Care data entry

Ms. Hippolita is a community healthcare worker who is performing blood pressure measurements in a village. She has just checked the blood pressure of Mr. Atenolol (ID 555-5), which was 134/88 with a heart rate of 76. Ms. Hippolita sends an SMS message to Rainbow Clinic specifying the patient and the blood pressure measurement. OASYS receives the message and identifies the mobile device number as Ms. Hippolita. OASYS then creates a new encounter for Mr. Atenolol as a point of care visit. To that encounter, OASYS adds the observations and values corresponding to the blood pressure of 134/88. Ms. Hippolita's information is entered as the clinician for the encounter, and the current date and time are attached to the encounter as well.

Example of User Interface

Ms. Hippolita replies: 'bp 134d88p76 # id 5555'

SMS Message to Ms. Hippolita: Mr. Atenolol's BP is recorded as 134/88, HR is recorded as 76. Reply 'void obs 76ef2' if this is incorrect.

Ms. Shes is a community psychiatry nurse who is rounding on mentally ill patients at a remote site. She has just visited Mr. Diltiazem (ID 678-9), who is suffering from mild anxiety and moderate depression. Ms. Shes sends an SMS message to Rainbow Clinic specifying the patient and her findings. OASYS receives the message and identifies the mobile device number as Ms. Shes. OASYS then creates a new encounter for Mr. Diltiazem as a point of care visit. To that encounter, OASYS adds the observations and values corresponding to findings of mild anxiety and moderate depression. Ms. Shes' information is entered as the clinician for the encounter, and the current date and time are attached as well. (Example scale for psychiatric observations: scale of 0-5 where 0=symptom free, 1=mild symptoms, 2=moderate, 3=severe, 4=very severe, 5=critical/life threatening)

Example of User Interface

Ms. Shes replies: 'anx1dep2#id6789'

SMS Message to Ms. Shes: Mr. Diltiazem's anxiety is recorded as 'mild', depression is recorded as 'moderate'. Reply 'void obs a42ed' if this is incorrect.

Diabetic Pt Glucose follow-up

Ms. Philotis is a patient of the Rainbow Clinic who has diabetes and is taking insulin. Rainbow Clinic has specified that these patients should be asked about their glucose measurements twice a day. At the scheduled time, the diabetes follow-up module uses OASYS' API to send a message to Ms. Philotis. Ms. Philotis has specified that she wishes to receive messages by SMS, so OASYS uses the SMS messaging service to deliver the message to Ms. Philotis. Ms. Philotis replies with her glucose measurement. OASYS recognizes the incoming message as a glucose measurement. Then OASYS creates a new point-of-care encounter for Ms. Philotis and enters the glucose measurement as an observation of this encounter. 

Example of User Interface

SMS Message to Ms. Philotis: Please don't forget to check your sugar! Reply 'bg XXX' where XXX is your blood glucose measurement.

Ms. Philotis replies: 'bg 97'

SMS Message to Ms. Philotis: Ms. Philotis' glucose is recorded as 97. Reply 'void obs 9fcd3' if this is incorrect. 

Patient self-identification for new healthcare problem investigation

Rainbow Clinic contracts with its local telecommunications provider to distribute short messages regarding healthcare issues or questions. One week, Rainbow clinic sends out a short message regarding the symptoms of tuberculosis. Ms. Annabella is a member of the community who is concerned regarding an exposure to tuberculosis and her risk of having the disease. Ms. Annabella sends a reply to the number indicated in the original message. That message is transmitted to OASYS, which recognizes it as an activation code for a patient survey module designed to interrogate patients regarding their risk of certain diseases. OASYS calls the survey module, which returns the survey to be performed. OASYS then administers the survey and returns the results to the survey module.

Example of User Interface

Broadcast message to community: Did you know that coughing up blood can be a sign of tuberculosis, a severe disease that can be passed from person to person? Tuberculosis can be treated! Reply 'lrn abt TB' to learn more.

Ms. Annabella replies: lrn abt tb

SMS Message to Ms. Annabella: We understand you want to learn more about TB. Are you asking about yourself or someone else? Reply 'tb q1a' for yourself, 'tb q1b' for someone else.

Ms. Annabella replies: tb q1a

SMS Message to Ms. Annabella: Have you noticed that you've been coughing without a reason, losing weight, fever, low energy, night sweats, or body aches? Reply 'tb q2a' if yes, 'tb q2b' if no.

Ms. Annabella replies: tbq2a

SMS Message to Ms. Annabella: You may be at risk for having TB. Would you like us to call you? Reply 'tb q3a' if yes, 'tb q3b' if no.

Ms. Annabella replies: tbq3a

SMS Message to Ms. Annabella: We will call you within 24 hours.

Arden Syntax-based responses

An implementation may require evaluation of a logical statement with delivery of a message to a recipient if the statement evaluates true or false. For example, if a patient has a CD4 count less than 200, send the patient a reminder message to take Septrim. The logic for these reminders is written in Arden syntax and is parsed by the Logic Module (see http://openmrs.org/wiki/Logic_Module). The Logic Module calls OASYS via its API when the Logic Module determines the need for a message to be sent to a recipient. The Logic Module also specifies the message to be sent. OASYS then delivers the message and returns the result to the Logic Module.

Example of User Interface

SMS Message to Mr. Pity: Your last CD4 count was 184. You should take Septrim every day to prevent further illness. If you would like more information, please reply 'chw'.

Medication List Display

Mr. Tis is a community health worker who is working in the field. He meets Mr. Who (ID 212-1), a patient of Rainbow Clinic. Mr. Who would like to know what medications he should be taking and how often he should take them. Mr. Tis sends an SMS message to Rainbow Clinic requesting a summary of Mr. Who's known medications and dosages. OASYS receives the message and calls the Pharmacy Module's API. In the API call to the Pharmacy Module OASYS includes Mr. Who's user_id. The Pharmacy Module then utilizes OASYS' API to return a message to Mr. Tis; in that message the Pharmacy Module specifies Mr. Who's current medication list.

Example of User Interface

Mr. Tis replies: med list #id 2121

SMS Message to Mr. Tis: Med List for Mr. Who as of 12 Dec 09: ASA 81mg qD, carvedilol 12.5mg BID, amlodipine 5mg qD, Atripla 1 tab qD archive:end

Medication Information Retrieval

Mr. Tis continues his field work and is asked a question about the indications and adverse effects of carvedilol. Mr. Tis sends an SMS to Rainbow Clinic requesting a summary of information regarding carvedilol. OASYS receives the message and calls the Pharmacy Module API. The Pharmacy Module identifies the medication and returns a message via the OASYS API to Mr. Tis.

Example of User Interface

Mr. Tis replies: med info carvedilol

SMS Message to Mr. Tis: Carvedilol (ID 3271-6) is a beta-selective anti-adrenergic agent used in the treatment of hypertension. Reply 'med info ind 32716' for information on indications of carvedilol, or 'med info ae 32716' for information on adverse effects of carvedilol.

Constraints 

Security concerns regarding patient information

OASYS will be involved in the transport of some amount of medical information - for example a patient receiving treatment in the AMPATH system suggests they may suffer from HIV infection. Also their involvement (if any) in an electronic food voucher program itself implies a diagnosis of nutritional deficiency. Both of these issues and many others may involve information that is private to the patient. OASYS shall take every effort to protect the privacy and honor the dignity of our patients. This may include security mechanisms such as password protection, verification of an agent's identity against the address from which a message is received, or message encryption. 

Security concerns regarding monetary exchange

The electronic food voucher program and similar programs, by their ability to be exchanged for either electronic currency or Kenyan shillings, become a currency surrogate. As such credits involved in these programs assume a monetary value and may become a target for criminal forces. Attacks on the system might include message interception, message spoofing attacks, theft of vouchers, theft of cellular phones, or password compromise. These programs will need to safeguard against such attacks to the best of its ability. The security mechanisms necessary might resemble those mentioned in section 2.4.1. 

Assumptions and Dependencies

This requirement specification assumes that an installation of OpenMRS has occurred. It is dependent on support for one or more messaging services is available at an installation (i.e. an SMS-capable modem or internet service for SMSLib). It does not strictly require that a module be installed that can take advantage of OASYS, as OASYS will have some inherent functionality (see Section 2.3.4, 2.3.7, and 2.3.10). 

Specific Requirements

Hardware Interfaces 

OASYS shall support use of a GSM modem as an option for SMS message delivery. 

Software Interfaces

OASYS shall offer an API for use by other OpenMRS modules. Via this API, OpenMRS module shall be able to specify a message recipient as well as the message to be delivered. 

OASYS shall incorporate software interfaces for message delivery via email and Twitter. SMS message delivery may also be accomplished by software interface to a service such as Clickatell.  

Communication Interfaces

    Via the software interfaces outlined in 3.1.3, OASYS shall support communications via SMS, email, twitter, and other simple message media. Through these interfaces, end users will be able to use short codes to interact with OpenMRS. 

Functional Requirements

SMS/Email/Twitter message delivery and receipt

Stimulus/Response Sequence

    Stimulus: OASYS is requested to send a message to a recipient (either from an API call or as a response to a previous short code request).

    Stimulus response: If the message request does not include a recipient address and the medium to be used, OASYS looks in its internal table (see 3.2.2) for this information based on the desired recipient's OpenMRS user_id. If none of these information are available, the message is undeliverable and OASYS should report an error. Once the recipient address and medium are obtained, OASYS should call the relevant API to deliver the message. 

    Stimulus: A message is received from a simple messaging medium (such as email, SMS, or twitter)

    Stimulus Response: OASYS should be aware of the date/time and sending address of the message. OASYS should examine the message. The first token of the message should be a recognized short code - if not, an error message should be sent to the sending address. Special characters should be treated per OMHE standards on Reserved Characters (see http://code.google.com/p/omhe/#What_is_OMHE?_-_Nuts_and_Bolts_Technical_Details\:). Once the short code is recognized, OASYS should take action as determined by that short code (see 3.2.1). 

Short code response

    The core function of the OASYS module is to respond to short messages from carried over various media. End users such as patients, community health workers, and clinicians will be prompted to send short codes via simple messaging media. OASYS shall receive these messages as per 3.2.0. OASYS shall then interpret these short codes and carry out the function specified for a short code. These short codes shall have pre-specified default codes, messages, and actions. These default codes may be renamed by the end user and the default messages may be rewritten. End users may also enter an alias for a short code that shall function as the original code as long as that alias does not compromise another short code's uniqueness. 

    (Note: the OMHE standard contains a good deal more short codes than the ones presented below. Short codes should be implemented as end-user need dictates; the entire OMHE standard does not need to be implemented. Those short codes that comprise a "core" set of functionality should be implemented first and are delineated with the term Core below. Those that are first priority to be implemented are delineated first). 

Stimulus/Response Sequence

    Stimulus: app yes

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID intends to attend their next scheduled appointment. The date/time of that observation are the date/time the message was received by OASYS. OASYS sends a confirmation message to the sending address. First.

    Stimulus: app no

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID intends to miss their next scheduled appointment. The date/time of that observation are the date/time the message was received by OASYS. OASYS sends a confirmation message to the sending address. First.

    Stimulus: app maybe

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID is unsure if they will attend their next scheduled appointment. The date/time of that observation are the date/time the message was received by OASYS. OASYS sends a confirmation message to the sending address. First. 

    Stimulus: pin #### (where #### is the correct pin linked to the OpenMRS ID the message is received from or a new pin)

    Stimulus response: OASYS looks up the sending address in an internal table and checks the pin. If it matches the previous pin, OASYS denotes that the user sending the pin message is authenticated and may receive "high security" messages for a prescribed period of time (this time period should be configurable by the module administrator). OASYS sends any "high security" messages pending delivery to the user. If there is no previous pin, OASYS enters #### as the pin and sends a confirmation message to the sending address along with a prompt to send either an 'auth yes' or 'auth no'. 

    Stimulus: pin #### (where #### is an incorrect pin)

    Stimulus response: OASYS looks up the sending address in an internal table and checks the pin. If it does not match the previous pin, OASYS denotes the user has failed authentication. If the number of failed attempts within a prescribed period of time exceeds the maximum designated by the module administrator, OASYS sends a final message to the sending address and locks that sending address out of OASYS until cleared by the module administrator. If the number of failed attempts has not been exceeded, OASYS informs the sending address of an incorrect pin attempt.

    Stimulus: chw

    Stimulus response: OASYS sends a message to an address specified by the module administrator. In that message, OASYS includes the sending address of the 'chw' message, the time/date the message was sent, the name attached to the OpenMRS ID attached to the sending address, and a message stating that the sending address has requested community health worker contact. OASYS sends a confirmation message to the sending address. 

    Stimulus: help (or hp, or Help)

    Stimulus response: OASYS sends a message to the sending address with generic commands for using OASYS. An example would be "Reply 'help med' to get help regarding your medications, 'help app' to get help regarding your upcoming appointments, or 'help lab' to get help regarding your laboratory results." Core.

    Stimulus: help xxx (where xxx is one of a pre-defined set of keywords, also hp or Help)

    Stimulus response: OASYS sends a message to the sending address with commands specific to the use of the system denoted by the keyword. An example for the keyword 'app' might be "Reply 'app yes' if you can make your next appointment, 'app no' if you cannot, 'app maybe' if you are unsure, 'app next' to get your next appointment date, or 'help app more' for more commands." Core.

    Stimulus: app next

    Stimulus response: OASYS sends a message to the sending address with the date/time specified in the most recent 'Next Appointment Date' observation stored in OpenMRS.

    Stimulus: nut send XXXX YY (where XXXX is a nutrition system ID and YY is a number of nutrition credits)

    Stimulus response: OASYS uses the nutrition system API (module not yet implemented) and requests a transfer from the nutrition account attached to the sending address' device to the account specified by XXXX. The amount of the transfer is YY credits. On receiving confirmation from the nutrition system (should be the nutrition module using the OASYS API), OASYS sends confirmation messages to both the sending address and the account specified by XXXX. N.B. the nut codes should be implemented on creation/installation of the nutrition module and should not be part of the OASYS default codes. 

    Stimulus: nut bal

    Stimulus response: OASYS uses the nutrition module API (not yet implemented) to retrieve the current balance of the account attached to the OpenMRS ID of the sending address. OASYS then sends a message to the sending address with the current balance.

    Stimulus: nut exchg XX (where XX is a number of nutrition credits)

    Stimulus response: OASYS uses the nutrition module API (not yet implemented) to request a credit exchange for the account attached to the OpenMRS ID of the sending address. It also passes the sending address to the nutrition module API. OASYS then sends confirmation of the exchange request to the sending address. 

    Stimulus: start (or sta, or begin)

    Stimulus response: OASYS prompts the sending address for an 'id XXXXXX' command (see below).

    Stimulus: id XXXXXX

    Stimulus response: OASYS looks up the name of the OpenMRS ID supplied. In an internal table, OASYS records the OpenMRS ID and sending address and sets a status bit to 'unconfirmed'. It then prompts the sending address with the name identified earlier and asks the sending address to confirm (id yes) or deny (id no) if this is the intended OpenMRS ID. 

    Stimulus: id yes

    Stimulus response: OASYS looks up the OpenMRS ID/sending address in its internal table and sets the verified bit to 'verified'. It then sends a confirmation to the sending address. 

    Stimulus: id no

    Stimulus response: OASYS looks up the OpenMRS ID/sending address in its internal table and voids the entry. It then prompts the sending address for a new 'id XXXXXX' message. 

    Stimulus: auth yes

    Stimulus response: OASYS looks up the OpenMRS ID/sending address in its internal table and sets an authorization bit to 'yes'. It then sends a confirmation message to the sending address.

    Stimulus: auth no

    Stimulus response: OASYS looks up the OpenMRS ID/sending address in its internal table and sets an authorization bit to 'no'. It sends a final confirmation message to the sending address. N.B. OASYS should not use this sending address again unless it receives an 'auth yes'.

    Stimulus: fu XXXXXX (where XXXXXX is an OpenMRS ID)

    Stimulus response: OASYS uses the Outreach module (not yet implemented) and passes the OpenMRS ID. N.B. The outreach module should use the OASYS API to send a response to this message.The fu codes may be added on implementation of the Outreach module, but should not be part of the default codes of OASYS.

    Stimulus: did XXXXX (where XXXXX identifies a prescription order in OpenMRS

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID reports they are compliant with the medication regimen specified by XXXXX. A confirmation message is sent to the patient.

    Stimulus: med XXXXX

    Stimulus response: OASYS uses the medication adherence API (not yet implemented) and passes the prescription identifier. N.B. The medication adherence module should use the OASYS API to send a response to this message. The med codes may be added on implementation of the medication adherence module, but should not be part of the default codes of OASYS. 

    Stimulus: bp XXXdYYYpZZZ #id AAAA

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the OpenMRS ID specified by AAAA. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID has a systolic blood pressure of XXX, a diastolic blood pressure of YYY, and a pulse of ZZZ. The date/time of the observation is the date/time the message received by OASYS. 

    Stimulus: bg XXX

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID intends to miss their next scheduled appointment. The date/time of that observation are the date/time the message was received by OASYS. OASYS sends a confirmation message to the sending address

    Stimulus: lrn abt XXX

    Stimulus response: OASYS launches the patient education module (not yet implemented) and passes the sending address as well as the keyword requested (XXX). N.B. The patient education module should use the OASYS API to send a response to this. This short code may be added on implementation of a patient education module but should not be part of the default short codes of OASYS. 

Associated Functional Requirements

    To accomplish the functional requirements listed above OASYS will need to be able to send and receive messages from short message media (see 3.2.0). It also will need to present an API to other OpenMRS modules (see 3.2.2),  maintain a table of connection information (see 3.2.3), and be able to read and write encounters and observations in OpenMRS (see 3.2.4).

API to OpenMRS Modules

    Many of the workflows involving OASYS begin with messages from other OpenMRS modules that prompt users of OASYS to employ the short codes like the ones listed above. The OpenMRS modules should access OASYS via an API that allows the OpenMRS module to specify the recipient's OpenMRS ID and a message to be delivered. If a response is desired from the recipient, the message should guide the recipient to use of the short codes corresponding to the desired response.

Stimulus/Response Sequence

    Background: Rainbow Clinic has an appointment reminder module. That module is designed to perform a daily scan of its patient base to compile a list of patients with appointments in the near future. The appointment reminder module then uses the OASYS API to send a message to that list of patients, guiding them to use the 'app yes', 'app no', or 'app maybe' codes to respond. In this example, XXXXX is an OpenMRS ID who has an appointment tomorrow.

    Stimulus: Appt Module uses OASYS API, passes "XXXXX" and "Hello. You have an appointment scheduled for Mar 6. Please reply 'app yes' if you will attend, 'app no' if you cannot, or 'app maybe' if you are unsure."

   Stimulus response: OASYS looks up the OpenMRS ID XXXXX and finds the sending address that corresponds to the OpenMRS ID. OASYS then delivers "Hello. You have an appointment scheduled for Mar 6. Please reply 'app yes' if you will attend, 'app no' if you cannot, or 'app maybe' if you are unsure" to that address. If the OpenMRS ID is invalid, there is no corresponding sending address, or the sending address does not wish to receive messages (an 'auth no', see 3.2.1.2), OASYS should report an error.

Associated Functional Requirements

    To accomplish the functional requirement listed above OASYS will need to be able to identify the sending address for an OpenMRS ID (see 3.2.3) and to transmit the message to those addresses (see 3.2.0). 

OASYS Internal Tables or OASYS Related Obs

    Any function that sends a message to an OpenMRS user will require the ability to track the messaging address for that OpenMRS user. In addition, users should have the option of specifying whether or not they wish to receive messages regarding their healthcare at that address (for example, people who share a mobile phone may not want to notify the others sharing the phone of personal health information). This table should follow OpenMRS data model conventions - for example, once data is entered into a table the entry may be voided but never deleted. 

    (Note: There are at least two possibilities for the storage of this information. One is to use user_property (see http://openmrs.org/images/5/59/Openmrs_data_model_1.10.png?format=raw under the 'user' domain). Another way is to create a separate table for storage of this data. An OASYS specific table should include fields for date created, voided, date voided, reason voided, creator, and so on.)

Stimulus/Response Sequence

    Stimulus: OASYS receives a request to link a messaging address to an OpenMRS user_id.

    Stimulus response: OASYS creates an entry linked to that OpenMRS user_id. In that entry it records the messaging address, the medium (i.e. SMS, twitter, email), the date the entry was created, who created the entry). It sets the verification bit to 'unverified' for this new entry. 

    Stimulus: OASYS receives a request to send messages to a messaging address (see 'auth yes', 3.2.1.2).

    Stimulus response: OASYS looks up the entry for that messaging address. It changes the authorization bit to 'authorized'.

    Stimulus: OASYS receives a request to stop sending messages to a messaging address (see 'auth no', 3.2.1.2)

    Stimulus response: OASYS looks up the entry for that messaging address. It changes the authorization bit to 'unauthorized'.

    Stimulus: OASYS receives a request to verify a messaging address (see 'id yes', 3.2.1.2)

    Stimulus response: OASYS looks up the entry for that messaging address. It changes the verified bit to 'verified'.

    Stimulus: OASYS receives a pin #### message.

    Stimulus response: OASYS looks up the entry for that messaging address and checks the pin field. 

        If there is no entry in the pin field, #### is entered as the pin. 

        If there is an entry and #### does not match, OASYS returns an error message to the messaging address. If greater than X failed attempts (specified by the user), that messaging address is locked out for Y time (specified by the user). 

        If #### matches the pin entry, OASYS denotes the messaging address as secure for "high security" messages for Z minutes (specified by the user) and sends any "high security" messages that were in queue to deliver. 

    Stimulus: OASYS recieves a request to send a message to an OpenMRS user_id.

    Stimulus response: OASYS looks up the entry for that OpenMRS user_id. If the verified bit is set to 'verified' and the authorized bit is set to 'authorized', OASYS delivers the message. If either the verification or authorization checks fail, OASYS should report an error. 

Associated Functional Requirements

    To accomplish the functional requirement listed above, OASYS will need to be given the messaging addresses (these can come from direct user input (see 3.1.1) or via a messaging interface (see 'id', 3.2.1.2). OASYS will also need to be able to send and receive messages from simple message media (see 3.2.0). 

OASYS use of OpenMRS 

    To accomplish some of the inquiries that OASYS will field, it will be necessary for OASYS to perform inquiries against the OpenMRS data model.

Stimulus/Response Sequence

    Stimulus: app next (see 3.2.1.2)

    Stimulus response: On receiving this message, OASYS looks in its table (see 3.2.3) to determine the OpenMRS user_id linked to the sending address from which the message is received from. OASYS then looks for the latest encounter in the OpenMRS data model (at AMPATH, this is recorded as the concept RETURN VISIT DATE). OASYS then sends a message to the sending address informing them of the value of the RETURN VISIT DATE entry.

    Stimulus: app yes (or app no, or app maybe; see 3.2.1.2)

    Stimulus response: On receipt of these messages, OASYS looks in its table (see 3.2.3) to determine the OpenMRS user_id linked to the sending address from which the message is received from. OASYS then adds an encounter for that user_id. To that encounter, OASYS adds an observation for whether the patient expects to attend the appointment or not.

    Stimulus: bp XXXdYYYpZZZ #id AAAA

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the OpenMRS ID specified by AAAA. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID has a systolic blood pressure of XXX, a diastolic blood pressure of YYY, and a pulse of ZZZ. The date/time of the observation is the date/time the message received by OASYS. OASYS sends a confirmation to the sending address. 

    Stimulus: bg XXX

    Stimulus response: OASYS adds a new encounter to the record of the OpenMRS ID linked to the sending address. To that encounter, OASYS adds an observation that the person identified by that OpenMRS ID intends to miss their next scheduled appointment. The date/time of that observation are the date/time the message was received by OASYS. OASYS sends a confirmation message to the sending address

Associated Functional Requirements

    To accomplish the functional requirement listed above, OASYS will need to be able to send and receive messages on simple message services (see 3.2.0). OASYS will also need to have an internal table as described in 3.2.3. 

Performance requirements 

    OASYS is designed to be a module installed into an implementation of OpenMRS. Many of these systems are in resource constrained environments, therefore the processing power and memory capabilities of these servers cannot support excessive loads. There are not firm time limits on performance of OASYS, however its performance in an implementation system may require a streamlined approach.