HealthyLifeHRA: Web Application
by
NING XIA
Submitted in partial fulfillment of the requirements
for the degree of Master of Science
Thesis Advisor: Dr. Gultekin Ozsoyoglu
Department of Electrical Engineering and Computer Science
CASE WESTERN RESERVE UNIVERSITY
August, 2014
CASE WESTERN RESERVE UNIVERSITY SCHOOL OF GRADUATE STUDIES
We hereby approve the thesis of
Ning Xia
candidate for the Master of Science
degree*.
committee chair Gultekin Ozsoyoglu, Ph.D.
Andy Podgurski, Ph.D.
Joseph Sudano, Ph.D.
Adam Perzynski, Ph.D.
date of defense June 16th, 2014
*We also certify that written approval has been obtained for any proprietary material contained therein.
2
Acknowledgements
First of all I would like to express my wholehearted gratitude to my advisor, Prof.
Gultekin Ozsoyoglu for his devoted guidance, encouragement and great mentorship throughout my time as a master’s student. I have learned a lot while under his supervision.
I would also like to thank the members of my master’s thesis defense committee:
Prof. Andy Podgurski, Prof. Adam Perzynski, Prof. Joseph Sudano and Prof. Meral
Ozsoyoglu. The time you have invested into reading my thesis and serving on the committee is much appreciated.
I would like to thank the software members of the HRA team Eamon Johnson,
Xiangcao Liu, Umang Banugaria, Tiancheng Wu, Peng Li, Can Tuzla and Pinar
Uskaner, as well as the team from Metro Health, Prof. Adam Perzynski, Prof. Joseph
Sudano, Sandra Andrukat, and Misty Harris, for their help with the development of the HealthyLifeHRA application for which this thesis also contributes to.
Last but not least, I would like to recognize the support that my friends and family have provided me throughout my graduate studies.
This thesis and the HealthyLifeHRA project was supported by an Agency for Health
Research and Quality research grant: AHRQ:1R01HS020919, Joseph Sudano, PhD,
Principal Investigator.
3
Table of Contents
Page
Acknowledgements ...... 3
Table of Contents ...... 4
List of Figures ...... 8
Abstract ...... 10
Chapter 1 Introduction ...... 12
1.1 Background...... 12
1.2 Overview ...... 13
1.3 Contributions ...... 16
1.4 Organization ...... 17
Chapter 2 HealthyLifeHRA Application Requirements and Database Design... 19
2.1 Application Requirements ...... 19
2.2 HealthyLife HRA Application Data Model Design ...... 23
2.2.1 ER Data Model ...... 23
2.2.2 Transforming ER Model to Relational Model ...... 44
Chapter 3 HealthyLifeHRA Application User Interface ...... 56
3.1 Information Pages ...... 60
3.1.1 Home Page ...... 61
3.1.2 About Us Page ...... 62
3.1.3 How It Works Page ...... 63
3.1.4 For Clinicians Page ...... 65
4
3.2 Login/Registration Pages ...... 66
3.2.1 Registration Page ...... 67
3.2.2 Login Page ...... 70
3.2.3 Forgot Password Page ...... 71
3.2.4 Reset Password Page ...... 73
3.3 Questionnaire Pages ...... 73
3.3.1 Getting Started Page ...... 74
3.3.2 Questionnaires ...... 77
3.3.3 HRA Reporting ...... 83
3.4 Administration Interface ...... 88
Chapter 4 HealthyLifeHRA Application Evolution ...... 95
4.1 Introduction ...... 95
4.2 HealthyLifeHRA Version 1 ...... 96
4.3 HealthyLifeHRA Version 2 ...... 98
4.4 HealthyLifeHRA Version 3 ...... 100
Chapter 5 HealthyLifeHRA Web Application Development ...... 102
5.1 HealthyLifeHRA Model-View-Controller--Basics ...... 103
5.2 Back-end Server Implementation ...... 107
5.2.1 Play Model Implementation ...... 107
5.2.2 Risk Computation Engine ...... 113
5.2.3 RESTful Web Service Development ...... 118
5.2.4 HTTPs Based Communication with Play Framework ...... 119
5.2.5 Security and Password Encryption ...... 121
5.3 Front-end Interface Implementation ...... 124
5
5.3.1 HTTP Routing ...... 124
5.3.2 Controllers ...... 125
5.3.3 Template Engine...... 127
5.3.4 Templates ...... 130
5.3.5 Information Pages...... 132
5.3.6 Login/Registration Pages ...... 133
5.3.7 Questionnaire Pages ...... 136
5.3.8 Administration Area ...... 144
Chapter 6 HealthyLifeHRA Stand-Alone Desktop Application Development . 146
6.1 Background...... 146
6.2 Server Implementation ...... 147
6.3 Creating a MySQL Database and a User ...... 154
6.4 User Interface Implementation ...... 156
6.5 Integration ...... 157
Chapter 7 Conclusion and Future Work ...... 162
7.1 Conclusion ...... 162
7.2 Future Work ...... 165
Appendices ...... 167
Appendix A - Facility Type Enum: ...... 167
Appendix B - Organization Type Enum ...... 167
Appendix C - Provider Type Enum ...... 167
Appendix D – Provider Access Level Enum ...... 168
Appendix E – Mortality Table ...... 168
Appendix F – HealthCategory List ...... 188
6
Appendix G – QuestionGroup List ...... 189
Appendix H – Response Type (AnswerPart) ...... 192
Appendix I – Question Skip Pattern ...... 201
Appendix J – Feedback Message Rules ...... 205
Appendix K – Typing Validation Rules ...... 209
Appendix L – MySQL Installation ...... 216
Appendix M – hra_initial.sql ...... 217
Appendix N – Database Creation Commands ...... 277
Bibliography ...... 290
7
List of Figures
Figures Page Figure 2.1 ER Diagram ...... 25 Figure 2.2ER diagram for mortality table entities ...... 42 Figure 2.3 Database Schema ...... 45 Figure 3.1 Home Page Mock-up ...... 57 Figure 3.2 System Flowchart ...... 59 Figure 3.3 Home Page ...... 61 Figure 3.4 About Page ...... 63 Figure 3.5 How It Works Page ...... 64 Figure 3.6 For Clinicians Page ...... 65 Figure 3.7 Registration Page ...... 67 Figure 3.8 Registration Input Errors ...... 68 Figure 3.9 Guest Registration ...... 69 Figure 3.10 Login Page ...... 70 Figure 3.11 Login Page Error ...... 71 Figure 3.12 Forgot Password Page ...... 72 Figure 3.13 Resetting Password Email Sent ...... 72 Figure 3.14 Reset Password Page...... 73 Figure 3.15 Getting Started Page ...... 75 Figure 3.16 Getting Started Page with Invalid Inputs ...... 76 Figure 3.17 Questionnaire Page ...... 77 Figure 3.18 Questionnaire Data Models and Relationship to Display ...... 79 Figure 3.19 Navigable Category List...... 80 Figure 3.20 Multi-part Question ...... 81 Figure 3.21 Question with Required Response ...... 81 Figure 3.22 Feedback Message ...... 82 Figure 3.23 Feedback for Out-of-range Answers ...... 82 Figure 3.24 Questionnaire Summary ...... 83 Figure 3.25 Report Page ...... 84
8
Figure 3.26 User Friendly Instruction ...... 85 Figure 3.27 Recommendations to Patient ...... 86 Figure 3.28 Response Explanations ...... 86 Figure 3.29 Action Plan ...... 88 Figure 3.30 Admin Login Window ...... 89 Figure 3.31 Admin Interface Home...... 89 Figure 3.32 List of Recoreds ...... 90 Figure 3.33 Record Editing ...... 91 Figure 3.34 Evaluating Questionnaires Page ...... 91 Figure 3.35 Compare Results ...... 92 Figure 3.36 Risk Recalculation ...... 93 Figure 4.1Client Risk Engine based HealthyLifeHRA System Architecture ...... 98 Figure 4.2 Server Risk Engine Based HealthyLifeHRA System Architecture ...... 100 Figure 5.1 HTTP Request Path of Play Framework Applications...... 105 Figure 5.2 Sample ER Diagram ...... 111 Figure 5.3 Risk Calculation Steps ...... 115 Figure 6.1 Folder Structure ...... 148 Figure 6.2 Platypus Configuration ...... 157 Figure 6.3 Mac OS App ...... 158 Figure 6.4 Bat to Exe Convert Configuration ...... 160 Figure 6.5 Windows App ...... 161
9
HealthyLifeHRA: Web Application
Abstract
by
NING XIA
A health risk assessment (HRA) system is an important tool for helping people realize what lifestyle changes they should have in order to live a healthier and longer life, and what benefits they can have by doing the right things. In this thesis, we discuss the design and implementation of various components of the web-based version of a health risk assessment system, called the HealthyLifeHRA system, which is being developed by a multi-institutional team of researchers.
The HealthyLifeHRA system allows a user to take a questionnaire, and produces a visualized report with statistics, messages, pictures, and bar charts about the user’s health status, that highlights potential mortality risks of the participant. Questions in the questionnaire include basic demographic information, epidemiologic data, and life-style information. This tool can be used by health care providers to communicate with patients on their health status. And individual users can use it to
10
become aware of their health situation, and, perhaps, take early measures to deal with various higher-level mortality risks in their lifestyles.
The HealthyLifeHRA family consists of a website version, a standalone version, an iPad version and an Android tablet version. Web-based version of the HealthyLifeHRA family takes advantage of various computing and web technologies, and provides multiple HRA client systems for use in primary care clinical settings. The web-based version includes a client-side interface library, a client-side report generation library and a server-side risk computation engine.
11
Chapter 1
Introduction
1.1 Background
Research studies [1] [2] [3] [4] show that lifestyle factors cause over half of the death before age 65. These research studies also help people realize the benefits that they can possibly have by making efforts to reduce lifestyle-related death risks.
In order to reduce such risks, it is essential to understand how lifestyle factors contribute to death risks of a person and how these lifestyle-related factors can be modified or improved to reduce these health risks. The health risk appraisal or assessment (HRA) can be an important tool in evaluating the impact of these lifestyle factors and current health conditions of an individual.
The Centers for Disease Control (CDC) and Prevention / Carter Center Health Risk
Appraisal Update Project, completed in 1987 [5] was a major contribution to the science of HRA. From 1987 to 1991, the Health Risk Appraisal program was distributed in the public domain through the Carter Center HRA program directed by Dr. Edwin B. Hutchins. The Carter Center HRA became the standard from which most current HRAs have been derived. In 1991, Dr. Edwin B. Hutchins established
The Healthier People Network, Inc. (HPN) as a non-profit corporation to continue the work originated at the CDC. HPN updated the HRA in 1997, by adding a version
12
for elderly populations. Over the past two decades, the HPN-HRA has been used by about 5000 health providers. There are also several commercialized HRA systems such as Sharecare [6] and [7] have been developed in recent years.
There is a need for the use of HRA for all groups of people, especially among racial/ethnicity minority groups, the uninsured, the poor, or those with limited health literacy. A HRA tool that can easily provide convenience for the general public becomes an urgent.
1.2 Overview
This thesis describes the design the architecture of a HRA application family called
HealthyLifeHRA, the implementation of a HRA website and the implementation of stand-alone desktop applications. The HRA website, stand-alone desktop applications along with (other team members’ contributions) HealthyLifeiPad and
HealthyLifeAndroid, forms the HealthyLifeHRA application family. Although each specific application in the HRA application family has its own specific variations, all applications share a common design style and common main components. In the rest of the document, we refer to this “common application” as the HRA application.
HealthyLifeHRA family of applications provides individuals (hereafter, called the participant, user, or patient) a questionnaire with a list of questions, and calculates, based on the answers, patients’ risk factors for 44 different causes of death. The
HRA application maintains questionnaire answers and computed risks indefinitely
13
for future trend analysis, and also produces multiple reports with messages, pictures and bar charts over a range of calculated statistics about the patient’s health status, which highlights potential death risks to the patient. The questions in the questionnaire include basic demographic information, epidemiologic data, and lifestyle information. Since the application tracks all questionnaire answers over time, health providers can use this tool to communicate with patients on their current health status as well as their health risk changes, and individual users can use it to stay aware of their health situation in different time periods, and, thus, take early measures to deal with risks in their lifestyles. Health providers may suggest useful actions for the patient to improve their health situation.
The design and implementation of the HRA web application over the last three years has been an evolving process, resulting in three distinct versions. As our understanding grew about the needs of the HRA application and the relevant technology evolved, we have responded by revising our software architecture and rolling out a new version of the application after thoughtful discussions of the evolving requirements and challenges. As an example, we originally designed static questionnaires with a typical non-historical relational database with no provenance information on any attribute values. It became clear that all of these decisions have to be reversed, resulting in new versions. The evolution of the HRA system is discussed in detail in Chapter 4.
Since the questionnaire interface is the core of our HRA system, we thrive to design a very flexible questionnaire representing method during the development process.
14
We started from the original simple template based questionnaire interface. It was very simple, but also not very extensible and not very convenient to change question’s position in a questionnaire. It was hard to customize and generate multiple questionnaires with existing questions. These new requirement prompted us to explore more flexible ways of customizing and presenting questionnaires. The notion of “positionless question” has been introduced to achieve this goal where each question had an identifier within its own health category, and could be placed into any (consistent) position within a questionnaire. This was necessary since each question is relatively independent of most of the other questions, and can be used at different questionnaire positions for generating multiple questionnaires.
We use a historical database for auditing needs, as medical institutions are required to maintain all of their patient data for certain time periods. In addition, we employ full data provenance as, over the time, questionnaire questions may change, risk computation formulas and auxiliary tables may vary, and all these changes are recorded and maintained in the database for consistent trend analysis over patients’ lifetimes.
For traditional paper based questionnaires, patients have to read specific instructions in order to proceed to the questionnaire properly without wasting time on unnecessary questions. These instructions could be misleading or easy to overlook, especially for older people. Therefore there was a need of introducing automatic skip patterns for questions or question groups, according to patients’ information and answers to previous questions. In order to ensure that the system
15
works properly on the patients’ input, it is necessary to validate the input. We have also designed a feedback message library to give some messages to patients based on their questionnaire responses.
We keep patient account safety in mind when design and develop our applications.
Several efforts have been made during our development process. We design and implement security mechanism including: authentication with built in secure module of Play framework, password encryption with salted password hashing algorithm and secure client-server HTTP connection.
We take advantage of web development technologies to create stand-alone desktop application for doctors who want to ask their patients to take HRA questionnaires and manage all their patients’ questionnaire data and information in a relatively closed environment other than the Internet.
1.3 Contributions
Contributions of this master thesis are listed as follows, MetroHealth and Case team members made tremendous contributions to the interface design:
Design and implement the HealthyLifeHRA website application architecture
and interface.
Design and implement the HealthyLifeHRA web application interface, feedback
messages and type validation.
16
Design and implement the database data model and data communication
between the client and the server.
Design and implement the security mechanism for enforcing patient privacy,
account safety and The Health Insurance Portability and Accountability Act of
1996 (HIPAA) [8] compliancy.
Design and implement desktop stand-alone applications.
Collaborate with other team members to develop the risk calculation engine
and report generation engine.
Generate and email PDF version of the report.
1.4 Organization
This thesis is organized into seven chapters. Chapter 2 describes the HealthyLifeHRA application requirements specifications, and the data model design. The data model design part includes the ER data model design and the transformation of the ER model to the relational model. In Chapter 3, we present the design details for four function groups of our HealthyLifeHRA web application, namely, information pages, login/registration pages, questionnaire pages and administration pages. Chapter 4 discusses our HealthyLifeHRA application evolution. In this chapter, we list the issues we have encountered, the new requirements we have had with each version, and the modifications that we have made for each version. Chapter 5 presents the
HealthyLifeHRA web application development details, and discusses the technologies that we use for developing the web application. Chapter 6 describes the
17
HealthyLifeHRA desktop application development. Chapter 7 concludes, and lists the future work.
18
Chapter 2
HealthyLifeHRA Application Requirements and
Database Design
2.1 Application Requirements
The HealthyLifeHRA application shall have the following requirement specifications.
1. For patients, reports are tailored to provide information on the measure of
“risk age”, diet, physical activity levels, preventive services use, and many
other aspects of health improvement or maintenance.
2. HRA shall focus provider’s “attention” on aspects of care that patients would
most benefit from. For example, an HRA that included stages of change items
shall help providers get a sense of where the patients are regarding health
behavior changes that are likely to improve their overall or specific condition
risk, and whether or not to engage in intense educational interventions for
one or more changes, gently prod the patient along to the first or next stage
of change, or to table the discussion until the patient expresses a desire to
change.
3. The application shall have following type of users: patient and user. The user
refers to any user that will be able to access part of admin interface and
19
manage some of the admin functionalities for authorization purpose. The
user can be categorized into provider and software administrator.
4. The application shall allow for, optionally, the registration and login of
patients. This involves password-based authentication. The password shall
be encrypted and the website shall enable HTTPS connection to enforce the
maximum security for the patient’s account.
5. Patients shall take questionnaires, and questionnaires shall be kept in a
historical database. Historical database refers to a database with the
capability to retain in the database all users, questionnaires, and
(questionnaire) responses, risk computation formulas/tables forever.
6. The database shall maintain data pedigree information or have full data
provenance capability. Full Data Provenance refers to the capability to
capture and maintain data provenance/lineage/pedigree for all data—except
display formatting data--in the database. That is, over time, questionnaire
questions may change, risk computation formulas may change, auxiliary
tables used for risk computations may change; and, yet, all of these changes
are recorded and maintained in the database.
7. Patients shall have the ability, if permitted by the doctors, to login and access
patient and questionnaire information (if they are registered users).
8. Users with multiple roles shall login and access patient information as well as
questionnaire information (content, date/time, place, etc.). Each specific role
20
for the user shall access certain part of the administration area if
authenticated via the login process.
9. Users with different roles shall have many different types of search
capabilities involving questionnaires of patients.
10. Doctors shall access questionnaire information per questionnaire and per
specific question responses across multiple questionnaires of the same user.
11. Doctors shall obtain statistical summary information of the questionnaires
for given a user or a set of user names/ids.
12. The system administrator shall be allowed to make modifications or even
delete questionnaire-related records.
13. Questionnaire response options shall be provided in the forms of checkbox,
filling-in or drop-down alternatives, whichever is appropriate.
14. Since the questionnaire has many questions, one single page is not sufficient
to hold all of the questions; thus, we break all the questions into several
health categories and this health category is also used for displaying
questions page by page. There shall be a forward and backward link to allow
the user to browse the previous questions. After the user answers all the
questions before submitting the questionnaire, the pages shall show the
current status for the questionnaire.
21
15. Recent research on similar tools suggests that the visual communication of
risk via outcome wheels, visual roulette wheels and pie charts is superior to
communication of risks using relative risks, probability coefficients or other
descriptive statistics (Cunningham 2008; Hoffman, Wilkes & Day 2006). HRA
results shall be displayed in the forms of visual communication of risk via
outcome wheels, visual roulette wheels and pie charts, or graphs, as elected
by the administrators, doctors, and/or patients.
By following the application requirement specifications, we identify the following database requirement specifications.
1. The HealthyLifeHRA database shall be maintained by users as specified in the
application requirement specification item 3: user, provider and software
administrator.
2. Users shall have the attributes id, name, email and password.
3. Patients shall have attributes: id, name, email, password, date of birth,
gender, address, zip code and phone number.
4. Patient questionnaires shall be maintained in the database, and shall not be
deleted, due to the historical database requirement of the application.
5. The database shall keep “create date” and “dropped from use” provenance
information for all attributes and relations to fulfill the data provenance
requirement.
22
2.2 HealthyLife HRA Application Data Model Design
2.2.1 ER Data Model
We use the ER Data Model [9] to capture the semantic contents of the database. The
ER diagram is shown in Figure 2.1. Notice that this ER diagram does not include the risk computation entities.
Our HealthyLifeHRA database has two design goals:
1. The database shall provide the capability to retain all the historical
information about patients, users, questionnaires, (questionnaire) answers and
risk calculation formulas/tables in the database. Put another words, the
database is a historical database (except for some display-related meta-entity
information), as far as the following temporal changes are concerned.
No “instance” information is ever deleted. As an example, questionnaires,
patients, risk values, etc., never get deleted, but, if they are not in use, they
are marked as “not in use”.
Risk computation formulas are never deleted. Whenever a formula is
changed, old versions are labeled with a time range, specifying when the
formula was in use. This way, any old questionnaire response and its risk
computations can be regenerated and verified, if need be.
23
24
Figure 2.1 ER Diagram
No mortality/variable tables used for risk computations are ever deleted.
Whenever, say, a population mortality table gets revised, the old version
is marked as “not in use”, and labeled with a time range, specifying when
the table was in use, and, then, it is kept in the database.
This capability is needed for auditing purposes.
2. The database shall have the capability to maintain data
provenance/lineage/pedigree for all data—except display formatting data in
the database. Capturing provenance allows for trend analysis studies over
questionnaires with changing questions/risk computation formulas/risk
computation-related tables, etc. That is, over time, questionnaire questions
may change, risk computation formulas may change, auxiliary tables used for
risk computations may change; and, yet, all of these changes are recorded
and maintained in the database. This is referred to as maintaining data
provenance/lineage/pedigree [10] in the data management research
community, and is useful for, say, a trend analysis researcher: with proper
algorithms, the researcher can make use of the data as it changes. To give an
example, let’s say, there have been 40 questionnaires filled by a patient over
40 years, and, during this time, many aspects of HRA have changed such as
questionnaire questions, risk computation formulas, mortality tables, etc.
However, the HRA database provides a researcher the capability to identify
the changes, make the necessary algorithmic adjustments (if needed), and
25
perform trend analysis for the patient using all 40 of the available
questionnaires.
In the sections below, all instance entities (minus some attributes such as patient email address or patient home address) and all risk computation entities are historical and their provenance information is fully kept. In addition, provenance information about mappings between question ids and questionnaires, necessary to trace the provenance of questionnaire and response entities, are also maintained.
2.2.1.1 Entities for Questionnaire Layout
The questionnaire layout portion of the database ER diagram contains a total of 7 entities. These entities define the different parts of the questionnaire
Below are the entity specifications with the key attributes are underlined:
QuestionnaireFrame (QnrF_Id[short], QnrF_ReportType[enum{midlife,20min,full}],
QnrF_CreateDate[datetime], QnrF_DroppedFromUseDate[datetime])
HealthCategory (HC_Id [int], HC_Title [string], HC_Description [string],
HC_CreateDate[datetime], HC_DroppedFromUseDate[datetime]))
QuestionGroup (QG_Id [int] , QG_CreateDate[datetime],
QG_DroppedFromUseDate[datetime]))
26
Question (Ques_Id [int], Ques_Title [string], Ques_Description [string],
Ques_IsRequired [boolean] , Ques_CreateDate[datetime],
Ques_DroppedFromUseDate[datetime]))
AnswerPart (AnsP_Id [int], AnsP_Name [string], AnsP_Title [string], AnsP_Unit
[string], AnsP_Type [enum{radio, text, dropdown}],
AnsP_CreateDate[datetime], AnsP_DroppedFromUseDate[datetime]))
AnswerPartOption (AnsPO_Id [int], AnsPO_Value [string], AnsPO_Label [string])
PreloadValue (PV_Id [int], PV_Gender [enum{male, female}], PV_Value [string],
PV_Type [enum{default, optimum}], PV_CreateDate[datetime],
PV_DroppedFromUseDate[datetime]))
Below are details of what each entity and its attributes will represent:
QuestionnaireFrame defines a specific questionnaire. For example, in the
current state of the HRA, the midlife, older adult 20-minute, and older
adult comprehensive questionnaires would each be their own
QuestionnaireFrame. The QnrF_Id attribute is for unique identification.
The QnrF_ReportType attribute is used to determine what type of report
should be displayed to the user once the questionnaire is submitted. It is
an enum which can take on three values: midlife, 20min, and full. This
entity also contains CreateDate and DroppedFromUseDate attributes
which are used to maintain a historical record of the questionnaire
layouts. The CreateDate is assigned to the current date-time when the
27
entity is created. The DroppedFromUseDate will remain null until the
entity is no longer used at which point the attribute will be give the value
of the date-time when it became no longer relevant. The
DroppedFromUseDate must always be greater than the CreateDate.
HealthCategory defines a category for related questions to be displayed
together. Generally, a HealthCategory will be used to group together all
the required questions for one or more risk factors. The HC_Id is for
unique identification, HC_Title is the title for the category, and
HC_Description is a string that will be used to give the user instructions
for the questions that will be contained within the category. The entity
also contains the CreateDate and DroppedFromUseDate attributes which
serve the same purpose as in the QuestionnaireFrame.
QuestionGroup defines a group of questions that will be displayed
together and will have the same numerical value when the questions are
displayed. Although this entity does not contain any attributes other than
an id, it is important to be able to dynamically assign the question
numbering when questions are presented to the user. The QG_Id is used
for unique identification. The entity also contains the CreateDate and
DroppedFromUseDate attributes which serve the same purpose as in the
QuestionnaireFrame.
Question defines a single question that can be included in questionnaires.
The Ques_Id is used for unique identification, Ques_Title is the main text
that will be displayed at the top of each question, Ques_Description is any
28
further instruction that would be presented to the user, and
Ques_IsRequired is a boolean stating whether a question must be answer
or not before a report can be generated. The entity also contains the
CreateDate and DroppedFromUseDate attributes which serve the same
purpose as in the QuestionnaireFrame.
AnswerPart defines each answer that will be contained within each
question. This allows for containing multiple response values in a single
question, such as having separate response values for the feet and inches
in a question asking for the user’s height. The AnsP_Id is used for unique
identification, AnsP_Title is a string that will be displayed alongside the
input control, and AnsP_Unit is a string stating what the units will be for
the value the user inputs. The AnsP_Name attribute refers to the name of
a variable that will correspond to either a risk variable directly used in
risk calculations or a variable used in intermediate computations. The
AnsP_Type attribute can hold a value of “text,” “dropdown”, or “radio” and
will define the type on input control that is used to obtain a response
from the user. The AnsP_High and AnsP_Low attributes define the
expected range for the response value. Theses two attributes only apply
to the AnswerParts that take in a numerical value in a text box. The entity
also contains the CreateDate and DroppedFromUseDate attributes which
serve the same purpose as in the QuestionnaireFrame.
AnswerPartOption defines the different options a user will have to select
from when a dropdown box or radio buttons are used for an AnswerPart.
29
The AnsPO_Id is used for unique identification, AnsPO_Value is the value
that will be stored in the variable defined by the corresponding
AnswerPart, and AnsPO_Label is the string that will be displayed to the
user when they are making a selection from radio buttons or a drop down
box.
PreloadValue defines either the default or optimal value for an
AnswerPart. A default value is used in the case a user does not provide a
response to a question. An optimal value is used when computing the
risk years and other parts of the report. The PV_Id is used for unique
identification, PV_Gender can either be left blank, or be “male” or “female”
and it defines if the value is specific to a single gender, PV_Value is a string
containing the value itself or a formula that can be evaluated to obtain the
value, and PV_Type which can be either “default” or “optimum” and
defines if the value is a default value or an optimum value. The entity also
contains the CreateDate and DroppedFromUseDate attributes which
serve the same purpose as in the QuestionnaireFrame.
2.2.1.2 Relationships for Questionnaire Layout
The questionnaire layout portion of the ER diagram contains 6 relationships, each of which is listed below with its cardinality in parentheses:
QuestionFrame (N) – HealthCategory (N)
HealthCategory (N) – QuestionGroup (N)
QuestionGroup (N) – Question (N)
30
Question (N) – AnswerPart (N)
AnswerPart (N) – AnswerPartOption (N)
AnswerPart (1) – PreloadValue (N)
Below, each of these relationships is described in more detail:
QuestionFrame – HealthCategory:
o This relationship allows linking multiple HealthCategories to multiple
QuestionnaireFrames. This is needed because generally each
questionnaire will contain multiple health categories and each health
category can belong in multiple questionnaires. The Position attribute
is an integer that marks the local position index of the HealthCategory
within the QuestionFrame. The position index for the first
HealthCategory within the QuestionFrame will have a value of 0 and
each HealthCategory afterwards will increment the position index by
1.
HealthCategory – QuestionGroup
o This relationship allows for a HealthCategory to contain multiple
QuestionGroups and for a QuestionGroup to belong to multiple
HealthCategories. It contains the Position attribute, which serves the
same purpose as the previous relationship. In addition to these
attribute, there is also a Gender attribute that can take a value of “”,
“male”, or “female”. The purpose of this attribute is to specify if a
QuestionGroup should only be displayed for a specific gender or both.
31
QuestionGroup - Question
o This relationship allows for a QuestionGroup to contain multiple
Questions and for a Question to belong to multiple QuestionGroups. It
contains the Position attribute, which serves the same purpose as the
previous relationships.
Question - AnswerPart
o This relationship allows for a Question to contain multiple
AnswerParts and for an AnswerPart to belong to multiple Questions.
It contains the Position attribute, which serves the same purpose as
the previous relationships.
AnswerPart - AnswerPartOption
o This relationship allows for an AnswerPart to contain multiple
AnswerPartOptions and for an AnswerPartOption to belong to
multiple AnswerParts. It contains the Position attribute, which serves
the same purpose as the previous relationships. The relationship
does not include the CreateDate and DroppedFromUseDate attributes
since we are not interested in the historical record of answer ranges.
AnswerPart – PreloadValue
This relationship allows for an AnswerPart to have multiple PreloadValues but each
PreloadValue must belong to a single AnswerPart. The relationship does not include the CreateDate and DroppedFromUseDate attributes since we are not interested in
32
the historical record of answer ranges. The relationship also does not contain the
Position attribute since a position is not relevant to PreloadValue.
2.2.1.3 Entities for Patient Information
The patient information portion of the ER diagram in Figure 2.1 contains a total of 5 entities. These entities are used to define a patient and the responses they provided each time they submitted a questionnaire.
Below are the entity specifications with the key attributes underlined:
Patient (P_Id [int], P_FirstName [string], P_LastName [string],
P_Gender[enum{“male”, “female”}], P_DateOfBirth [date], P_Email [string],
P_Password [string], P_Salt [string], P_PhoneNumber [string], P_Street
[string], P_City [string], P_State [state], P_ZipCode [string])
QuestionnaireInstance (QnrIns_Id [int], QnrIns_Date [date])
Answer (Ans_Id [int], Ans_Value [string])
Risk (Rk_Id [int], Rk_Value [string])
RiskType (RkT_Id [int], RkT_Name [string], RkT_CreateDate [datetime],
RkT_DroppedFromUseDate [datetime])
Below are details of what each entity and its attributes represent:
The Patient entity defines each patient that has taken a questionnaire. The
P_Id attribute is used for unique identification. The P_FirstName,
33
P_LastName, P_Gender, P_DateOfBirth, P_Email, P_Password, P_Salt,
P_PhoneNumber, P_Street, P_City, P_State, and P_ZipCode attributes are all
used to store personal information about the patient
The QuestionnaireInstance entity is used to record each time a patient
submits one of the questionnaires. It contains the QnrIns_Id attribute, which
is used for unique identification. The QnrIns_Date is assigned to the current
date-time when the entity is created.
The Answer entity is used to store the response that a user provides for each
AnswerPart in the corresponding QuestionnaireInstance. It contains the
Ans_Id attribute, which is used for unique identification, and the Ans_Value
attribute which stores the response value.
The Risk entity contains the risk value for a certain RiskType computed for a
specific QuestionnaireInstance. Each Risk entity contains a Rk_Id which is
used for unique identification and a Rk_Value which is used for storing the
computed risk value.
The RiskType entity defines a specific type of risk that can be computed from
the Answer response values. It has a RkT_Id attribute which is used for
unique identification and a RkT_Name attribute which will be used as a lable
to describe the risk type. This entity also contains RkT_CreateDate and
RkT_DroppedFromUseDate attributes which are used to maintain a historical
record of the risk types. The RkT_CreateDate is assigned to the current date-
time when the entity is created. The RkT_DroppedFromUseDate will remain
null until the entity is no longer used at which point the attribute will be
34
given the value of the date-time when it became no longer relevant. The
RkT_DroppedFromUseDate must always be greater than the RkT_CreateDate.
2.2.1.4 Relationships for Patient Information
The patient information portion of the ER diagram contains 6 relationships, each of which is listed below with its cardinality in parentheses:
Patient (1) – QuestionnaireInstance (N)
QuestionnaireInstance (1) – Answer (N)
Answer (N) – AnswerPart (1)
QuestionnaireInstance (1) – Risk (N)
Risk (N) – RiskType (1)
QuestionnaireInstance (N) – QuestionnaireFrame (1)
Below, each of these relationships is described in more detail:
Patient – QuestionnaireInstance
o This relationship links each questionnaire instance to the patient that
submitted the questionnaire. It contains one attribute (Date) which
stores the date when the questionnaire was submitted. This date can
be used along with the provenance information in the questionnaire
layout entities to regenerate the questionnaire instance when it was
originally taken.
QuestionnaireInstance – Answer
35
o This relationship ties each Answer to a specific
QuestionnaireInstance. There are no extra attributes for this
relationship.
Answer – AnswerPart
o This relationship ties each Answer to a specific AnswerPart from the
questionnaire that the patient had taken. This allows us to tie the
Answer provided by the user to the variable that the corresponding
AnswerPart represents.
QuestionnaireInstance – Risk
o This relationship ties each computed Risk to the specific
QuestionnaireFrame that the risk value was computed from. Each
Risk is associated with a since QuestionnaireFrame but each
QuestionnaireFrame can have multiple Risks.
Risk – RiskType
o This relationship defines what RiskType each Risk is associated with.
Each Risk is associated with a single RiskType.
QuestionnaireInstance – QuestionnaireFrame
o This relationship defines which QuestionnaireFrame the
QuestionnaireInstance is an instance of.
36
2.2.1.5 Entities for Provider/Admin Information
The portion of the database ER diagram defining the provider and admin information contains a total of 5 entities. These entities define the system management roles and their facility and organization.
Below are the entity specifications with the key attributes underlined:
User (User_Id [int], User_FirstName [string], User_LastName [string],
User_Email[string], User_Type[enum{Provider, SoftwareAdmin}])
Facility (Fac_Id [int], Fac_Name [string], Fac_Type[enum {see Appendix A}],
Fac_Street [string], Fac_City [string], Fac_State [string], Fac_ZipCode [string])
Organization (Org_Id [int], Org_Name [string], Org_Type [enum{see Appendix B}],
Org_Street [string], Org_City [string], Org_State [string], Org_ZipCode
[string])
Provider (Prvdr_Id [int], Prvdr_Type [enum{see Appendix C}], Prvdr_AccessLevel
[enum{see Appendix D}])
SoftwareAdmin (SA_Id [int])
Below are details of what each entity and its attributes represent:
The User entity defines any user that will be able to log into the admin
interface. The User_Id attribute will be used to uniquely identify a user. A
user can be either a Provider or a Software Administrator and this is defined
37
in the User_Type attribute. The User_FirstName, User_LastName, and
User_Email all define the corresponding information about the user.
The Facility entity defines the facility at which users may work. The Fac_Id
attribute is used for unique identification. The Fac_Type attribute is an emun
that can have one of the values listed in Appendix A and it describes the type
of a facility. The address of the facility is defined by the Fac_Street, Fac_City,
Fac_State, and Fac_ZipCode attributes. The name of facility is defined in the
Fac_Name attribute.
The Organization entity defines the organizations that operate at one or
more Facilities. The Org_Id attribute is used for unique identification. The
Org_Type attribute define the type of organization and can have one of the
values listed in Appendix B. The name of the organization is stored in
Org_Name and the location for the organization is stored in the attributes
Org_Street, Org_City, Org_State, and Org_ZipCode.
The Provider entity defines a type of User that works with Patients and has
some sort of admin access. The Prvdr_Id attribute is used for unique
identification. There are multiple different type of providers and this is
defined by the Prvdr_Type attribute which is an enum that can have one of
the values listed in Appendix C. Providers can also have different levels of
admin access, which is defined by the Prvdr_Type attribute which is an enum
that can have one of the values listed in Appendix D.
38
The SoftwareAdmin entity defines a type of User that will have admin access
to be able to manage the HRA system. The SA_Id attribute is used for unique
identification.
2.2.1.6 Relationships for Provider/Admin Information
The provider/admin information portion of the ER diagram contains 5 relationships, each of which is listed below with its cardinality in parentheses:
User (N) – Facility (N)
Facility (N) – Organization (N)
User (1) – SoftwareAdmin (1)
User (1) – Provider (1)
Provider (N) – Patient (N)
Below, each of these relationships are described in more detail:
User – Facility
o This relationship describes the Facility at which a User works at. A
User can work at multiple Facilities and a Facility can have multiple
Users work at it.
Facility – Organization
o This relationship describes which Facilities an Organization operates
at. A Facility can be used by multiple Organizations and an
Organization can operate at multiple Facilities.
User – SoftwareAdmin
39
o This relationship defines that a SoftwareAdmin is a type of User. All
SoftwareAdmins are Users but not all Users are SoftwareAdmins.
User – Provider
o This relationship defines that a Provider is a type of User. All
Providers are Users but not all Users are Providers.
Provider – Patient
o This relationship defines the Providers that a Patient visits. A Patient
can visit have multiple Providers and a Provider can have multiple
Patients under their care.
2.2.1.7 Risk Calculation Entities
Please note that risk calculations only involve entities, and there are no relationships involving risk computations. There are three types of risk calculation entities: cause entity, mortality table entities and coefficient table entities.
Cause Entity: Currently, there are 44 causes for death. Cause entity is historical, and its provenance information is kept. The entity specification is given below.
Cause (CauseName [varchar: 100 bytes], CauseFormula [varchar: 200 bytes],
Cause_CreatDate[date], Cause_DroppedFromUseDate[date])
Mortality Table Entities: there are 36 mortality tables (for different causes) that are used in risk calculations, listed in Appendix E.
“Current” 5-year mortality table entity and its historical version:
40
mo-5 (age_min[int:4 bytes], age_max[int: 4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], mo-5.CreatDate [Date])
All old mo-5 table entities in all old mo-5 tables are kept in a single historical table, named mo-5-old, with the following specification: mo-5-old (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], mo-5.CreatDate [Date], mo-
5.DroppedFromUseDate [Date])
10-year mortality table entity: mo-10 (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double] , mo-10.CreatDate [Date])
All old mo-10 table entities in all old mo-10 tables are kept in a single historical table, named mo-10-old, with the following specification: mo-10-old (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], mo-10.CreatDate [Date], mo-
10.DroppedFromUseDate [Date])
20-year mortality table entity:
41
mo-20 (age_min[int:4 bytes], age_max[int: 4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], mo-20.CreatDate [Date])
All old mo-20 table entities in all old mo-20 tables are kept in a single historical table, named mo-20-old, with the following specification: mo-20-old (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], mo-20.CreatDate [Date], mo-
20.DroppedFromUseDate [Date])
The specific mortality table to be used in the patient risk computations (from among the 5-, 10-, or 20-year mortality tables) is selected based on the patient’s age as follows. If the age of the patient is in the range [18, 35], [36, 65], or above 65 then the HRA system uses the 20-year, 10-year, or 5-year tables, respectively, to calculate the mortality risk.
Figure 2.2ER diagram for mortality table entities
We also create similar mortality tables for the older adult computations. We have two tables, one for the 20-minute risk computations and one for the comprehensive risk computations.
42
twentyminute_mo (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double] , createDate [date])
All old twentyminute_mo table entities are kept in a single historical table, named twentyminute_mo-old, with the following specification: twentyminute_mo-old (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], createDate [date], droppedFromUseDate [date]) comprehensive_mo (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double] , createDate [date])
All old comprehensive_mo table entities are kept in a single historical table, named comprehensive_mo-old, with the following specification: comprehensive_mo-old (age_min[int:4 bytes], age_max[int:4 bytes], sex[varchar:45 bytes], causename[varchar:200 bytes], value[double], createDate [date], droppedFromUseDate [date])
Metropolitan Insurance Company Weight Table: This table is used in heart attack risk calculation. mw - Metropolitan insurance company weight table entity has the current table mw, and its historical version, namely, mw-old, as specified below.
43
mw (mw_id [short int], sex [varchar : 10 bytes], heighta[int: 4 bytes], height [int: 4 bytes], value [double], mw.CreatDate [Date])
All old mw table entities in all old mw tables are kept in a single historical table, named mw-old, with the following specification: mw-old (mw_id [short int], sex [varchar : 10 bytes], heighta[int: 4 bytes], height [int:
4 bytes], value [double], mw.CreatDate [Date], mw.DroppedFromUseDate [Date])
There are several other entities related to each specific cause risk value calculations.
Please refer Umang’s thesis [25] for detail information.
2.2.2 Transforming ER Model to Relational Model
This section presents the transforming from ER model to the relational model and the database implementation. Figure 2.3 shows the database schema except for all the risk related tables, since each risk related tables are simply transformed from the ER model.
44
Figure 2.3 Database Schema
The following tables directly represent correspondingly named entities of the ER model.
QuestionnaireFrame (id: short, createDate: date, droppedFromUseDate: date, questionnaireType: int, name: string)
Constraint:
Primary Key: id
Not Null: createDate
Foreign Key: none
Reference: none
45
Degree: 5
HealthCategory (id: short, createDate: date, droppedFromUseDate: date, title: string, type: int, description: string)
Constraint:
Primary Key: id
Not Null: createDate, title, type
Foreign Key: none
Reference: none
Degree: 6
QuestionGroup (id: short, createDate: date, droppedFromUseDate: date, description: string)
Constraint:
Primary Key: id
Not Null: createDate
Foreign Key: none
Reference: none
Degree: 4
Question (id: short, createDate: date, droppedFromUseDate: date, isRequired: boolean, title: string, description: string)
Constraint:
Primary Key: id
46
Not Null: createDate, isRequired
Foreign Key: none
Reference: none
Degree: 6
AnswerPart (id: short, createDate: date, droppedFromUseDate: date, name: string, title: string, input: int, unit: string, high: int, low: int)
Constraint:
Primary Key: id
Not Null: createDate
Foreign Key: none
Reference: none
Degree: 9
AnswerPartOption (id: short, label: string, value: string)
Constraint:
Primary Key: id
Not Null: none
Foreign Key: none
Reference: none
Degree: 3
RiskType (id: short, createDate: date, droppedFromUseDate: date, name: string)
Constraint:
47
Primary Key: id
Not Null: createDate, name
Foreign Key: none
Reference: none
Degree: 4
Patient (id: long, firstName: string, lastName: string, dateOfBirth: string, gender: int, race: string, hispanicOrigin: string, email: string, password: string, salt: string, resetKey: string, state: string, city: string, street: string, zipCode: string, phoneNumber: string)
Constraint:
Primary Key: id
Not Null: none
Foreign Key: none
Reference: none
Degree: 16
User (id: long, firstName: string, lastName: string, string, email: string, password: string, salt: string, resetKey: string, userType: int)
Constraint:
Primary Key: id
Not Null: none
Foreign Key: none
Reference: none
48
Degree: 8
Facility (id: short, name: string, facilityType: int, state: string, city: string, street: string)
Constraint:
Primary Key: id
Not Null: name, facilityType
Foreign Key: none
Reference: none
Degree: 7
Organization (id: short, name: string, organizationType: int, state: string, city: string, street: string, zipCode: string)
Constraint:
Primary Key: id
Not Null: name, organizationType
Foreign Key: none
Reference: none
Degree: 7
The following One-To-Many or One-To-One relationships are captured as part of the associated entities on either the Many side (if any) or the One-side. We transform these relationships and entities into tables as follows:
49
PreloadValue (id: short, createDate: date, droppedFromUseDate: date, gender: int, type: string, value: string, answerPart_id: short):
This table captures PreloadValue entity and AnswerPart (1) – PreloadValue (N) relationship.
Constraint:
Primary Key: id
Not Null: createDate, gender, type, value
Foreign Key: answerPart_id
Reference: AnswerPart
Degree: 7
Answer (id: long, value: string, answerPart_id: short, questionnaire_id: long), this table captures Answer entity and AnswerPart (1) – Answer (N) and Questionnaire
(1) – Answer (N) relationships.
Constraint:
Primary Key: id
Not Null: value
Foreign Key: answerPart_id, questionnaire_id
Reference: AnswerPart, Questionnaire
Degree: 4
Risk (id: long, value: string, riskType_id: short, questionnaire_id, long), this table captures Risk entity and RiskType (1) – Risk (N) and Questionnaire (1) – Risk (N) relationships.
50
Constraint:
Primary Key: id
Not Null: value
Foreign Key: riskType_id, questionnaire_id
Reference: RiskType, Questionnaire
Degree: 4
Provider (id: short, providerAccessLevel: int, providerType: int, user_id: long), this table captures Provider entity and User (1) – Provider (1) relationship.
Constraint:
Primary Key: id
Not Null: providerType, providerAccessLevel
Foreign Key: user_id
Reference: User
Degree: 4
SoftwareAdmin (id: short, user_id: long), this table captures SoftwareAdmin entity and User (1) – SoftwareAdmin (1) relationship.
Constraint:
Primary Key: id
Not Null: none
Foreign Key: user_id
Reference: User
Degree: 2
51
The following Many-To-Many relationships are transformed into a new join table and two One-To-Many relationships. These two relationships are captured in this join table. We transform these relationships into tables as follows:
QuestionnaireFrame_HealthCategory (id: short, position: short, category_id: short, frame_id: short):
This table captures QuestionnaireFrame (N) – HealthCategory (N) relationship.
Constraint:
Primary Key: id
Not Null: position
Foreign Key: frame_id, category_id
Reference: QuestionnaireFame, HealthCategory
Degree: 4
HealthCategory_QuestionGroup (id: short, gender: int, position: short, category_id: short, group_id: short):
This table captures HealthCategory (N) – QuestionGroup (N) relationship.
Constraint:
Primary Key: id
Not Null: position
Foreign Key: category_id, group_id
Reference: HealthCategory, QuestionGroup
Degree: 4
52
QuestionGroup_Question (id: short, position: short, question_id: short, group_id: short):
This table captures QuestionGroup (N) – Question (N) relationship.
Constraint:
Primary Key: id
Not Null: position
Foreign Key: group_id, question_id
Reference: QuestionGroup, Question
Degree: 4
Question_AnswerPart (id: short, position: short, question_id: short, answerPart_id: short):
This table captures Question (N) – AnswerPart(N) relationship.
Constraint:
Primary Key: id
Not Null: position
Foreign Key: question_id, answerPart_id
Reference: Question, AnswerPart
Degree: 4
AnswerPart_AnswerPartOption (id: short, position: short, answerPartOption_id: short, answerPart_id: short):
This table captures AnswerPart(N) – AnswerPartOption (N) relationship.
Constraint:
53
Primary Key: id
Not Null: position
Foreign Key: answerPart_id, answerPartOption_id
Reference: AnswerPart, AnswerPartOption
Degree: 4
Patient_Provider (id: short, patient_id: long, provider_id: short):
This table captures Patient (N) – Provider (N) relationship.
Constraint:
Primary Key: id
Not Null: none
Foreign Key: patient_id, provider_id
Reference: Patient, Provider
Degree: 3
User_Facility (id: short, user_id: long, facility_id: short):
This table captures User (N) – Facility (N) relationship.
Constraint:
Primary Key: id
Not Null: none
Foreign Key: user_id, facility_id
Reference: User, Facility
Degree: 3
54
Organization_Facility (id: short, organization_id: short, facility_id: short):
This table captures Organization (N) – Facility (N) relationship.
Constraint:
Primary Key: id
Not Null: none
Foreign Key: organization_id, facility_id
Reference: Organization, Facility
Degree: 3
2.2.2.1 Database Creation commands
For creating tables in our database, we have the detailed database creation commands in Appendix N.
55
Chapter 3
HealthyLifeHRA Application User Interface
The HealthyLifeHRA software architecture is designed for scalability, easily serving many concurrent users at a time: all user interface functionalities are implemented on the client-side. The client-side rendering of survey results is graphically visualized, as much as possible, for effective and user-friendly presentation purposes, without sapping the server-side computational power. The server-side of the application deals with (i) the execution of the website functions, (ii) receiving
JSON document from client-side and execute risk computations, and (iii) storing and returning the results to the client-side as JSON document when needed.
Besides the software architecture, there are another two issues that our
HealthyLifeHRA application development effort has paid attention to: user interface design and the presentation of results. On the user interface side, we have unified the user experience across the applications even though the interface itself and the result presentation look-and-feel may change to a degree from application to application. The interface has been configured to filter out empty-results.
Collapsible/expandable panels have been used when necessary within the interface and during result presentation for users to reduce visual clutter.
56
Figure 3.1 Home Page Mock-up
Wireframing is an important first step for website application design and implementation. It primarily allows you to organize the information hierarchy of your page, making it easier for you to plan the layout according to how you want your user to access the information. Wireframing is important because it allows the
57
designer to concentrate on planning the layout and the interactions of the interface without being distracted by colors, typography. The user interface design of
HealthyLifeHRA web application is based on the mock-up graphical user interface wireframes. Figure 3.1 shows such a wireframe of home page.
In order to organize the whole website’s functionalities, it is necessary for us to follow a clear system flowchart to design and implement interfaces for each such functionality. The web pages of our system can also be categorized into several such functional groups, namely, information pages, login/registration pages, questionnaire pages and report pages. This system flowchart commonly serves as the site map for some websites. Figure 3.2 shows the flowchart of the system.
58
Figure 3.2 System Flowchart
We also provide an administration interface for customizing the questionnaire and evaluating the questionnaire results.
59
3.1 Information Pages
The information pages provide general information concerning every aspect of the system for patients. These pages include: “Home” page, “About Us” page, “How It
Works” page, “For Clinicians” page and “Term of Service” page.
60
3.1.1 Home Page
Figure 3.3 Home Page
The home page for most websites serves as the welcoming page, highlights the most important functionalities and guides the patients to the pages with information that
61
they are interested in. Figure 3.3 shows the home page. The home page of our
HealthyLifeHRA consists of several sections: navigation bar, welcome window, main content and footer. The navigation bar contains several tabs: “Home”, “Get Started”,
“About Us”, “How It Works” and “For Clinicians”. The welcoming window contains a video demonstration and three buttons, namely, “Take Your Personalized HRA”,
“View a Sample HRA” and “See a Sample Report”. By clicking these tabs and buttons, the system will lead patients to corresponding pages. The main content portion of the home page is designed to provide other useful information and the updates of the system.
3.1.2 About Us Page
As shown in Figure 3.2 the system flowchart, the “About Us” tab will take patients to the page where the patients can learn about the team. Figure 3.4 shows the about page.
62
Figure 3.4 About Page
3.1.3 How It Works Page
Buttons “View a Sample HRA” and “See a Sample Report” on the home page provide another access point to the “How It Works” page, which includes the background information about the health risk assessment and several sample questionnaires and sample reports. Therefore patients can have a general idea about the
63
questionnaires that they are about to take and what kind of information or results that they could get by taking the questionnaires.
Figure 3.5 How It Works Page
Figure 3.5 shows the “How It Works” page.
64
3.1.4 For Clinicians Page
The “For Clinicians” page provides a set of information pages organized by the left navigation list. The “For Clinicians” page provides information for clinicians who want to adopt our system for their practices. The clinicians can also get the scientific and technical details behind our system.
Figure 3.6 For Clinicians Page
65
Figure 3.6 shows the partners and participating institution information of the “For
Clinician” page.
3.2 Login/Registration Pages
By clicking the button “Take Your Personalized HRA” or the tab “Get Started”, patients can log into an existing account, create a new account, or continue to the questionnaire as a guest. The registration and login functionality is one of important functionalities of our system. It also serves as the interface for the authentication mechanism of our system.
Authentication is the process of verification that an individual or an entity is who it claims to be. This process helps verify and protect the identity and privacy of the user of the system or website. Authentication is commonly performed by submitting a user name and password, which are private information that the specific user should know herself and herself only. We design our web application with several common website development practices. Email address is used as one of common credentials for the authentication has its own advantages. With the help of email address account, the user can be verified by her clicking of the verification email.
And the email address account name can also be served as a mechanism for resetting the password if the user forgets the password in the future. Password strength control is another important factor for the authentication process. A strong password policy along with password encryption and storage mechanism makes it difficult to crack the password through manual or automated efforts. The login
66
process is also very important for protecting the user account. A practical way to protect against the login interception during login is by using a certificate-based encryption scheme (for example, SSL). We design our system with security in mind to ensure the maximum safety of user’s account.
3.2.1 Registration Page
The registration or signup page allows patients to create a new account or continue to take questionnaires as a guest. Figure 3.7 shows the registration page.
Figure 3.7 Registration Page
The registration or signup page contains several required fields for patients to input: first name, last name, email address and password. When the patients click the “Create Account” button, all the input fields values will be sent to the server. In
67
order to successfully create a new account, patients have to input valid information accordingly. There is a set of rules for the inputs of creating the account. Each Input field is validated either via interface while inputting or via server-side validation process after clicking the “Create Account” button.
Figure 3.8 Registration Input Errors
68
As shown in Figure 3.8, there is a notification message above those input fields if any input value violates the validation rules. Once those validations rules are met, the system can create the account for patient.
The patients can also login with their existing account by clicking the link “Click here go login”. If the patients decide not to signup now, they can still get the chance to take the questionnaire by clicking the link “Skip signup for now and take an HRA as guest.”. After taking the questionnaire as a guest, patients still have the chance to store the questionnaire responses and results from the report page. We will discuss this functionality in detail later. Figure 3.9 shows the register page from the report page.
Figure 3.9 Guest Registration
69
3.2.2 Login Page
Figure 3.10 Login Page
As shown in Figure 3.10, the login page contains fields for the patient’s email and password and a “Login Now” button. By clicking this button, the credential with be verified on the server-side before continuing to the next page. If the credentials are correct, the Getting Started Page will be rendered but if the credentials are incorrect, an alert message will be displayed informing the user that the email/password combination was incorrect or there is no record for the input credentials. Figure 3.11 shows such a login error.
70
Figure 3.11 Login Page Error
3.2.3 Forgot Password Page
If the patients happen to forget their password, we provide a functionality of resetting the password. From the login page, patients can click the link “Forgot your password? Reset here.” to reset the password by providing registered email address. Figure 3.12 shows the forgot password page.
71
Figure 3.12 Forgot Password Page
Figure 3.13 shows the message after clicking the “Reset” button on the forgot password page.
Figure 3.13 Resetting Password Email Sent
72
The server will generate a temporary link for resetting the password and send this link to the provided email address.
3.2.4 Reset Password Page
Once patients click the link in the password resetting email, the browser will open the page for resetting the password. Figure 3.14 shows the password-resetting page.
Figure 3.14 Reset Password Page
3.3 Questionnaire Pages
Since the HealthyLifeHRA web application currently has three different types of questionnaires, the Adult, the 20-Minute Older Adult and the Comprehensive Older
Adult, it is necessary to gather some basic information from the patients that can be retained on their accounts. This basic information is also used for providing
73
recommendations of selecting different questionnaires and rendering corresponding questionnaire from the server side. Once patients select a specific questionnaire configuration the system will take them to the questionnaire page of their choice. After answering the questionnaire questions and submitting the questionnaire, a report will be displayed according to the questionnaire type that chosen by patients.
3.3.1 Getting Started Page
As mentioned previously, this page provides several input fields for gathering basic information on the left hand side and displays a text box on the right hand side that describes each questionnaire and who should take it. To further aid the user in selecting the correct questionnaire, a recommendation will also be provided in the text box based on the user’s date of birth when patients finish typing their date of birth. Users under the age of 65 are recommended to take the Adult HRA, whereas users with age 65 and older are recommended the 20-Minute Older Adult HRA.
Figure 3.15 shows the getting started page with recommendation.
74
Figure 3.15 Getting Started Page
Once the user has filled out the form, the user select one of three buttons at the bottom of the scene, with each taking the user to one of the three questionnaires.
When a button is clicked, a form validation will take place to ensure that all required fields are provided responses and all inputs are valid on the server side. The required fields for the form are first name, last name, gender, date of birth, race, if the patient is Hispanic, and zip code. The phone number, email, and zip code are also validated to ensure that a valid input was provided. If any of these fields fail the validation, an alert message describing the error is displayed and the corresponding labels for the invalid field are highlighted red labels to attract the patient’s attention.
Figure 3.16 shows the invalid input with highlighted labels.
75
Figure 3.16 Getting Started Page with Invalid Inputs
If all fields pass the validation, the patient is taken to the selected questionnaire page.
76
3.3.2 Questionnaires
Figure 3.17 Questionnaire Page
In order to organize and display the questionnaire questions properly we take the interface representation into consideration when design our data model. Figure
3.17 shows the questionnaire page. The questionnaire questions are related to the
77
age and sex of the patient. Some questions are suitable for patients with certain age range, while other questions are suitable for all age ranges. We also want to provide the flexibility that the healthcare provider can configure the questionnaire with existing questions. We define QuestionnaireFrame to represent these specific questionnaire configurations: adult questionnaire, older adult 20-minute questionnaire, and older adult comprehensive questionnaires.
Each such specific questionnaire consist of several questionnaire sections or categories, we divide all the questionnaire questions into such sections according to the sex of the patient, age range and question type. We define HealthCategory to represent each such section. For example, “Blood Pressure” represents a category of questions related to the blood pressure: take blood pressure medicine, blood pressure, estimated blood pressure, etc. Appendix F lists all health categories.
Some questions are highly related to each other or belong to the same conceptual question family. We define QuestionGroup to represent such question family. Each
QuestionGroup consists of several Questions. For example, “Blood Pressure
Medication”, “Blood Pressure” and “Estimate Blood Pressure” belong to the same
QuestionGroup. Appendix G lists all question groups.
The response format of questionnaire questions can be very flexible. For some questions, patient can choose an option from multiple options, while other questions require the patient to input multiple parts. For example, question
“Describe your body frame size” requires the patient to choose an option from
78
“Small”, “Medium” and “Large”. Questions like “Height” include two parts “feet” and
“inches” value. We define AnswerPart to represent this response data abstraction, and AnswerPartOption to be the options for each such AnswerPart. Appendix H lists all response names and their type. Please also refer [11] for complete question information.
Since the responses to AnswerPart are important for the risk value calculation and report generation, we capture each such response corresponding to AnswerPart. We design this data model abstraction to facilitate the questionnaire representation and data capture. Figure 3.18 shows the data model of the questionnaire.
Figure 3.18 Questionnaire Data Models and Relationship to Display
79
The questionnaire shall also be user friendly, interactive, concise and functional.
From the data model abstraction design intuition, we derive the questionnaire to be with the following functionalities for various platforms:
Display the ordered list of questions to the patient, one category a time. The
designer of the questionnaire shall define the categories for a specific patient.
The questionnaire page shall have functionalities to allow the patient to
continue the questionnaire, and navigate back to previous questions that
have been answered. To this end, the questionnaire shall have a “Go back”
button and a “Continue” button. In addition, it shall have a navigation menu,
which allows the patient to return to previous completed sections. Figure
3.19 shows an example of the navigable health category list.
Figure 3.19 Navigable Category List
Questions may have multi-part answers. Figure 3.20 shows an example of the
multi-part question.
80
Figure 3.20 Multi-part Question
Answers are given by interaction with a drop-down list, radio buttons, or a
text box.
A response to a question may be required in order to continue with the
questionnaire. Figure 3.21 shows a question requires a response.
Figure 3.21 Question with Required Response
The display of some questions may depend on answers to prior questions
(e.g., sex, smoking)
The questionnaire presents a summary of responses before continuing to the
calculation portion.
The questionnaire presents a summary of responses before continuing to the
calculation portion.
The questionnaire presents feedback for out-of-range answers and feedback
based on answers. Figure 3.22 shows a feedback based on specific answers.
Figure 3.23 shows the feedback for out-of-range answers.
81
Figure 3.22 Feedback Message
Figure 3.23 Feedback for Out-of-range Answers
The patient is able to view a summary of their questionnaire responses before proceeding to the report. When viewing the summary, the patient can revisit one of the health categories to correct their response by clicking one of the questions on the summary page. This will load the health category that contains the selected question and the may modify their response. Figure 3.24 shows the summary page.
82
Figure 3.24 Questionnaire Summary
3.3.3 HRA Reporting
The presentation of the HRA report is designed to be with the following characteristics: user friendly, informative, functional and interactive. Figure 3.25 shows a part of the report page.
83
Figure 3.25 Report Page
In addition to the report itself, patients are also able to create a PDF version of their report for printing and email the report by entering an email address in a text field at the top of the page by clicking corresponding buttons. We use a JavaScript library to generate the Data URL string [44] and send it back to the server for generating the email attachment. The server will send the PDF report to the provided email address upon receiving the Data URL string. We will discuss this in detail later.
84
We design the report to be user friendly that we want to provide the patient with intuitive and easy understanding pictures, charts and cartoons, etc. Figure 3.26 shows a user-friendly instruction.
Figure 3.26 User Friendly Instruction
We also want to design the report representation to be very informative and functional enough to provide actually useful information for the patient. The patients could get very useful recommendations or explanations of their responses.
Figure 3.27 shows recommendations according to the patient’s response.
85
Figure 3.27 Recommendations to Patient
Figure 3.28 shows several explanations to the responses.
Figure 3.28 Response Explanations
One of the major purposes of the report is to inform the user how they can live a healthier life. This is in part accomplished with the Action plan shown in Figure
86
3.29. The Action Plan gives the patient a list of actions that they can take to improve and maintain their health. This part of the report is intractable so the user can actually select the actions they plan on taking and provide a date for when they hope to improve their health by.
The Action Plan contains three sections of selectable actions. The first section contains selectable actions based on the user’s stage of change responses for smoking, exercise, alcohol usage, and nutrition. Along with each of these selectable actions is a message displaying the user’s response to the stage of change questions.
The second section contains more selectable actions based on the remainder of the questionnaire responses. The third section displays specific actions that the user can take and the displayed actions in this section are dependent on the actions selected in the first two sections.
87
Figure 3.29 Action Plan
3.4 Administration Interface
The administration area of our web application has several functionalities. It allow administrator with different privileges to view and manage parts of the admin area.
Since we are still working on the admin interface to provide more functionality for
88
the admins, the flowing discussion is based on our previous version. Figure 3.30 shows the admin login page.
Figure 3.30 Admin Login Window
Once logged in, the admins should see different portion of the admin interface according to their privileges. Figure 3.31 shows the home of admin interface.
Figure 3.31 Admin Interface Home
Admins can view each entity’s detail information by clicking corresponding purple buttons. This is a simple way of viewing and managing the database data. Figure
3.32 shows the detail information of a list of records in our database.
89
Figure 3.32 List of Recoreds
By clicking a record, the admin can enter the interface for editing the record. Figure
3.33 shows the record-editing page.
90
Figure 3.33 Record Editing
By clicking the “Evaluating Questionnaires” button, admin can enter the page for evaluating questionnaires. Figure 3.34 shows the page.
Figure 3.34 Evaluating Questionnaires Page
91
There are two functionalities on this page. The admin could select questionnaires from these two dropdown lists. One will show the comparison results against the test data (Figure 3.35), and the other will recalculate the risk values according to the existing questionnaire responses (Figure 3.36).
Figure 3.35 Compare Results
92
Figure 3.36 Risk Recalculation
Another important feature of the administration area is to allow administrators to customize or modify questionnaires according to their needs. As shown in Figure
3.18, we have already demonstrated the relationship between the entities and questionnaire representation. We can add an instance of an entity in the admin area
93
by adding a record in the admin area. This record will be persisted into our database automatically. In the following of this thesis we refer this automatic process for adding database record as adding an instance of an entity. We show the following process of adding a questionnaire from scratch in the admin area. We first add a
QuestionnaireFrame entity instance, which defines the specific questionnaire to be added and several HealthCategory entity instances according to the requirement.
Then we add instances of QuestionnaireFrameHealthCategory, which will link the newly added QuestionnaireFrame entity to each of the HealthCategory instances.
We follow the same way to add the rest parts of the questionnaire. Once we finish all the entries, we have the whole questionnaire.
94
Chapter 4
HealthyLifeHRA Application Evolution
4.1 Introduction
We originally designed static questionnaires with a typical non-historical relational database with no provenance information on any attribute values, as well as a thick client within a client-server software architecture. It became clear during our development that these decisions had to be changed as our expectations from the application have evolved and changed over time. We decided to have many different questionnaires, e.g., adult, older adult questionnaires as well as shorter questionnaires for patients with limited time to take a questionnaire. Later, we realized that doctors might personalize questionnaires of different patients based on their patients’ history of lifestyles. We also realized that questionnaires had to have very flexible layouts, leading way to “positionless questions” in questionnaires, etc.
We were also not helped by browser companies’ recent decisions to request an acknowledgement from clients each time an applet execution is called for. And, we encountered many issues such as browser limitations such as Apple operating systems switching to 64-bit Java runtime, and, yet, Google providing only a 32-bit
Google Chrome browser, or unresolved browser bugs such as string passing errors
95
between client JavaScript and Java applets for Safari browsers. These issues forced us to change our designs and our software architecture. To summarize, each system design evolution has been driven by many issues, leading to multiple redesigns of our HRA application family. Below we briefly discuss some of these design issues and our actions as a response.
4.2 HealthyLifeHRA Version 1
Our first HRA web application had client-server architecture with a thick client, where the risk calculation engine, written in JavaScript, resided at the client. This resulted in a very server-side scalable design with only a couple of client-server communications per questionnaire.
With the huge computing power improvements for personal computing devices, we believed that the client side devices, such as personal computers (specifically browsers), smart phones and tablets could easily handle the computational requirements of risk calculations. So, we took advantage of the client side computability by implementing the risk calculation engine at the client side in
JavaScript. JavaScript is a dynamic programming language. It can interact with users via client side browsers, and also perform as a general purpose programming language. With all these consideration, we designed and implemented the client side risk calculation engine and the interface interaction library with a JavaScript library called jQuery. Since we used JavaScript to calculate risks at the client side browser,
96
we change the data communication format from XML to JSON (JavaScript Object
Notation).
Below we list the salient features of version1.
Client-server architecture: o Thick client that has the rick computation engine. o Client written fully in JavaScript. o First, XML-based then Jason-based data exchange between server and client. Questionnaires: o Static questionnaire layouts. o Full skip pattern implementations in queries o Limited data validation constraints for questionnaire answers.
Risk engine: o Risk formulas in the database o Manual risk computation correctness testing. o Gender and age-specific mortality tables used in risk computation.
Relational database: o Non-historical database o No data provenance maintenance Report generation: o Report generation with hard-coded “rules”. o No e-mailing capability.
97
Figure 4.1Client Risk Engine based HealthyLifeHRA System Architecture
Figure 4.1 shows our design of HealthyLifeHRA system architecture in a client-centric way that we can fully take advantage of the client side computability to alleviate the server load. The questionnaire responses are captured by the client-side JavaScript library to generate JSON document, and used as inputs for the client-side JavaScript risk engine. The JSON format responses and the JSON format risk values are sent back to the server for storage after the client-side calculation.
4.3 HealthyLifeHRA Version 2
We encountered performance issue with the JavaScript client-side risk engine when executing the risk calculations for the report generation. We re-implement the
98
client-side risk computation engine into a Java applet, since the Java performance is better than JavaScript.
Below we list the salient features of version 2.
Client-server architecture: o Still a thick client, but with a Java applet containing the risk engine on the client-side. Risk engine redesign, reimplementation in Java and C++, and testing: o Risk formulas obtained from the database, and, parsed per risk computation. o One risk computation function per risk type via a decision tree approach. o Risk engine testing: C++ risk engine and JavaScript risk engine testing systems. o Race-, gender, and age-specific mortality tables for risk computation. Questionnaires: o Three types of questionnaire types o Positionless questions o Flexible questionnaire layouts Database redesign: o Historical database o Full data provenance maintenance Integration of web, iPad and android apps: o questionnaire layouts, o account login/creation, o basic information update, o saving responses, and o e-mailing pdf versions of reports.
99
4.4 HealthyLifeHRA Version 3
With our development of mobile platforms, we wanted to design our software architecture a such way that the web server changes or customizations can easily propagated to mobile applications with minimum code changes at the mobile application level.
Figure 4.2 Server Risk Engine Based HealthyLifeHRA System Architecture
We also enforced the security of patients’ account, personal information and questionnaire data across all platforms. All patient data are sent back to the server via secure connection and stored in our encrypted database server. It was also necessary for our system to provide functionalities to support mobile platform communication with the server. We added to the architecture new web service functionalities so that each application in the HealthyLifeHRA application family, as
100
well as any other future third-party applications, can access the HRA database easily and safely. Also, we had to re-implement the risk engine in C++ for the iPad app, and in Java for the Android app and the website. Figure 4.2 shows the server-centric system architecture.
Below we list the salient features of the third and the current version.
Client-server architecture:
o Very thick server, all questionnaire risk computations and report
related risk computations on the server-side.
o Server provides web service for mobile apps’ access.
o Add guest session and allow guest to signup after finishing sample
questionnaire.
Risk Engine:
o C++ risk engine for iOS apps and Java risk engine for Android apps
and website.
Report Generation:
o All report generation rules are stored in the database.
101
Chapter 5
HealthyLifeHRA Web Application Development
The HRA website development takes advantage of two open-source modern web technologies namely, the Play Framework [12] and jQuery [13]. The Play
Framework is a popular Java based modern web development frameworks. The jQuery is a popular feature-rich cross-platform JavaScript library, which is designed to simplify the client-side scripting of HTML and provides simple event handling, animation, Ajax [14], with an API that works across many browsers. The website version of HRA application family uses the Play Framework to organize the data model and database access, and to provide the back-end support for the whole website. The Play Framework also provides a template engine, which enables the front-end programmer to manipulate the objects in a similar fashion as the back- end object manipulation. The HRA application includes a client side interface
JavaScript/jQuery library and a visualization library for HRA report generation and rendering. The client side interface engine manages the interactions between the patient and the system, which provides question navigation, patient input validation and feedback messages without issuing server communications.
The HRA application is designed to provide convenience for the patient to take the questionnaires on multiple platforms. Patients can take questionnaires via an
HTTPS-enabled secure website or on mobile devices with the iOS app and an
102
Android app. The stand-alone desktop version of the HRA application is designed to provide use for doctors to use it in their offices without connecting to the Internet.
The HealthyLifeHRA family is designed and developed to keep the privacy of participants and maintain patient information securely. The website version of
HealthyLifeHRA employs HTTPS protocol communication between the client patient and the server. We also enforce a secure authenticated login process by employing the Play Framework secure module and salt-hashed password encryption [15] on the server side.
5.1 HealthyLifeHRA Model-View-Controller--Basics
Model-View-Controller (MVC) is a software architectural pattern for user interface implementation. It has been widely adopted as a design pattern for web application development nowadays. Next we summarize the basics of the Play framework for our further discussion of implementation. Play framework provides so many features with respect to each M-V-C development components [30]. For our
HealthyLifeHRA we use most of major features to develop each component. We will discuss implementation details in the following sections.
The Play framework is a simple Java MVC framework without requiring complex configuration and setup. It focuses on developer productivity, and targets
RESTful[16] architecture. The Play framework’s goal is to ease web applications development while allowing Java use. A Play application follows the MVC
103
architectural pattern applied to the web architecture. This pattern splits the application into separate layers: the Presentation layer and the Model layer. The
Presentation layer is further split into a View and a Controller layer [17].
The Play framework is fully stateless, and request/response-oriented. All HTTP
Requests follow the same path:
1. The framework receives an HTTP Request.
2. The Router component tries to find the most specific route that able to
accept this request. The corresponding action method is then invoked.
3. The application code is executed.
4. If a complex view needs to be generated, a template file is rendered.
5. The result of the action method (HTTP Response code, Content) is then
written as an HTTP Response.
Figure 5.1 summarizes the HTTP Request path of Play Framework Applications.
104
Figure 5.1 HTTP Request Path of Play Framework Applications
The Model is the domain-specific representation of the information on which the application operates. Domain logic adds ‘meaning’ to raw data (e.g., calculating if today is the user’s birthday, or the totals, taxes, and shipping charges for a shopping cart). Most applications use a persistent storage mechanism such as a database to store data. MVC does not specifically mention the data access layer because it is understood to be underneath, or encapsulated by, the Model.
The model has a central position in a Play application. It is the domain-specific representation of the information on which the application operates. The Play
105
framework use Hibernate [18] (through Java Persistence API (JPA) [19]) to persist
Java objects in database automatically. JPA is a specification without the actual implementation, while the Play framework use Hibernate JPA implementation to fulfill the JPA specifications. The Play framework also provides a set of useful helpers to simplify the management of JPA entities. We call this Play JPA Hibernate implementation Play JPA in the rest of the thesis. In our HealthyLifeHRA web application, we use Play JPA to implement and manage our models. Most of time, we need to save the model object data permanently. The most natural way is to save this data into a database. The Play distribution includes JDBC for MySQL database— which is what we use.
The View renders the model into a form suitable for interactions, typically a user interface. Multiple views can exist for a single model, for different purposes. In a
Web application the view is usually rendered in a ‘web format’ like HTML, XML or
JSON. However there are some cases where the view can be expressed in a binary form, e.g. dynamically rendered chart diagrams.
The Controller responds to events (typically, user actions) and processes them, and may also invoke changes on the model. In a Web application, events are typically
HTTP requests: a Controller listens for HTTP requests, extracts relevant data from the ‘event’, such as query string parameters, request headers…, and applies changes to the underlying model objects.
106
Figure 4.2. HTTP Request via Play Framework Controller
With the Play framework, you can define parameters in the action method signature.
The framework from the corresponding HTTP parameters automatically resolves these parameters. The Play framework provides full, straightforward access to
HTTP and its concepts.
5.2 Back-end Server Implementation
5.2.1 Play Model Implementation
Most modern websites are developed with object oriented programming languages such as Java, C#, Ruby and JavaScript, and, a (usually, relational) database management system (RDBMS) such as MySQL, PostgreSQL and SQLite. For
107
relational DBMSs, this creates an object-relational “impedance mismatch” issue in that data types in a programming language are not set-oriented, and in a database system are set-oriented, and, thus, creating incompatibilities. This issue is exacerbated when the programming language is object-oriented with “rich” objects.
In Java terms, we would like the state of objects to live outside the scope of JVM so that the same state is available later.
Object-Relational Mapping (ORM) technique is a technique that connects the rich object in a programming language specific application to flat tables in a relational database management system. Using the ORM frameworks such as Hibernate, the properties and relationships of the objects in an application can be stored and retrieved more easily, from a database without writing SQL statements directly and with less overall database access code.
The model (the M in MVC) plays an essential role in a Play application. It is the domain-specific representation of the data on which the application operates. The
Play framework uses Hibernate ORM (with Java Persistence API (JPA) specification) to persist Java objects in database automatically. For our web application, we use
MySQL as our persistence database with the MySQL JDBC driver shipped with the
Play distribution.
JPA entity is defined as the persistence domain object. Typically an entity in JPA represents a table in a relational database, and each entity instance corresponds to a row in that table. In Java these entities are defined as Java classes. And a JPA entity maps to a table in the database, therefore the task of converting ER model to Play
108
model can be simplified as defining JPA entity classes, and the Play framework will persist entities to the corresponding tables in database automatically.
JPA defines several types of annotations for the application development [20]. There are three most important types of annotations:
JPA annotations for Classes
JPA annotations for Fields
JPA annotations for Relationships
Play will start the Hibernate entity manager when it finds one or more classes annotated with @javax.persistence.Entity. Since each entity annotated with
@javax.persistence.Entity will be persisted in a table in the database, the table name will be the same with the class name. However, the database table name for this entity can also be modified by adding annotation
@javax.persistence.Table(name = “custom_name”). Play framework provides a set of useful helpers to simplify the management of JPA entities. The play.db.jpa.Model class is the main helper class for JPA. By extending this class, it provides a lot of helper methods to simplify the JPA access. The play.db.jpa.Model class automatically provides an auto-generated Long id field. However, if one does not want use the provided Long id as the primary key of the entity, the JPA class can also extend play.db.jpa.GenericModel class and add annotation to the customized id field:
@Id @GeneratedValue
109
public short id
In Java, it is suggested [21] to make all fields private, and provide accessors and mutators or getter and setter methods to access these fields for the best practice.
This is to promote encapsulation. Play framework takes care of this issue by default under the hood. As matter of fact, there are a lot of fields in the Play application defined as public (e.g. public short id) for easy accessing yet ensuring encapsulation.
Relationships are persistent fields in persistable classes that reference other entity objects. The four relationship modes are represented by the following annotations:
@javax.persistence.ManyToMany
@javax.persistence.ManyToOne
@javax.persistence.OneToMany
@javax.persistence.OneToOne
We show here a concrete example of (a) creating two entities and the relationship of these two entities to illustrate the model development, and (b) mapping the JPA entities and relationships to the corresponding relational tables.
110
Figure 5.2 Sample ER Diagram
As shown in figure 5.2, we have the following two entities:
QuestionnaireFrame (QnrF_Id[short],
QnrF_ReportType[enum{midlife,20min,full}], QnrF_CreateDate[datetime],
QnrF_DroppedFromUseDate[datetime])
HealthCategory (HC_Id [int], HC_Title [string], HC_Description [string],
HC_CreateDate[datetime], HC_DroppedFromUseDate[datetime]))
We also have a many-to-many relationship:
QnrF-Contains-HC
The QuestionnaireFrame entity class:
@Entity public class QuestionnaireFrame extends GenericModel {
@Id @GeneratedValue(strategy=GenerationType.AUTO) private short id;
...
111
@OneToMany(mappedBy = "frame") @OrderBy("position") public List
...
}
As we can see from the implementation code, we first annotate the class with
@Entity to indicate this class is a JPA entity, and the QuestionnaireFrame class extends the play.db.jpa.GenericModel class to customize a short id field.
Similarly we implement the HealthCategory entity class:
@Entity public class HealthCategory extends GenericModel {
@Id @GeneratedValue(strategy=GenerationType.AUTO) private short id;
...
@OneToMany(mappedBy = "category") public List
...
}
For the many-to-many relationship between two entities, there are several ways of implement with Play JPA. However, for our ER model, usually there is a position field for the many-to-many relationships. We could have used @ManyToMany annotation to implement the many-to-many relationship. However, this would cause
JPA persistence issues. The best solution in this case is to create a class that models
112
the join table of these two entities [22]. Therefore, we define a joint entity
QuestionnaireFrameHealthCategory and add @ManyToOne annotations to frame and category. We also add @OneToMany annotations to a list of this entity in
QuestionnaireFrame and a list of this entity in HealthCategory to complete the many-to-many implementation.
@Entity @Table(name = "QuestionnaireFrame_HealthCategory") public class QuestionnaireFrameHealthCategory extends GenericModel {
@Id @GeneratedValue(strategy=GenerationType.AUTO) private short id;
@Required @NotNull @ManyToOne public QuestionnaireFrame frame;
@Required @NotNull @ManyToOne public HealthCategory category;
public short position;
... }
5.2.2 Risk Computation Engine
The HRA risk computation engine is the core functional library of our HRA system.
We have adapted, and modified when necessary, the risk computations specified in
113
the HEALTHIER PEOPLE NETWORK Version 6.0 (HPNV6.0) [23] Health Risk
Appraisal Software Program. This program uses an individual's health-related behaviors and personal characteristics, U.S. mortality statistics, and epidemiologic data to compute that race specific individual's probability of dying in the next 5, or
10, or 20 years from 44 different causes of death, including heart attack, cancers, and injuries. The questionnaire covers such habits as smoking, seat belt use, and exercise. In addition, physiological data such as weight, blood pressure, and cholesterol are requested [23]. In this section we discuss data format design and method design for the risk computation engine. Please find the implementation details and all data tables in corresponding references. The version 3 server-side risk engine is implemented in Java programming language based on our previous client-side JavaScript implementation [24][43]. The Java risk computation engine
[25][26] closely resembles the JavaScript engine follow the same risk computation method. Umang also developed the C++ version for the iOS applications [25].
Our risk computation engine uses the questionnaire responses, mortality statistics and the auxiliary data tables as input for all causes. Intuitively, we could write a function or method for each such cause and pass all necessary parameters into this specific function and calculate the risk value. Since it is necessary to calculate quite amount of cause risk values, while each risk calculation uses different formula and corresponding data tables, it is not convenient to manage the source code if modify or add causes. We want to simplify the risks calculation in a unified manner yet with maximum flexibility for adding more causes. Considering the complexity of the
114
cause formula, the multi-dimensional nature of the data tables and the extensibility of the software library, we design the risk calculation engine in a string evaluation manner. We store the formula of each cause in a string, which consists of constant values, variables and operators and other symbols. The calculation involves three basic steps (Figure 5.3):
Figure 5.3 Risk Calculation Steps
The first part of risk calculation is the precursor transformation. Precursors are a group of life characteristics that create mortality risks for individuals. As examples, sex, age, smoking, alcohol use are precursors. Some of the precursors are
“modifiable precursors” such as smoking or alcohol usage. For a given patient and a given questionnaire question, the question answer value forms a specific precursor value for the patient, e.g., sex value of “female” and age value of “25” for questions with labels “sex” and “age”, respectively.
There are altogether 44 different causes of deaths. The risk computation of each cause (of death) needs “constants” that are obtained from “data tables”, given the
115
precursor values (i.e., question answer values) for the patient. Here, by “precursor transformation”, we refer to the task of locating a certain constant, given the precursor values of a patient from the mortality table for the cause.
Clearly, some of the precursor values (i.e., question answer values) are strings, e.g.,
“female”. And, other question answer values fall within an integer range of certain data table.
Notice that range definitions are not independent of the other columns. For instance, one table could define multiple overlapping age ranges, which are only distinct given the values in the other columns.
Taking all of these to our consideration, we design an efficient JSON format to access specific value for some given string values.
“riskfactorname”: { “data”: [ [ val1, val2, val3 ], [ val4, val5, val6 ], …. ], “mapping”: { “sex”: { “male”: 0, “female”: 1
116
}, “age_min|age_max”: { “1|44”: 0, “45|64”: 1, “65|150”: 2 }, … }, “mapOrder”: [ “sex”, “age_min|age_max”, … ] }
This JSON format is comprised of three attributes:
“data”: stores the values from the tables as a multidimensional array, each of
the table is regarded as a dimension of the array.
“mapping”: maps each column’s real values into an index value of the
corresponding dimension of the multidimensional array.
“mapOrder”: determines the ordering of the objects in the mapping object.
The second step of the risk calculation is the actual risk formula evaluation (risk calculation) for causes. When a cause value is being calculated, it involves the following steps:
Find the corresponding formula for this cause by the cause name.
Parse the formula into four types of symbols:
o Numbers: 0123456789
o Operators: /*-+()
117
o Precursor symbols
o Lookup symbols
For each precursor symbol, find the corresponding value from the
multidimensional array with the string of the precursor symbol.
For each lookup symbol, find the corresponding value from the
multidimensional structured mortality tables.
The third part of risk calculation is the reporting value calculation. Since the reporting of the HRA contains multiple charts and tables, which collectively visualize the results of different statistics for the risk calculations and list messages that vary according to questionnaire answers. Since some of the values for reporting require modification of responses, we cannot use the original responses to calculate the specific reporting values. However, the mechanism for calculating this modified version of risk is the same with the original risk calculation.
5.2.3 RESTful Web Service Development
A web services API for the server is created to allow data to be shared between the web, Android, and iPad clients. This enables each of the clients to create and log into the same set of accounts, store the questionnaire responses in a central location, and email reports. It is very simple to implement this web services API due to the
RESTful nature of Play framework. The API is implemented with several controller methods and a HTTP routes configuration file.
118
We list all API related routes in the routes configuration file:
# Method URL Path Controller Method
GET /api/midlifeLayout API.getMidlifeLayout
GET /api/20minuteLayout API.get20MinuteLayout
GET /api/comprehensiveLayout API.getComprehensiveLayout
POST /api/emailReport Application.mail
POST /api/login API.login
POST /api/updateInfo API.updateInfo
POST /api/saveResponses API.saveResponses
POST /api/createAccount API.createAccount
POST /api/heartBeat API.heartBeat
The values in the first column define the type of HTTP request that the URL accepts.
The second column defines that path that the web service can be accessed at. The last column defines the method in the controller classes that is called when a proper request is made to one of the web services. Please see Banugaria’s thesis for more details [25].
5.2.4 HTTPs Based Communication with Play Framework
The built-in server of Play Framework supports the HTTPS protocol, which can be used in the production application. It provides the support of certificate management, either via classical Java KeyStore or simple “.cert” and “.key” files. To
119
start an HTTPS in the application, just declare the “https.port” configuration property in the “application.conf” configuration file:
http.port=9000
https.port=9443
Play Framework support various kinds of certificates, including: X509 certificates,
Java KeyStore certificates and self-signed certificates with OpenSSL. For our website we purchase a third party SSL certificate to enable the HTTPs secure connection.
It is worth mentioning the following configurations for X509 certificate and Java
KeyStore in case of switching to different certificates in the future. For the X509 certificate, the certificate files have to be placed in the “conf” directory of the application. The X509 certificates must be named as follows:
“host.cert”: the certificate
“host.key” : the key for the certificate
The following parameters for X509 can be configured in “application.conf” file:
certificate.file=conf/host.cert
certificate.key.file=conf/host.key
trustmanager.algorithm=JKS
# Incase the key file is password protected.
120
certificate.password=secret_password
For the Java KeyStore certificates, the following properties can be configured in the
“application.conf” file:
ssl.KeyManagerFactory.algorithm=SunX509
trustmanager.algorithm=JKS
keystore.file=conf/certificate.jks
keystore.password=secret_password
5.2.5 Security and Password Encryption
It is necessary to enforce the security for the user account system. The most important aspect of a user account system is the mechanism for protecting the user passwords. The best way to protect the password is to employ “salted password hashing” [27].
Hash algorithms are one-way functions that turn any amount of data into a fixed- length “fingerprint” that cannot be reversed. They also have the property that if the input changes by a tiny bit, the resulting hash is completely different. But merely run the password through a cryptographic hash function is far more than enough to enforce the password security. There are existing ways of cracking the hashed
121
password, such as: dictionary and brute force attacks, lookup tables, reverse lookup tables and rainbow tables [15].
Lookup tables and rainbow tables only work because each password is hashed the exact same way. If two passwords were the same, and the password hashes would be the same. We can prevent these attacks by randomizing the hash, so that when the passwords with the same string format will have different hashes. We use java.security.SecureRandom class to randomize the hashes by appending or prepending a random string called “salt”, to the password before hashing. There are several well-designed algorithms for enforcing the salted password hashing:
PBKDF2, bcrypt and scrypt.
We implement the PBKDF2[28] salted password hashing algorithm with Java, and store the “salt” and hashed password in our database for validating the login password. We list the following function signatures with explanations of the controller “PasswordHash.java”.
Function signature: public byte[] genSalt(), this method generates a random salt byte array with java.security.SecureRandom class for generating the salted password hashing.
Function signature: private String toHex(byte[] binary), “binary” is a byte array and this method is a private method that can be called within this class for converting a byte array to hexadecimal string.
122
Function signature: private byte[] fromHex(String hex), “hex” is the string with hexadecimal characters, this private method converts the hexadecimal string to a byte array.
Function signature: private byte[] pbkdf2(char[] password, byte[] salt, int iterations, int bytes), “password” is a character array of the original password string, “salt” is a byte array of generated random bytes, “iterations” is the iteration count for the
PBKDF2 algorithm and the “bytes” is the length of the hash to compute in bytes for
PBKDF2.
Function signature: public String createHash(String password, byte[] saltArray),
“password” is the string format of the original password without salted hashing, and the input “saltArray” is the byte array of the salt string. This method generates the salted password hashing.
Function signature: private boolean slowEquals(byte[] a, byte[] b), this method compares two byte arrays “a” and “b” in length-constant time. This comparison method is used so that password hashes cannot be extracted from an on-line system using a timing attack and then attacked off-line.
Function signature: public boolean validatePassword(String password, String correctSalt, String correctHash), “password” is the password string to be regenerated with the “correctSalt” stored in our database, the regenerated salted hash will be compared to the stored “correctHash” in ourdatabase. The method returns the comparison result as a boolean value.
123
5.3 Front-end Interface Implementation
The frontend or the presentation layer implementation of HealthyLifeHRA web application takes advantage of modern web development technologies such as Play framework, Twitter Bootstrap [29] and JavaScript/jQuery/Ajax. In order to explain the interface implementation clearly, next we cover some of the basics of HTTP routing, controller and template engine [30]. After that, we discuss the three major functionalities for the HealthyLifeHRA web application: basic information management and login/registration management, questionnaire interaction and report generating, the administration area management, and the implementation of these three major functionalities in terms of controllers and views. Without loss of generality, we discuss typical controller methods and important controller methods in detail as examples.
5.3.1 HTTP Routing
Play’s router is the component in charge of translating the incoming HTTP requests into action calls (controller methods) and configured by a route file with the content:
# Method URL Path Controller Action
GET /home Application.index
124
This would be translated into get the HTTP GET request for “/home” to be handled by the controller method Application.index. The controller method then renders the actual HTML page as the response to the GET request.
5.3.2 Controllers
Controller is an essential part bridging the model and the view. After routing has determined which controller to use for a request, the controller is responsible for making sense of the request and producing the appropriate output.
A controller in Play framework is a Java class: package controllers; import play.mvc.Controller;
/** * The Application controller class. */ public class Application extends Controller {
/** * Render Index page. */ public static void index() {
render();
}
}
Each public, static method in a Controller class is called an action. The signature of for an action method is: public static void action_name(parameters ...);
125
The “parameters” can be defined in the action method signature. These parameters will be automatically resolved by Play from the corresponding HTTP request parameters. These HTTP request parameters can also be retrieved within the action method with the “params” map: String id = params.get(“id”);
There are many other features provided by the Play framework controller [31], such as:
Retrieve HTTP parameters from URI path, query string and form data. We
use this feature to get HTTP parameters for our web application.
Advanced HTTP to Java binding, JPA object binding and custom binding. We
use JPA object binding to retrieve related object in our web application.
Results type for the response generated by the action method can be plain
text, JSON string, XML string, template execution, URL redirection and
interceptions. We use all of these great features for our web application.
Session and Flash scopes.
Session and Flash scopes are two most frequently used features. Due to the stateless nature of Play session, it handles session differently with respect to the traditional server session saving. It is important to understand that Session and
Flash data are not stored in the server, but are added to each subsequent HTTP
Request, using the Cookie mechanism.
126
5.3.3 Template Engine
The Play framework provides interface supports for the whole web application. Play has an efficient template system, which allows to dynamically generate HTML, XML,
JSON or any text-based formatted document. A tag system allows front-end developers to create reusable functions.
A template is a text file, and some parts of the file are placeholders for dynamically generated contents. The template’s dynamic elements are written using the Groovy.
Groovy’s syntax is very close to Java’s. Usually, these dynamic elements are objects rendered from controller methods. Dynamic elements are resolved during the template execution. Then the result is sent as part of the HTML response.
Expressions: ${…}
The simplest way to make a dynamic element is to declare an expression ${…}. The result of evaluating the expression is inserted in the place of the expression. For example, if we want to display the name of a different patient, we can write:
Patient: ${patient.firstName} ${patient.lastName}
. Each time, the patient object could be different. Therefore this would display different patient’s names.Template decorators: #{extends /} and #{doLayout /}
Decorators provide a solution to share a page layout or design cross several pages.
We create templates with common layout and design elements, then we add:
Main Template
127
#{doLayout /}
#{extends ‘template.html’ /} to the beginning of the partial HTML file, therefore all layout and design elements are inherited from the “template.html”.
Tags: #{tagName /}
A tag is a template fragment that can be called with parameters. These parameters usually are Java objects rendered from controller methods. You can manipulate these objects as you do in the Java codes. For example, if you want to list all the patients, you can use #{list} tag like this:
- ${p.firstName} ${p.lastName}
#{list items:patientList, as ‘p’}
#{/list}
Actions: @{…}
From a template you can generate a URL corresponding to a specific route which associated with a controller method with @{…}. For example
Home will create a URL for the home page: http://localhost/home if we have the route configured with
GET /home Application.index
128
Scripts: %{…}%
A script is a more complicated set of expressions with variable declarations and statement definitions. For example, if you want to display a patient’s name in upper case you can write:
%{
fullName = patient.firstName.toUpperCase() + ‘ ’
patient.lastName.toUpperCase()
}%
${fullName}
Implicit objects available in a template
When a template is rendered from an action, Play adds implicit objects:
Variable Description API documentation errors Validation errors play.data.validation.Validation.errors() flash Flash scope play.mvc.Scope.Flash lang The current language play.i18n.Lang messages The messages map play.i18n.Messages The output stream out java.io.PrintWriter writer params Current parameters play.mvc.Scope.Params play Main framework class play.Play The current HTTP request play.mvc.Http.Request request session Session scope play.mvc.Scope.Session
129
5.3.4 Templates
We design a “main.html” template for pages that provide basic information with
Twitter Bootstrap. Since we want to show navigation bar buttons and footer links for most pages, we implement the “main.html” template as follows:
130
131
...