1.1

1.1.1

1.1.2

1.1.3

1.2

1.2.1

1.2.2

1.2.3

1.3

1.3.1

1.3.2

1.3.3

1.4

1.4.1

1.4.2

1.4.3

1.4.4

1.5

1.5.1

1.5.2

1.5.3

1.5.4

1.5.5

1.6

1.6.1

1.6.2

1.6.3

1.7

1.7.1

1.7.2

1.7.3

1.7.4

1.8

1.8.1

1.8.2

1.9

1.9.1

TableofContentsIntroduction

OpenMRSAroundtheWorld

ABriefHistory

Example:AmaniClinic

Planning

IsOpenMRSforYou?

IdentifyingYourNeeds

TransitioningtoOpenMRS

GettingStarted

InstallationandInitialSetup

OpenMRSInformationModel

GettingAroundtheUserInterface

Configuration

CustomizingOpenMRSwithPlug-inModules

ManagingConceptsandMetadata

SharingConceptsandMetadata

ConfiguringVisits

CollectingData

ThePatientDashboardInDepth

RegisteringPatients

DataEntry

HTMLForms

XForms

UsingData

CohortBuilder

Reporting

PatientAlertsandFlags

AdministeringOpenMRS

UserManagementandAccessControl

Maintenance

Troubleshooting

GettingHelpfromtheOpenMRSCommunity

Epilogue

LeavingAmaniClinic

AboutthisBook

Appendices

AppendixA:Glossary

1

1.9.2

1.9.3

AppendixB:ExampleHTMLFormSource

AppendixC:DocumentHistory

2

Introduction

3

OpenMRSAroundtheWorldOpenMRSclinicalandresearchlocationsasof2016

Thisisyourbook.SimplyscrolltothetopofanypageandclicktheEDITlinktocontributechanges.Wanttocontributemorethansmalledits?Learnmoreabouthowtocontribute.

OpenMRSisanelectronicmedicalrecordsystem(EMR)platform,designedforuseinthedevelopingworldandfirstestablishedin2004.Today,thesystemhasevolvedintoamedicalinformaticsplatformusedonnearlyeverycontinent,supportinghealthcaredeliveryandresearchinanextremelywidevarietyofcontexts.

Ourworldcontinuestoberavagedbypandemicsofepicproportions,asuntoldmillionsofpeopleareinfectedwithdiseasessuchasHIV/AIDS,multi-drugresistanttuberculosis,malaria,andmanyothers.Manyoftheseinfectionsoccurindevelopingcountries,wherelackofeducationandresourcescontributetoscoresofpreventabledeaths.Preventionandtreatmentinterventionsonthisscalerequireefficientinformationmanagement,whichisparticularlycriticalasclinicalcaremustincreasinglybeentrustedtolessskilledproviders.Whetherforlackoftime,lackofmoney,ornoaccesstosoftwaredevelopers,mosthealthcareprogramsindevelopingcountriesmanagetheirinformationwithsimplespreadsheetsorsmall,poorlydesigneddatabases--iftheyhaveanyelectronicinfrastructureatall.Mosthealthcarerecordsinthedevelopingworldarestillmaintainedonpaper.

Asaresponsetothesechallengesindevelopingcountries,OpenMRSwascreatedasamedicalrecordplatform--arisingtidewhichwehopewillliftallships.Itisdesignedtoofferabettertoolforinformationmanagement,butalsotoreduceunnecessary,duplicateefforts.Intheyearssinceitsinception,theOpenMRScommunityhasgrownfromahandfuloforganizationstoamassivecollaborativeeffortbybothgroupsandindividuals,allfocusedoncreatingmedicalrecordsystemsandacorrespondingimplementationnetworkthatallowsself-relianceinsystemdevelopment,eveninresource-constrainedenvironments.

Sinceitsbeginning,OpenMRShasbeenbasedontheprinciplesofopennessandofsharingideas,softwareandstrategiesfordeploymentanduse.Thesystemisdesignedtobeusableinveryresource-poorenvironmentsandcanbemodifiedwiththeadditionofnewdataitems,formsandreportswithouttheneedtowritecomplicatedapplicationcode.Itisintendedasaplatformthatorganizationscanadoptandmodify,avoidingtheneedtodevelopasystemfromscratch.

Andindeed,organizationsaroundtheworldaredoingjustthat.OpenMRSisnowinuseinclinicsinArgentina,Botswana,Cambodia,Congo,Ethiopia,Gabon,Ghana,Haiti,Honduras,India,Indonesia,Kenya,Lesotho,Malawi,Malaysia,Mali,Mozambique,Nepal,Nicaragua,Nigeria,Pakistan,Peru,Philippines,Rwanda,Senegal,SouthAfrica,SriLanka,Tanzania,The

OpenMRSAroundtheWorld

4

Gambia,Uganda,UnitedStates,Zanzibar,Zimbabwe,andmanyotherplaces.Thisworkissupportedbymanyindividualsandorganizations,includinginternationalandgovernmentaidgroups,NGOs,andfor-profitandnon-profitcorporations.

OpenMRSisnotonlyinuseinmanydifferentplaces,butitisalsobeingusedtomeetmanydifferentneeds.InKenya,itisusedtosupporthealthcaredeliveryforhundredsofthousandsofpatientsatanetworkofover50clinics--someconnectedbytypicalnetworks,butmanywheretheconnectionrequiresofflinesynchronizationtoexternalstoragethatcanbephysicallytransportedbetweensites.AnotherNGOusesacentralOpenMRSserverconnectedtoclinicsinmultiplecountriesviasatelliteInternetconnections.InMalawi,creativeindividualswithatalentfortechnologyhavebuiltamobilecartrunningOpenMRSthatphysiciansrollaroundtheirclinic,interactingwiththesystemusingatouchscreen.InRwanda,thenationalministryofhealthhasworkedtorolloutaconnectednationalhealthcaresystemusingOpenMRS.IntheUnitedStates,OpenMRSisusedtotrackpatientsatlargesportingevents,formobileprovidersofhealthcaretohomelesspeople,andasapersonalhealthrecordthatallowscancerpatientstosharetreatmentandhomehealthcareinformationwithcaregiversandfamilymembers.

OpenMRSinuseatTRACPlusClinicinKigali,Rwanda.

Inthelastseveralyears,useofmobiletechnologyhasincreaseddramatically,particularlyinthedevelopingworld.Insomedevelopingcountries,therearemoremobilephonesthanpeople!Facilitatedbyotheropensourceprojects,OpenMRScanbeintegratedwithSMSmessaging,allowingcommunityhealthworkerstoaddinformationaboutadherencetomedicationregimenstoapatient'srecord,astheymakeroundsthroughvillagesinruralAfrica.Elsewhere,mobilephoneapplicationsareusedtoguidethesecommunityvolunteersinhome-basedHIVtestingandcounseling,enrollingprospectivepatientsfromthecomfortoftheirownhomes.

Besidesclinicalcare,theplatformcanalsobeusedinresearchsettings.IntheUnitedStates,OpenMRShasbeenusedbothintrainingmedicalinformaticsstudents,aswellasinconductingvariousresearchprojectsinthefieldsofpublichealth.InPeruOpenMRSisusedastheresearchdatabaseforalargestudyofdrugresistanttuberculosisfundedbytheUSNationalInstitutesofHealth.Becausethesystemhasbeendesignedasanextensibleplatform,itisveryeasyforresearcherstoadaptOpenMRStodowhattheyneed.

OpenMRSAroundtheWorld

5

OpenMRSAroundtheWorld

6

ABriefHistoryOneofOpenMRS'birthplaces–MoiUniversityTeachingandReferralHospitalinEldoret,Kenya(2004)

Throughoutthe1990s,anacademicpartnershipflourishedbetweenIndianaUniversitySchoolofMedicineintheUnitedStatesandMoiUniversityinEldoret,Kenya,providingKenyanmedicalstudentswithaccesstohealthcaretraining.ThisprogramcontinuedtogrowforseveralyearsuntilasevereoutbreakofHIV/AIDSinWesternKenyacausedtheprogramtorethinkitsgoals,atwhichpointtheAcademicModelforPreventionandTreatmentofHIV/AIDS(AMPATH)wascreated.ThenumberofpatientsinKenyacontinuedtogrow,andbasicITsystemsincludingMicrosoftAccesswereusedtomonitorpatientcare.

InFebruary2004,theamountofdatahadbecometoolargeforAMPATH'sexistingsystems,sotheirmedicaldirectorinvitedBurkeMamlin,fromtheRegenstriefInstituteinIndianapolis,UnitedStates,tovisitthesiteandevaluatehowimprovementsinmedicalinformaticstechnologycouldimproveAMPATH'sdatamanagement.Regenstriefhadlongbeenrecognizedasaleaderinmedicalinformaticsresearch,andBurkebroughthiscolleaguePaulBiondichalongwithhimonthevisittoKenya.Itquicklybecameapparentthatanewsystemwasneeded.PaulandBurkebegantodesignthedatamodelforanewmedicalrecordssystemforAMPATH,whichwouldgoontobecomeOpenMRS.

Atthesametime,aBoston-basednon-profitnamedPartnersInHealth(PIH)waspioneeringtheuseofweb-basedEMRsindevelopingcountries.TheyhadbuiltthePIH-EMR,whichtheywereusingtosupportthetreatmentofmulti-drugresistanttuberculosisinPeruandHIVinHaiti.ButHamishFraser,PIH'sdirectoroftheEMRproject,wasworried:PIHwasabouttoexpandintoRwanda,Lesotho,andMalawi,andhefeareditwouldbedifficulttomaintaintheirhome-builtsystemin5countries.

InSeptember2004,PaulandBurkemetHamishattheWorldCongressonMedicalandHealthInformatics(MedInfo)conferenceinSanFrancisco.Itbecameapparentthatthethreesharedsimilargoalsandneeds,sotheyagreedtoworkcollaborativelytodevelopasystemthatwouldbesuitableforthevariousneedsofhumanitarianworkinAfricannationsandbeyond.

ABriefHistory

7

PaulandBurkehireddeveloperBenWolfetobeginworkonprogramminganearlyprototypeofOpenMRS,basedontheirpreviousworkatAMPATHandRegenstrief.Severalmonthslater,PIH'sleaddeveloperDariusJazayerijoinedtheproject,mergingPIH-EMR'sfunctionalityintothenewsystem.TheprevioussystemsatAMPATHfocusedondataentry,whileatPIH,thefocuswasmoreonclinicalworkflow.ThenewsystemcombinedfeaturesofboththeAMPATHandPIHsystems.

BecauseofthestrongcooperationbetweenPIHandRegenstriefandthelongdistancesinvolved,itbecameclearthatanopensourcesoftwaremodelofdevelopmentwasthebestwaytosustainandgrowtheplatform,andtheOpenMRSprojectwasborn.

WhilethecollaborationbetweenRegenstriefandPIHcontinuedandthenewsystemwasbeingdesigned,thegroupswerelookingforadditionalsupportinAfrica.TheyturnedtotheircolleagueChrisSeebregts,fromtheSouthAfricanMedicalResearchCouncil(MRC).Chriswasalreadyheavilyinvolvedinthefieldofmedicalinformaticsthroughoutsub-SaharanAfrica,andbroughtwithhimawealthofknowledgeabouttheneedsofinformaticsimplementations.SeebregtshadbeenadaptingOpenMRSforuseinSouthAfricaandstartedtobuildupacommunityofimplementersofthesoftwarearoundtheworld.HisworkledtomassivegrowthoftheOpenMRScommunity(nownearly2,000strongasoflate2011).InFebruary2006,AMPATHlaunchedOpenMRSinKenya,andPIHbroughtittoRwinkwavu,Rwanda,inAugustofthesameyear.TheSouthAfricanMRCfirstswitchedonthesystematRichmondHospitalinKwaZulu-Natalattheendof2006.

AsboththeOpenMRSapplicationandopensourcecommunitygrew,theygatheredtheattentionofmanyotherlargeprojectsandagencies.Someofthesehaveextendedbothfinancialandconsultingsupportoverthepastseveralyears,including:

TheUnitedStatesCenterforDiseaseControl(CDC)

TheUnitedStatesCenterforDiseaseControl(CDC)

Canada'sInternationalDevelopmentResearchCentre(IDRC)

NationalInstitutesofHealthFogartyInternationalCentre

TheMillenniumVillagesProjectoftheEarthInstitute,ColumbiaUniversity

TheRockefellerFoundation

WorldHealthOrganization

Inanefforttobroadenparticipationintheprojectaroundtheworld,OpenMRSbeganparticipatingintheGoogleSummerofCode(GSoC)programin2007.GSoCprovidesuniversitystudentswhowishtoparticipateinopensourcedevelopmentprojectswithastipendandaclosementoringrelationshipwithanexperiencedprojectteammember.Participationintheprogramhascontinuedsincethen--OpenMRSisnowoneofthelargeropensourceprojectsintheprogram,boastingalargeclassofalumni,anumberofwhomcontinuetocontributetotheproject.Manyofthesealumnicomefromthedevelopingworld,andsomehavegoneontosuccessfulsoftwaredevelopmentcareers.

ABriefHistory

8

TheinauguralOpenMRSImplementersMeetinginCapeTown,SouthAfrica.

OneoftheaimsoftheOpenMRScommunityistohelpbuildlocalcapacityintheplaceswhereitisused.Tothatend,participantsinthecommunityareencouragedtodevelopprogramsandprocessesthatencourageentrepreneurshipandthecreationofpartnershipstogrowthefieldofmedicalinformatics,particularlyinthedevelopingworld.Forexample,inKigali,Rwanda,PartnersInHealthjump-startedalocaltrainingprogramknownasE-HealthSoftwareDevelopmentandImplementation(EHSDI).This9-monthcourseconductedinpartnershipwiththeRwandaDevelopmentBoardandtheKigaliInstituteofScienceandTechnology(KIST)wasdesignedtoteachstudentstodevelopmedicalinformationsystems.ItincludesextensivetraininginusingtheOpenMRSplatform.

ThenumberofindividualandorganizationalvolunteerswhoparticipateintheOpenMRScommunityhascontinuedtogrow,triplinginsizebetween2010and2011.Theseindividualsparticipateinvariousways,fromdocumentationandbugreports,fromtrainingandprovidingsupporttoothercommunitymembers.ThereleaseofOpenMRS1.8wasmadepossiblebytheassistanceofover50contributors.

Further,collaborationswithotheropensourcesoftwareorganizationssuchasOpenDataKitandPentahohaveproducedvolunteercontributionstoOpenMRS,andcommercialconsultingorganizationssuchasThoughtWorksInc.havecontributedmanyhourstodevelopingandimprovingOpenMRS.

Atthecloseof2011,theOpenMRScommunityispreparingtolaunchanindependentnot-for-profitorganizationtohelpsupporttheproject'sneedsasitgrows.Thegoalofthisorganizationwillbetoprovidetechnicalinfrastructureandcommunitymanagement,toassistcollaborationandcooperationofprojectvolunteersthroughouttheworld,andtoprovidetrainingandsupporttothosewhoseektoimplementOpenMRSasakeypartofamedicalinformaticsstrategyinclinics,hospitals,andgovernmenthealthorganizations.

FromitshumblebeginningsasasolutiontoaprobleminasmallAfricantown,OpenMRShasbecomethelargestopensourcehealthcareprojectontheplanet.Between2006and2011,OpenMRSatAMPATHinKenyahasrecordedover111,000,000pointsofdataforover180,000patients,helpingtosavemanythousandsoflives.Everyday,similarstoriesareretoldsomewhereelse

ABriefHistory

9

aroundtheworldwiththeassistanceofthousandsofvolunteers.TheOpenMRScommunitycontinuestogrow,andweareexcitedthatyou'reinterestinginjoiningus.Regardlessofyourbackgroundorinterests,thereisawayforyoutobothcontributeandgainfromtheworkofothersintheOpenMRScommunity.

What'sNewinVersion1.9

ThisversionofOpenMRSincludesanewconcept,Visit.AvisitiscomprisedofatleastoneEncounter.Encounterhasbeenredefinedinthisversionasatransactionbetweenapatientandatleastonehealthcareprovidertoprovideserviceorassessapatient'shealthstatus.

OpenMRSAttributesnowallowsforimplementation-specificcustomizationsofcertaintypesofOpenMRSdata.Inearlierreleases,onlyPersoncouldbecustomized.Now,youcanalsocustomizeProvider,Visit,andLocationdata.

ConceptMappinghasbeenimprovedinthisrelease,nowallowingyoutodefinehowyoursystem'sconceptsrelatetoexternalconceptsandstandards.

ABriefHistory

10

Example:AmaniClinicWeassumeifyou'rereadingthisbookthatyou'reinterestedindeployingOpenMRStosupportclinicalcareintherealworld.Tobridgethedividebetweentheoryandpractice,andtoillustratethesometimeschallengingprocessofdeployingalargehealth-careinformationsystem,wehaveusedtheexampleofthefictionalAmaniClinicasacasestudythroughoutthisbook.

Everytimeyouseethisimageinthebook,youwilllearnhowAmaniClinicusedtheinformationdiscussedtoplanandimplementOpenMRS.

WhileasingleexamplecouldneverpossiblycaptureallthecomplexityofthemanydifferentcontextsinwhichOpenMRSmightbeused,wehopeitwillserveasinspirationtothinkabouthowyourenvironmentmaybesimilarordifferent.Wealsohopethatasyouread,youwillstarttoconsiderthequestionsyouneedtoasktobegintodesignandimplementyourowninstallationofOpenMRS.

AbouttheAmaniClinic

Ourfictionalcasestudy,AmaniClinicinKisiizi,Uganda.

KisiiziisasmalltowninsouthwestUganda,over40kilometersfromthenearestlargecity.MuchofthefameofKisiiziisbasedonitshydroelectricpowergeneratingstationanditsrelativelylargehospital,whichhandlesmostofthehealthcarefortheregion.

Justovertwoyearsago,aEuropean-basedNGOprovidedfundingtohelplaunchanewhealthcarefacilitywe'llcall"AmaniClinic"inthetown.Thisclinicwasopenedspecificallytoaddresstheneedformaternalandchildhealth(MCH)careinKisiiziandthesurroundingareas.

Sinceitsopening,theclinichasbeenverysuccessfulinestablishingitself,andhasattractedafullstaffofdoctors,nurses,andassistants.Newpatients,bothpregnantwomenandnewmothers,arecontinuallybeingregisteredintheclinic,butthereisverylittleinformationavailableabouttheefficacyoftheworkintheclinic,ortheoutcomesforitspatients.Therefore,thefundingagencyhasrequestedthattheclinicworktoimplementaninformationsystem,tohelpbettermonitorandevaluatethehealthcareoutcomesofthepatientsovertime,andtohelptheclinicscaleuptoseemorepatientsmoreefficiently.TheagencyrecommendedthattheclinicconsiderusingOpenMRS,whichhadbeensuccessfullyusedbyotherprojectsfundedbythatagencyinothercountries.

Thefundingmodelprovidedforsomeinformationandcommunicationtechnology(ICT)infrastructuretogettheprojectstarted,aswellasforsomestaffingsupport.However,decidinghowtoallocatethismoneywasleftuptotheclinic'slocalmanagement.Afterreceivingthegrantfunding,thedirectorofthesitehiredClaudine,agraduateofamedicalinformaticstrainingprograminneighboringRwanda,tohelpleadtheeffort.Thisnewly-hiredinformaticsmanager,inturn,hiredDaniel,recentuniversitygraduatefromKampalawithexpertiseinICTinfrastructureandsystemadministration.

Sincetheclinicwasopened,doctorsandnurseshaveusedpaperformstocollectdataabouttheirpatients.Theseformsarestoredinfoldersandkeptinalockedfileroomuntilapatient'sappointment.Whenthepatientsarrive,theyaregiventheirfoldertocarrywiththemastheytalkwiththevarioushealthcareproviderstheywillseeduringtheirvisit.Eachoftheseproviderscompletesthe

Example:AmaniClinic

11

relevantpaperformstoaddinformationaboutthevisit.Theformsareaddedtothepatient'sfolder,whichisreturnedattheendoftheirvisit.

ClinicalstaffwereconcernedwhentheyheardabouttheupcomingdeploymentofOpenMRC,becauseofthepossibilityofchangestothewaytheyareusedtoworking.However,theinformaticsmanagerhasassuredthemthattheycancontinuetousethefamiliarpaperforms.Whenapatientarrivesattheclinic,theywillberegisteredbyapatientregistrationclerk.Afterthepatient'svisitiscomplete,adataentryclerkwillentertheinformationfromthatvisitintoOpenMRS.

ManypeopleinKisiizihavebasicICTskills,andthereisalocalInternetcafe,supportedbyanNGOthatprovidesbasicICTtrainingtolocalresidents.Tworecentstudentshavebeenhiredasthefirstpatientregistrationanddataentryclerksfortheclinic.

Meanwhile,thesystemadministratorhasfinishedhispreparationworkandhasdeployedabasiclocalareanetwork(LAN)toconnectaserverthatwillhosttheOpenMRSapplicationtoPCsinthefileroom,intheclinicmanager'soffice,andintheICTroom.TheLANisconnectedtotheInternet,althoughtheconnectionisn'tveryfastandoftengoesoffline.Theserverispoweredbyanuninterruptiblepowersupply(UPS),thatwillensureitstaysrunningdespiteanyfluctuationsinthelocalpowergrid.

Throughtherestofthisbook,youwillfollowtheprogressofthepeopleattheAmaniClinicastheyinstallOpenMRS,customizeittofittheneedsoftheirclinic,anduseOpenMRSfromdaytoday,firsttoenterdataandthentoextractitforpatientvisitsandforreportingtotheirfundingagencyonanongoingbasis.

Example:AmaniClinic

12

Example:AmaniClinicWeassumeifyou'rereadingthisbookthatyou'reinterestedindeployingOpenMRStosupportclinicalcareintherealworld.Tobridgethedividebetweentheoryandpractice,andtoillustratethesometimeschallengingprocessofdeployingalargehealth-careinformationsystem,wehaveusedtheexampleofthefictionalAmaniClinicasacasestudythroughoutthisbook.

Everytimeyouseethisimageinthebook,youwilllearnhowAmaniClinicusedtheinformationdiscussedtoplanandimplementOpenMRS.

WhileasingleexamplecouldneverpossiblycaptureallthecomplexityofthemanydifferentcontextsinwhichOpenMRSmightbeused,wehopeitwillserveasinspirationtothinkabouthowyourenvironmentmaybesimilarordifferent.Wealsohopethatasyouread,youwillstarttoconsiderthequestionsyouneedtoasktobegintodesignandimplementyourowninstallationofOpenMRS.

AbouttheAmaniClinic

IsOpenMRSforYou?

13

KisiiziisasmalltowninsouthwestUganda,over40kilometersfromthenearestlargecity.MuchofthefameofKisiiziisbasedonitshydroelectricpowergeneratingstationanditsrelativelylargehospital,whichhandlesmostofthehealthcarefortheregion.

Justovertwoyearsago,aEuropean-basedNGOprovidedfundingtohelplaunchanewhealthcarefacilitywe'llcall"AmaniClinic"inthetown.Thisclinicwasopenedspecificallytoaddresstheneedformaternalandchildhealth(MCH)careinKisiiziandthesurroundingareas.

Sinceitsopening,theclinichasbeenverysuccessfulinestablishingitself,andhasattractedafullstaffofdoctors,nurses,andassistants.Newpatients,bothpregnantwomenandnewmothers,arecontinuallybeingregisteredintheclinic,butthereisverylittleinformationavailableabouttheefficacyoftheworkintheclinic,ortheoutcomesforitspatients.Therefore,thefundingagencyhasrequestedthattheclinicworktoimplementaninformationsystem,tohelpbettermonitorandevaluatethehealthcareoutcomesofthepatientsovertime,andtohelptheclinicscaleuptoseemorepatientsmoreefficiently.TheagencyrecommendedthattheclinicconsiderusingOpenMRS,whichhadbeensuccessfullyusedbyotherprojectsfundedbythatagencyinothercountries.

Thefundingmodelprovidedforsomeinformationandcommunicationtechnology(ICT)infrastructuretogettheprojectstarted,aswellasforsomestaffingsupport.However,decidinghowtoallocatethismoneywasleftuptotheclinic'slocalmanagement.Afterreceivingthegrantfunding,thedirectorofthesitehiredClaudine,agraduateofamedicalinformaticstrainingprograminneighboringRwanda,tohelpleadtheeffort.Thisnewly-hiredinformaticsmanager,inturn,hiredDaniel,recentuniversitygraduatefromKampalawithexpertiseinICTinfrastructureandsystemadministration.

Sincetheclinicwasopened,doctorsandnurseshaveusedpaperformstocollectdataabouttheirpatients.Theseformsarestoredinfoldersandkeptinalockedfileroomuntilapatient'sappointment.Whenthepatientsarrive,theyaregiventheirfoldertocarrywiththemastheytalkwiththevarioushealthcareproviderstheywillseeduringtheirvisit.Eachoftheseproviderscompletestherelevantpaperformstoaddinformationaboutthevisit.Theformsareaddedtothepatient'sfolder,whichisreturnedattheendoftheirvisit.

ClinicalstaffwereconcernedwhentheyheardabouttheupcomingdeploymentofOpenMRC,becauseofthepossibilityofchangestothewaytheyareusedtoworking.However,theinformaticsmanagerhasassuredthemthattheycancontinuetousethefamiliarpaperforms.Whenapatientarrivesattheclinic,theywillberegisteredbyapatientregistrationclerk.Afterthepatient'svisitiscomplete,adataentryclerkwillentertheinformationfromthatvisitintoOpenMRS.

ManypeopleinKisiizihavebasicICTskills,andthereisalocalInternetcafe,supportedbyanNGOthatprovidesbasicICTtrainingtolocalresidents.Tworecentstudentshavebeenhiredasthefirstpatientregistrationanddataentryclerksfortheclinic.

Meanwhile,thesystemadministratorhasfinishedhispreparationworkandhasdeployedabasiclocalareanetwork(LAN)toconnectaserverthatwillhosttheOpenMRSapplicationtoPCsinthefileroom,intheclinicmanager'soffice,andintheICTroom.TheLANisconnectedtotheInternet,althoughtheconnectionisn'tveryfastandoftengoesoffline.Theserverispoweredbyanuninterruptiblepowersupply(UPS),thatwillensureitstaysrunningdespiteanyfluctuationsinthelocalpowergrid.

Throughtherestofthisbook,youwillfollowtheprogressofthepeopleattheAmaniClinicastheyinstallOpenMRS,customizeittofittheneedsoftheirclinic,anduseOpenMRSfromdaytoday,firsttoenterdataandthentoextractitforpatientvisitsandforreportingtotheirfundingagencyonanongoingbasis.

IsOpenMRSforYou?

14

IdentifyingYourNeedsDiscussingrequirementsandneedsatTRACPlusclinicinKigali.

Thischaptercoverssomebasicstrategiesforidentifyingyourorganizationalneeds,andhowOpenMRSmighthelp.ItdoesnotgointodetailaboutwhatOpenMRSdoesorhowitstoresdata--youwillfindthatinotherchapters.Instead,weencourageyoutofirsttakeastepbackandthinkaboutyourorganization.

Yourorganizationalgoalsandpractices

Fornow,forgetabouttechnologyandinsteadthinkaboutyourorganizationalgoalsandprocesses.Here'salistofquestionstostart:

Whatarethehigh-levelgoalsofyourorganization?

Whataretheteamsandstaffintheclinic?Whatrolesexist?Whatfunctionsdoeseachroleperform?

Whattasksarestaffinvolvedwithonaday-to-daybasis?

Whatservicesdoestheclinicprovidetoyourpatients?Whatactivitiesareinvolved?

Whatother3rd-partyorgovernmentorganizationsdoyoureportto?Whatinformationisincludedineachofthesereports?

Answeringthesequestionswillprobablyhelpyouthinkofmorerelatedquestions.Makesureyouconsiderthemthoroughly.

TakeadvantageofinstitutionalknowledgeAsyouthinkaboutyourpatientsandhowtheyinteractwithyourorganization,talktoyourclinicalandadministrativestaff--boththosewhohavebeenaroundalongtime,andthosewhohavejustjoined.Talktoasmanypeopleaspossibletogetacompletepictureofeveryserviceprovidedtopatients.

IdentifyingYourNeeds

15

Peoplegenerallywanttobepositiveindescribingtheirworkplaces,soyoumayneedtoasksomepeoplemultipletimes.Getphysicalorelectroniccopies,orpicturesofallpaperformsifpossible.Figureoutwhere(e.g.,specificroomsanddesks)dataisrecordedontopaperandbywhom.Writeanoverviewofcurrentpracticesanddefinespecificshortcomingsthatcouldbeaddressedbyusinganelectronicmedicalrecordssystem.

Notethatpracticesmayvaryseasonally,forexampleifthehospitalismuchbusierduetoincreasedmalariaduringrainyseasonormalnutritionbeforeharvest.

MapyourneedstoOpenMRS

OpenMRShasbeendesignedtobeflexibleandadaptable,basedoninputfrommanydifferentpartners,butitmaynotbeanexactfitforthewaysthatyourorganizationcurrentlyworks.Doingthingsthe"OpenMRSway"couldmeanadaptingyourworkflowandadoptingbestpracticesinmedicalinformatics.Bepragmaticandflexible,andthinkaboutwhetheryourcurrentworkingpracticesmightneedtochange.

RememberthatOpenMRSoffersmanyopportunitiestocaptureandanalyzeinformationinnewwaysnotpreviouslypossible.Takingadvantageofthesenewpossibilitiesmightleadtopositivechangesandimprovementsforyourorganization.

Donot"reinventthewheel"TheopensourcenatureofOpenMRSextendsbeyondapplicationitselftoamuchlargeropencommunitywhereideasandexperiencesareshared.Therearemanyexistingresourcesavailableintheformofpre-builtOpenMRSfeatures(modules)andcontentthatanewimplementershouldtakeadvantageof.Youshouldexplorethefollowingresourcesbeforebuildinganythingnew.

Reuseanexistingconceptdictionary

Awell-constructed,matureconceptdictionary(seethe"OpenMRSInformationModel"chapter)isastrongfoundationforanyOpenMRSImplementation.

TheMilleniumVillagesProject(MVP)maintainsawell-curatedconceptdictionary.Ifthisdictionaryisapplicabletoyourdomainofcare,youshouldstronglyconsiderusingit.Thebestwaytolearnaboutthisdictionaryisthroughapartnerproject,theMaternalConceptLab.

http://om.rs/book-mcl

OtherOpenMRSimplementerscanalsohelpadviseyouaboutotherconceptreferencesforyourdomain.Readthe"GettingHelpfromtheOpenMRSCommunity"chapterformoreinformation.

Adaptexistingforms

ImplementersshouldevaluatedatacollectionformsbuiltbyotherOpenMRSusersbeforecreatingnewcustomformsfortheirspecificneeds.

ImplementersacrosstheOpenMRScommunityhaveinvestedalotofresourcesinensuringthattheirformsreflectclinicalbestpractices,internationalstandards,andcurrentresearch.Theseformshavealreadybeenoptimizedforelectronicdataentry.ManyOpenMRSpartnersdevelopformsusingmedicalinformaticsexpertsthatmaynotbeavailabletoallprojects.Finally,creatingformsistimeconsuming;thoseresourcescouldberedirectedtootherefforts.

TheOpenMRSFormBankisanewcommunity-drivenprojectthatisbeginningtocollectexistingformsfromotherusers.VisitFormBankfordetails,orcontactotherimplementersforhelp.Readthe"GettingHelpfromtheOpenMRSCommunity"chapterformoreinformation.

IdentifyingYourNeeds

16

Explorethemodulerepository

ImplementersshouldconsulttheOpenMRSModuleRepositoryathttps://addons.openmrs.org/beforeconsideringcustomizationthroughsoftwaredevelopment.

Thereisagoodchancethatsomeonehascreatedamoduletoaddressneedsyoumayhave.Readthe"CustomizingOpenMRSwithPlug-inModules"chapterforalistofrecommendedmodules.

Amanidiscoverstheirspecificneeds

OncetheclinicdeterminedtheywoulduseOpenMRS,theybeganthinkingspecificallyabouthowtheywouldintegratetheirexistingprocessesintotheworkflowsupportedbythesoftware.Asthenewly-hiredmedicalinformaticsmanager,Claudineknewsheshouldspeakwitheveryoneworkingintheclinicandwatchthemduringatypicaldaytounderstandhowtheywork.Whenshespoketothem,sheassuredthemthatOpenMRSwouldhelptomaketheirworkeasier,andtheywouldstillbeusingthesameoverallprocessestheywerefamiliarwith.

ClaudinefoundmanyresourceswithintheOpenMRScommunity,includingpre-existingconceptdictionariesandformsthathadbeenusedinotherclinics.ShewasabletotaketheseartifactsandadaptthemtoAmani'spaperformsalreadyinuse.Startingoutwiththeworkofotherssavedquiteabitoftime.

IdentifyingYourNeeds

17

TransitioningtoOpenMRSApaper-basedpatientregisterbookatanAfricanOpenMRSclinic.

ThischapteroutlinesstepsthattypicallymakeupaOpenMRSproject,andshouldbereadbypeopleabouttoembarkonaOpenMRSimplementation.Someofthisinformationmaybeobvioustoexperiencedprojectmanagers.Acomprehensiveguidetoprojectmanagementisbeyondthescopeofthisbook,butwehaveincludedsomehigh-levelprocessconsiderationstogetyoustartedthinkingaboutwhatneedstohappen.

Werecommendyoutrytobuildastructuredimplementationprocess.It'simportanttoplancarefully--thedecisionsyoumakeduringthisprocessrequiresubstantialinvestmentsofresources,andyouwillbelivingwithyourchoicesfortheforeseeablefuture.

WhenyoustartoutonanewOpenMRSproject,youshouldspendtimethinkingabout(atminimum):

Whichpeoplewillbeinvolvedintheproject

BusinessgoalsofusingOpenMRS

Howyouwillapproachtheinitialconfiguration

Whatongoingsupportyouwillneed

CostsassociatedwithICTinfrastructure

Traininganddocumentation

Changemanagement

Peopleandtheprojectteam

Yourprojectimplementationteamshouldincludeclinicstaff:

TransitioningtoOpenMRS

18

1.Managementareawareoffundingobligationsandthirdpartyreportingrequirements.

2. Healthcareprovidersarefocusedonimprovingpatientcare.

3. Administrativestaffarespecialistsofworkflowissuesandclinicprocesses.

Theteamcouldalsoincludethefollowingpeoplethatmayormaynotbefromtheclinic:

1. AsystemadministratorisinchargeofinstallingandmaintainingOpenMRSinsideoftheclinic'sICTinfrastructure.

2.Medicalinformaticsexpert(s)createclinicaldocumentationandensurethatdataismanagedproperlyinthesystem.Developreports.

3. (Optional)Aprojectmanagerorcoordinator.Forlargerimplementations,thispersonworkstoholdpeopleaccountabletofinishingtheirworkinatimelymanner,andensurestheprojectisontrack.

4. (Optional)Softwaredevelopersmaybeneededforlocationsthatdecidetocustomizethesystem.

Itisveryimportanttoincludeclinicalstaff(forexamplenurses,dataentryclerks,andothers)inyourimplementationteamfromtheearliestphasesoftheprojectsothattheresultingdeploymentisusefulforthemandeasyforthemtouse.

ManaginganOpenMRSprojectwillrequireamajortimeinvestmentfrompeoplewithinyourorganization,evenifyouemployanexternalconsultant.OrganizationsoftenunderestimatetheamountoftimethatwillberequiredfromtheirstaffinimplementinganenterpriseICTproject.Thistimeinvestmentincludesitemssuchastraining,modifyingexistingprocesses,andprovidingneworupdatedinformationtorelevantpeople.DeployingOpenMRSisnodifferent.It'snotsomethingthatcanbeaddedtotheendofanalreadybusyschedule,andweurgeyoutokeepthisinmindandtakeitintoconsiderationwhenplanning.

GoalsBythispointintheproject,youshouldhaveagoodideaofwhatindicatesasuccessfulOpenMRSimplementationforyourclinic.Thiscouldbesomethinglikereducingtimetopreparemonth-endreportsby50%,orincreasingantiretroviraltreatment(ART)inHIV-infectedpregnantwomenby25%.Yourgoalsshouldbespecific,measurable,attainable,relevant,timely--orSMART.

Thesegoalswillhelpyouindirectingandmanagingyourproject.Forexample,iftheprojectgroupwantssomecustomizationthatrequiresbudgetandeffort,youroverallgoalswillhelpyoudecidewhetherornottoconsiderthatcustomization.YourgoalswillhelpyoutofocusonwhyyouareimplementingOpenMRSandwhatyouwanttoachieveinthelongrun.

Incrementaladoption

Itoftenmakessensetodividetheimplementationprocessintosmaller,moremanageablesections,whichcanbeimplementedindiscretestagesoriterations.Implementinginstagesallowspeopletogetusedtochangesgraduallywithoutfeelingoverwhelmed,andallowsyourimplementationteamtoberesponsivetofeedbackfromusersduringtheprocess.

Anotherreasonpeoplechoosetodevelopiterativelyisthatitisveryhardforuserstocorrectlyorfullyexplaintheirrequirementsatthebeginningoftheproject.Givingpeoplehands-onexperienceofanearlyversionofthesystemhelpsthemunderstandhowitworksandwhatmightbepossible.Theycanthenprovideyouwithvaluablefeedback,andtheymightidentifynewrequirements.

TransitioningtoOpenMRS

19

TheAmaniClinicchosetointroducechangeiteratively.Firsttheystartedusingthesystemforpatientregistration.Thisaffectedonlytheadministrativestaffwithoutimpactingtheclinicalstaff.Latertheystarteddoingretrospectivedataentry,whichincludedpaperformsforcliniciansthathadminorchanges,aswellastraininganewdataentryclerk.

Pilotprojects

Largermulti-siteimplementationsmaywishtodevelopapilotapproachtohelpreducerisk.Inthisscenario,youwouldonlydeployOpenMRSatonesiteandlearnabouttheprocessinamorecontrolledway.Youcanthenincorporatewhatyou'velearnedintoacoordinatedimplementationprocessforothersites.

Ongoingsupportanddevelopment

ItisamistaketothinkaboutanOpenMRSprojectasaone-offinstallationthatwillmeettheneedsofyourorganizationfortheforeseeablefuture.Organizationsarealwayschangingandevolving.Yourmedicalrecordsystemshouldevolvewithyou,otherwiseitwilleventuallybecomeoutofsyncwiththeorganization.

OnceyouhavebeenusingOpenMRSforawhileandstaffarecomfortablewithit,youwilllikelywanttotakeadvantageofadditionalfunctionality.EachimprovementornewpieceoffunctionalityyoudecidetoimplementinOpenMRSwilltakeresources,soyouwillwanttoplanaheadforthese.

Evenifyourorganizationalneedsdon'tchange,youneedtoplanforongoingsupportofOpenMRS,including:

Keepingyoursystemup-to-datewithsecuritypatches

UpgradingtothelatestversionofOpenMRS(notalwaysnecessary,butOpenMRSiscontinuallyimprovingusabilityandaddingfunctionality)

Upgradingthemodulesyouusetofixbugsandimprovefeatures

Maintenanceofyourserverandnetworkinfrastructure

Formoreinformation,seethe"Maintenance"chapter.

TrainingTrainingisalsoanimportantpartofanyOpenMRSimplementationproject.Yourtrainingcouldtakemanyformsdependingontheneedsofyourusers,butitoftenmakessensetospendresources(e.g.,timeandmoney)onformalandreusabletrainingresourcessuchasuserguides,lessonplans,andothermaterials.

Tryingtocovereverythinginonetrainingsessionprobablywon'tbeeffective.Peoplewillwantandneedtimetodigestthenewideastheylearnandusethemintheirdailywork,andyoumustanticipatestaffturnover.Instead,considerholdingsmallertrainingsessionsthatintroduceconceptsandspecificfunctionality,followedbyperiodsoftesting,pilotingandfeedback.Customizeyourtrainingforyouraudience--noteveryoneneedstositthroughatwo-hourtrainingsessionondataentryifonlyasinglepersonisresponsibleforthisrole.Whenpossible,trainpeopletobecometrainers.Thisincreasespeoples'senseofownershipinyourOpenMRSimplementation,andhelpspeopletobetterrememberwhattheylearn.

Trainingisanongoingprocess.Newemployeeswillneedtobetrainedwhentheystart,andpeoplefamiliarwiththesystemcanbenefitfromlearningaboutmoreadvancedtopics.PeoplemayneedfurthertrainingwhentherearesignificantupgradesornewfunctionalityisaddedtoOpenMRS.

Changemanagement

TransitioningtoOpenMRS

20

Introducinganelectronicmedicalrecordsystemwillcausechangesinworkflowandprocessesatyourorganization.Thesechangesmaybe"political"andcausechallengesinyourorganization,ortheymaybemorepracticalandtechnicalchanges.Eitherway,toomuchchangeatthesametimeisoftendifficultandstressful.

Tohelp,givepeopletimetoacceptandsupporteachchangesothattheyshareinownershipofthenewsystem,ratherthanfeelingasifsomethinghasbeenforcedonthem.FocusonsimpletasksatthebeginningofdeploymentandintroducemoredifficulttasksaspeoplestarttobetterunderstandOpenMRS.Showstaffhowthenewsystemwillmaketheirworkeasierandwheretheirfeedbackhasbeenincorporated.

Goodplanningcanminimizetherisksaroundchange,butitisimportanttobeflexiblewithinyourplan.Unforeseenthingsoftenoccur,andaplanthatistoorigidcouldpreventyoufromreachingthebestsolution.

TransitioningtoOpenMRS

21

InstallationandInitialSetupAnOpenMRSserverinUganda.

YoucandownloadOpenMRSfromtheOpenMRSwebsite:

http://download.openmrs.org

TherearetwowaystoinstallOpenMRS:Standalone,andEnterprise.YoumusthaveJava6orhigherinstalledonyoursystemtorunOpenMRS.ForOpenMRSPlatform2.0+(includesthecommunity'sReferenceApplication2.5+),Java8orhigherisrequired.

OpenMRSStandaloneprovidesasimplifiedinstallationoptionwithanembeddeddatabaseandwebserver.ItisagreatwaytoevaluateandexploreOpenMRS,lettingyougetalocalversionupandrunningwithinminutes,andincludesdownloadoptionswithsampledata.OpenMRSStandaloneshouldrunfineforsmallerinstallations(fewerthan10,000patientrecords),butifyouaresettingupalargerinstallation,werecommendusingtheEnterpriseinstallation.Ifyouarenotsurewhichmakessense,youcanstartwithaStandaloneinstallationandmigrateyourdatatotheEnterpriseversionlater.

OpenMRSEnterpriseisappropriateforlargerinstallations.IfyoualreadyhaveaJavaservletcontainerandadatabaseinstalled,andyouwanttosetupOpenMRStousetheseresources,youshoulduseOpenMRSEnterprise.

OpenMRSStandalone

Toinstallthestandaloneversion,downloadtheZIPfileanddecompressit,thendouble-clicktheopenmrs-standalone.jarfiletorunit.Thefirsttimeyourunthisfile,itwillinstallOpenMRSandopenyourbrowsertothenewOpenMRSinstance.

InstallationandInitialSetup

22

Duringsetup,thereisanoptiontoinstalldemodata.Youmaychoosetoinstallademoconceptdictionary,whichcanjump-startyourformcreationprocess.Youmayalsoinstalldemopatientdata,whichwillprovideabetterdemonstrationofpatientencountersanddemographics.

DonotdeleteorrenameanyfilesorfoldersafterdecompressingtheZIPfile.Thesefilesandfoldersarerequiredbythestandaloneinstaller.

Alternatively,fromthecommandline,youcannavigatetothedecompressedfolderandrunthefollowingcommand:

java-jaropenmrs-standalone.jar

OnLinux,youcanalsodouble-clickonthefilenamedrun-on-linux.sh.Ifyouarepromptedforhowtorunit,justselectrun.Alternatively,youcanuseacommandlineshelltonavigatetothedecompressedfolderandrunthefollowingcommand:

./run-on-linux.sh

UpgradingStandalone

ToupgradeacopyofOpenMRSStandalone,dothefollowing:

1. StopthepreviousversionofOpenMRSStandaloneandexittheapplication.

2. DownloadandextractthemostrecentversionofOpenMRSStandalone.

3. CopyyourdatabasedirectoryfromthepreviousversiontothisnewOpenMRSdirectory.

4. Copyyouropenmrs-standalone-runtime.propertiesfromthepreviousversiontothisnewOpenMRSdirectory.

5. InstallOpenMRSStandaloneasdescribedabove.ThenewversionofOpenMRSwillrunwithyourolddata.

Loggingin

Bydefault,theinitialusernameandpasswordareasfollows:

Username:admin

Password:Admin123

Youmustimmediatelychangetheadminpasswordafterinstallationforsecuritypurposes.Tochangeyourpassword,clickMyProfileintheupperrightofOpenMRS,andchoosetheChangeLoginInfotab.Updateyourpassword,thenclickSaveOptions.Youcanalsochangeyourusername,andprovideyourrealname,onthisscreen.

Stoppingandrestarting

AslongasOpenMRSisrunning,youcanreturntotheapplicationbyopeningthefollowingURLinyourbrowser.

http://localhost:8081/openmrs-standalone/

Beforeyouchangecertainpreferences,suchastheportonwhichMySQLorTomcatruns,youmuststoptheapplication.

Tostoptheapplication,usetheStopbuttonintheuserinterface,orchooseFile>Quit.Alternatively,runtheJARfileonthecommandlinewitha-stopparameter.

YoucanrestarttheGUIbyclickingStart,ordouble-clickingontheJARfileagain.Alternatively,youcanruntheJARfilewitha-startparameter.

InstallationandInitialSetup

23

Bydefault,OpenMRSrunstheMySQLdatabaseonport3316,andtheTomcatserveronport8081.Touseadifferentport,stoptheapplication,thenchangetheportnumberintheopenmrs-standalone-runtime.propertiesfileorintheGUI,andrestart.Tooverridetheportfromthecommandline,runtheJARfilewitha-tomcatportor-mysqlportparameter.

ChangingtheportnumberwillchangetheURLusedtoaccesstheapplication.Toaccesstheapplication,youcanchooseFile>LaunchBrowser,orruntheJARfilewitha-browserparameter.

OpenMRSEnterprise

YoumusthaveApacheTomcatandMySQLinstalledonyoursystembeforeinstallingtheenterpriseversionofOpenMRS.

DownloadtheEnterpriseWARpackagefrom

http://download.openmrs.org

NavigatetotheTomcatWebApplicationManagerandenteryourTomcatadministratorcredentials.

http://localhost:8080/manager/html

Browsetothelocationoftheopenmrs.warpackage,anddeployit.

Theinitialsetupwhichfollowsmaytakesometime.Attheendoftheprocess,theWebApplicationManagerwillrefresh,and/openmrsshouldbedisplayedinthelistofapplications.Tomcatshouldalsostarttheapplication(Running=True).

OpentheOpenMRSwebapplicationtocompletetheinitialsetupprocess.

http://localhost:8080/openmrs

GettingStartedwithOpenMRSEnterprise

ThefirsttimeyourunOpenMRS,thesetupwizardwillhelpyouconfigureyourinstallation.Followtheinstructionsinthiswizardtosetupyourdatabaseandpopulateitwithtestdataifnecessary.

Tochangeyourconfigurationlater,stoptheapplication,editthefileopenmrs-runtime.properties,andrestarttheapplication.OnWindows,youcanprobablyfindthisfileinthislocation:

C:\DocumentsandSettings\YOURUSERNAME\ApplicationData\OpenMRS

or

C:\Windows\system32\config\systemprofile\ApplicationData\OpenMRS

OnMacOSXorLinuxsystems,itisprobablylocatedinthislocation:

~/.OpenMRS

or

/usr/share/tomcatX/.OpenMRS

AfteryouhavefinishedconfiguringOpenMRS,reloadtheapplicationintheWebApplicationManager.Opentheloginpage,typicallyatthisURL.

http://localhost:8080/openmrs

IfTomcatisinstalledonanotherserveroranotherport,replacelocalhostor8080asapplicable.

InstallationandInitialSetup

24

Usetheadministratorusernameandpasswordyouspecifiedintheconfigurationwizardtologin.Ifyoudidnotspecifyausernameandpassword,tryusingthedefaultusernameadminandpasswordAdmin123.

UpgradingOpenMRSEnterprise

ToupgradeacopyofOpenMRSEnterprise,dothefollowing:

1. UsetheTomcatWebApplicationManagertostopthepreviousversionofOpenMRS.

2. DownloadthemostrecentversionofOpenMRSEnterprise.

3. InstallOpenMRSasdescribedabove.ThenewversionofOpenMRSwillrunwithyourolddata.

AmanichoosestheEnterpriseversion

AlthoughAmaniClinicissmall,theydecidedtoinstalltheEnterpriseversion.ClaudineisveryfamiliarwithApacheTomcatandMySQL,anddecidedshewouldlikemorecontroloverthesystem.SheinstalledUbuntuLinuxonthephysicalserver,theninstalledJava6,MySQL,andTomcat.Afterdoingso,shedownloadedtheopenmrs.warfileandinstalleditintheTomcatapplicationserver.Excludingdownloadtimeforthesoftware,shewasabletocompletetheprocessinlessthanonehour.

InstallationandInitialSetup

25

OpenMRSInformationModelReferencebookslineashelfinaruralAfricanclinic.

ThischapterexplainstermsandconceptswhichareusefultounderstandasyouinstallanduseOpenMRS.

Data

TheactualinformationyouwanttorecordinOpenMRSiscalledData.ExamplesofDatainOpenMRSarePatients,Encounters,andObservations.Tosupportthisdata,anddescribeitsmeaning,youneedadditionalMetadata.

WhenauserdeletesapieceofdatainOpenMRS,theinformationactuallyremainsinthedatabase.Itismarkedasvoided,sothatitwillnotshowupintheinterface,butitisnotimmediatelydeletedfromthedatabase.Ifauserdeletesapieceofdatabyaccident,anadministratorcanunvoidittoreturnittothesystem.Topermanentlydeletedatafromthedatabase,anadministratormustpurgethatdata.Typically,thisshouldneverbedoneinaproductionsystem.

MetadataThefundamentalexpectationofOpenMRS'sdesignisthatyouwillcustomizeitforyourclinicalprogram'susecase.Thesystemhasnobuilt-inideaofthepatient'sweightorseeingthepatientinanoutpatientvisit.Instead,youcanconfigurethesethingsyourself,tomatchyourproject'sworkflow.Generallyspeaking,thethingsthatyouneedtoconfigureinordertodescribetherealpatientinformationyouwillbecapturingarereferredtoasmetadata.AnexampleofapieceofmetadataisaLocationthatrepresentsahospital.

AnadministratormayalsoretiremetadatainOpenMRS.Thisdoesnotmeanthatthemetadataisdeleted,butratherthatitisnotintendedtobeusedgoingforward.Oldinformationthatreferstotheretiredmetadataremainsvalid.Anadministratormayunretiremetadataifitbecomesrelevanttoactiveuseagain.Ifnoactualdatareferstoapieceofmetadata,anadministratormaypurgethemetadatatopermanentlyremoveitfromthedatabase.

OpenMRSInformationModel

26

Forexample,thehospitalyoureferpatientstocloses.Therefore,youcannolongerreferpatientsthere.ThisLocationcannowberetiredinOpenMRS.Thiswouldnotinvalidatethefactthatmanypatientswerereferredthereinthepast.

Conceptsandconceptdictionary

Themostimportantpartofthesystem'smetadataistheConceptDictionary,whichisalistofallthemedicalandprogram-relatedtermsthatyouwilluseasquestionsandanswersinObservations.ThisdictionarydoesnotneedtobecompletewhenyoubeginusingOpenMRS.Youshouldexpectnewtermstobeaddedandoldtermstoberetiredasyouruseofthesystemevolves.Itisbettertostartwithapre-populatedConceptDictionary,ratherthanstartingfromscratchyourself.Seethechapter"SharingConceptsandMetadata"formoredetails.

EveryquestionyouaskaboutapatientneedstobedefinedbyaConcept.(Forexample,torecordapatient'sweightyouneedaconceptlikeWeightinkilograms.)

Ifyouwanttoaskaquestionthathasafixedsetofcodedanswers,thoseanswersarealsoConcepts.(Forexample,thequestionconceptBloodTypemayhave4differentanswerconcepts:A,B,AB,andO)

PersonsEveryindividualwhoisreferredtoinapatientrecordinOpenMRSisstoredinthesystemasaPerson.TheseincludePatients,anypatientrelativeorcaretaker,Providers,andUsers.

AllPersonshavethesecharacteristics.

Names

Apersoncanhaveoneormorenames,oneofwhichmustbemarkedasthepreferredname.Thepreferrednamewillbedisplayedinsearchresultsandpatientscreens.

Addresses

Apersonmayhavezeroormorecontactaddresses.Youmayconfiguretheformatoftheseaddressesforyourparticularlocale.

PersonAttributes

Tosupportyourlocalneeds,youcandefineadditionalpiecesofinformationaboutthepeopleinyoursystem,ontopofthosethatarenativelysupportedbyOpenMRS.YoucandefinethedatatypeofaPersonAttribute,aswellasanyconstraintsonthepossiblevalues,usingmetadata.ThismetadataiscalledaPersonAttributeType.

PersonAttributesaresuitableforstoringotherinformation.Buthistoricalvaluesofpersonattributesarenotretained.Forexample,youshoulduseapersonattributetorecordapatient'scontacttelephonenumber.Thisinformationmaychange,butifitdoesso,thesystemneedonlystorethemostrecentvalue,andneednotretainpreviousvalues.Itisnotappropriatetouseapersonattributetostoresomethinglikethepatient'sheight,whichisrecordedatagivenpointintime,butcanbeexpectedtochangeandshouldbetrackedasitdoesso.

PatientsAnyonewhoreceivescareinOpenMRSmustbeaPatient(forexample,anyonewhohasanEncounterorwhoisenrolledinaProgram).EveryPatientmusthaveatleastoneIdentifier,whichisexplainedbelow.

APatientisalsoaPerson,meaningtheymusthaveatleastonenameandtheymayhaveaddresses.

OpenMRSInformationModel

27

PatientIdentifier

ThePatientIdentifierisamedicalrecordnumberassignedbyyourfacility,usedtoidentifyandre-identifythepatientonsubsequentvisits.

APatientIdentifierTypedefinestheformatofaparticularkindofpatientidentifier.Forexample,youmightdefinethatAmaniIDisanidentifiertypethatisrequiredforeverypatient;theformatis2lettersfollowedby6digitsandusesaparticularcheckdigitalgorithm.

ACheckDigitisanextradigitthatisaddedtotheendofanidentifier,anddependsontherestoftheidentifier.ItallowsOpenMRStodeterminewhetheranidentifierhasbeenmistyped.ForexampleusingaLuhncheckdigit,"1234-1"isvalid,but"1234-5"isincorrect.Itisastronglyrecommendedbestpracticetousecheckdigitsinallpatientidentifiersthatyouassign.Formoreinformationaboutcheckdigits,seehttps://en.wikipedia.org/wiki/Check_digit.

Relationships

ARelationshipisabidirectionallinkbetweentwoPersonsinOpenMRS.

ThemetadatathatdescribesaparticularkindofrelationshipisaRelationshipType.Itdefinesthenamesofeachdirectionoftherelationship.TypicalRelationshipTypesareParent/ChildandDoctor/Patient.

AttheAmaniClinic,itisnecessarytouserelationshipstolinkamother'spatientrecordtothepatientrecordofherchildren.Onemightalsouserelationshipstorecordthelinkbetweenapatientandtheirprimarycareprovider.

Visits

AVisitinOpenMRSrepresentsexactlywhatitsoundslike:atimeperiodwhenapatientisactivelyinteractingwiththehealthcaresystem,typicallyatalocation.ThemetadatadifferentiatingdifferenttypesofvisitsisaVisitType.VisitTypesaredisplayedintheuserinterface,andcanbesearchedagainst.

Avisitcontainsencounters,whichstoremoregranulardataabouttreatmentsorservices.

AttheAmaniClinic,apatientmighttypicallycheck-inatregistration,beseenbyadoctor,andreceivesmedicationdispensedinthepharmacy.ThiswouldberecordedasonevisitoftypeofOutpatient,andcontainthreeencounters(Registration,Consultation,andDispensing).

Encounters

Amomentintimewhereapatientisseenbyprovidersatalocation,anddataarecaptured.Generallyspeaking,everytimeyouenteraforminOpenMRSthiscreatesanEncounter.Encounterstypicallybelongtoavisit,buttheymayalsostandalone.

ThemetadatathatdescribesakindofencounterisanEncounterType.Thesearedisplayedintheuserinterface,andyoumayalsosearchagainstthem.

OpenMRSInformationModel

28

DuringatypicalAmaniClinicOutpatientVisit,apatientchecksinatregistration,isseenbyadoctor,andreceivesmedsdispensedinthepharmacy.Thiswouldberecordedasonevisitcontainingthreeencounters,whosetypesareRegistration,Consultation,andDispensing.

Providers

AProviderisapersonwhoprovidescareorservicestopatients.Aprovidermaybeaclinicianlikeadoctorornurse,asocialworker,oralabtech.Generallyspeaking,anyhealthcareworkerthatapatientcanhaveanencounterwithisaprovider.

ProvidersmayhavefullrecordsinOpenMRSaspersons,ortheymayjustbeasimplenameandIDnumber.

Locations

ALocationisaphysicalplacewhereapatientmaybeseen.

Locationsmayhaveahierarchy,forexampleChildren'sWardmightbealocationwithinthelocationAmaniClinic.

Youmightalsostorephysicalareas(forexampleEasternProvince,orCalifornia)asLocations.YoushouldnotuselocationstorepresentlogicalideaslikeAllDistrictHospitals.

Observations

AnObservationisonesinglepieceofinformationthatisrecordedaboutapersonatamomentintime.

EveryobservationhasaConceptasitsquestion,anddependingonthedatatypeoftheconcept,ithasavaluethatisanumber,date,text,Concept,etc.

MostoftheinformationyoustoreinOpenMRSisintheformofObservations,andmostObservationshappeninanEncounter.WhenyouenteraforminOpenMRS,typicallyoneEncounteriscreatedwithanywherebetweentensorhundredsofObservations.

NotethatanindividualObservationisvalidonlyatonemomentintime,anditdoesnotcarryforward.Youmayquerythesystemforthelastobservationforpregnancystatusbutthisdoesnottellyouwhetherornotthepatientispregnantatanypointafterthemomentofthatobservation.

ExamplesofobservationsincludeSerumCreatinineof0.9mg/dLorReviewofcardiopulmonarysystemisnormal.

Observationgroups

SometimesasingleObservationisnotsufficienttocaptureanentirepieceofpatientinformation,andyouneedtousemultipleObservationsthataregroupedtogether.

Forexample,recordingthatapatienthadarashasanallergicreactiontopenicillinwouldneedtobestoredastwoobservationsplusathirdonethatgroupstheprevioustwotogether:

1. Concept="Allergen",codedvalue="Penicillin",group=(3)

2. Concept="Reaction",codedvalue="Rash",group=(3)

3. Concept="AllergicReactionConstruct",groupmembers=(1),(2)

Orders

OpenMRSInformationModel

29

AnOrderisanactionthataproviderrequestsbetakenregardingapatient.

ForexampleaprovidercouldorderaCompleteBloodCountlaboratorypanelforapatient.

AnOrderonlyrecordsanintention,notwhetherornottheactioniscarriedout.TheresultsofanOrderaretypicallyrecordedlaterasObservations.

PrescribingamedicationisaDrugOrder.Adrugordercanbeplacedforagenericdrug,representedbyaConcept(forexample,500mgofCiprofloxacin,twiceaday).IfyouareusingOpenMRStomanageaformularyofspecificmedications(i.e.,DrugsinOpenMRS),youmayalsorecordDrugOrdersagainstthose.Forexample,adrugordermightbeOne500mgtabletofCiprofloxacin,twiceaday.

Allergylists

OpenMRSletsyoumanuallymaintainanAllergyListforapatient,includingtheallergen,reaction,severity,etc.

ThislistismanagedseparatelyfromObservations:observinganallergicreactiontoadrugdoesnotautomaticallyaddanAllergytothelist.

UnlikeanObservation(whichhappensatonemomentintime),anAllergyislongitudinaldata,withstartandenddates.

Problemlists

OpenMRSletsyoumanuallymaintainaProblemListforapatient.ThislistismanagedseparatelyfromObservations:observingthatthepatienthas"DiagnosisPresent=Diabetes"doesnotautomaticallyaddaproblemtothelist.Unlikeanobservation(whichhappensatonemomentintime),aproblemislongitudinaldata,withstartandenddates.

Programenrollments,workflows,andstates

AProgramrepresentsanadministrativeprogramorstudythatapatientmaybeenrolledin(forexample,ChildNutritionStudyorDOTSTuberculosisTreatmentProgram).

AProgramEnrollmentrepresentsthefactthatapatientisenrolledinoneoftheseprogramsoveratimeperiodataLocation.Thisislongitudinaldatawithastartdateandenddate.

AProgramcanalsodefineadministrativeWorkflows,andpossibleStatesthepatientmayhavewithinthoseworkflows.AnInitialStateisonethatapatientisallowedtostartinwhentheyarefirstenrolledinaprogram.ATerminalStateisonethatclosestheprogramenrollmentifthepatientisplacedinit.

ForexamplearesearchstudyoninfantnutritionmighthaveaworkflowcalledStudyEnrollmentStatuswiththestates:

PatientIdentified(initial)

MotherConsentedtoStudy

StudyComplete(terminal)

LosttoFollowup(terminal)

Thesestatesaremeanttorepresentadministrativestatuses,notclinicalones.ForexampleputtingapatientinaLosstoFollowupstaterepresentsanofficialdeclarationandwillnothappenautomaticallyevenifnoencountersareenteredforthepatientforseveralmonths.

Forms

OpenMRSInformationModel

30

AFormrepresentsanelectronicformthatmaybeusedforenteringorviewingdata.ThebasicOpenMRSsystemdoesnotdefineaspecifictechnologyforenteringforms.Youwillneedtouseoneofthecommunity-developedformentrymodules.Seethechapter"DataEntry"formoredetails.

TheFormEntry(Infopath)andXFormsmodulesrelyonaFormSchema,whereyoudefinewhichConceptsareusedontheForm.TheHTMLFormEntrymoduledoesnotrequireyoutomanagetheschema.

Users,roles,andprivileges

AUserinOpenMRSisanaccountthatapersonmayusetologintothesystem.

Thereal-lifepersonisrepresentedbyaPersonrecordinOpenMRS,andapersonmayhavemorethanoneuseraccount.IfyouwantapatienttobeabletoviewherownrecordinOpenMRS,thenyouneedtocreateauseraccountandlinkittothepatient.

ARolerepresentsagroupofprivilegesinthesystem.Rolesmayinheritprivilegesfromotherroles,andusersmayhaveoneormoreroles.

APrivilegeisanauthorizationtoperformaparticularactioninthesystem.Thelistofavailableprivilegesaredefinedbythecoresystemandbyadd-onmodules(forexample,DeletePatientsandManageEncounterTypes),butyouneedtoconfigurewhichroleshavewhichprivilegeswhileyouareconfiguringyoursystem.

TheinformationmodelinuseatAmaniClinic

ApatientnamedAsabaarrivesatAmaniClinic,wheretheregistrationclerkJamescreatesherelectronicrecordandstoreshercontactphonenumberas312-555-7890.OnpapertheNurse,Kissa,recordsAsaba'sweightas61.5kgandordersapregnancytest.Jamesenterstheseontoanelectronicscreen.

FromtheperspectiveoftheOpenMRSmodel,wehavethefollowingmetadata:

Thenurse,Kissa(aProvider)Theregistrationclerk,James(aUser)ContactPhoneNumber(aPersonAttributeType)Weight,inkilograms(aConcept,withclassFindinganddatatypeNumeric)UrinePregnancyTest(aConcept,withclassTest)AmaniClinic(aLocation)OutpatientVisit(anEncounterType)OutpatientTriageForm(aForm)

WhenAsabaisfirstseenattheregistrationdesk,Jamescreatesthefollowingdata:

APatient(Asaba)APersonAttribute(type=ContactPhoneNumber,value=312-456-7890).

AfterAsabaseesthenurse,whogivesapaperformtoJames,hecreatesmoredata:

AnEncounterwith:

OpenMRSInformationModel

31

patient=Asabatype=OutpatientVisitform=OutpatientTriageFormlocation=AmaniClinicprovider=NurseKissacreator=RegistrationClerkJames

AnObservation(inthatencounter),ofWeightinkilograms=61.5.

AnOrder(inthatencounter),forUrinePregnancyTest

OpenMRSInformationModel

32

GettingAroundtheUserInterfaceAnOpenMRSimplementer-programmergivesademonstrationofthesystemashisclinic.

ThischaptergivesabriefoverviewofkeypartsoftheOpenMRSuserinterface,whichwillbehelpfulasyoureadthechapterstofollow.

Loggingintothesystem

OpenMRSrunsasawebapplication,meaningyouuseitviaawebbrowser.Beforeyoucanaccessanypagesinthesystem,youneedtologin.Todothisthefirsttime,youwillneedtoknowtheadministratorpasswordthatyouchoseduringfirst-timesetup.Refertothechapter"InstallationandInitialSetup"forthosedetails.

Usersthatforgettheirpasswordmayresetitiftheyhaveconfiguredasecretquestionandknowtheanswer.TheSignuplinkisprovidedbytheRequestAccountmodule,ifyouhaveitinstalled.

GettingAroundtheUserInterface

33

Home

InthedefaultinstallationofOpenMRS,allusersseethesamehomepageafterloggingin.Tocustomizedifferenthomepagesfordifferenttypesofusers,youcanusetheRoleBasedHomePagemodule.

AsshownintheOpenMRShomepageabove,allpagesallowyouto:

1. Logoutandedityourprofile,or

2. Changeyourlanguageforthecurrentsession.

YoucanconfiguretheallowedlanguagesviaasettingintheAdministration>Maintenance>Settingspage.

Administration

AsasystemadministratorormanagerforanOpenMRSinstallation,youwillfrequentlyneedtoaccesstheconfigurationandadministrationfunctionsaccessiblethroughtheAdministrationpage.

GettingAroundtheUserInterface

34

1. YoucanaccesstheAdministrationpagefromanywhereintheapplicationbyclickingitslinkinthetop-rightofthescreen.

2. ConfigurationpagesfortheOpenMRScorefunctionalityarelistedintheleftandcentercolumns.

3. Configurationpagesforfunctionalityinadd-onmodulesarelistedintherightcolumn.

4. Youadd/remove/start/stopadd-onmodulesfromtheManageModulespage.

ViewingandcreatingpatientsOneofthemostcommonactionsfornon-administrativeusersofthesystemistofindandopenexistingpatientrecords.Ifthedesiredpatientrecordisnotfound,usersmaybeabletocreatenewonesiftheyhavesufficientprivileges.

YoucansearchforapatientbyIDnumber.Clickingonthesearchresultwillopenthatpatient'sdashboard.IfauserdoesnotfindapatientbyIDnumberorname,youmaycreateanewpatient.

GettingAroundtheUserInterface

35

Patientdashboard

Dataentrystaffwillspendalotoftimeonthepatientdashboardpage.Thisgivesaccesstodifferentpartsofapatient'srecordandallowsyoutoenterformsintotherecord.

Theworkflowofthepatientdashboardpageisnotefficientforaclinicianwhowantstoaccessapatient'srecordatthepointofcare.TosupportthoseworkflowsyoushouldconsiderdownloadingandinstallingtheClinicalSummarymoduleortheHTMLFormFlowsheetmodule.

Thepatientdashboardpageisdescribedinmoredetailinthechapterentitled"ThePatientDashboardInDepth".

GettingAroundtheUserInterface

36

GettingAroundtheUserInterface

37

CustomizingOpenMRSwithPlug-inModules

OpenMRShasamodulararchitecture,whichallowsspecialfunctionalitytobeeasilyaddedorremovedfromthesystem.Moduleshavefullaccesstothesystemandcanmodifyorenhancethebehaviorofthesystem.Forexample,theSyncmoduleaddstheabilityforanOpenMRSservertosynchronizeitsdatawithotherOpenMRSservers;theHTMLFormEntrymoduleprovidesawaytocreateweb-basedformsforcollectingdata;andtheFlowsheetmoduleaddsanewwayforviewinginformation.ModulesalsoprovideamechanismforadaptingOpenMRStolocalneeds.FormoreinformationaboutpublishedmodulesvisittheOpenMRSWiki:

https://wiki.openmrs.org/display/docs/Modules/

ModulerepositoryYoucanviewavailablemodulesintheOpenMRSAdd-onsindex:

https://addons.openmrs.org/

Itisaplacewhereyoucanfindpublishedmodules.Eachmodulehasapagewithadescription,alinkfordownloading,andalinktothemodule'sdocumentation.

Somemodulesmaybeunderdevelopment,butnotyetpublishedinthemodulerepository.ManyofthesecanbeseenbybrowsingGitHubforrepositoriesstartingwith"openmrs-module-"intheirname.ManycommunitymodulescanbefoundundertheOpenMRSorganizationonGitHub:

https://github.com/openmrs/

Managingmodules

CustomizingOpenMRSwithPlug-inModules

38

YoucanseeavailablemodulesunderAdministrationpage,ManageModules.Thelistingcontainsalltheinstalledmodules.Youcanseetheirstatus(iftheyarestarted,stoppedorfailedtostart)aswellasuninstallthem.

Touninstallamodule:

1. Stopthemodule

2. Startthemodule

3. Uninstallthemodule

Amoduleisdistributedasasinglefilewiththe.omodextension.YoucaninstallitfromthededicatedManageModulessectionontheAdministrationpage.

Youcaneitherpointtoalocalpathtothe.omodfileorfindandinstallamoduledirectlyfromtheInstallfromModuleRepositorysectionwhichconnectstothemodulerepository.

Toinstallamodule:

CustomizingOpenMRSwithPlug-inModules

39

1. ChooseafileandclickUpload

2. Searchforamodulebyname

3. Installthechosenmodule

Ifuploadsarenotallowedfromtheweb,youcancopythe.omodfileintothefolder:

~/.OpenMRS/modules

(where~/.OpenMRSisassumedtobetheApplicationDatadirectorywhichtherunningOpenMRSiscurrentlyusing.YoucanfindtheexactlocationunderAdministration>ModuleProperties.)Aftermovingthefiletothatlocation,restartOpenMRS.Themodulewillbeloadedandstarted.

Bundledmodules

OpenMRSisdeliveredwithsomebundledmoduleswhichareincludedinastandardinstallation.Thelistmaydifferfromversiontoversion.Someexamples:

HTMLFormEntry

AllowsanyonewithbasicHTMLprogrammingskillsandknowledgeoftheOpenMRSsystemtocreateformswhichcanbeenteredwithoutanyproprietarytoolsdirectlyfromawebbrowser.Itisapreferredformentrymodule.HTMLFormsallowalotofcontrolovertheform'slayout.https://wiki.openmrs.org/display/docs/HTML+Form+Entry+Module

XForms

AllowsdataentrytobedonedirectlyfromanyJavaScriptenabledbrowser.ThemoduleconvertsanOpenMRSformtoanXForm.XFormsarewellsuitedtoformsthatwillbefilledoutonmobiledevices.

https://wiki.openmrs.org/display/docs/XForms+Module

HTMLWidgets

ProvidesasetofreusableHTMLformfieldwidgetsthatencapsulatethecommoninputrequirementsforOpenMRS.Itismeanttobesomethingthatdeveloperscanutilizeintheircode.https://wiki.openmrs.org/display/docs/HTML+Widgets+Module

Reporting

Providesafeature-richanduser-friendlywebinterfaceformanagingreportswithinOpenMRS.https://wiki.openmrs.org/display/docs/Reporting+Module

ReportingCompatibility

ContainspagesandfeaturesthatwerepreviouslyincludedintoOpenMRScorecodeitselfandareneededtoruntheReportingmodule.Itwaswrittenforthe1.5andlaterreleasesofOpenMRS.https://wiki.openmrs.org/display/docs/ReportingCompatibility+Module

Otherpopularmodules

ClinicalSummary

Allowsyoutocreateclinicalsummaries.https://wiki.openmrs.org/display/docs/Clinical+Summary+Module

CustomizingOpenMRSwithPlug-inModules

40

Groovy

Wascreatedasaproofofconcept(forembeddingGroovyintoOpenMRS)andtoserveasabasemoduleforothermodulesthatwanttouseGroovyscriptingaswell.https://wiki.openmrs.org/display/docs/Groovy+Module

HTMLFormFlowsheet

Allowsyoutogenericallymodelapaperflowsheet.ProvidesbasicfunctionalityforembeddingsmallHTMLFormsinsideoflargerHTMLForms,whereeachsmallHTMLFormrepresentsonerowinapatientchart.Additionally,themoduleallowsyoutospecifyanynumberoftabsinatab-basedlayout,eachcontainingadistinctHTMLForm.https://wiki.openmrs.org/display/docs/HtmlFormFlowsheet+Module

HTMLFormEntryDesigner

WYSIWYGFormDesignerfortheHTMLFormEntrymodule.https://wiki.openmrs.org/display/docs/HTML+Form+Entry+Designer+Module

IDGeneration

ProvidesafacilityformanagingidentifiergenerationandallocationwithinanOpenMRSimplementation.Introducesdifferentidentifiergenerationstrategiesincludingautomaticandpooled.https://wiki.openmrs.org/display/docs/Idgen+Module

MetadataSharing

Allowsallkindsofmetadata(concepts,HTMLforms,locations,roles,programs,etc.)tobeexchangedbetweendifferentOpenMRSinstallations.https://wiki.openmrs.org/display/docs/Metadata+Sharing+Module

RequestAccount

Allowsuserstorequesttheirownaccounts,specifyingtheirownpreferredusernameandpreferredpassword.Anadministratorcanthenapproveordenypendingaccountrequests.https://wiki.openmrs.org/display/docs/Request+Account+Module

RESTWebservices

ExposestheOpenMRSAPIasRESTwebservice.https://wiki.openmrs.org/display/docs/REST+Web+Services+API+For+Clients

Role-basedHomePage

Allowsforadministratorstodefineacustom"homepage"foreachdefinedrolewithinthesystem.Thesehomepagesmaybesimplypagesthatalreadyexist,andwhichparticularuserswouldbebestservedtohaveastheirdefault.Forexample,systemadministratorsmaywanttheAdministrationpageastheirdefaulthome.Alternatively,administratorscan"author"newpageswithintherunningapplicationfortheirusers.https://wiki.openmrs.org/display/docs/Role+Based+Homepage+Module

Synchronization

FitsinscenarioswhenyouhavemultiplesitesusingOpenMRSwithseparatedatabasesandyouwantthemtocopydatatoeachotherthatwillkeepthemsynchronized.https://wiki.openmrs.org/display/docs/Sync+Module

Writingyourownmodule

CustomizingOpenMRSwithPlug-inModules

41

Thissectioncoversbasicsofwritingyourownmodule.WeencouragetocontributemodulesyouwritetotheModuleRepository.Youcanalsouseourcoderepositoryforyourmodule.Formoreinformation,pleasevisitthispage

https://wiki.openmrs.org/display/docs/Creating+Modules

Inordertodevelopandtestamodule,youwillneedtohaveOpenMRSinstalledinaversiononwhichyouwanttorunyourmodule.

ItisbesttouseadedicatedMavenarchetypetocreateanewmodule.BeforeyoustartyouwillneedtoinstallMaven.SeetheMavenwebsiteathttp://maven.apache.org/formoreinstructions.

Thenextstepistoupdatethesettings.xmlfiletopointMaventotheMavenModuleArchetype.Youcanfindthefileinoneofthefollowinglocations:

Linux:~/.m2

WindowsXP:C:\DocumentsandSettings\user_name.m2

WindowsVista/7:C:\Users\user_name.m2

Ifthesettingsfiledoesnotexistyouneedtocreateone.Addthefollowingcontent:

<settingsxmlns="http://maven.apache.org/SETTINGS/1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0

http://maven.apache.org/xsd/settings-1.0.0.xsd">

<pluginGroups>

<pluginGroup>org.openmrs.maven.plugins</pluginGroup>

</pluginGroups>

<profiles>

<profile>

<id>OpenMRS</id>

<activation>

<activeByDefault>true</activeByDefault>

</activation>

<properties>

<archetypeCatalog>http://mavenrepo.openmrs.org/nexus/service/local/repositories/releases/content/archet

ype-catalog.xml</archetypeCatalog>

</properties>

<repositories>

<repository>

<id>openmrs-repo</id>

<name>OpenMRSNexusRepository</name>

<url>http://mavenrepo.openmrs.org/nexus/content/repositories/public</url>

</repository>

</repositories>

<pluginRepositories>

<pluginRepository>

<id>openmrs-repo</id>

<name>OpenMRSNexusRepository</name>

<url>http://mavenrepo.openmrs.org/nexus/content/repositories/public</url>

<snapshots>

<enabled>false</enabled>

</snapshots>

</pluginRepository>

</pluginRepositories>

</profile>

</profiles>

</settings>

Mavenisacommandlinetool,soopenaconsoleandenterthefolderinwhichtocreateaprojectforyournewmodule.Thecommandyouneedtorunis:

CustomizingOpenMRSwithPlug-inModules

42

mvnmodule-wizard:generate

Followthestepsofthewizardbyansweringthequestions.Attheend,anewMavenprojectwillbegenerated.Tobuildityoujustneedtoentertheprojectfolderandrun:

mvninstall

Youwillfindtheproduced.omodfileforyourmoduleinthedirectoryomod/target.

DevelopingamodulerequiresfromyoutobefamiliarwiththeSpringframework.ReadtheSpringwebsiteathttp://www.springsource.com/formoredetails.TherearealsoafewthingsspecifictotheOpenMRSplatformwhichyouwillneedtoremember:

TheSpringwebcontextfilecanbefoundatomod\src\main\resources\webModuleApplicationContext.xml.

ModulesareabletoaddandmodifytablesintheOpenMRSdatabase.Thefilesomod\src\main\resources\sqldiff.xmlandomod\src\main\resources\liquibase.xmlholdtheSQLcommandswhichcanbeexecutedasamoduleisinstalled.

ModulescanextendOpenMRScoreJSPpagesviaextensionpoints.Amoduleregistersanextensioninomod\src\main\resources\config.xmlforeachextensionpointinthesystemtowhichitwantstoaddcontent.

YoushouldfindextensionpointsintheJSPpagesyouwanttoextend.Lookfor:

<openmrs:extensionPointpointId="..."

Itisbesttolearnbyexample,soyoushouldlookatsomeothermodulesintheOpenMRScoderepositoryforcodesnippetstoreuseinyourownwork.ConsiderexaminingtheWebservices.restmodule.

CustomizingOpenMRSwithPlug-inModules

43

ManagingConceptsandMetadataHavingwell-definedconceptsiscrucialforeveryOpenMRSinstallation.OpenMRSisdeliveredwithjustafewbasicconceptsanditisuptoyoutogathertherest.

Creatingconceptsisacomplextaskwhichrequiresexpertiseandexperiencesowedonotrecommenddoingitonyourown.ItisbesttocontactourcommunityandusesomeofexistingconceptdictionarieslikeMVPorMCL.Formoreinformationonhowtogetintouchwiththerightpeople,seetheGettingHelpfromtheOpenMRSCommunitychapter.

YoucaneitherenterconceptsonyourownmanuallyoruseatoolliketheMetadataSharingModuletoimportthem.Inthischapter,wewillpresenthowtoenterconceptsmanuallyviathewebinterface.

ConceptclassTostartwithyouwillneedtosetupConceptClasses.Thestandardinstallationincludesaround15predefinedconceptclasses.ToviewthementertheAdministrationpage>ManageConceptClasses.

1. AddanewConceptClass

2. ClicktoeditanexistingConceptClass

Youwillseealistwithnamesanddescriptions.Youcaneditthembyclickingonanameandalsodeletebyselectingcheck-boxesnexttotheirnames.Notethatyoucannotdeleteconceptclassesthatareusedinconceptsalready.ThereisalsoalinkAddConceptClasstoenternewones.

Conceptdatatype

ConceptDatatypesarepurposedtoindicatedifferentformatsofdatastoredinconcepts.Theyarepredefinedandread-only.YoucanviewthemunderAdministration>ManageConceptDatatypes.

ManagingConceptsandMetadata

44

Concept

ToviewconceptsavailableinyoursystemclickDictionaryinthetopmenu.YouwillbeabletosearchforparticularconceptsbynameorID.Thereisalsoacheck-boxthatallowstosearchforretiredconceptswhicharenotsupposedtobeusedanymoreorarereplacedwithnewones.YoucanalsoenteranewconceptfromhereclickingAddnewConcept.

ManagingConceptsandMetadata

45

1. Openconceptdictionary

2. Addanewconcept

3. Searchforconcepts

4. Searchresults

Let'screateaconcepttorepresentANTENATALVISITREASON.Wewilluseitlaterinthebookinadataentryform.TheformforcreatingaconceptallowsyoutoenterFullySpecifiedNameaswellassynonyms.YoucanaddsynonymswithAddSynonymbutton[2].AtleastoneofthenamesneedstobemarkedasPreferredwiththeradiobuttonnexttoit.

Whilecreatinganewconceptyouneedtodecideondatatype.Inthiscaseitwillbeacodedconceptthatisyouwillprovidealistofanswers.Answersneedtobedefinedasconcepts.Youneedtocreatethembeforehandorelseaddthemlater.

ManagingConceptsandMetadata

46

1. Switchbetweenlanguages

2. Addasynonym

3. Selectdatatype

4. Editalistofanswers(thissectionchangesdependingonthechosendatatype)

ManagingConceptsandMetadata

47

5. Addmappings

Conceptmapping

ConceptMappingsareaddedtofacilitatemanagingconceptdictionariesandpointtootherconceptswhichhavethesamemeaning.Mappingsareusefulwhenyouneedtoreceiveorsendinformationtoexternalsystems,lettingyoudefinehowyoursystem'sconceptsrelatetoexternalconceptssuchasstandardizedmedicalvocabularies(e.g.,ICD,LOINC,SNOMED).

Forexample,addamappingtoaconceptintheMCLdictionary.Youcansavetheconceptnowandcreatesomeanswers.

RepeatthestepsandcreatetheconceptsPLANNINGPREGNANCYandCURRENTLYPREGNANTofClassFindingandDatatypeBoolean.ThelastpossibleanswerwillbeOTHERofClassMiscandDatatypeN/A.Aftercreatingthreenewconcepts,youcaneditANTENATALVISITREASONandaddthemasanswers.

ConceptdrugToviewConceptDrugs,gotoAdministration>ManageConceptDrugs.Youcaneitherenteraconceptdrugbyclickingitsnametoeditit,oryoucancreateanewonethroughtheAddConceptDruglink.YoumustenteranameandchooseoneoftheconceptsofdatatypeDrug.

MetadataTherearedifferenttypesofMetadatawhichneedtobemanaged.ThelistincludesLocations,EncounterTypes,OrderTypes,etc.YoucanviewandeditthemeasilyviatheAdministrationpage.

Patientidentifier

Apatientidentifierisanyuniquenumberthatcanidentifyapatient.ExamplesareaMedicalRecordNumber,aNationalID,aSocialSecuritynumber,adriver'slicensenumber,etc.Apatientcanhaveanynumberofidentifiers.ThePatientIdentifierTypetabledefineswhattypeofidentifiersarecollectedinyoursystem.

Apatientcanhavemultipleidentifiersofeachtypedefinedinyoursystem.Forexample,apatientcouldhavefiveidentifiersoftypeof"MedicalRecordNumber"becausetheywereseenatfivedifferenthospitalsthatcollectedfivedifferenttypesofIDs.

Thepatientsearchscreensearchesacrossallidentifierthatarestillactiveforapatient.

Newidentifiertypesaregenerallycreatediftheyhavedifferentcharacteristics.Forexample,oneidentifiercanbeonlyastringofnumbers,anotherisanumberwithahyphenplusacheckdigit,etc.

Identifiersuniquelyidentifypatientswithinthesystem.Differenttypesofidentifiersaredistributedbyvarioushealthcaresystems.Someofthesesystemswillbewithinyourcontrol,soyouwillbeabletocontrolhowidentifiersarecreatedanddistributed;however,therewilllikelybeidentifiersthatarenotwithinyourcontrolbutareusefultorecordwithinyoursystemtoaidinpatientidentification.

Inordertoseepredefinedidentifiertypes,ortoaddanewone,gotoAdministration-ManageIdentifierTypes.Let'sexamineOpenMRSIdentificationNumber.

ManagingConceptsandMetadata

48

TheRegexFormatandDescriptionofformatfieldsareempty,butyoucouldaddherearegularexpressiontovalidateeachenteredidentifier.Forexample:

\d{1,8}-\d

wouldallow1to8digitsfollowedbyadashandasingledigit.

Itisalsopossibletochooseoneofseveralpre-definedIdentifiervalidators.HereLuhnCheckDigitValidatorisused.Thepurposeofcheckdigitsissimple.Anytimeidentifiers(typicallynumber+/-letters)arebeingmanuallyenteredviakeyboard,therewillbeerrors.Inadvertentkeystrokesorfatiguecancausedigitstoberearranged,dropped,orinserted.

Checkdigitshelpstoreducethelikelihoodoferrorsbyintroducingafinaldigitthatiscalculatedfromthepriordigits.Usingtheproperalgorithm,thefinaldigitcanalwaysbecalculated.Therefore,whenanumberisenteredintothesystem(manuallyorotherwise),thecomputercaninstantlyverifythatthefinaldigitmatchesthedigitpredictedbythecheckdigitalgorithm.Ifthetwodonotmatch,thenumberisrefused.Theendresultisfewerdataentryerrors.

InternationalizationConceptscanbeeasilyinternationalized;thatisyoucanenterdifferentconceptnamesforeveryallowedlocale.Thelistofallowedlocalesisstoredinasettinglocale.allowed.listascommaseparatedlanguagecodes(forinstanceen,fr,orde).YoucaneditthesettingfromAdministration>Maintenance>Settings.SeethislinkforthefulllistofISO639.2languagecodes:

ManagingConceptsandMetadata

49

https://wiki.openmrs.org/display/docs/Localization+and+Languages

Currently,metadatacannotbeinternationalized.

ManagingConceptsandMetadata

50

SharingConceptsandMetadataWorkingwithOpenMRSformsatHôpitalAlbertSchweitzer,Deschapelles,Haiti.

Insteadofcreatingconcepts,formsandothermetadatayourself,youarehighlyencouragedtousesomewhicharepubliclyavailable.YoucanusecompleteconceptdictionarieslikeMCLorMVPaswellasmetadatapackageswhichincludejustafractionofdictionaries,forms,locations,etc.

Sharingformsentailssharingassociatedconceptsandothermetadata.Tofacilitatethistask,theMetadataSharingmodulewascreated.Itallowsallkindsofmetadata(concepts,forms,locations,roles,programs,etc.)tobeexchangedbetweendifferentOpenMRSinstallations.

Anydependentmetadatawillbepackagedalongwiththeexporteditem.Forexample,ifyouexportaconceptwhichhascodedanswers,themodulewillpackagetheinitialconceptalongwithallthecodedanswerconcepts,classanddatatype.Ifyouexportaform,itwillpackagetheformalongwiththeencountertype,allconceptsusedonthatform,etc.

Theimportprocessisdesignedinawaytohelpidentifyitemsinyoursystemthataresemanticallythesameastheonesincludedinapackagesothatyoucanskipimportingthemanduseyours.

Youcanfindsomepublishedformsat:

https://wiki.openmrs.org/display/RES/Form+Bank

SharingConceptsandMetadata

51

Let'sseeanexampleofimportingaformwiththeMetadataSharingmodule.TheAmaniAntenatalHistoryformwillbepresentedindetailinthe"DataEntry"chapter.

AfterinstallingtheMetadataSharingmodule,gotoAdministration>ImportMetadata.

1. Importanewpackage

2. Seealistofpreviouslyimportedpackagesyouaresubscribing

Tostart,clicktheImportpackagebuttonandonthenextscreen,pointtoafileyouwanttoimport.

1. Choosealocalfileyouwanttoimport

2. EnterasubscriptionURL

SharingConceptsandMetadata

52

Thenextstepistochooseatrustlevel.Asstatedbefore,whileimportingapackageyouwillhaveachancetouseconcepts,locations,etc.whichexistinyoursystemratherthancreatingnewonesfromthepackage.Ifyouchoosetodoso,youcaneitheroverwriteyourexistingitemsorkeeptheonesyoualreadyhave.IfyouchooseRequireConfirmation,youwillbeaskedtoreviewmostofthemetadatabeforeimportinganddecidewhatyouwanttodo.TheTrustIncomingoptioninmostcaseswilldefaulttooverwriteyourexistingmetadataandwillnotrequireconfirmation.ClickNexttoproceed.

1. Itemsneedingassessment

2. Itemstobecreated

3. Itemstoskip

4. Itemsinyoursystemwhichwillbeusedinstead

5. Itemswhichwillbeoverwritten

6. Openstheassessmentscreen

7. Allitemsinthepackage

Onthenextscreen,youwillseesomedetailsaboutthepackageandclickingNextagainwillbringyoutotheImportSummarypagewhereyoucanassessitems.Asinourexample,youwillhavetoreviewtwenty-nineconcepts.

SharingConceptsandMetadata

53

TheassessmentscreendependingonthecaseallowsyoutochooseCreateNew,SkipifPossible,ChooseExisting-KeepMine,andChooseExisting-Overwrite.IfyouselectChooseExistingyouwillbeabletosearchforanexistingitemonyoursystembyclickingChoosereplacement.Inthisexample,youcannotselectCreateNewasitwouldviolatearestrictionthattherecannotbetwoconceptsinthesystemwiththesamename.

Oncereviewingalltheitemswhichneedtobeassessed,youcanimportthepackage.

SharingConceptsandMetadata

54

AgoodsourceofconceptsistheMaternalConceptLab:

http://www.maternalconceptlab.com

Itallowsyoutofindconceptsyouneedanddownloadthemasmetadatapackages.YoucanthenimportthemdirectlytoyourOpenMRSinstallationasneededwiththehelpoftheMetadataSharingmodule.

TheMetadataSharingmodulepromotesdecentralizedmanagementofmetadatawhereeveryonecanbothcreateandimportmetadatapackages.

SharingConceptsandMetadata

55

ConfiguringVisitsApatientmayreceiveseveralkindsofcareandserviceswhileatahealthclinic.Forexample,theymayseeaclinician,haveanX-raytaken,andbegivenalabtest.EachoftheseservicesisanEncounter,recordedinaform.OpenMRSusesVisitstocollecttheserelatedencountersintoonegroup.

VisitsaremanagedinAdministration>Visits.Hereyoucandefinethekindsofvisitsandtheirattributes,andsetthedefaultbehaviorforhowvisitsarecreated.

ManageVisitTypes

AVisitTypeisanameanddescriptionofakindofvisit.Everyvisithasatype.Youshouldcreatevisittypesthatmatchhowyourhealthsiteclassifiesvisits,suchas"Outpatient,""Hospitalization,""Dental,""PatientEducation,"or"TBClinic."

ManageVisitAttributeTypes

Ifyouwishtorecordextrainformationaboutvisits,youcancreateVisitAttributesandassignthemtoVisitTypes.Forexample,youmightcreateattributesfor"FollowupVisit,"or"DistancePatientTraveled."

ConfigureVisits

ThereareseveralsettingsfortheVisitfeature.

Visitisenabledbydefault,butisanoptionalfeature.WhileVisitisenabled,thepatientdashboardwillshowatabcalledVisitsandgroupallencountersbyvisit.Ifdisabled,thepatientdashboardwillshowtheEncounterstabandlistencounterschronologicallywithnogrouping.

Avisithasastarttimeandanendtime.Thestartdateandtimeisautomaticallysetwhenavisitiscreated.Theenddateandtimeisleftblankbydefault.Itissetmanuallybyadataclerk.

TheStartautoclosevisitstaskoptionchangesthis.Ifenabled,auto-closewillautomaticallysettheenddatetothestartdate,andtheendtimeto23:59.

Auto-closeisusefulforvisittypesthatneverlastmorethanaday,suchasoutpatientordentalvisits,orwheretheexactendtimeisn'timportant.Auto-closeisnotrecommendedforvisittypesthatlastmultipledays,suchashospitalization,orwhereanexactdurationmightbeimportant,suchasanemergencyroomvisit.

ConfiguringVisits

56

TheEncounterVisitHandlercontrolsvisitcreationandencounterassignmentwhenanencounteriscreated.Thedefaultoptionwillautomaticallylinktheencountertoamatchingvisit,orcreateoneifnoneexists.Tomatch,avisitmustbeatthesamelocation,andtheencounterdatesmustbebetweenthevisitstartandendtimes.ThesecondoptionassignsanencountertoamatchingVisitifoneexists,butdoesnotcreateanewone.Thethirdoptionwillnotassignencounterstoanything.

TheEncounterVisitHandlerwillonlyaffectnewencounters,andonlywhileenabled.Itdoesnotaffectexistingvisits.Ifyouturnthefeatureoff,orifyouupgradefromanearlierversionofOpenMRS,itwillnotretroactivelycreatevisits.

ConfiguringVisits

57

ThePatientDashboardInDepthThePatientDashboardistheplacetovieworeditapatientrecord,andaddnewVisitsandEncounters.

ThePatientDashboardappearancemaybechangedbymodules.Thischapterwillshowthedashboardasitlookswithoutmodules.

FindingorCreatingaPatient

Tobegin,wemustfindorcreateapatient.ThisisdonefromtheFind/CreatePatientlinkonthetopmenu.

CreatingpatientsisexplainedintheRegisteringPatientschapter.

Header

Theheaderbarappearsatthetopofthedashboard.Itcontainsasummaryofsomepatientdetails:name,IDnumber,gender,ageandbirthdate,weight,andregimen.Therewillbealinktoanyvisitinprogress.Ifnovisitsareinprogress,onecanbebegunwiththeStartVisitbutton.

OverviewTab

ThePatientDashboardInDepth

58

TheOverviewtabonthePatientDashboard.

TheOverviewtabgivesaccesstoseveralpatientfeatures.

IfapatientisamemberofanyProgram(configuredinAdministration>Programs),itwillbedisplayedhere.

TheExitPatientfromCarebuttoninthePatientActionssectionwillendthepatient'sparticipationinanyprogram.

TheRelationshipstabshowsrelationshipsbetweenthePatientandotherpatients,providers,orusersintheOpenMRSinstallation.Thedefaultrelationshiptypesincludeparent-child,sibling,doctor-patient,andaunt/uncle-niece/nephew.YoucanaddrelationshiptypesinAdministration>Person>ManageRelationshipTypes.

AllergiesarelistedintheAllergiesbox.

UsetheProblemListtohighlightongoinghealthproblems.

RegimensTab

ThePatientDashboardInDepth

59

TheRegimenstabonthePatientDashboard.

TheRegimenstabshowsapatient'scurrentandcompletedtreatmentregimens.

Visits/EncountersTab

TheVisits/EncounterstabonthePatientDashboard.

TheVisitstabshowsallofthepatient'sencounters,groupedintovisits.IftheVisitsfeatureisdisabled,thetabwillbenamedEncounters.

Tostartanewvisit,clicktheAddVisitlinkintheVisitstab,ortheStartVisitbuttonintheheader.

ThePatientDashboardInDepth

60

Toviewavisit,clickthelinkwiththevisit'sname.Ifauserhaseditingprivileges,thevisitwillopenineditmode.

Avisit,openedineditmode.

Ineditmode,youcanaddorremoveencountersfromthevisit.

Toviewanencounter,returntoPatientDashboard>Visitstab.ClickontheViewicontotheleftoftheencounter.Ifauserhaseditingprivileges,theencounterwillopenineditmode.

Anencounteropenedineditmode.Forthisexample,weusedtheFormEntrymoduletocreateanddisplaytheencounter.

ThePatientDashboardInDepth

61

DemographicsTab

Viewthepatient'saddressandnamesfromtheDemographicstab.TheEditPatientlinkswillletyoueditthepatient'sinformation,includingidentifiers,birthanddeathdates,andrelationships.

TheDemographicstabonthePatientDashboard.

GraphsTab

TheGraphstabcandisplaygraphsofpatientinformationsuchasCD4counts.

FormEntryTab

TheFormEntrytabonthePatientDashboard.

Toaddoreditencounters,selecttheFormtab.Thelastthreeencountersarelistedatthetop.

Toaddanewencounter,selectaformfromtheEnterFormbox.FormsetupanduseisdescribedinmoredetailinthechaptersonDataEntry,HTMLForms,andXForms.

ThePatientDashboardInDepth

62

ThePatientDashboardInDepth

63

RegisteringPatientsInordertobeabletofilloutformsforapatient,youmustfirstcreateaPatient.Often,aregistrationclerkordataentryclerkwillcreatepatientsinthesystem.Youshoulddecidewhichmodelworksbestforyourclinic,topreventduplicationofrecords.

YoucancreatepatientsbyclickingFind/CreatePatientinthetopmenu.

ThefirststepincreatingapatientrecordistofillouttheshortCreatePatientform.Afterenteringthenecessaryinformation,clickonCreatePerson.Youcanentermoredetailsonthenextscreen.

RegisteringPatients

64

FamilyName,IDNumber,andIdentifierTypearerequired.Identifiertypeisdiscussedindetailinthe"ManagingConceptsandMetadata"chapter.

ClickSavetogotothePatientDashboardscreen,whereyoucanseeallthedetails,forms,etc.forthenewlycreatedpatient.

RegisteringPatients

65

DataEntry

Anelectronicmedicalrecordssystemhasmanyadvantagescomparedtoatraditionalpaper-basedsystem.Dataiscollectedusingelectronicforms,andastandardtemplatemeansthateachuserseesthesamestructure,simplifyingtherepresentationoftheunderlyinginformationstructureandcomplexity.Electronicformsalsoallowforbasicdatavalidation.

Anadministratormustdesigntheformtemplatesthatdataclerkswilluse.TherearethreeformsmodulesinOpenMRS.AnOpenMRSinstallationmayusemorethanonestyle,butforsimplicity,it'srecommendedyoubeginwithone.Theyarecomparedbelow.

FormType Advantages Disadvantages

HTMLForms

EasytouseOngoingdevelopmentofnewfeaturesSupportscomplexlogicoperationsExtendableAllowsreviewofformsaftersubmission

RequiresHTMLknowledgeNotsupportedonmobiledevices

XFormsOpensourceEasytouseWorkswellonmobiledevices

Doesnotsupportsomecomplexlogicoperations

InfoPathOriginalapproachtodataentryviaformsOthersmayalreadybefamiliarwiththetechnology

NotopensourceRunsonlyonWindowsRequirespaymentoflicensefeesNonewdevelopmentbytheOpenMRSteam

DataEntry

66

ThenextchaptersdescribeHTMLFormEntryandXFormsinmoredetail.

InfoPathforms,createdwiththeFormEntrymoduleandMicrosoftInfoPath,arenotrecommended.MicrosoftInfoPathisproprietarysoftware,andtheformsaredifficulttotroubleshoot.InfoPathformswillcontinuetowork,buttherewillbenonewdevelopment.

DataEntry

67

HTMLFormsThischapterwilldiscussonlytheHTMLFormentrymethod.Thisisthesimplestandmoststraightforwardapproachtodataentry.ItissupportedbytheHTMLFormEntrymodule,whichisincludedwiththedefaultdistributionofOpenMRS.

BasicHTMLformstructure

EveryHTMLformmusthavethefollowingminimalelements:

<htmlform>

<p>Dateofencounter:<encounterDate/></p>

<p>Healthcenter:<encounterLocation/></p>

<p>Clinician'sname:<encounterProviderrole="Provider"/></p>

...

<p>Nameofobservation:<obsconceptId="x"/></p>

<p><submit/></p>

</htmlform>

Formheader

Itiseasiesttoleavetheseessentialelementsinaformheadersectionthatyoure-useatthetopofeachform.Themandatoryobservationelementisincludedbelow.

Casestudy:AmaniClinic

ThecliniciansattheAmaniClinicneededawaytocapturepatienthistoryaspartoftheirmaternalandchildhealth(MCH)program.TheyhadbeenincontactwiththeMilleniumVillagesProject(MVP)viatheOpenMRSimplementersmailinglist.MVPstaffsharedtheirAntenatalVisitform.TheimplementationteamdecidedtousetheHistorysectionfromtheMVPformasabasisfortheirMCHhistoryform.

TheMVPAntenatalHistorysectionlookedlikethis:

HTMLForms

68

Step1:Identifyandcreateconcepts

Beforeyoucreateaform,youmustensurethatallreferenceconceptsarepresentintheconceptdictionary.BecausetheMVPteamalreadyhadaconceptdictionary,theAmaniClinicwereabletoimporttheconceptstheyneeded.Ifyoudon'thaveaccesstoanappropriateconceptdictionary,youcanalsocreatenewconceptsdirectly,followingthestepsoutlinedinthechapterManagingConceptsandMetadata.

TheMVPformincludedfourteendifferentQuestionConcepts,aswellasAnswerConceptsfor[1],[3],[6],[9],[11],[13],and[14].

Step2:Createtheform

Tocreateaform,clickontheManageHTMLFormslinkontheAdministrationpage.

HTMLForms

69

ClickNewForm.

EnterthebasicforminformationandclickSave.

Step3:CreatevisualformstructurewithHTML

HTMLformsallowyoutocreateastructurethatcloselyresemblesyourpaperforms,althoughitmaynotbepreciselythesame.

ThedegreetowhichyourformresemblesthepaperformdependsonyourHTMLlayoutskills--allHTMLtagsaresupported.Tablelayoutisbeyondthescopeofthisguide,buttherearemanyresourcesavailableonline.

ThisisthebasicstructureoftheexampleHTMLform,withaplaceholderlabelinsertedforeachobservation:

HTMLForms

70

Step4:Insertobservationelements

Next,insertaformtagforeachobservationinyourforms.TheseobstagsarenotHTMLtags,butarerequiredbyOpenMRS.Thefollowingsectionsprovideexamplesofeachconceptdatatypeusedontheexampleform.TheHTMLFormEntrymoduleprovidesawidevarietyofothertags.PleaseconsulttheHTMLFormreferenceonthewikiforfulldocumentationalongwithotherexamples.

https://wiki.openmrs.org/display/docs/HTML+Form+Entry+Module+HTML+Reference

Note:TheConceptIdentifiernumbersusedinthisexamplewillnotmatchtheConceptIdentifiersinyourlocalOpenMRSinstance.

Example1:Dateobservation

ToinsertaDateObservation,includetheQuestionConceptIDofanydate-basedConcept.TheformattinglabelbehindtheDateBoxcannotberemoved.

<table>

<tr>

<td>

<b>LastMenstrualPeriod:</b>

</td>

<td>

<obsconceptId="1427"/>

</td>

</tr>

</table>

Example2:Booleanobservation

HTMLForms

71

ToinsertaBooleanobservation,includethequestionconceptIDofanybooleanconcept.ThereareseveraldifferentstylesavailableforBooleantypes.

...

<table>

<tr>

<td>

<b>High-RiskSex:</b>

</td>

<td>

<obsconceptId="1355"style="yes_no"/>

</td>

</tr>

</table>

....

Example3:Codedobservationwithradiobuttons

Thisobselementisinsertedwiththeradiobuttonstyle.YoumustspecifyeachanswerconceptIDeventhoughtheyarealreadyrecordedinthesystemasanswersforthequestionconcept.Ifyouwanttouseanameotherthantheconceptnameforananswerconcept,youmustincludetheanswerconceptlabel.

Torendertheradiobuttonsvertically,insert<br\/>attheendofeachlabelforthepreviousbutton.

...

<table>

<tr>

<td>

<b>ReasonForVisit:</b>

</td>

<td>

<obsconceptId="1433"style="radio"answerConceptIds="1435,1434,5622"answerLabels="PlanningPregna

ncy&lt;br\/&gt;,CurrentlyPregnant&lt;br\/&gt;,Other"/>

</td>

</tr>

</table>

...

Example4:Codedobservationwithmulti-selectcheckboxes

HTMLForms

72

Thisobselementisinsertedwiththecheckboxbuttonstyle.YoumustspecifyeachAnswerConceptIDeventhoughtheyarealreadyrecordedinthesystemasanswersforthequestionconcept.Ifyouwanttouseanameotherthantheconceptnameforananswerconcept,youmustincludetheanswerconceptlabel.

Eachcheckboxselectedactuallyrepresentsanindividualobservation;thequestionconceptiscommonbuteachanswerconceptisunique.

...

<table>

<tr>

<td>

<b>RecentContraceptiveUse:</b>

<br/>

<obsconceptId="1635"answerConceptId="1107"answerLabel="None"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="780"answerLabel="OralContraception"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="190"answerLabel="Condoms"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="5277"answerLabel="NaturalPlanning/Rhythm"style="checkbo

x"/>

<br/>

<obsconceptId="1635"answerConceptId="5278"answerLabel="Diaphragm"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1378"answerLabel="Depo-Provera"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1359"answerLabel="Norplant"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1388"answerLabel="Surgery"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="5622"answerLabel="Other"style="checkbox"/>

<br/>

</td>

</tr>

</table>

...

Completeform

HTMLForms

73

SeeAppendixBforFullHTMLsource.

EnterPatientDataUsinganHTMLForm

ClickonFind/CreatePatientfromanywherewithinOpenMRS.

Begintypingthepatient'sIDnumberorname,thenselectthepatientforwhomyouareenteringdata.

ClicktheFormEntrytab.

HTMLForms

74

Selecttheappropriateformasshownbelow,thenfillinthepatientdataandclicktheEnterFormbuttononthepagethatappears.

YoucannowseethecompletedformundertheFormEntrytabofthepatient'schart.

HTMLForms

75

XFormsThischapterwillexplainanddemonstratetheuseoftheXFormsModuleforpatientdataentry.

WhatanXFormis

XFormsisanXMLformatforspecifyingadataprocessingmodelforXMLdataanduserinterface(s)fortheXMLdata,suchaswebforms.XFormswasdesignedtobethenextgenerationofHTML/XHTMLforms,butisgenericenoughtouseinastandalonemannerorwithpresentationlanguagesotherthanXHTMLtodescribeauserinterfaceandasetofcommondatamanipulationtasks.

Whatthismoduledoes

AllowsdataentrytobedonedirectlyfromanyJavaScriptenabledbrowser.

Enablesyoutoreplacethedefaultpatientregistrationformwithacustomonewithoutanyprogramming.

Letsyouenterobservationsduringpatientregistration.

Supportsuploadingofpicture,sound,andvideofilestogetheranddisplaysandplaysthem.

LetsyoudesignXFormsusingabrowser-basedformdesigner.

ServesOpenMRSformsasXFormstoexternalapplications.

Servesusersandpatientsets,includingmedicalhistory,toexternalapplications.

AcceptsformdatasubmittedfromexternalXFormsapplications.

SupportscreationofpatientsandentryofobservationsforbothnewandexistingpatientsusingbasictextSMS.

Whatitdoesn'tdo

GiveyouasmuchflexibilityastheHTMLFormEntrymodulewhenitcomestotheformlayoutandlooks.

SomefeaturespresentintheHTMLFormEntrymodulearenotyetimplemented(e.g.:relationships).

CreatinganXFormIntheAdminpage,undertheFormssectionselectManageForms.

XForms

76

CohortBuilderTheCohortBuilderisatoolintheReportingCompatibilitymodule(includedwithmostOpenMRSinstallations)thatletsyouperformad-hocqueriesforpatientswithdefinedcharacteristics,andcombinesmultiplequeriesintomorecomplexones.

Acohortqueryreturnsalistofpatientsmatchingthespecifiedcriteria.CohortBuildercannotcreatelistsofdataelementsotherthanpatients.Forexample,youcanusethecohortbuildertosearchforallpatientswithanyweightobservation>70,butitisnotpossibletocreatealistofallobservationsofweight>70.

Tousethistool,clickCohortBuilderatthetopofanypage.

Cohortdefinitions,cohorts,andsearchhistoryEachPatientSearchisaddedtoyoursearchhistory.Thishistoryispreserveduntilyouchoosetoclearitorthewebapplicationisrestarted.Youmayalsosaveyoursearchhistorytopreserveitforfuturere-use.

Youmaysaveanysearch(simpleorcombined)asaCohortDefinitiontomakeiteasiertore-runthatsamesearchinthefuture.Whenyousaveacombinedsearch,itincludescopiesofallitscomponentsearches.

YoumayalsosavethelistofpatientsresultingfromaqueryasaCohort.Thelistofmembersinasavedcohortwillneverchange.Ontheotherhand,runningasavedsearchagainmayproducenewresults.

Theinitialscreenofthecohortbuildercontainsseveralsections:

1. Thetoptabsallowyoutorundifferentkindsofqueries.

2. Eachqueryyouperformgoesintothesearchhistory.

3. TheSave,Load,andClearbuttonshelpkeepyourentiresearchorganized.

4. Afterrunningaquery,cohortmembersaredisplayedhere.

5. ClickthisSavebuttontosavethiscohortforfuturere-use.

6. ClicktheseSavebuttonstosaveapreviousqueryasacohortdefinitionforfuturere-use.

7. Usethelinkatthetopofthecohortbuildertoloadsavedcohortsandcohortdefinitions.

CohortBuilder

77

Searchingbyobservation

Tosearchforpatientswhohaveobservationsmatchingcertaincriteria,choosetheConcept/Observationtab.Starttypingthenameofaconceptthatyouwanttosearchfor[1],andchoosethatconceptfromthesearchresults[2].

IfyouchooseaconceptwhosedatatypeisanythingotherthanN/A,youcansearchforobservationswhosequestionistheconceptyouselected[3].Dependingonthedatatype,youcanlimitthistoanumericordaterange,ortospecificcodedanswers.Youcanalsochoosewhichobservationsyouarelookingfor(first,last,min,max,any,none)orcombine(average),andyoucanspecifydateranges.

Thisexamplewillbuildacohortofpatientswhoselastsystolicbloodpressuremeasurementwasabove130mmHg:

CohortBuilder

78

Youcanalsosearchforanyobservationsthathaveyourchosenconceptasananswer.(You'dtypicallyusethisfordoingahighlyselectivesearch,whichyou'lllaterfilterdowntosomethingmorespecific.)

InthisexamplewesearchforpatientswhohaveanyobservationwhoseanswerisHypertension,whichmightincludebothconfirmeddiagnosesofhypertensionaswellasconsultstoruleoutHypertension:

Searchingbydemographics

SelectthePatientAttributestabtosearchbasedonsimpledemographiccharacteristics:gender,age,birthdate,andvitalstatus.

CohortBuilder

79

Inthisexample,wesearchforlivingmalepatientsbetween45and65yearsold:

Searchingbyencounters

SelecttheEncounterstabtosearchforpatientsbasedonencounterstheyhavehad.Youcansearchbyencountertype(control-clicktoselectmultipletypes),location,theformwithwhichtheencounterwasrecorded,dateranges,andthenumberofmatchingencounterstolookfor.

Inthisexamplewesearchforpatientswhohavehadatleast3encounterswhosetypeswereeitherADULTINITIALorADULTRETURN:

Searchingbyprogramenrollments

CohortBuilder

80

SelecttheProgramEnrollmenttabtosearchforpatientsenrolledinaparticularprogram,orpatientswhohaveaparticularstatus.

Inthisexample,wesearchforpatientswhohaveeverbeenintheHypertensionProgram:

CombiningsearchesAfteryouhavedoneseveralsearches,theCompositiontaballowsyoutocombinethemusingBooleanalgebra.YoucanuseAND,OR,NOT,orparenthesestobuildcomplexcombinationsoftheothersearchesinyourhistory.RefertoyourprevioussearchesusingthenumbernexttothemintheSearchHistorysection.

Here,wesearchforpatientswhomatchacombinationofthepreviousexamplequeries:

CohortBuilder

81

ReportingThischapterdescribeshowtousetheReportingmoduletoproduceasimplereportonseveralindicators--thetypeyoumightuseformonitoringandevaluatingaprogram.

Althoughthischapterwillcoverthebasics,asyourOpenMRSimplementationgrows,you'llwanttotakeadvantageoftheReportingmodule'sadditionalfeatureslike:

Multipletypesofindicator-basedreports

Quickwaystobreakdownindicatorsbasedongender,agegroups,etc.

Severalkindsofpatientreports

Theabilitytoscheduleregularreporting

EasyformattingoptionsforprintedoutputusingExceltemplates

AnAPIthatJavadeveloperscanextendtoaddcustomreports,indicators,anddisplays.

Themodule'sfullfunctionalityisbeyondthescopeofthisbook.YoucanfindfurtherdocumentationontheOpenMRSWiki:

https://wiki.openmrs.org/display/docs/Reporting+Module

ThischapterfollowsaftertheonesonDataEntry,becauseyoucannotactuallybuildreportswithoutsomedatatorunthemon.Butwhileplanningtheprojectyoushouldfollowthebestpracticeofdeterminingwhatoutputsyouwant,andworkingbackwardsfromtheretodeterminetheminimalsetofdatathatyouneedtocollecttoproducethoseoutputs.

Backgroundandterminology

ThereportingmoduleisbuiltaroundtheideaofDefinitionsthatareevaluatedtoproduceoutput.

Reportsanddatasets

IngeneralaReportDefinitioncanhavemultipleDataSetDefinitions.Whenrun,thiswillproduceareportwithmultipledatasets,whichisrenderedtoaformatchosenbytheuser.

Cohorts

AlmostallreportsproducedwithOpenMRSrefertogroupsofpatients.Areportmayberunondifferentpatientgroups,orrequireidentifyingorcountingsub-groupsofpatients.Themoduleletsyoudefinecohortqueries(asdiscussedinthechapter"CohortBuilder").Whenthereportisrun,thesequerieswillbeevaluatedtoproduceactualcohortsofpatients.

Indicators

Inthischapter,welookatareportthatisbasedonIndicators,andspecificallyindicatorsthatlookatthecountofpatientsinacohortinaperiodoftime.

Parametersandmapping

UnlikeintheOpenMRSCohortBuilder,reportsandtheirunderlyingqueriesareintendedtobecreatedonce,andreused.Tosupportthisidea,reportsandqueriesusuallytakeparameters.Forexample,areportintendedtoberunmonthlywouldhaveStartDateandEndDateparameters,andtheuserwouldbeaskedforthesewhentheygeneratethereport.

Reporting

82

Theunderlyingqueriesinthereportalsotypicallytakeparameters.IfthereportisgoingtodisplaythenumberofpatientsenrolledintheChildNutritionStudyattheendofagivenmonth,itwouldneedtohaveanunderlyingCohortQueryfor"patientsenrolledinChildNutritionStudyonadate."p;[/0"+{}hatdatewouldbeanEffectiveDateparameter.

Whentheuserrunsthereport,theyareaskedforaStartDateandanEndDate,buttheyarenotaskedtospecifyanEffectiveDate.Whendesigningthereport,youwillneedtodefinehowparametersintheunderlyingqueriesobtaintheirvalues,basedonthevaluesprovidedbytheuserwhenrunningthereport.Thisprocessiscalledmapping.

Theideaofmappingparametersiscomplicated.Thefollowingresourcesincludemoreinformationaboutwhyitisnecessary,andhowtodoit:

http://om.rs/bookmapping

http://om.rs/bookmapvid

AmaniClinic'sweeklyreport

BeforeadoptingOpenMRS,AmaniClinicusedtospendsignificanttimeattheendofeverymonthtabulatingpaperregistersandpatientchartstoproduceamonthlyreportfortheMinistryofHealth.WhenplanningtheirOpenMRSimplementation,theydecidedthattoimprovetheirprogram,theyneededmoreimmediatefeedback.TheclinicandMinistryofHealthmetanddecidedonfiveindicatorsonwhichtheywantedareporteveryweek.Theymodifiedtheirpaperdatacollectionformstomakesurethattheywerecapturingtherightdatatoproducethoseindicators,aswellastheperiodicMinistryofHealthreports.

We'llfocusontwooftheindicatorstheycalculated:

1. Numberoffemalepatientsseenduringtheweek,and

2. Thepercentageofthosewhowere>16yearsold,notpregnant,andusingappropriatefamilyplanning

DefiningtheUnderlyingCohortQueries

Calculatingthefirstofthoseindicatorswasverystraightforward:theydefinedthistobeanyfemalepatienthavinganencounterbetweenthestartandendoftheweek.

Thesecondindicatorwasmorecomplicated:theyhadtobreakdownboththenumeratorandthedenominatorintomultiplecohortqueries.Forthedenominatortheyneeded:

Notpregnant("noobsforEstimatedDateofConfinementwithavalueinthefuture")

Female

Age>16attheendoftheweek

Hadanencounterduringtheweek(sameasthequeryforthefirstindicator)

Thenumeratorrequiredjustonemorecohortquery,forpatientswhoself-reporteduseofcontraceptivemethodsotherthan"NaturalPlanning/Rhythm"duringtheweek.

Reporting

83

Buildingthereportintheuserinterface

Havingdeterminedhowtocalculatetheirindicators,theyproceededtobuildthemintheReportingmodule'suserinterface.First,theybuiltthelow-levelqueries[1].Theythencomposedthetwoindicatordefinitions[2]fromthosecohortqueries.Finally,theycreatedareportdefinition[3]thatincludedthetwoindicators.

BuildingcohortqueriesTheCohortQuerymanagementpageshowsyouthedifferenttypesofqueriesavailable.Clickingonanyofthe[+]linksletsyoucreateanewqueryofthattype.

ThesimplestquerybuiltbyAmaniClinicincludedonlyfemalepatients:

Therestofthequeriesneededtoincludeparameters.Forexample,thequerytofindpatientswithanyencounterbetweentwogivendates,the"onorafter"and"onorbefore"fieldsweresetasaParameter[1]anduser-friendlynames"StartDate"and"EndDate"wereprovided.

Reporting

84

SomeofthequeriesbuiltinthisexampleincludedparametersthatwerenotdirectlyequivalenttotheStartDateandEndDateofthereport.The"notpregnant"querywasaDateObservationQuerythatincludedasingleparameter,whichtheylatermappedtotheEndDateofthereport.

Reporting

85

Combiningcohortqueries

AfterAmaniClinicstaffcreatedtheunderlyingqueriesthattheirreportrequired,theybuiltseveralCompositionCohortQueriestotiethemtogether.Themostcomplicatedquerycalculatedthedenominatorofthesecondindicator,"non-pregnantwomen,age>16,seenduringtheweek."

Thisistheircompositionquery,whichincludesthetwoparametersStartDateandEndDate.Itincludesfourunderlyingqueries,withvaluesinthosequeriesmappedtothesetwoparameters.Finally,thequeriesarecombinedwithANDtorunthemalltogether.

Here,weseethesevencohortqueriestheybuilt:

Indicators

Havingbuiltcohortqueriestodotheunderlyingcalculations,theyusedthesetobuildthetwoindicators.TheIndicatorspageisaccessedfromtheManageReportDefinitionssectionoftheAdministrationpage.

Reporting

86

Sinceindicatorsaregenerallycalculatedoveratimeperiod,ataparticularlocation,theindicatorstheycreatedcontainthedefaultStartDate,EndDate,andLocationparameters.(SincetheAmaniClinicwasonlymanagingasinglesiteinOpenMRS,theyignoredtheLocationparameter.)

Countindicators

ThesimplesttypeofindicatorisaCountindicator,whichcountsthenumberofpatientswhomatchacohortquery.

TheyusedaCountindicatortobuildtheirfirstindicator,shownbelow.Theunderlyingcohortqueryisacompositionqueryincluding"Females"and"AnyEncounterBetweenDates."

Fractionindicators

ThemostusefultypeofindicatorformonitoringprogramprogressistheFractionindicator,whichtakestwocohortdefinitions,representinganumeratorandadenominator,anddisplaysthisasafraction.(Itensuresthatthenumeratorpatientsareasubsetofthedenominator.)

AmaniClinicbuilttheirsecondindicatorasafractionindicator.TheunderlyingcohortqueryforthenumeratorwasasimpleCodedObservationQuery,whilethedenominatorwastheCompositionQuerydescribedabove.

Periodindicatorreport

Havingcreatedtheirindicators,theybuiltareportthatcombinedthem.TheyusedaPeriodIndicatorReport,whichisasimplewaytoshowtheindicatorsyouhavealreadydefined.

Reporting

87

Runningthereport

Torunthisreport,theAmaniClinicdatamanagerclickstheReportinglinkonthetopofthescreenandselectstheProgramMonitoringReport.Theymustenterthestartandenddateoftheweekforwhichtogeneratethereport.

Theoutputofthereportincludesclickablelinkstothelistsofpatientsmatchingeachindicator.

Reporting

88

PatientAlertsandFlagsIt'simportanttoactivelyuseyourdatatoprovidefeedbacktousersofthesystem,bothforclinicalpurposesanddataqualitypurposes.OnewaytodothisiswiththePatientFlagsmodule,whichcandisplayFlagsonapatientdashboardwhencertaincriteriaaremet,andtofindallpatientsthatmatchasetofcriteria.Wewillbrieflydescribethismodulehere,butyoucanfindfurtherdocumentationatthefollowinglocation:

https://wiki.openmrs.org/display/docs/Patient+Flags+Module

Usingthismodulerequiressignificanttechnicalknowledge.ThischapterassumesthatyouarefamiliarwithCSS,SQL,Groovy/Java,andtheOpenMRSAPI.

First,youneedtoinstallPatientFlagsmodulefromtheOpenMRSmodulerepository,andthengotoitssectionontheAdministrationpage.First,definecategoriesofalerts[1].Then,youcandefinelogicandmessagesforthesealerts[2].

CategorizingflagsbyprioritiesFromtheManagePrioritieslink,youcandefinedifferentcategoriesofalerts,eachofwhichcanbedecoratedwithcustomCSS.

Inthisexamplewedefinetwodifferentcategoriesofalerts,themorecriticalofwhichwillbehighlightedinorange,andtheotheringray.Notethatyouneedtoincludethestyle="..."inyourstyleproperty.

Definingflags

Tosetupaflag,youneedtodefineacalculationthatreturnsthecohortofpatientsforwhomtheflagshouldbeshown.Therearemultiplewaystodothis,eachrequiringadifferenttypeoftechnicalknowlege.

Allflags,regardlessofhowtheyarecalculated,letyouspecifytextandaPriority.Thetextisdisplayedonapatientdashboardforpatientstowhomtheflagapplies,andthePrioritycontrolstheformattingoftheflagifdisplayed.

Finally,youcandecidewhetherflagsareReal-Time,whichmeansthattheflagstobedisplayedarecalculatedwheneveryouviewapatientdashboard.Ifyoudon'tmakeaflagreal-time,youcanstillexecutetheflagcalculationsondemandasabatch.

SQLflags

PatientAlertsandFlags

89

ThecalculationbehindthistypeofflagisaSQLstatementthatwillbeexecutedagainstthedatabase,andmustincludeaselect(something).patient_id...statement.Theresultsofthisquerywillbeintersectedwithallnon-voidedpatientstoproducetheCohortfortheflag.

ManysystemadministratorsknowhowtowriteSQLqueries,andovertimetheybecomefamiliarwiththeOpenMRSdatamodel,makingthistypeofflagveryaccessible.Atthesametime,writingthistypeofflagcanbeerror-prone.Thereisnothingtopreventyoufromomittingaclause,suchastoensureyouareonlylookingatnon-voideddata.

Inthisexamplewearesearchingforallpatientswhohavecarriedatleast4pregnancies.

SinceSQLflagsmustinclude.patient_idintheirselectclause,wehavetojointheobstableagainstthepatienttable,eventhoughwearen'tusingthattable.

Groovyflags

ThemostpowerfultypeofflagallowsyoutowriteGroovyorJavacode,whichcancallOpenMRS'sJavaAPIandperformcomplexcalculationsonpatientdata.TheadvantageofwritingflagsinGroovyisthattheOpenMRSAPItakescareofdetailslikeensuringyouareonlygettingnon-voideddata.ThelimitationisthatmostmanagersofOpenMRSsystemsdonotknowhowtowriteGroovy/Javacode.

AGroovyflagreturnsacohortofallpatientsthatmatchthecalculation.Inthisexamplewefindallpatientswhoareexpectedtogivebirthinthenext3months,butwhohave_not_hadanencounterinthelast3months.

PatientAlertsandFlags

90

PatientAlertsandFlags

91

UserManagementandAccessControlRolesandPrivilegesarecontrolledthroughtheAdministrationpage,undertheManageUserssection.

OpenMRSusesprivilegesandrolestocontrolaccesstodatawithinthesystem.Privilegesdefinewhatcanorcannotbedoneinthesystem(e.g.,EditPatientsorAddUsers),whilerolesareusedtogroupprivilegesintomoremanageablegroupings.Tomakethesystemeasiertomanage,rolescancontainotherrolesaswellasprivileges.Rolesinheritalltheprivilegesoftheirparentroles.

Wewillusethisexample:youareworkingwithseveralprivilegesrelatedtopatientdata—e.g.,ViewPatients,EditPatients,andAddPatients.TheViewPatientsprivilegeletsuserslookatpatientsinthesystem,theEditPatientsprivilegeletsuserseditinformationaboutexistingpatients,andtheAddPatientsprivilegeallowsuserstocreateacompletelynewpatientrecordwithinthesystem.

Nowimaginethatyouneedtoassigntheproperrulestothreepeople:MarytheMedicalStudent,BobtheDataAssistant,andEricatheDataManager.Youwantmedicalstudentstobeabletoviewpatients,butnoteditoraddthem.Dataassistantsshouldbeabletonotonlyview,butalsoeditpatientdata.Andyouwantyourdatamanagerstobeabletocreatenewpatientswithinyoursystem.

Designingroleandprivilegeschemes

Inordertogivetheseprivilegestotherelevantusers,youmustdefinearoleforeachofthesetypesofuser.

Role Privilege(s)

MedicalStudent ViewPatients

DataAssistantViewPatients

EditPatients

DataManager

ViewPatients

EditPatients

AddPatients

Now,bydefiningthemainrolesforusersofyoursystemandassigninguserstothoseroles,youhaveamucheasiersystemtomanageanduserswillautomaticallyinheritallprivilegesgiventotheirrole(s).Ofcourse,someuserswillhavemultipleroles.Now,let'stakethisprocessonestepfurther.Whileitmaynotseemnecessaryinthissimpleexample,asyoursystemgrows,youwilllikelyendupwithalargenumberofdifferentroles.Veryoften,certainrolescanbedefinedasacombinationofotherroles.Inourexample,aDataManageroverseestheDataAssistantsandthereforeshouldhavealloftheirprivilegesplussomeadditionalprivileges.So,let'sredesignourrolesslightlytoshowhowthismightwork.

Role InheritPrivilegesfromRole(s) AdditionalPrivilege(s)

MedicalStudent ViewPatient

DataAssistantViewPatient

EditPatient

DataManager DataAssistant AddPatient

UserManagementandAccessControl

92

YoucanseethattheDataManagerrolecanbemoreclearlydefinedasaDataAssistantwiththeextraabilitytoaddpatientstothesystem.Inaddition,ifyoushouldchangeorenhancetheprivilegesoftheDataAssistantroleatanytimeinthefuture,theDataManagerwillautomaticallyadapttothosechanges—forexample,ifyoudecidedamonthlatertoallowanyDataAssistanttoEditEncounters(byaddingtheEditEncountersprivilegetotheDataAssistantrole),theDataManagerrolewouldautomaticallygaintheabilitytoeditencountersaswell.

Inacommondeploymentscenario,youwillhaveseveralrolesthatusethesameprivilegeswithonlyafewdifferences.Itissimplertomanagetheseprivilegesbydefininganewrolefromwhichtheotherscanallinherit.Forexample,youmayhaveroleslikeClinician,DataAssistant,andCaregiverthatallhavethesamerulesaboutviewingpatientdata.YoumightbenefitfromcreatinganewPatientDataViewerrole,assigningittoeachofthoseotherroles,andthenmanagingtheprivilegesinoneplace(underthatnewrole).Whenthereisapolicychangeaboutviewingpatientdata,oranewmoduleisaddedthataddsnewfunctionsforviewingdata,youwouldupdatethePatientDataViewerrole.Alltheinheritingroleswouldautomaticallyusethenewsettings.

Built-inroles

TherearesomespecialrolesthatarepredefinedwithinOpenMRSandcannotbedeleted:Anonymous,Authenticated,andSystemDeveloper.AnyprivilegesgrantedtotheAnonymousrolewillbeavailabletopeoplewithoutloggingintothesystem.Generally,Anonymousprivilegesshouldbekeptveryrestricted,sincepatientinformationmightotherwisebecompromised.PrivilegesgrantedtotheAuthenticatedrolearegrantedtoanyonethatlogsintoyoursystem,nomatterwhatotherrole(s)theymightbeassigned.GrantingprivilegestotheAuthenticatedroleisaneasywaytograntprivilegestoallusersofthesystem.TheSystemDeveloperroleisautomaticallygrantedfullaccesstothesystemandshouldonlybegrantedtosystemadministrators.

Superusers(systemadministrators)areautomaticallygrantedallprivilegesinthesystem;therefore,youmustbeverycarefultoprotectyoursystemadministratorpassword.

Someprivilegesarebuiltintothesystemandcannotbedeleted.Otherprivilegesmaybeaddedbymodules.Itisunlikelythatyouwillbeaddingnewprivilegesyourself,sinceprivilegesareonlyusefulwhentheyareunderstoodandusedbythesystem.Ontheotherhand,youwilldefinitelybecreatingnewrolestofityourneedsandwillbemanagingprivilegeswithinthoseroles.

Creatingroles

YoucreaterolesthroughAdministration>ManageRoles.

1. Allowstoaddanewrole

UserManagementandAccessControl

93

2. Listsallrolespresentinthesystem

3. Clickaroletoeditit.

IfyouthenfollowtheAddRolelink,youwillseeaformforaddinganewrole.

1. EnterRoleName

2. ChooseRolesPrivilegesofwhichyouwanttoinherit

3. ChoosePrivilegeswhichyouwantthisRoletohave

Creatingusers

Tocreatetheseusers,we'llgothroughAdministration>ManageUsers.Thispagealsoletsyoufindandeditexistingusers.

UserManagementandAccessControl

94

1. CreateanewUser

2. SearchUsersbyNameorRoles

3. Searchresults

4. EditasingleUser

UsersinOpenMRSneedtobeassociatedwithPersons.YoueitherneedtocreateanewPerson,orattachtheuseraccounttoanexistingone.

InbothcasesyouwillbetakentothesameAdd/EditUserscreen.(Ifyouselectedanexistingperson,thefieldsintheDemographicInfosectionwillbefilledoutforyou.)

UserManagementandAccessControl

95

ManagingProviders

ForeveryEncounteryoumustenteroneormoreProviders,thepersonwhoprovidedthecareorservices.Formsusuallyincludeadropdownboxtoselectaprovider.

ThesystemadministratormustexplicitlyidentifyProviders.ThisisdonethroughAdministration>Providers>ManageProviders.

Therearetwokindsofproviders.InOpenMRS1.8andearlier,aproviderhadtobeassociatedwithauseror,lessoften,apatient.Theadministratorhadtocreateauser,andthensearchforthemwiththePersondropdownbox.Thisismostusefulwhenaproviderhasauserlogin.

AtmanyOpenMRSsites,onlyafewuserslogintothesystem.Often,treatmentnotesareenteredbydataclerksafteranencounter,andcliniciansneverlogin.Perhapstherearehundredsofproviderswhovolunteeratthecliniconlybriefly.FromOpenMRS1.9on,theseproviderscanbeenteredasaname,andauserloginisnotrequired.

Forsystemsecurity,patientprivacy,andeaseofmaintenance,it'sbesttoenterprovidersonlyasaProviderNamewhenpossible.Youshouldcreateauseriftheproviderneedstologinorbegivenspecialpermissionsthrougharole.Youcanassignausertoaprovideratalatertimeifitbecomesnecessary.

TocreateaProvider,gotoAdmin>ManageProvidersandclickAddProvider.

UserManagementandAccessControl

96

Theidentifierisauniquewordornumberthatyouprovide.It'srecommendedthatyoucreateidentifiersinawaythat'ssimpleandeasy,suchasusingtheprovider'slastnameandfirstname.

Next,decideifthisproviderwillbeassociatedwithaPerson,oronlybeenteredasaprovidername.IfyouchoosethePersonstyle,youmusthavealreadycreatedaUserforthem.BegintypingtheirnameinthePersonfield,andselectthemfromtheauto-completelistofmatchingusers.ForaProviderwhoissimplyaProviderName,entertheirnameintheProviderNamefield.

ClickSavetosavetheprovider.

UserManagementandAccessControl

97

MaintenanceOpenMRSserverroominWebuye,Kenya.

OnceyouhaveinstalledandconfiguredOpenMRSanditisbeingusedtosupportday-to-dayclinicaloperations,thereisstillworktobedone.Toensurethesystemrunssmoothlyanderror-free,usethefollowingtipsasastartingpointtocreateamaintenanceplanforyourOpenMRSinstallation.Werecommenddocumentingthisplanandreviewingitregularly.

Servermanagement

Althoughoutsidethescopeofthisbook,itisimportanttokeepbothyourOpenMRSserver(s)andclientsystemsupdatedwiththelatestsecuritypatches.InWindows,youshouldusetheWindowsUpdatetooltoreviewandinstallcriticalsystemupdates.IfyouuseLinux,useeitherapt-getupgradeoryumupdate,dependingonwhatdistributionofLinuxyouuse.

BeforeupgradingMySQL,Java,orApacheTomcat(andofcourse,OpenMRS)youshouldcheckwiththeOpenMRScommunitytoseehowthoseupgradesmighteffecthowOpenMRSrunsonyourserver.Seethe"GettingHelp"sectionformoreinformation.

Youshouldalsoperiodicallychecktoensureyourserverhasplentyoffreediskspace.Additionally,ifyouarerunningaWindowsserver,ensureyoursystemhasanti-virussoftwareinstalledanditisup-to-date.

Backups

Youshouldensureyoursystemhasabackupstrategy.Muchhasbeenwrittenonthissubjectandgeneralknowledgeaboutbackupsisbeyondthescopeofthisbook.However,therearesomespecificitemstoconsiderwhenbackingupyourOpenMRSserver.

Maintenance

98

Mostimportantly,youneedtocreateabackupstrategyforyourMySQLdatabase.Perhapsthesimplestwaytodothisisbyusingthemysqldumputilitythatshipswiththedatabase.Ideally,youwillwanttoshutdownOpenMRSbeforebackingup,andrestartitoncethebackuphascompleted.Ifyouarenotabletodoso,orwishtohavethesystemremainina"read-only"mode,youmaywanttousetheoptionsofmysqldumptolocktables.ConsulttheMySQLdocumentationfordetails.

Youshouldalsoensureyouarebackingupthe.OpenMRSdirectory.Thisdirectory,whichstoresmodulesandconfigurationfiles,isstoredinthehomedirectoryoftheuserthatrunstheTomcatserveronWindowsorLinux.

Performancetuning

Overthepastseveralyears,implementersofOpenMRSaroundtheworldhavecompiledinformationaboutimprovingtheperformanceoftheirsystems.Thereareseveralcomponentsofthesystemthatmayneedtobetunedtoensureoptimalperformance.Pleaseusetheinformationinthefollowingsectionsasaguideandastartingpoint--youwillneedtoexplorewhatsettingsworkbestforyoursystem.

OpenMRSsettings

Note:Fromversion1.9andabove,"globalproperties"willbereferredtoas"settings"intheguide.

YoumayneedtoadjustsomesettingsinOpenMRS.Todothis,usetheMaintenance>AdvancedSettingspageundertheOpenMRSAdministrationsection,findthedesiredsettingandclearorchangeitsvalueasdescribedinthefollowingtips,thenclicktheSavebuttonatthebottomofthepage.

Clearoutthepatient.identifierRegexsettingtodisableregularexpressionidentifiersearches.

Clearoutthepatient.identifierPrefixandpatient.identifierSuffixsettingstodisable"like"identifiersearches.

Makesurethatthedashboard.regimen.displayDrugSetIdssettinghasconceptIDnumbersandnotnames.Inotherwords,use"1085,1159"insteadof"ANTIRETROVIRALDRUGS,TUBERCULOSISTREATMENTDRUGS".

SetthesearchWidget.batchSize,searchWidget.runInSerialModeandsearchWidget.searchDelayIntervalsettingstotuneyoursearchesforbetterperformanceandsuityourimplementation'senvironment.Youmaywishtoconsiderthespeedofyournetworkconnection,typingskillsandaveragenumberofsimultaneoususersonatypicalworkday.Youmightalsoconsiderreducingthevalueofthesettingsperson.searchMaxResultsandsearchWidget.batchSizetoreducetheloadonthesearchwidgetsandserverforbetterperformance.

ApacheTomcat

Tomcathasseveralsettingsthatmaybeadjustedtooptimizeitsuseofmemory:

ExperiencehasshownitisbesttoinstallTomcatfromthedownloadsectionathttp://tomcat.apache.org/ratherthananyothersource.IfusingUbuntuLinux,wedonotrecommendusingtheapt-getinstaller.

IncreasetheamountofmemoryallocatedforTomcat.DependingonhowyoustartorrunTomcat,useoneofthefollowingmethods:

IfrunningTomcatfromthecommandline,addthefollowingparameters:

-Xmx512m-Xms512m-XX:PermSize=256m-XX:MaxPermSize=256m-XX:NewSize=128m

Maintenance

99

IfrunningTomcatasaWindowsservice,launchtheTomcatMonitorapplication.GotoConfigure>Java>JavaOptionsandaddthefollowingtothelistedsettings:

-Xmx512m-Xms512m-XX:PermSize=256m-XX:MaxPermSize=256m-XX:NewSize=128m

IfrunningTomcatasaLinuxservice,editthe/etc/init.d/tomcat(orequivalent)scriptandmodifythelineforCATALINA_OPTStoreadasfollows:

CATALINA_OPTS="-Djava.library.path=/opt/tomcat/lib/.libs-Xmx512m-Xms512m-XX:PermSize=256m-XX:MaxP

ermSize=256m-XX:NewSize=128m"

AdjustTomcattopreventpotentialmemoryleaks.Tomcathasadefaultsettingthatoftencausesmemoryleaks.Toturnitoff,opentheconfigurationfile.

<TOMCAT_HOME>/conf/web.xml

InJSPservletdefinitionaddthefollowingelement:

<init-param>

<param-name>enablePooling</param-name>

<param-value>false</param-value>

</init-param>

ExperimentwithbettergarbagecollectioninTomcattopreventPermGenoutofmemoryerrors.TouseanewerversionofTomcatgarbagecollection,youneedtoaddthefollowingtoCATALINA_OPTS,aswasshownaboveinthepreviousstep.

MySQL

OptimizingMySQLdatabasesettingswillhelpOpenMRStorunmoreefficiently,especiallyasyourinstallationgrowsinthesizeofdatayouarestoring.

Increasetheinnodb_buffer_pool_size.ItisthesizeinbytesofthememorybufferInnoDBusestocachedataandindexesofitstables.Thelargeryousetthisvalue,thelessdiskI/Oisneededtoaccessdataintables.Onadedicateddatabaseserver,youmaysetthistoupto80%ofthemachinephysicalmemorysize.However,donotsetittoolargebecausecompetitionforphysicalmemorymightcausepagingintheoperatingsystem.ModifythefollowinginMySQL'smy.inifile,oradditifitisnotpresent.

max_allowed_packet=64M

Increasethemax_allowed_packetsize.WhenMySQLattemptstoworkwithapacketofdatalargerthanspecified,itcausesapackettoolargeerrorandclosestheconnection,causingOpenMRStostopworking.IncreasingthisvalueallowsMySQLtohandlelargersetsofdata.ModifythefollowinginMySQL'smy.inifile,oradditifitisnotpresent.

innodb_buffer_pool_size=3G

YoumayalsoconsiderrunningaMySQLperformance-tuningscriptandmakingadjustmentstoyourMySQLconfigurationfilebasedonitssuggestions.Onesuchscriptisavailablehere:

https://wiki.openmrs.org/display/docs/Performance+Tuning

Replicationoptions

Maintenance

100

ReplicationofyourOpenMRSinstallationacrossmultipleserversormultiplesitesisanadvancedtopicthatisoutsidethescopeofthisbook.However,youshouldbeawarethatseveraloptionsexistifyourequireaccesstoyourOpenMRSdatafromalternatelocations.

MySQLreplication

TheMySQLdatabaseoffersmethodsforreplicatingyourdatabaseacrossmultipleservers,meaningitispossibletohavemultiplesynchronizedcopiesofyourOpenMRSdata.PleaseconsulttheMySQLdocumentationfordetails.Ifyoupointanidentically-configuredOpenMRSserveratthisreplicateddatabase,youwillhaveamirroredinstanceofOpenMRS.Itisimportanttoensurethatifyoumakechangestotheprimarysystem,thosesamechangestakeplaceonallservers.

Syncmodule

AnotheroptionisavailableforOpenMRSinstallationswithmultiplesites.Thecommunity-developedSyncmoduleisavailablefromtheOpenMRSmodulerepository,andallowsdatatobesynchronizedacrossanetwork(orexternaldatastorage)usingtoolswithinOpenMRSitself.PleasesearchtheOpenMRSWikiformoreinformationabouttheSyncmodule.

UpgradingOpenMRS

TheOpenMRSimplementeranddevelopercommunitiesprovideapplicationandcustomizationsupportviamailinglists,IRC,andothermeans.See"GettingHelpfromtheOpenMRSCommunity"formoreinformation.

WhenthedevelopmentteamreleaseanewupgradeforOpenMRS,theywillprovideeitheranewversionoftheOpenMRSStandaloneinstallerortheOpenMRSEnterpriseinstallerfiletorunonyourserver.IfusingtheStandaloneversion,followtheupgradeinstructionsincludedwiththeapplication.IfusingtheEnterpriseversion,youshouldbeabletoundeploytheOpenMRSwebappinApacheTomcat,anddeploythenewversion.

Besuretotestanyupgradesonaserverotherthantheprimaryserveryouusefornormalclinicalsupport.Alwaysbesuretobackupyoursystembeforeupgrading.

UpdatingmodulesSupportedcommunity-developedOpenMRSmodulesareregularlyupdated,andthosenewversionsarepublishedintheOpenMRSAdd-onsindex.Youshouldcheckforupgradedmodulesregularly.Gotohttps://addons.openmrs.org/orviewthe"ManageModules"pagefromtheOpenMRSAdministrationpage.Fromthere,youcanupgradeamodulewithupdatesautomaticallybyclickingInstallUpdate,oryoumaymanuallyuploadthenewversionbyfollowingtheinstructionsonthepage.

Amani'smaintenanceplan

Maintenance

101

AspartofhisresponsibilitiesasICTinfrastructuremanagerfortheclinic,Danielcreatedawrittenmaintenanceplan.Inthisdocument,hehasincludeddaily,weekly,andmonthlytasks.Theonlydailytaskisanautomatedone--DanielcreatedascriptonhisUbuntuservertostopOpenMRS,backupMySQLandotherOpenMRSfiles,andrestarttheapplication.Thisscriptrunsovernightwhiletheclinicisclosed.Weekly,Claudinemanuallychecksthediskspaceandrunsapt-getupgradetoupdatesystemcomponents.Everymonth,ClaudinecheckstheOpenMRSwebsiteforOpenMRSupgradesandupgradestothemodulestheclinicuses.

Maintenance

102

TroubleshootingYourInstallation

Unfortunately,sometimesthingsdonotgoexactlyplanned.Thischaptercanhelpyoudealwiththemostcommonproblems.

WerecommendusingApacheTomcat6.0.29torunOpenMRS.AnyJ2EE-compliantJavaservletcontainershouldbeabletorunit,butmostpeoplewhouseOpenMRSarerunningitwithTomcat,whichmaymakeiteasiertogetsupportifyouencounterproblems.

IfyouarenotyetusingTomcat6.0.29,considerupgradingTomcatbeforeyoucontinue.WerecommendgettingTomcatfromthislink.

http://tomcat.apache.org/

WhentroubleshootingTomcat,yourfirststepshouldalwaysbetoreviewtheTomcatlogs.InWindows,thesearestoredatthefollowinglocation.

C:\ProgramFiles\ApacheSoftwareFoundation\Tomcat6.0\logs

Historically,MySQLhasbeenrecommendedasthedatabaseofchoicetousewithOpenMRS.ThenewerdatabasefromtheopensourceprojectMariaDBshouldalsobecompatiblewithOpenMRS.WorkisunderwayintheOpenMRScommunitytoprovidesupportforotherdatabasessuchasOracle,MicrosoftSQLServer,andothers,butthesedatabasesarenotyetsupported.

YoumaynotbeabletoresolveyourproblemwithOpenMRSusingthetroubleshootingmaterialinthischapter.ThatisOK--theOpenMRScommunityisavailabletohelp!CheckouttheGettingHelpfromtheOpenMRSCommunitychapterformoreinformationabouthowtocommunicatewithothers,askquestions,andgetanswers.

Somepossibleproblemsandsolutions

OpenMRSfailstoinstallwithmessage"Errorcreatingbeanwithname'messageSourceServiceTarget'"

Troubleshooting

103

MySQLmustberunningbeforestartingandinstallingOpenMRS.Ifitisnot,youmayseethefollowingerrormessageinyourwebbrowserandlogfileswhenyouattempttoinstallOpenMRS:

org.springframework.beans.factory.BeanCreationException:Errorcreatingbeanwithname'messageSourceServiceTarg

et'definedinclasspathresourceapplicationContext-service.xml

EnsureMySQLisinstalledandrunningbeforeattemptingtostartandinstallOpenMRS.

MySQLConfigureInstancehangsonstartingtheservice,orreportsError1045

OnWindows,thecomputermaystoprespondingwhilerunningtheMySQLConfigureInstancetool.Mostcommonly,thisoccursbeforethetoolmarksStartingtheserviceascomplete,becausethereisalreadyaMySQLservicerunning.

Tofixthis,youshoulddeletethepre-existingMySQLserviceinWindows,andtrytheinstallationagain.YoucanfindinstructionsonhowtododeleteaMySQLserviceatthislink.

Alternatively,youmayseeaMySQLError1045,ifyourcomputerhaspreviouslyhadaMySQLinstanceinstalled.Thismeansthattherootpasswordisincorrect,andismostcommonlycausedbyresidualdatafromthepreviousinstallation.

Tofixthis,youshoulddeletetheMySQLdatadirectory.OnWindows7,youmayneedtorebootanddeletethedirectory,ortouseanunlockingprograminordertodeletethisdirectory.

YoucanalsochangethepasswordthatOpenMRSusestoaccessyourMySQLdatabase,byeditingtheopenmrs-runtime.propertiesfile,asdescribedlaterinthischapter.

StartingTomcatserviceonWindowsfails

IfyoucannotstarttheTomcatserviceonWindows,trycheckingtheTomcatlogs.Youcanfindthelogsinthefollowingdirectory.

<TOMCATHOME>\logs

Errorslike"FailedcreatingjavaC:\ProgramFiles\Java\jre1.6.0\bin\client\jvm.dll"

Tofixthisproblem,searchformsvcr71.dllonyourharddrive,andcopythatfiletothislocation.

C:\Windows\System32

InstallingOpenMRSorrunningdatabaseupdatesfailswithmessage“Couldnotacquirechangeloglock”

Topreventconflictingupdates,liquibasebeginseachupdatebycreatingarowintheliquibasechangeloglocktable.Thisrowactsasalock.IfOpenMRSorApacheTomcatcrasheswhileanupdateisinprogress,theupdatemayfailtocomplete

andthisrowwillnotberemovedfromthetable.

YoumayseethefollowingerrormessageinyourwebbrowserorintheTomcatlogs,thenexttimeyoustartuporattempttoinstallorupdateOpenMRS:

"ErrorCouldnotacquirechangeloglock"

Deletingthisrowfromtheliquibasechangeloglocktablewillsolvetheproblem,andallowinstallationorupdatestoproceednormally.TodeleterowsfromtheliquibasechangeloglocktableusingacommandlineSQLclient,runeitherofthefollowingSQLcommands:

truncatetableliquibasechangeloglock;

Troubleshooting

104

deletefromliquibasechangeloglock;

IfyouprefertouseaGUIclientforMySQL,youshouldnavigatetotheliquibasechangeloglocktableanddeleteallrowsfromthattable.Whenyouhaveclearedthetable,restartTomcatifnecessary,andrestartOpenMRS.

ProblemsconnectingtoTomcatonport8080

Otherinstalledprogramsmayalreadybeusingport8080.ThiswillpreventTomcatusingthisport.Somesoftwaremayalsouseport8005,whichshouldnotinterferewithrunningTomcat,butmaypreventitfromstartingupcorrectly.

Ifyouknowwhatprogramisusingtheseports,youmaychoosetostoporremovethatprogram.Alternatively,youcanconfigureTomcattorunonadifferentportbyeditingTomcat’sserver.xmlfiletochange8080toadifferentvalue(eg8090).

Ifyouneedfurtherhelp,seethe"GettingHelpfromtheOpenMRSCommunity"chapterformoreinformation.

PermissionproblemswhenrunningTomcatasaserviceonUbuntu

IfyouaretryingtorunTomcatasaserveronUbuntu,youmayrunintopermissionissues.Thefollowingerroristypicaloftheseproblems:

java.security.AccessControlException:accessdenied(java.io.FilePermission/usr/share/tomcat6/webapps/openmrs/

WEB-INF/dwr-modules.xmldelete)

TheeasiestwaytosolvethisissueistodisabletheJavasecuritymanagerorsimilarstartupscript,whichyoucanfindatthislocation.

/etc/init.d/tomcat6

EditthefileandsetTOMCAT6_SECURITYtono.

#UsetheJavasecuritymanager?(yes/no)

TOMCAT6_SECURITY=no

TomcatstopsrespondingafterupdatingorreloadingOpenMRSintheWebApplicationManager

TomcatandtheJVMallocatememorytoawebappeachtimeyouusetheUpdateorReloadfunctionsintheWebApplicationManager.Whentheappisdestroyedorrecreated,someofthismemorymaynotbereleased.Ifyouupdateorreloadthewebapptoomanytimes,Tomcatmayrunoutofallocatedmemory,andwillstopresponding.YouwillalsoseethefollowingerrorintheTomcatlogs:

java.lang.OutOfMemoryError:PermGenspace

Itisnotpossibletocompletelyavoidthisproblem.HoweveryoucanmitigateitbyallowingTomcattousemorememory,orbyrestartingTomcatifyouhavetorepeatedlyupdateorreloadawebapp.

DeployingOpenMRSusingtheTomcatManagerwebapplicationfails

Forvariousreasons,tryingtodeployOpenMRSusingtheTomcatManagerwebapplicationmayfail.Ifthisoccurs,youshouldundeployOpenMRSusingtheTomcatManager,thenstopTomcat.

YoucandothisonthecommandlineunderLinuxorOSX.First,findtheprocessID(PID)byrunningthefollowingcommand:

Troubleshooting

105

psax|greptomcat

Thismayreturnseverallines,eachstartingwithanumber.Lookforalonglinethatcontainssomethinglike/usr/local/tomcator/opt/tomcat.ThePIDisthefirstnumberonthatline.StopTomcatwiththefollowingcommand:

kill-9PID

Finally,youcanrestartTomcatasfollows:

servicetomcat6start

LogbackintotheTomcatManagerwebapplicationanddeployOpenMRSnormally.

OpenMRS(openmrs.war)deployssuccessfullybutfailstostart

IfthereareissueswiththeOpenMRSsettingsforapplication_data_directory,openmrs.warmaysuccessfullydeploy,butthenfailtostart.ThefollowingmessagesareseeninTomcat'slogs:

SEVERE:ErrorlistenerStart

SEVERE:Context[/openmrs]startupfailedduetopreviouserrors

Ensurethattheruntimepropertiesfileexists,andthattheapplication_data_directoryisspecifiedinthisfile.Thenensurethatthedirectoryexists,andthatTomcathasreadandwritepermissionstothedirectory.

IfthedirectoryexistsasspecifiedintheruntimepropertiesfileandTomcathastheappropriatepermissions,youmayhavesecurityviolationproblemsinyourTomcatconfiguration.Ifyouneedfurtheradvice,considerseekinghelpfromthecommunity,asdescribedinthechapter"GettingHelpfromtheOpenMRSCommunity".

UnabletologintoTomcatManagerduetolostpassword

TheTomcatadminpasswordisrequiredtologintotheTomcatManagerwebapplication,andtodeployandundeployapplications,includingOpenMRS.

Ifyouhaveforgotten,lost,ormisplacedthispassword,youcanretrieveitfromthefiletomcat-users.xml.OnWindows,thisisprobablylocatedatthislocation.

C:\ProgramFiles\ApacheSoftwareFoundation\Tomcat6.0\conf\

Thedatabasepasswordorotherpropertiesaresetincorrectly

IfyouhaveinstalledtheOpenMRSStandaloneapplication,youcanmodifysettingsbyeditingtheopenmrs-standalone-runtime.propertiesfileinthedirectorywhereyouextractedtheZIPpackage.

TomodifysettingsfortheOpenMRSEnterpriseversion,youshouldeditthefileopenmrs-runtime.properties.Youshouldfindthisfileinoneofthefollowinglocations:

OnWindowssystems:

C:\DocumentsandSettings\YOURUSERNAME\ApplicationData\OpenMRS

C:\Windows\system32\config\systemprofile\ApplicationData\OpenMRS

OnMacOSXorLinuxsystems:

~/YOURUSERNAME/.OpenMRS

Troubleshooting

106

/usr/share/tomcatX/.OpenMRS

TheOpenMRSadministratoraccountpasswordhasbeenforgotten

Ingeneral,whenauserislockedout,thepasswordshouldberesetbytheadministratorusingthe"EditUser"pagefromtheOpenMRSAdministrationpage.Inraresituationsinwhichtheadministrator'saccounthasbeenforgotten,theonlywaytoresetthepasswordistodirectlymodifytheOpenMRSdatabase.Thisshouldonlybeattemptedbyadvancedusers,andyoushouldalwaysbackupyourdatabasebeforemakingchanges.

YouwillneedtomodifytheuserstableintheOpenMRSdatabaseschema.Findtherowfortheuserinquestionandchangethepasswordandsaltvaluestothefollowing:

password:4a1750c8607d0fa237de36c6305715c223415189

salt:c788c6ad82a157b712392ca695dfcf2eed193d7f

Somemodulepagesthrowjava.lang.ClassNotFoundException

TherearecurrentlysomeissueswithcompatibilitybetweenOpenMRSandversionsofApacheTomcatlaterthan6.0.29.OpenMRSmodulesthatrelyoncertaincustomexpressionlanguagefunctionswillthrowajava.lang.ClassNotFoundExceptionexception.

IfyouencounterthisissueusingaversionofTomcatgreaterthanv6.0.29,youmayneedtodisableanymodulesthatrelyoncustomexpressionlanguagefunctions,orinstallTomcat6.0.29forusewithOpenMRS.

StartingOpenMRSfailswithmessage“Modulefiledoesnothavethecorrect.omodfileextension”

OpenMRSwillnotstartiftherearenon-modulesinthemodulesdirectory.Youmayfindamessageinthelogssimilartothese:

org.openmrs.module.ModuleException:Modulefiledoesnothavethecorrect.omodfileextensionModule:derby.lo

g

org.openmrs.module.ModuleException:Modulefiledoesnothavethecorrect.omodfileextensionModule:velocity

.log

Tosolvethisproblem,deleteormoveanyfilesinthemodulesdirectorythatarenotmoduleswithan.omodextension.

Inparticular,theBIRTRuntimecreatesvariouslogfilesinthemodulesdirectorywhentheBIRTmoduleisstopped.IfyouareusingtheBIRTReportmodule,theremaybenon-modulefilesintheOpenMRSmodulesdirectory--typically,derby.logorvelocity.log.Thesefilescansafelybemovedtoanotherlocationordeleted.

Topreventthederby.logfrombeingcreatedinfuture,deletethedirectoryorg.apache.derby.core_10.1.2.1whichislocatedunderthefollowingdirectory.

birt-runtime-2_2_0/ReportEngine/plugins/

MySQLpacketlengtherrors,orMySQLError2006

Theseerrorsoccurwhentheclientorservertriestohandledatalargerthanthemaximumpacketlength.Thedefaultmaximumpacketlengthis1MB.Someitems(suchasformdata)caneasilyexceedthismaximum,causingerrorswhenimportingdataintoorexportingdatafromtheOpenMRSdatabase.

ToincreasethemaximumpacketlengthallowedbyyourMySQLserver,youshouldstoptheserver,edittheconfigurationfile,thenrestarttheserver.Theconfigurationfileistypicallylocatedatoneoftheselocations.

Troubleshooting

107

Windows:C:\ProgramFiles\MySQL\MySQLServerx.x\my.ini

LinuxorMacOSX:/etc/my.cnf

Thisfileshouldalreadycontainasectionwiththeheader[archive:mysqld].Youcanaddthefollowinglinebelowthatheader:

max_allowed_packet=64M

YoucanalsoincreasethemaximumpacketlengthusingtheMySQLAdministratorapplication,byopeningtheHealthsectionandchangingthemax_allowed_packetsettingontheSystemVariablestab.Thissettingcanbeincreaseduptoamaximumof1024Masnecessary.

DependingonyourMySQLclient,youmayalsoneedtoadjustthemaximumpacketlengthoftheclient.IfyouareusingtheMySQLcommandlineclient,youcanstartitwithanincreasedmax_allowed_packetbyaddingthefollowingaftertheMySQLcommand:

--max_allowed_packet=64M

ProblemsconnectingtoMySQLonasystemwithmultipleMySQLinstallations

IfMySQLisalreadyinstalledandrunningonyoursystem,OpenMRSStandalone'sinitialsetupmaybeunabletocreatetheOpenMRSuseranddatabase.Youmayalsoencounterthisproblemafterinstallation,ifyouhaveinstalleda"traditional"MySQLserverandtrytorunOpenMRSStandalone.

ThisproblemhappensbecauseMySQLclientsonUNIX-basedsystemsalwaysuseUNIXsocketstoconnecttoMySQLwhenlocalhostisspecifiedintheconnectionURL.Thisisaknownissue/limitation/buginMySQLandisdocumentedinmoredetailbytheMySQLproject.

http://bugs.mysql.com/bug.php?id=31577

ItispossibletorunOpenMRSinaseparatedatabaseinstancethantheonealreadyexistingonyoursystem(forexample,torunOpenMRSStandaloneonasystemwhereMySQLisalreadyinstalled).Todoso,youmustfirstensurethatthenewdatabaseinstanceisrunningonadifferentport.

Then,ensurethatyouareconnectingtoMySQLviaTCP/IPinsteadofusingthesameUNIXsocketastheexistinginstance.Theeasiestwaytodothisistouse127.0.0.1insteadoflocalhostintheconnectionstring.Analternativeistoadd&server.port=XXXXtothevalueofconnection.urlintheopenmrs-runtime.propertiesfile,whereXXXXistheportusedbytheOpenMRSMySQLinstance.

Forexample,iftheMySQLinstanceusedbyOpenMRSisrunningonport4242,theopenmrs-runtime.propertiesfileshouldincludeoneofthefollowinglines:

connection.url=jdbc:mysql://127.0.0.1:4242/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&us

eUnicode=true&characterEncoding=UTF-8

connection.url=jdbc:mysql://localhost:4242/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&us

eUnicode=true&characterEncoding=UTF-8&server.port=4242

TomcaterrorlogcontainsIOExceptionwhileloadingpersistedsessions

ApacheTomcattriestorestoretheexactmemorystateaftereachrestart.OpenMRSdoesnotdependonthisfeature,soyoucanignoreanywarningsprintedtotheTomcatlogsthatlooksimilartothefollowing:

SEVERE:IOExceptionwhileloadingpersistedsessions:java.io.WriteAbortedException:writingaborted;java.io.N

otSerializableException:

Troubleshooting

108

Ifyoufindthesemessagesannoying,youcanturnoffsessionpersistence.Editthe<TOMCAT_HOME>/conf/server.xmlfileanduncommentthelinethatincludes:

<Managerpathname=""/>

JavaHeapSizeerrors

OpenMRSusesalotofmemoryforcaching.Certaintasks,suchasexportingdata,maycauseaJavaHeapSizeerror.YoucanmitigatethisbyincreasingthedefaultmemoryallocationinTomcat.

IfyouarestartingTomcatonthecommandline,youshouldpassthefollowingparameterstoincreasethedefaultmemoryallocation:

-Xmx512m-Xms512m-XX:PermSize=256m-XX:MaxPermSize=256m-XX:NewSize=128m

IfyouarerunningTomcatasaWindowsService,youcanincreasethememoryallocationbyaddingthissamelinetothelistofstartparameters.Makesurethatyouaddthistotheendoftheexistingparametersexactly.AnextraspaceattheendofthelinecanpreventTomcatfromstartingproperly.YoucanfindthelistofstartparametersintheTomcatMonitorapplication,bygoingtoConfigureTomcat>Java>JavaOptions,orviatheControlPanel>Services>ApacheTomcat>Properties>StartParameters.

Ifyouarerunninga64-bitversionofTomcatasaWindowsService,youmustedittheWindowsRegistrytoaddthatlinetotheHKEY_LOCAL_MACHINE\SOFTWARE\ApacheSoftwareFoundation\Procrun2.0\Tomcat5\Parameters\JavaJVMsettingsintheRegistry.

IfyouarerunningTomcatonUbuntu,edititsstartupscriptsuchas/etc/init.d/tomcat6andmakethefollowingchanges:

if[-z"$JAVA_OPTS"];then

JAVA_OPTS="-Djava.awt.headless=true-Xmx128M"

fi

if[-z"$JAVA_OPTS"];then

JAVA_OPTS="-Djava.awt.headless=true-Xmx1024M-Xms1024M-XX:PermSize=256m-XX:MaxPermSize=256m-XX:NewS

ize=128m"

fi

IfyouarerunningTomcatasaLinuxservice,openthe/etc/init.d/tomcatscriptandappendchangetheCATALINA_OPTSvariable:

CATALINA_OPTS="-Djava.library.path=/opt/tomcat/lib/.libs-Xmx512m-Xms512m-XX:PermSize=256m-XX:MaxPermSize=25

6m-XX:NewSize=128m"

Memoryleaks

Aftertroubleshooting,youmaydeterminethatTomcatorOpenMRSishavingproblemswithmemoryleaks.

TomitigatememoryleakproblemsinTomcat,considerenablingpoolingbyaddingthefollowingelementtotheJSPservletdefinitioninthefile<TOMCAT_HOME>/conf/web.xml:

<init-param><param-name>enablePooling</param-name><param-value>false</param-value></init-param>

Troubleshooting

109

IfyoubelieveyouhavediscoveredamemoryleakinOpenMRSandarecomfortablelookingattheOpenMRSapplicationcodetoidentifywheretheleakislocated,youmayliketotroubleshootfurthertofindoutthecause.OpenMRSdevelopersuseYourKitProfilertodiscoveranddebugmemoryandCPUconsumptionissues.

YourKitiskindlysupportingmembersoftheOpenMRScommunitywithitsfull-featuredJavaProfilerproduct.Ifyouhavedevelopmentskillsyoumaywanttousethistooltounderstandwhytheapplicationisleakingmemoryorconsumingtoomanyprocessorresources.AsanactiveparticipantintheOpenMRScommunity,youcanrequestalicensebyopeningasupportdeskticket:

https://help.openmrs.org/

BugsinOpenMRSIfyoubelieveyouhavediscoveredaproblemthatmaybeabuginOpenMRS,weencourageyoutoreportthatbug.TheOpenMRSdevelopmentteamtakesbugreportsseriouslyandcontinuallyfixesasmanybugreportsaspossibleforfuturereleases.PleaseseeourbugreportpageontheOpenMRSwikiforfurtherdetailsandinstructions:

https://issues.openmrs.org/

Troubleshooting

110

GettingHelpfromtheOpenMRSCommunityA2011meetingoftheOpenMRScommunityinKigali,Rwanda.

OpenMRSissupportedbyavibrantcommunity.Whetheryouneedhelpinstalling,using,updatingorextendingOpenMRS,youcanfindhelpinavarietyofplaces.

OpenMRSID

OpenMRSIDisanaccountusedtoparticipateinmostofthecommunityresourcestosupportimplementersanddevelopers,andisrequiredtousemostofthetoolsonthispage.LearnmoreaboutOpenMRSIDandsignuponline

https://id.openmrs.org/

OpenMRSWikiDocumentationforOpenMRSisavailableinthewiki.

http://wiki.openmrs.org

Youcanfindinformationforusersanddevelopers,aswellasdetailsofsharedmodulesandotherresources.

Youcansearchforinformationinthewikiusingthesearchbaratthetopofthepage.Alternatively,usethelinksontheleftofthepagetonavigatetotherelevantsection.

Ifyoufindanerrorintheinformationonthewiki,pleasecorrectitifyoucan!IfyoudonotalreadyhaveanOpenMRSID,youcanregisterforfreeusingtheSignUplinkatthetopofthepage.Afterloggingin,youwillseeanEditbuttonatthetopofmostpages.Clickthisbutton,makeyourchanges,andclickSave.Ifyouarenotcertainaboutmakinganedit,justleaveacommentonthepagewithyourquestionsorconcerns.Weappreciateyourhelp!

GettingHelpfromtheOpenMRSCommunity

111

OpenMRSTalkforums

MostofthediscussionwithinthecommunityoccurswithinOpenMRSTalkavailableat:

https://talk.openmrs.org/

Theimplementersmailinglistisacommunitymailinglistforpeopleusing,consideringusing,orotherwiseinterestedinOpenMRS.Youcanaskquestions,seekadvice,andlearnfromothersonthemailinglist.Searchthearchivesforsimilarproblemsbeforeyoupost-someoneelsemayhavealreadyansweredyourquestions!

AskOpenMRS

AskOpenMRSisasafeplacetoaskquestionsaboutinstallingandusingOpenMRSandtogetanswersfromothersinthecommunity.

https://ask.openmrs.org/

Ifyouaskaquestionandgetsomeanswers,pleasebecourteousbyselectingthebestanswer(thishelpspeoplethatcomelaterwiththesamequestiontomoreeasilyfindthebestanswer).Asyougainexperience,helpcontributetothecommunitybyhelpingtheanswersofothersinthecommunity.

IRC

InternetRelayChat(IRC)isaprotocolforreal-timeInternetchat.TheOpenMRScommunityusethe#OpenMRSchatroomonirc.freenode.net.

FormoreinformationonhowtoconnecttoIRCvisit:

http://om.rs/irc

AllIRCdiscussionsareloggedandavailableonline.

Telegram

JoinrealtimediscussionsonTelegram.Youcanchatthroughawebbrowserorwithamobileapplication.JointheOpenMRSTelegramchatat:

http://om.rs/tg

Havingtrouble?IfyouhaveproblemswithyourOpenMRSID,orwithanyofthetoolslistedabove,pleaseopenasupportdeskticketandsomeonewillrespondtoyourissue.

http://om.rs/helpdesk

Ifyouarenotabletologinwhencreatingtheticket,pleaseremembertoincludeyournameandcontactinformation.

GettingHelpfromtheOpenMRSCommunity

112

Epilogue

113

LeavingAmaniClinic

WenowendourvisittoAmaniClinic.Wesawhowtheclinicmanagementstartedwiththeideaofusingamedicalinformationsystemtosupporttheworkflowoftheirclinic.TheyimplementedOpenMRStomanagetheirdata,evaluateandreportontheirproject'seffectiveness,andultimatelyimprovecarefortheirpatients.

Claudine,Daniel,James,andKissaallhadchallengesinplanningandgettingusedtonewwaysofworking,butwecanbelievethattheirincreasedabilitytobettermanagehealthcaredeliverywillresultinhealthier,happierpeopleinthevillageofKisiizi.

Wehopeyouhavefoundtheirstory,alongwiththeinformationpresentedinthisguide,usefulinthinkingaboutyourownsituation.

Asareminder,thisbookservesonlyasanintroductiontotheOpenMRSmedicalrecordsystemandourlargeropensourcecommunity.Youarenowamemberofanewextendedfamilyofpeopleworkingtogethertomakeandimprovetechnologyforhealthcareoneverycontinent.Wehopeyouwillbeasexcitedaswearetomakeadifferenceinourcommunities,andwehopetoseeyouinourmailinglistsandwikis,andhearyouinourmeetingsverysoon.

Welcomeandgoodluck!

LeavingAmaniClinic

114

LeavingAmaniClinic

115

AboutthisBook

Thisisyourbook!

OpenMRSisopensource.Thatmeansanyoneintheworldcanhelpimprovethecode.Likewise,thiselectronicbookisopensourceaswell,meaninganyoneiswelcometohelpimprovethisImplementersGuidetoo(seebelowonhowtocontribute)!ThesourceforthisbookishostedonGitHub.

Seeanerror?Wanttosuggestupdatesorhelpimprovetheguide?Learnhowtocontribute.

Historyofthisbook

ThisfirsteditionofthisbookwascreatedinOctober2011duringthefirstGoogleSummerofCodeDocumentationSprint.WeareindebtedtotheGoogleOpenSourceProgramsOffice,theFLOSSManualsfoundation,andAspirationfororganizingthisweek-longeventwherefouropensourceprojects(OpenMRS,SahanaEden,OpenStreetMap,andKDE)joinedforcestoshareknowledgeandcreatemanualsfortheirusercommunities.

TheauthorsforthefirstversionwereRafalKorytkowski(Poland),GlenMcCallum(Canada),NóirínPlunkett(Ireland),DariusJazayeri(UnitedStates),andMichaelDowney(UnitedStates).

Wereceivedproofreading,structuraladvice,andeditingassistancefromPaulBiondich(UnitedStates),HamishFraser(UnitedStates),AllenGunn(UnitedStates),DanielKayiwa(Uganda),BurkeMamlin(UnitedStates),SaptarshiPurkayastha(India),JanetRiley(UnitedStates),andBenWolfe(Kenya).

AboutthisBook

116

PhotographsinthisbookarecourtesyofJamesArbaugh,MichaelJ.Downey,FrankFries,MathewSsemakadde,andStephanieTaylor.TheoriginalbookcoverwasdesignedbyLalehTorabi.

WewouldalsoliketothankthecountlesspeoplewhohavecontributedtoOpenMRSdocumentationoverthepastsevenyears,andthewritingteamof_CivicCRM:AComprehensiveGuide,_allofwhichservedasinspirationandthebasisformuchofthisbook.TheOpenMRScommunitythankseveryonewhoparticipatedinmakingthisbookareality.Thankyou!

AboutthisBook

117

Appendices

118

AppendixA:Glossaryadministrativestaff:Individualswhomanagepeopleordatainaclinicalsetting.

allergylist:Aseriesofallergiesthatapatientmighthaveorfromwhichapatientcouldbesuffering.

bug:ArepeatableprobleminOpenMRS.

bugreport:Areportcreateddescribingarepeatableproblemtosoftwaredevelopers.

bundledmodule:AnOpenMRSmodulethatisincludedwithadownloadedOpenMRSinstallation.

checkdigit:Anextradigitthatisaddedtotheendofanidentifieranddependsontherestofidentifier.

clinician:Adoctor,nurse,orotherclinicalofficerwhoprovideshealthcaretopatients.

cohort:Agroupofpatientsthatcanbedefinedbyoneormorecommontraits.

concept:Theideathatencompassesanyquestionwhichcanbeaskedaboutapatient;anobservablepointofdata.

conceptclass:AcategoryofOpenMRSConceptswithassociatedtraits.

conceptdatatype:AdescriptorofthetypeofdatawhichagivenOpenMRSConceptdescribes(e.g.,numeric,text,etc.).

conceptdictionary:Alistofallthemedicalandprogram-relatedtermsusedinOpenMRSasquestionsandanswers.

customization:Theideaofadaptingasystemtosuitone'sspecific,particularneeds.

data:Apieceofknowledgethatcanbereducedtoasinglevalue.

demographics:Informationaboutaperson,typicallyincludingdateofbirth,location,name,etc.

drug:AspecificformulationofamedicationrepresentedinOpenMRS.

electronicmedicalrecord:Acomputersystemthatallowsforrecording,storage,andretrievalofinformationrelatedtothedeliveryofhealthcaretopatients.

encounter:Aclinicaltransactionbetweenapatientandoneormorehealthcareprovidersforthepurposeofprovidingpatientservicesorassessingthehealthstatusofthepatient.Anencounterhappensatonepointintime.http://www.astm.org/Standards/E1384.htm

error:Amessageinacomputersystemthatdescribeaproblemcurrentlyorrecentlyoccurring.

flag:Avisualindicatorofcertaincriteriaonapatientchart.

form:Anelectronicformthatmaybeusedforenteringorviewingdata.

Groovy:Acomputerscriptinglanguagethatallowsautomationandquickperformanceoftasks.

implementationplan:Awrittendocumentwhichdetailsspecificgoalsandtasksininstalling,customizing,andusingOpenMRS.

implementationteam:AdefinedgroupofpeopleworkingtogethertodeployOpenMRSinaspecificproject.

implementer:SomeonewhohasorisintheprocessofdeployingOpenMRSinaspecificlocationorcontextofuse.

informatics:Thestudyofinformationtechnologyappliedtoaspecificdomain.

internationalization:Theadaptationaninformationsystemorpiecesofinformationtobeusedinmultiplelocations.

IRC:ShortforInternetRelayChat,anonlinetooltocommunicatewithothersin"realtime."OpenMRSusesIRCtoallowdevelopersandimplementerstocollaborateandmeet.http://go.openmrs.org/irc

AppendixA:Glossary

119

localareanetwork:Amethodofconnectingmultiplecomputersforcommunicationoverdistances.

location:Aphysicalplacewhereapatientmayreceivehealthcareservices.

longitudinal:Havingagoalofobservingortrendingovertime.

mailinglist:Acollectionofnamesandaddressesusedbyacompanytosendmaterialtomultiplerecipients.Ontheinternet,mailinglistsincludeeachperson'se-mailaddressratherthanapostaladdress.http://www.entrepreneur.com/encyclopedia/term/82424.html

medicalinformatics:Adisciplineofstudyingtheuseofinformationtechnologyinthefieldofmedicalscience.

metadata:Apieceofinformationthatdescribesotherinformation.

module:AsoftwarepackagethatextendsOpenMRSfunctionalityinspecificways;oftendevelopedbyothersintheOpenMRScommunity.

modulerepository:Anonlineresourcetofindandmaintaincommunity-developedOpenMRSadd-onmodules.https://addons.openmrs.org/

observation:Onepieceofinformationthatisrecordedaboutapersonatamomentintime.

opensource:Amethodofdevelopingsoftwarewherethesourcecodeisfreelyavailableforotherstoexamine,use,andbuildupon.Alsoatypeofsoftwaredevelopmentcommunitybasedaroundsharingofworkandcollaboration.

order:Anactionthataproviderrequestsbetakenregardingapatient.

patient:Apersonreceivinghealthcareservices.

patientdashboard:AvisualrepresentationofapatientwithinOpenMRS,includinghisorherdemographicsandotherimportantinformation.

patientidentifier:Anyuniquenumberthatcanidentifyapatient.ExamplesareaMedicalRecordNumber,aNationalID,aSocialSecurityNumber,adriver'slicensenumber,etc.

person:Everyindividualwhoisreferredtoinanypatient'srecordinOpenMRSmustbestoredinthesystem.

personattribute:storeadditionalpiecesofinformationaboutthepeopleinyoursysteminadditiontothosethatarenativelysupportedbyOpenMRS.

pilotproject:Activelyplannedasatestortrial.

platform:Acomputersystemthatissimplebydesign,intendedtobecustomizedandadaptedforuseinawidevarietyofcontexts.

privilege:AdefinitionofwhatactionsauserisallowedtotakewithinOpenMRS.

problemlist:Alistofapatient'sproblemsthatservesasanindextohisorherrecord.Eachproblem,thedatewhenitwasfirstnoted,thetreatment,andthedesiredoutcomeareaddedtothelistaseachbecomesknown.Thusthelistprovidesanongoingguideforreviewingthehealthstatusandplanningthecareofthepatient.

http://medical-dictionary.thefreedictionary.com/master+problem+list

profile:AnOpenMRSuser'sbasicinformation,includingname,userID,password,andlanguagepreferrence.

program:Aplannedseriesofadministrativeorresearchevents.

programenrollment:RepresentsthefactthatapatientisenrolledinoneoftheseProgramsoveratimeperiodataLocation.

provider:Ahealthcareprofessional,orgroupofhealthcareprofessionalswhoprovideaservicetopatients.

purge:TopermanentlydeletedatafromtheOpenMRSdatabase.

AppendixA:Glossary

120

relationship:AdescriptionofhowtwopersonsinOpenMRSareconnected,e.g.,motherandchild.

retire:TomakemetadataunusableinthefuturewhileretainingitinOpenMRSforpastreference.

role:RepresentsagroupofprivilegesinOpenMRS.

sampledata:Fictional,anonymizedinformationrepresentingpatientcarewithinOpenMRS.SomeversionsofthesoftwareincludethisartificialdatatomakeiteasiertoplananOpenMRSimplementation.

SMARTgoals:Objectivesforaprojectthatarespecific,measurable,attainable,realistic,andtimely.

softwaredeveloper:ApersonwhoisabletoprogramcustomizationsoradditionalfunctionalityinOpenMRS.

state:Aconditionorsituation;status.

superuser:AnOpenMRSuserwithpermissiontoperformallmanagementtasksintheapplication.

systemadministrator:Apersonwhoisresponsibleforday-to-daymaintenanceofacomputersystemornetwork.

uninterruptiblepowersupply:Abattery-basedsystemthatprovidesinstantshort-termpowertoacomputerorotherdevicesduringapoweroutage.

unretire:Tore-designatemetadataasusable.

unvoid:MakedatavisibleinOpenMRSthathadpreviouslybeenvoided.

user:ApersonwhousesOpenMRS,ormorespecificallythedatainthesystemrepresentingthatperson.

visit:Acollectionofoneormoreencountersthatdefineaninteractionbetweenthepatientandthehealthcaresystem.Somecommonexamplesofvisitsincludeoutpatientclinicvisits,inpatientvisits(hospitalization),andemergencyroomvisits.

void:Tomarkdataasdeletedfromauserperspective,butretainitintheOpenMRSdatabase.

wiki:Awebsitecontainingdocumentationandotherresourcesforaprojectororganization.

workflow:Aseriesoftaskstoaccomplishagoal.

AppendixA:Glossary

121

AppendixB:ExampleHTMLFormSource

<htmlform>

<!--Autogeneratedexampleform(templatefrom01-Nov-2010-->

<macros>

paperFormId=(Fillthisin)

headerColor=#009d8e

fontOnHeaderColor=white

</macros>

<style>

.section{

border:1pxsolid$headerColor;

padding:2px;

text-align:left;

margin-bottom:1em;

}

.sectionHeader{

background-color:$headerColor;

color:$fontOnHeaderColor;

display:block;

padding:2px;

font-weight:bold;

}

table.baseline-alignedtd{

vertical-align:baseline;

}

</style>

<spanstyle="float:right">PaperFormID:$paperFormId</span>

<h2>AmaniAntenatalHistory(v1.0)</h2>

<sectionheaderLabel="1.EncounterDetails">

<tableclass="baseline-aligned">

<tr>

<td>Date:</td>

<td>

<encounterDatedefault="today"/>

</td>

</tr>

<tr>

<td>Location:</td>

<td>

<encounterLocation/>

</td>

</tr>

<tr>

<td>Provider:</td>

<td>

<encounterProvider/>

</td>

</tr>

<tr>

<td>PatientName:</td>

<td>

<lookupclass="value"expression="patient.personName"/>

</td>

</tr>

</table>

</section>

<sectionheaderLabel="2.AntenatalHistory">

<tableborder="1"cellspacing="0"class="baseline-aligned">

<tr>

<td>

AppendixB:ExampleHTMLFormSource

122

<tableborder="1"cellspacing="0">

<tr>

<td>

<table>

<tr>

<td>

<b>ReasonForVisit:</b>

</td>

<td>

<obsconceptId="1433"style="radio"answerConceptIds="1435,1434,5622"answerLabels="Plann

ingPregnancy&lt;br\/&gt;,CurrentlyPregnant&lt;br\/&gt;,Other"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>AntenatalVisits#:</b>

</td>

<td>

<obsconceptId="1425"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>IfPregnant,was

<br/>pregnancyintended?</b>

</td>

<td>

<obsconceptId="1426"style="radio"answerConceptIds="1065,1066,1067"answerLabels="Yes&l

t;br\/&gt;,No&lt;br\/&gt;,Unknown"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>LastMenstrualPeriod:</b>

</td>

<td>

<obsconceptId="1427"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

AppendixB:ExampleHTMLFormSource

123

<b>DateofDelivery:</b>

</td>

<td>

<obsconceptId="1596"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>BloodType:</b>

</td>

<td>

<obsconceptId="1426"style="radio"answerConceptIds="152674,152675,152676,152677,152

678,152679,152680,152681"answerLabels="A+,A-&lt;br\/&gt;,B+,B-&lt;br\/&gt;,0+,0-&lt;br\/&gt;,AB+,

AB-&lt;br\/&gt;"/>

</td>

</tr>

</table>

</td>

</tr>

</table>

</td>

<td>

<tableborder="1"cellspacing="0">

<tr>

<td>

<table>

<tr>

<td>

<b>High-RiskSex:</b>

</td>

<td>

<obsconceptId="1355"style="yes_no"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>HIVTest:</b>

</td>

<td>

<obsconceptId="1356"style="yes_no"dateLabel="&lt;br\/&gt;Date:"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>Partner'sHIVStatus:</b>

</td>

AppendixB:ExampleHTMLFormSource

124

<td>

<obsconceptId="1436"style="radio"answerConceptIds="664,703,1067"answerLabels="Negativ

e&lt;br\/&gt;,Positive&lt;br\/&gt;,Unknown"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>STITreatment:</b>

</td>

<td>

<obsconceptId="1428"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>RPR/VDRL:</b>

</td>

<td>

<obsconceptId="299"style="radio"answerConceptIds="1228,1229"answerLabels="Reactive&l

t;br\/&gt;,NR"/>

</td>

</tr>

</table>

</td>

</tr>

<tr>

<td>

<table>

<tr>

<td>

<b>LastTetnus:</b>

</td>

<td>

<obsconceptId="1428"/>

</td>

</tr>

</table>

</td>

</tr>

</table>

</td>

<td>

<table>

<tr>

<td>

<b>RecentContraceptiveUse:</b>

<br/>

<obsconceptId="1635"answerConceptId="1107"answerLabel="None"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="780"answerLabel="OralContraception"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="190"answerLabel="Condoms"style="checkbox"/>

<br/>

AppendixB:ExampleHTMLFormSource

125

<obsconceptId="1635"answerConceptId="5277"answerLabel="NaturalPlanning/Rhythm"style="che

ckbox"/>

<br/>

<obsconceptId="1635"answerConceptId="5278"answerLabel="Diaphragm"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1378"answerLabel="Depo-Provera"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1359"answerLabel="Norplant"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="1388"answerLabel="Surgery"style="checkbox"/>

<br/>

<obsconceptId="1635"answerConceptId="5622"answerLabel="Other"style="checkbox"/>

<br/>

</td>

</tr>

</table>

</td>

<td>

<table>

<tr>

<td>

<b>PreviousComplications:</b>

<br/>

<obsconceptId="1430"answerConceptId="113859"answerLabel="Hypertension"style="checkbox"/>

<br/>

<obsconceptId="1430"answerConceptId="1431"answerLabel="LowBirthWeightBaby"style="checkbo

x"/>

<br/>

<obsconceptId="1430"answerConceptId="119481"answerLabel="DiabetesMellitus"style="checkbox"

/>

<br/>

<obsconceptId="1430"answerConceptId="48"answerLabel="Miscarriage"style="checkbox"/>

<br/>

<obsconceptId="1430"answerConceptId="1171"answerLabel="CesareanSection"style="checkbox"/>

<br/>

<obsconceptId="1430"answerConceptId="228"answerLabel="AntepartumHemorrhage"style="checkbox"

/>

<br/>

<obsconceptId="1430"answerConceptId="230"answerLabel="PostpartumHemorrhage"style="checkbox"

/>

<br/>

<obsconceptId="1430"answerConceptId="130"answerLabel="PuerperalSepsis"style="checkbox"/>

<br/>

<obsconceptId="1430"answerConceptId="113602"answerLabel="ProlongedLabor"style="checkbox"/>

<br/>

<obsconceptId="1430"answerConceptId="127847"answerLabel="Recto-vaginalFistula"style="check

box"/>

<br/>

<obsconceptId="1430"answerConceptId="49"answerLabel="Vesico-vaginalFistula"style="checkbox"

/>

<br/>

<obsconceptId="1430"answerConceptId="5622"answerLabel="Other"style="checkbox"/>

<br/>

</td>

</tr>

</table>

</td>

</tr>

</table>

</section>

<submit/>

</htmlform>

AppendixB:ExampleHTMLFormSource

126

AppendixB:ExampleHTMLFormSource

127

AppendixC:DocumentHistory

Version2.0(Current)

Released:June,2012,ConvertedtoGitBookformat:November,2016

DescribesOpenMRSVersion:1.9.x

Notes:Updatedtodescribe1.9changes.TheseincludethenewVisitsfeature,changestoconceptmappings,andchangestoproviders.

Version1.0

Released:October,2011

DescribesOpenMRSVersion:1.8.x

Notes:TheOpenMRSGuidewascreatedattheGoogleSummerOfCode/FLOSSManualDocumentationCamp.

AppendixC:DocumentHistory

128