motech documentation · motech documentation, release 0.24-snapshot •notify nurse when patient...

MOTECH DocumentationRelease 0.24-SNAPSHOT

Grameen Foundation

August 19, 2015

Contents

1 About MOTECH 31.1 MOTECH Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 What can MOTECH do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Getting Started Implementers 52.1 Installing MOTECH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Configuration System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Modeling Data with MOTECH Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4 Messaging in MOTECH Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602.5 Connecting MOTECH to OpenMRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612.6 Integrating MOTECH with CommCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642.7 Using the Tasks Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682.8 Configuring Pill Reminders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842.9 Configuring Your MOTECH App to be HIPAA Compliant . . . . . . . . . . . . . . . . . . . . . . . 842.10 Tour of MOTECH UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842.11 Security Rules - Dynamic URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852.12 Automatic REST API documentation UI in MOTECH . . . . . . . . . . . . . . . . . . . . . . . . . 88

3 Architecture and Technical Overviews 913.1 Core Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913.2 Event and Scheduler Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933.3 Modules Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963.4 Data Services Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963.5 Security Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

4 Modules 1014.1 Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.2 Appointments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.3 Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.4 CMS Lite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.5 CommCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.6 Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.7 Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.8 Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.9 Hindi Transliteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.10 Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.11 IVR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.12 Message Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

i

4.13 mTraining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.14 OpenMRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.15 Pill Reminder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.16 Schedule Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024.17 Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034.18 SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034.19 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

5 Developing the MOTECH Platform 1055.1 Setting up a Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.3 Developing and Submitting a Patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225.4 MOTECH Code Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.5 Commit Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.6 Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255.7 Code Review Workflow and Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345.8 Authoring Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365.9 Managing External OSGi dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365.10 Project Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405.11 Release Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405.12 Browser Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425.13 Static resources - faster UI development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

6 Deployment 1456.1 Load Balancing with Apache 2 WebServer - Sticky Session . . . . . . . . . . . . . . . . . . . . . . 1456.2 Using MOTECH with multibyte characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

7 Demos 1497.1 Demo: Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497.2 IVR Demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1567.3 Demo: Modeling a New System with MOTECH Data Services . . . . . . . . . . . . . . . . . . . . 1707.4 Demo: MOTECH Data Services Bulk Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727.5 Demo: OpenMRS Schedule Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737.6 Demo: SMS-Based Pregnancy Message Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757.7 Demo: Create a Care Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

8 Contribute 1818.1 Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828.3 Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

9 Release Notes 1859.1 Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1859.2 Older Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

10 Roadmap 19310.1 Version 0.25 - Early 2015 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19310.2 Version 1.0 - mid-late 2015 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

11 MOTECH Mailing Lists 19511.1 MOTECH Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19511.2 MOTECH Implementers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

12 Javadoc 19712.1 org.motechproject.admin.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

ii

12.2 org.motechproject.admin.mds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20612.3 org.motechproject.admin.messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20712.4 org.motechproject.admin.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20812.5 org.motechproject.bundle.extender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21312.6 org.motechproject.commons.api . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21512.7 org.motechproject.commons.api.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22512.8 org.motechproject.commons.api.model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22712.9 org.motechproject.commons.date.exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22712.10 org.motechproject.commons.date.model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22812.11 org.motechproject.commons.date.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23212.12 org.motechproject.commons.date.util.datetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24012.13 org.motechproject.commons.sql.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24212.14 org.motechproject.commons.sql.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24312.15 org.motechproject.config.core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24412.16 org.motechproject.config.core.constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24512.17 org.motechproject.config.core.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24912.18 org.motechproject.config.core.filestore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25712.19 org.motechproject.config.core.filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25912.20 org.motechproject.config.core.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25912.21 org.motechproject.config.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26112.22 org.motechproject.config.monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26412.23 org.motechproject.config.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26512.24 org.motechproject.email.builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27212.25 org.motechproject.email.contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27612.26 org.motechproject.email.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27712.27 org.motechproject.email.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28312.28 org.motechproject.event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28512.29 org.motechproject.event.listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28812.30 org.motechproject.event.listener.annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29112.31 org.motechproject.event.messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29412.32 org.motechproject.mds.annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29612.33 org.motechproject.mds.builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30212.34 org.motechproject.mds.config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30612.35 org.motechproject.mds.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31312.36 org.motechproject.mds.dto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37412.37 org.motechproject.mds.enhancer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41812.38 org.motechproject.mds.event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41912.39 org.motechproject.mds.ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42112.40 org.motechproject.mds.ex.csv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42412.41 org.motechproject.mds.ex.entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42512.42 org.motechproject.mds.ex.field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42912.43 org.motechproject.mds.ex.lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43012.44 org.motechproject.mds.ex.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43312.45 org.motechproject.mds.ex.rest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43612.46 org.motechproject.mds.filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43812.47 org.motechproject.mds.helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44412.48 org.motechproject.mds.javassist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45512.49 org.motechproject.mds.jdo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45812.50 org.motechproject.mds.listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46712.51 org.motechproject.mds.listener.proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46812.52 org.motechproject.mds.listener.register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46912.53 org.motechproject.mds.lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47012.54 org.motechproject.mds.performance.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47112.55 org.motechproject.mds.performance.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

iii

12.56 org.motechproject.mds.performance.service.impl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47512.57 org.motechproject.mds.query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47612.58 org.motechproject.mds.repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48912.59 org.motechproject.mds.rest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49812.60 org.motechproject.mds.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50612.61 org.motechproject.mds.service.impl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55112.62 org.motechproject.mds.service.impl.csv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56612.63 org.motechproject.mds.service.impl.csv.writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57512.64 org.motechproject.mds.service.impl.history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57712.65 org.motechproject.mds.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58212.66 org.motechproject.mdsmigration.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62612.67 org.motechproject.osgi.web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62612.68 org.motechproject.osgi.web.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64912.69 org.motechproject.osgi.web.exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65112.70 org.motechproject.osgi.web.ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65212.71 org.motechproject.osgi.web.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65512.72 org.motechproject.osgi.web.settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65712.73 org.motechproject.osgi.web.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65812.74 org.motechproject.scheduler.builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66512.75 org.motechproject.scheduler.contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66712.76 org.motechproject.scheduler.exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68712.77 org.motechproject.scheduler.factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68812.78 org.motechproject.scheduler.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68912.79 org.motechproject.scheduler.service.impl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69712.80 org.motechproject.security.annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70312.81 org.motechproject.security.authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70412.82 org.motechproject.security.builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70712.83 org.motechproject.security.constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70912.84 org.motechproject.security.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71412.85 org.motechproject.security.ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72512.86 org.motechproject.security.model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72812.87 org.motechproject.security.repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73512.88 org.motechproject.security.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74512.89 org.motechproject.security.validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75812.90 org.motechproject.server.api . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76012.91 org.motechproject.server.config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76812.92 org.motechproject.server.config.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77212.93 org.motechproject.server.config.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78312.94 org.motechproject.server.osgi.event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78412.95 org.motechproject.server.osgi.status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78612.96 org.motechproject.server.osgi.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79012.97 org.motechproject.server.startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79312.98 org.motechproject.server.ui.ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79412.99 org.motechproject.server.web.controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79412.100org.motechproject.server.web.form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80012.101org.motechproject.server.web.helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80512.102org.motechproject.server.web.validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80812.103org.motechproject.tasks.annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81112.104org.motechproject.tasks.contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81312.105org.motechproject.tasks.domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82712.106org.motechproject.tasks.ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88612.107org.motechproject.tasks.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88912.108org.motechproject.tasks.repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89112.109org.motechproject.tasks.service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892

iv

12.110org.motechproject.tasks.util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

13 Acknowledgements 91113.1 Balsamiq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91113.2 GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91113.3 JetBrains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91113.4 YourKit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911

v

MOTECH Documentation, Release 0.24-SNAPSHOT

The topics below will give you an introduction to MOTECH, an open source mHealth platform developed by theGrameen Foundation. Some of these topics are quite technical in nature (i.e. aimed at software developers), whileothers are more accessible to people who aren’t familiar with software code.

Contents 1


2 Contents

CHAPTER 1

About MOTECH

Mobile Technology for Community Health (MOTECH) is a modular, extensible open source software project origi-nally designed for mobile health (mHealth), which can also be used outside of the health domain. It allows organiza-tions to use mobile technology to communicate information to patients, collect data about patients, alert caregivers topatients’ status, and schedule caregivers’ work. The modular system allows organizations to choose among multiplemHealth technologies and to enable data sharing for users of the system.

1.1 MOTECH Architecture Overview

MOTECH consists of the core platform and several modules, each providing use of a technology such as SMS oremail, or access to an external system such as CommCare. Organizations can choose to install one or more modules,and developers can extend MOTECH by writing new modules. MOTECH is written in Java. It depends on opensource systems including Apache Tomcat, Apache ActiveMQ, and Quartz. For more information about MOTECHarchitecture, see Core Architecture and Modules Architecture.

1.2 What can MOTECH do?

The MOTECH Platform can be used for setting appointments, tracking any scheduled activity, and managing workersdeployed in the field. Its initial implementations have been for mHealth projects that improve health by sendingmessages to patients and caregivers based on an evaluation of the recommended schedule of care compared to thepatient’s health-related actions. Some features of typical MOTECH-based applications are:

Communicate information to patients via voice or SMS according to a schedule of care defined for the patient’scondition, e.g.:

• Reminders for ANC appointments, lab visits, etc.

• Reminders to take medication on schedule, e.g., DOTS, ART, etc.

• Reminder notices to take children for scheduled immunization services

Collect data from patients or caregivers, e.g.:

• Patients report their symptoms prior to treatment or during treatment (adverse events)

• Patients give feedback on service delivery

• Caregivers report what service was delivered to a patient and on what date

Alert caregivers of the status of their patients, e.g.:

• Notify Community Health Worker when patient has not taken ART, DOTS or other drugs

3


• Notify nurse when patient has not kept a scheduled appointment (e.g., ANC visit)

Facilitate communication between patients, caregivers, and/or health administrators, e.g.:

• Establish secure peer networks for patients who share similar health concerns

• Initiate conversations between patients and caregivers in a way that allows the caregiver to manage the workloadeffectively

4 Chapter 1. About MOTECH

CHAPTER 2

Getting Started Implementers

We recognize that the MOTECH Platform Server requires deep programmatic understanding to implement. TheMOTECH Platform Server was built to be generic, allowing for complex customization through the user interface.This section is intended for you, as an implementer of MOTECH, to help get started with installation and begincreating custom solutions to meet your needs. After the installation, you will have to configure the implementationand begin building applications within the platform. The topics below cover some of the common features that needto be configured for a MOTECH app.

As the platform matures, most of the features below will be usable by implementers without developingany software code. As of now, a number of these features do require some coding in order to use (thetopics below provide sample code where appropriate). Feel free to reach out to our MOTECH-dev group if you get stuck or can’t decide the best path forward.

2.1 Installing MOTECH

This installation guide is used for demo systems based on Ubuntu 14.04 LTS. It assumes you are running on the sameand is not suitable for a full production install which requires additional steps to ensure security of the system. Forexample, it’s not advisable to use the root username in MySQL to setup the databases. MOTECH will run on otheroperating systems but the commands required and external packages will change. The changes shouldn’t be drasticbut they aren’t documented here.

2.1.1 Install and Configure Dependencies

MOTECH depends on the following software:

Tomcat7Java7 (OpenJDK or OracleJDK) OpenJDK installs as a dependency of Tomcat7ActiveMQMySQL

A full install script is available here.

1. Install Tomcat7, ActiveMQ and MySQL

sudo apt-get install -y tomcat7sudo apt-get install -y activemq mysql-server

5

http://docs.motechproject.org/en/latest/get_started/install.sh


Note: MySQL is going to ask you for a root password. You have to input it twice.Remember it because we’ll use this later.

2. Change the ownership of the tomcat7 directories

sudo chown -R tomcat7:tomcat7 /var/lib/tomcat7/ /usr/share/tomcat7/sudo service tomcat7 restart

3. Configure ActiveMQ

ActiveMQ needs an enabled instance to run. Use the following command to create a sym-bolic link from instances-available to instances-enabled.

sudo ln -s /etc/activemq/instances-available/main /etc/activemq/instances-enabled/mainsudo sed -e ’s/


Once complete, test the MySQL connection by clicking the ‘Verify SQL Connection’ button. Then, click ‘Continue’

2.1.4 Complete Startup Settings

The MOTECH startup settings screen asks you to choose a language and select a login mode. Choose ‘Repository’ tocreate a new admin username and password.

2.1. Installing MOTECH 7


You will be redirected to the MOTECH login screen where you enter the admin username and password you justcreated and your installation is complete.

2.2 Configuration System

This document describes the MOTECH configuration system.

2.2.1 Step 1: Specify Config Locations

Default Behavior

By default, all configuration files are loaded from one of the following locations:

....${user.home}/.motech/config/

For example, if Motech runs under the user motech in Linux, configuration files will be searched in“/home/motech/.motech/config” folder.

Or:

..../etc/motech/

If the configuration files are not found in the above mentioned location, files will be searched in “/etc/motech” folder.

Overriding Default Behavior

If you want to override the location where configuration files are loaded from, you have to add config-locations.properties to ${user.home}/.motech or to ${user.home}/ directory. Otherwise the property file in classpath

8 Chapter 2. Getting Started Implementers


will be picked up. Default config-locations.properties file:

....config.location= ${sys:user.home}/.motech/config/,/etc/motech/.

where “${sys:user.home}” is used to specify the home directory.

Note that, multiple locations can be specified for config.location property, and motech-settings.properties (which con-tains platform core config) config file will be searched starting from the first location and then falling back to nextspecified location, if it is not found. The directory in which it is found, is considered as the current config location andall other config files will be looked only in that particular location. For e.g., in the above sample config, if you havemotech-settings.properties in /etc/motech/, then all config files will be searched in /etc/motech/ location only. Youcannot have files in different locations.

2.2.2 Step 2: Bootstrap Configuration

There are certain properties which are essential for the system to start up. These properties can be defined either inbootstrap.properties file or by environment variables. The properties are:

• db.url – The database connection url, e.g.: localhost:5984

• db.username – The user who has access to the database.

• db.password – Password to connect to the database.

• tenant.id – Optional. Default value is default.

• config.source – Optional. The source from which MOTECH core configuration and all module configurationsshould be read. Valid config values can be either one of FILE or UI. Default value is UI.

During startup, the system will look for these configurations in the following locations, falling back in order (that iswhen the properties are found in any of the following locations, search look up will stop):

1. Config Directory Environment Variable: If MOTECH_CONFIG_DIR environment variable is defined, then thesystem will load properties from ${MOTECH_CONFIG_DIR}/bootstrap.properties.

2. Config Environment Variables: Config is loaded from one or more environment variables:

• MOTECH_DB_URL – specifies value for db.url

• MOTECH_DB_USERNAME - specifies value for db.username

• MOTECH_DB_PASSWORD – specifies value for db.password

• MOTECH_TENANT_ID – specifies value for tenant.id

• MOTECH_CONFIG_SOURCE – specifies value for config.source

3. Location from Property file: bootstrap.properties file is loaded from any one of the locations specified in config-locations.properties file described above.

We are working on a feature in which, if bootstrap.properties is not found in any of the above mentioned locations, aUI will be presented to user after startup, prompting for bootstrap properties.

2.2.3 Step 3: MOTECH Core Config

There are some system configurations and activemq configurations which are needed to get MOTECH up and running.

• System configurations:

– system.language - Can take en(English), pl(Polski), es(Spanish), fr(French), it(Italian), sw(Swahili)as values(although only English and Polski are implemented as of now). Optional, default value is en.

2.2. Configuration System 9


– statusmsg.timeout - Represents the expiration time(in seconds) of messages and notifications in adminUI. Optional, default value is 60.

– login.mode - Can be repository or openId (case insensitive).

– provider.name - OpenId? provider name, mandatory in case login mode is openId.

– provider.url - OpenId? provider url, mandatory in case login mode is openId.

• Security configurations(For more details you should read the security configuration section):

– security.required.email - Indicates whether you must provide an email address when creating the user.

– security.failure.login.limit - The permissible number of incorrect login attempts, default value is 0.After this limit is reached the user is blocked. After a successful login counter is reset. If the value is0 then blocking is inactive.

– security.session.timeout - The session timeout in seconds, default 30 minutes. After this time sessionwill be closed.

– security.password.minlength - The minimum length of the password, default 0. if the value is 0 thenlength checking is disabled.

– security.password.validator - The password validator, it specify password rules e.g. 1 number, 1 spe-cial character. Can take none, lower_upper(at least 1 uppercase and lowercase), lower_upper_digit(atleast 1 uppercase, lowercase and digit), lower_upper_digit_special(at least 1 uppercase, lowercase,digit and special character) as values, default none validator is used.

• Activemq configurations:

– jms.queue.for.events - Queue name to hold motech event messages. Optional, default value is Queue-ForEvents.

– jms.topic.for.events - Topic name to hold motech event messages. Optional, default value is Topic-ForEvents.

– jms.broker.url - JMS broker URL. Can take failover URLs also. Sample values: tcp://localhost:61616,failover:(tcp://192.168.32.1:61616,tcp://192.168.32.2:61616)?randomize=false

– jms.maximumRedeliveries - Maximum number of redeliveries in case of any exceptions and a mes-sage consumption fails. Optional, default value is 0.

– jms.redeliveryDelayInMillis - Delay(in seconds) between successive re-deliveries of messages. Ifdelay=d and first exception was raised at time=t, then successive redelivery times are calculated usingexponential backoff . i.e. t+d, t+(d*2), t+(d*4), t+(d*8), t+(d*16) and so on, till maximum redeliverycount is reached. Optional, default value is 2000.

– jms.concurrentConsumers - Optional, default value is 1.

– jms.maxConcurrentConsumers - Optional, default value is 10.

– jms.session.cache.size - Optional, default value is 10.

– jms.cache.producers - Optional, default value is false.

Case 1: When ConfigSource is FILE

Define motech-settings.properties file in any one of the locations defined in config-locations.properties with the abovementioned properties.



Case 2: When ConfigSource is UI

After server startup, if core settings are not configured already, you will be presented with a startup page which asks forSystem Language, Queue URL for events, Login Mode and user setup based on login mode. Other activemq settingscan be changed in Settings tab after logging in.

2.2.4 Step 4: Module Configurations

Case 1: When ConfigSource is FILE

Module specific property files can be added to:

....// directory

and any JSON templates/configurations to:

....//raw/ directory.

A typical example of a motech’s module symbolic name:

....

prefixed with “org.motechproject.motech-”.

All these files are monitored for changes. So, any change to these config files at runtime would be detected and savedin DB. Restart the module if required using Manage Modules tab in UI. We are enhancing the config monitor to raisean event in case of config change. This event can be listened by interested modules and take appropriate actions.

Case 2: When ConfigSource is UI

After server startup, you can find each module having settings UI associated with it in the Manage Modules tab, whereyou can edit the properties for the module. Also, restart the module if required. We are enhancing the config monitorto raise an event in case of config change.

2.3 Modeling Data with MOTECH Data Services

2.3. Modeling Data with MOTECH Data Services 11


Table of Contents

• Modeling Data with MOTECH Data Services– Introduction

* MDS generated entities bundle– MDS Entities

* Automatically added fields– MDS Lookups– Data Services– EUDE - End User Defined Entities

* Creating EUDE through UI* Defining a Lookup through the UI* Creating EUDE through the Entity API* Creating Lookups through the API* Regenerating the entities bundle* Programmatic access to EUDE entities

– DDE - Developer Defined Entities* Defining entities - the @Entity annotation* DDE entity fields - @Field and @Ignore annotations* DDE relationships* Using DataNucleus annotations* DDE service interfaces* Defining editable lookups for DDE entities* Programmatic usage of DDE entities

– MEDE - MDS Enhanced Developer Defined Entities* Extending DDEs through the UI* Extending DDEs through code

– Supported field types* Map type

– History tracking for entities* Controlling whether to record history* Retrieving history using code

– MDS Trash Bin* Using Trash using code

– The MDS Data Browser– Data browsing settings

* Changing the settings through the UI* Changing the settings through annotations

– The REST API* REST endpoints* Response codes* Read response* Parameters and lookups* REST fields exposed* Changing REST settings through the UI* Changing REST settings through annotations* REST documentation

– Entity validations* Configuring validations through the UI* Configuring validations using annotations

– MDS Lookup Service– Executing custom queries

* Executing JDO queries* Executing SQL queries

– Using Spring Transactions with MDS– Security

* Access to the Data Services module* Access to the instances

– CRUD Events* Tasks integration

– Instance Lifecycle Listeners– Entities Migrations– Javadoc



2.3.1 Introduction

MOTECH Data Services (MDS) is the data layer for the MOTECH Platform. MDS allows defining the data modelboth through code (using annotations or the exposed API) and the Schema Editor UI. It is capable of exposing genericservices which allow executing CRUD operations on the defined model. It also is capable of exposing a fully functionalREST API for the defined entities on the fly. Entities defined through means of code can always be extended or gettheir settings modified through the MDS Schema Editor or its underlying API.

The benefits of MDS include:

• Generated user interface for data entry

• UI-based schema editor, and the ability to enhance developer-defined entities

• Generated OSGi services and Java APIs for accessing data objects

• Generated REST APIs for external data access

• Generated CRUD events for MDS entities (and exposure of these events via the Tasks module)

• Ability to register actions that execute on instances based on CRUD triggers

• Bulk import/export of data

• Change tracking (auditing) of data

• Object-level security

MDS uses DataNucleus underneath for persistence in a relational data store. Currently MDS officially supports twoRDBMS engines MySQL and PostgreSQL. Javassist is used for code generation and OSGi mechanics such as bytecodeweaving are used for replacing the code at runtime.

MDS generated entities bundle

All classes generated by MDS live in the mds-entities OSGi bundle, which gets generated at runtime and installed inthe directory ~/.motech/bundles. The bundle is always regenerated when changes are made to the MDS schema. Thisgenerated bundle can also be downloaded using the following url: http:///modulemds/jar.

2.3.2 MDS Entities

MDS defines an Entity concept. An MDS entity maps directly to a POJO class and a table in the relational database.Entities consist of fields which are directly mapped to the object fields and columns in the database table. MDSsupports multiple field types.

MDS integrates itself with the Tasks module, so a user can create a working application with a minimal amount ofcode. Entities generate task data providers which allow access to the data within MDS. Entities can also be configuredto publish MOTECH events which are fired after CRUD operations are completed in MDS. These CRUD events, areexposed as task triggers in a dynamically generated task channel. CRUD actions are also exposed as actions withinthe task module, allowing users to create database manipulating logic through the tasks module.

We can group entities into three categories:

EUDE - End User Defined Entities. The entities created using the UI by the end user. These classes do not exist atcompile time, but only after they are generated by MDS. Adding the bundle generated by MDS to the classpath willallow compile time access however. EUDE entities can also be defined using the MDS API through the EntityService.Users can view and create instances of the entities through the MDS Data Browser.

DDE - Developer Defined Entities. Developers can use annotations to mark their POJO classes as MDS Entities.These will be treated in the same way as EUDE entities, instances of the DDEs will also be accessible through the


http://www.datanucleus.org/http://www.mysql.com/http://www.postgresql.org/http://www.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/http://wikipedia.org/wiki/Plain_Old_Java_Objecthttp://wikipedia.org/wiki/Plain_Old_Java_Object


data browser. Users can still view the schema for these entities through the Schema Editor, add fields and modifysettings(although they can’t remove fields declared by the developer in the java class).

MEDE - MDS Enhanced Developer Defined Entity. These are DDEs that were enhanced with additional fields addedeither through the UI or the Entity API. This are the same as DDE, but with additional fields added at runtime. Thosefields can be accessed at compile time using Java Reflection API.

Automatically added fields

All entities in MDS will be enhanced with the following fields automatically:

Name Type Descriptionid Long The id field of the entity, used to uniquely identify the instance.owner String The username of the owner of the instance. This field can be used with security settings for

the entity in order to filter access to only instance owners.creator String The username of the creator of the instance. Automatically set to username of the MOTECH

user that created the instance. Note that security can be set up to limit instance access to onlycreators of those instances.

modi-fiedBy

String The username of the user that last modifier of the instance. Automatically set to theusername of the user that last edited the entity.

creation-Date

Date-Time

The datetime on which this entity was created. Filled automatically.

modifica-tionDate

Date-Time

The datetime on which this entity was last modified. Updated automatically.

Access to these fields can be done through reflections, through re-declaring them in the DDE class or by inheriting theMDSEntity class.

2.3.3 MDS Lookups

Lookups allow easily defining and executing queries on MDS entities. A lookup allows querying for a single ormultiple fields. A lookup field is always corresponding to a single field in the entity. It can be also configured to eitherreturn a single or multiple results.

Note: If more then one instance matches the criteria of a single return lookup, the lookup will fail.

Lookups at this moment can only use AND logic for doing a query for multiple fields. For OR(or move complex)logic JDO queries have to be used. Lookups also allow comparing fields against provided parameters using a customoperator or using a range or set of values, defining such lookups is not supported through the UI at the moment though.

For each lookup two additional versions of the method will be generated. The first one is the same as thelookup, but with an additional parameter at the end - org.motechproject.mds.query.QueryParams. This class con-tains pagination directives - page number and page size, it also contains information about ordering the results - anorg.motechproject.mds.util.Order object containing the sort direction and sort column. This version of the lookup isuseful for operating on large data sets and providing ordered views to the user. The third version is the same as thebasic lookup, but it returns a number (long) - the total count of the entity in the database. The name of the countmethod consists of count and the capitalized original lookup method name. For example for a lookup with a methodname byName the count method will be called countByName.

Note: When defining a DDE, it doesn’t matter which version of the lookup you define, all three methods will begenerated. For compile access to them however, they have to be explicitly defined in your service. More info ondefining lookups in DDEs can be found in the section about defining DDE Data Services


https://docs.oracle.com/javase/tutorial/reflect/


2.3.4 Data Services

All access to entities in MDS is done through Data Services. These are services implementing theorg.motechproject.mds.service.MotechDataService interface. They are exposed as OSGi service that can be re-trieved from the OSGi BundleContext. All data access exposed by MDS, either the REST API, the UI data browser,Csv Import/Export etc. is done through these services. The class of the service is generated at runtime and it extendsthe base DefaultMotechDataService class. Developers can extend the **MotechDataService** interface in order toadd their own lookups to the interface simply by declaring the method signatures and annotating them properly.

2.3.5 EUDE - End User Defined Entities

These entities are created by end users, either through the UI or using the exposed API. No programming knowledgeis required in order to define an EUDE using the first method. Although these entities are not known at compiletime(unless the jar generated by MDS is added to the classpath) programmatic access to these entities is still possibleusing Java Reflection API and some handy helper classes exposed by MDS - mainly the MdsLookupService.

Note: All EUDE classes share the same java package: org.motechproject.mds.entity

Creating EUDE through UI

The easiest way to create EUDE entities is to use the MOTECH UI. First select Data Services from the left navigationmenu(Modules menu), then navigate to the Schema Editor tab. You will see a dropdown allowing to select an existingentity for modification or deletion. Next to the dropdown menu you will see a New Entity button.

After that the user is asked for the name of the entity. This can be anything that is a legal name of a class in Java.


https://docs.oracle.com/javase/tutorial/reflect/


The view for managing entity fields is then displayed to the user. Users can add a field by selecting its type, choosinga name and a display name. ‘display name’ represents what will be visualised to the users in the MDS Data Browser,task editor etc. ‘name’ represents the actual name of the field that will be used for class and table creation. After thisdata is entered, hitting the green plus sign will add the field.

The field is then expanded and the user is presented with options to modify the field settings:

The Basic sections allows to change the previously entered name and display name, it also allows marking the fieldas required, meaning that users will be prevented from creating an instance without any value in this field. A defaultvalue for the field can also be entered, as well as a tooltip that will be shown to users creating instances of the entity.



The Metadata section allows adding metadata to the field. This used internally by MDS for features such as relation-ships. End users should not worry about this section, but advanced users can add any values they wish for their ownprocessing needs. Metadata is retrieved with the field schema using the Entity API. An example of using metadatacould be a scenario when we are writing a third party export tool, that takes the MDS Schema and imports it into a3rd party system. The field metadata can be used by that tool in order to recognize some fields as requiring specialprocessing logic.

The Validation section allows setting specific validation rules for the field. Users will then be constrained by thesevalidations when creating instances of the entity. Validations are type specific.

The Settings tab allows users to set type specific settings of the field. An example setting is the ‘Max text length’ of aString field, which indicates the maximum length of the string at the database level.



Existing fields can be deleted using the trash bin icon next to their type.

When the user is done modifying the entity, clicking Save changes will save the changes to schema and regenerateMDS entities. Clicking Abandon Changes will abandon all changes made by the user since the last save.

Defining a Lookup through the UI

Users can use the UI for adding lookups to an entity. These lookups can then be executed either directly through thedata services or using the Data Browser UI. In order to add a new lookup, first open the advanced settings of an entityby clicking the ‘Advanced Settings’ button.



After that users can create lookups by clicking on the ‘New Lookup’ button.

The name fo the lookup can then be modified as well as whether it returns a single or multiple objects. In order tomake a lookup useful, it has be executed on a given set of fields, which can be added on the right side of the windowby clicking the ‘New Lookup Field’ button and selecting the right field from the dropdown. They can be deleted usingthe trash bin button.



In order to remove a lookup, the delete button in the lower right of dialog can be used.

When the user is done adding lookups to an entity, clicking Save changes will save the changes and trigger regenera-tion. Clicking Abandon Changes will abandon all changes made by the user since the last save.



Creating EUDE through the Entity API

Creation of entities can be also done using the org.motechproject.mds.service.EntityService. This an OSGi serviceexposed by MDS which allows creation and modification of MDS entities, exposing everything that the UI does. Inorder to use the service it has to be retrieved from the OSGi context, either directly using the OSGi API or a Blueprintreference can be used to inject a proxy for that service directly as a Spring bean.

Example of retrieving the service manually:

import org.motechproject.mds.service.EntityService;import org.osgi.framework.*;

...

public EntityService getEntityService() {// note that if using Spring, the BundleContext can be injected as any other bean// which allows skipping this stepBundleContext bundleContext = FrameworkUtil.getBundle(EntityService.class).getBundleContext();

// get the service reference from the bundle contextServiceReference ref = bundleContext.getServiceReference(EntityService.class);

// return the service for the reference, or null if there are no references// the service should always be available, so a null reference definitely indicates some sort errorreturn ref == null ? null : bundleContext.getService(ref);

}

and the preferred way using blueprint. Note that thanks to this declaration an EntityService bean becomes available inyour Spring context.



After getting hold of the service the entity can be created using the createEntity method:

EntityService entityService = getEntityService();

EntityDto entity = new EntityDto("Patient");

// the EntityDto instance returned will have the id value setentity = entityService.createEntity(entity);

If we want to edit an existing entity, we can retrieve it using the EntityService:

// We can use the org.motechproject.mds.util.ClassName utility in order// to get the EUDE class name given just the nameString className = ClassName.getEntityName("Patient");

// className is org.motechproject.mds.entity.PatientEntityDto entity = entityService.getEntityByClassName(className);

When we have the EntityDto instance, fields can get added to the entity using the service and EntityDto returned:

// a simple integer fieldFieldDto simpleField = new FieldDto("simpleInt", "Simple integer", TypeDto.INTEGER);

// a required name fieldFieldDto nameField = new FieldDto("name", "Patient Name", TypeDto.STRING, true);

// an optional date of birth field, with a tooltipFieldDto dobField = new FieldDto("dob", "Date of Birth", TypeDto.DATETIME, false, null,

"Patients date of birth, leave blank if unknown");

// a required Social ID field, defaulting to 0FieldDto socialIdField = new FieldDto("socialId", "Social ID", TypeDto.LONG, true, 0L);

// add the fields to the entity created earlierentityService.addFields(entity, simpleField, nameField, dobField, socialIdField);

In order to make these changes take effect, data bundle regeneration must be triggered.

Creating Lookups through the API

Just as any other edits on the entity schema, lookups can also be created using the EntityService. In a similar fashion tofields, the addLookups method can be used for adding lookups to an entity. Given that we have the EntityDto objectand the EntityService(), we can create lookups in the following manner:

// this lookup will check the name field, during an exact comparisonLookupDto lookupByName = new LookupDto("By name",

true, // single object returntrue, // expose this lookup through RESTArrays.asList(new LookupFieldDto("name", LookupFieldDto.Type.VALUE)

));

// this a complex lookup using multiple fieldsLookupDto complexLookup = new LookupDto("Complex lookup",

false, // return multiple objectsfalse, // do not expose by REST

Arrays.asList(



// the custom operator matches() will be used for querying on the name fieldnew LookupFieldDto("name", LookupFieldDto.Type.VALUE, Constants.Operators.MATCHES),// the dob parameter will take a range, with a min and max valuenew LookupFieldDto("dob", LookupFieldDto.Type.RANGE),// for the state field, a set of possible values can be suppliednew LookupFieldDto("state", LookupFieldDto.Type.SET),// the search through relationship fields is possible using the dot operatornew LookupFieldDto("relationshipField.number", LookupFieldDto.Type.VALUE))

);

// add the lookupentityService.addLookups(entity, lookupByName, complexLookup);

In order to make these changes take effect, data bundle regeneration must be triggered.

Regenerating the entities bundle

After we are done with modifications to the entity schema, we must trigger regeneration in order for the classes to getupdated and made available in OSGi. For this we need to use org.motechproject.mds.service.JarGeneratorService,which we can retrieve the same way that we can retrieve the EntityService. Once we have an instance of the service,all we need to do is call the regenerateMdsDataBundle method:

JarGeneratorService jarGeneratorService = getJarGeneratorService();

jarGeneratorService.regenerateMdsDataBundle();

After the schema gets regenerated and all bundles using MDS get refreshed, the EUDE class should be available foruse.

Programmatic access to EUDE entities

EUDE classes can be accessed using java reflections. This is an example of creating an instance using reflections:

// first get the interface class name of the name entity// this helper method will always return org.motechproject.mds.entity.PatientString interfaceName = ClassName.getInterfaceName("Patient")

// Retrieve the Data ServiceMotechDataService service = ServiceUtil.getServiceForInterfaceName(bundleContext, interfaceName);

// Get the Class object for the entityClass entityClass = service.getClassType();

// create a patient instance and set the name to "John"Object instance = entityClass.newInstance();PropertyUtil.setProperty(instance, "name", "John");

// save it using the serviceservice.create(instance);

As you can see the access is done through the Data Service. We can obtain the Class object for the generated class anduse it for doing all required operations using reflections.



2.3.6 DDE - Developer Defined Entities

Developers can use annotated POJO classes in order to define the model for their application. Entities defined in thisway will be treated in a similar fashion to EUDE entities, they can also be accessed using the MDS Data Browser.New fields can also be added to DDEs - so that they become MEDE.

DDEs are represented by actual Java classes used for defining them. OSGi bytecode weaving is used in order toenhance these classes at runtime and add additional fields for them. Because of this, these classes can be used withease in code, since they are available during compile time to developers.

Defining entities - the @Entity annotation

In order to define a DDE by using the org.motechproject.mds.annotations.Entity annotation. This are the contentsof Patient.java, an example fo a DDE entity:

package org.motechproject.example;

import org.motechproject.mds.annotations.*;

@Entitypublic class Patient {

}

When the module containing this entity gets installed MDS will scan it for classes annotated with @Entity, and theclass above would get picked up for processing. Schema for the entity is then generated and persisted in the databaseof MDS, the class is also enhanced by DataNucleus. The MDS weaving hook then replaces the bytecode for this classin module ClassLoaders with the DataNucleus/MDS enhanced version, making it available to the modules using it.

Note: The module must export the package of the entity in OSGi, using the Export-Package directive in its manifest.

The @Entity annotation has the following parameters:

• name - The name of the entity displayed to the user. Defaults to the simple name of the annotated class.

• module - The name of the module for this entity. Defaults to the module name of the bundle from which thisentity comes from.

• namespace - The namespace in which the entity is defined. Optional, defaults to empty.

• tableName - The actual name of the table in the database for this entity. Allows users todirectly control the name in the data store. The default table name will take the form of:MDS___. If an entity has no namespace or module, those partswill be omitted.

• recordHistory - Set to true if MDS should record history for this entity.

DDE entity fields - @Field and @Ignore annotations

An entity does not have much use without any fields. MDS will treat any public field or field with public getter/setterin the class as an MDS field. In the class below, the field name will be picked up automatically as a field to be persistedin the database:


private String name;


http://wikipedia.org/wiki/Plain_Old_Java_Object


public String getName() {return name;

}

public void setName(String name) {this.name = name;

}}

The @Field annotation can be used for more explicit marking and control over the fields basic properties. In theexample below, the required parameter of the annotations is used to mark the name field as required, moreover thephysical column name in the database is set to “P_NAME”:


@Field(name = "P_NAME", required = true)private String name;

public String getName() {return name;

}

public void setName(String name) {this.name = name;

}}

The @Field annotation could also be placed on the setter or getter methods for the same effect.

Not every public field, or not every field that has a public getter or setter has to be persisted in the database. The@Ignore annotation can be used for marking such field as not persistent:


@Ignorepublic String name;

}

The name field in the example above will not become a database field and no MDS schema will be generated for it.This field will also not be accessible through the data browser.

DDE relationships

Creating relationships between entities is currently only possible for DDE. The definition of a relationship depends onthe type of the relation. MDS supports one-to-one, one-to-many, many-to-many and master-detail relationships, bothuni-directional and bi-directional. The way to define relationships for DDEs is presented in the examples below.

• One-to-one To create a one to one relationship, one of the related entities, should define a field of class, thatrepresents the second entity. Both classes must of course be valid MDS Entities. The code below, provided thatBook is an entity, will create a simple, uni-directional, one-to-one relationship between Author and Book.

@Entitypublic class Author {

@Fieldprivate String name;



@Fieldprivate Book book;

...}

• One-to-many To create a one to many relationship, one of the entities should define a collection of relatedentity. Just like in one-to-one relationships, both classes must be valid MDS entities to work. The code belowshows an example of a simple, uni-directional, one-to-many relationship between Author and Book (one authoris related with many books).



@Fieldprivate Set book;

...}

• Bi-directional relationships The bi-directional relationship is a model, in which both sides of a relation areaware of the existence of a relationship and can both refer to the other side of a relation.

To make the relationship bi-directional, two additional steps must be taken:

– The second entity must also define a relationship to the other entity

– Exactly one MDS field of a bi-directional relationship must be annotated with [email protected](mappedBy = “fieldName”) annotation. The fieldName should cor-respond to the field name that is in a relationship, in the another entity.

Please see the code below, for an example of a one-to-many, bi-directional relationship.



@Field@Persistent(mappedBy = "author")private Set book;

...}

@Entitypublic class Book {

@Fieldprivate String title;

@Fieldprivate Author author;

...}

• Many-to-many In this type of a relationship, both classes define a collection of related entity instances. The



many to many relationships are bi-directional by definition, which means it’s not possible to create a uni-directional version of such relation. The code below shows an example of a many-to-many relationship.



@Field@Persistent(mappedBy = "author")private Set book;

...}

@Entitypublic class Book {

@Fieldprivate String title;

@Fieldprivate Set author;

...}

• Master-detail MDS also supports master-detail model, where entity can inherit some fields from another entity.This is achieved by simple class inheritance, using Java keyword extends. Naturally, both classes must be validMDS entities for this to work. The code below shows an example of such master-detail model.

@Entitypublic abstract class Config {


@Fieldprivate Map properties;

...}

@Entitypublic class ModuleConfig extends Config {

@Fieldprivate String moduleName;

@Fieldprivate String moduleVersion;

...}

• Eager/lazy loading By default loading an entity with relationship will load its related entities, but that behaviourcan be configured through @Persistent(defaultFetchGroup = “true/false”) annotation. Please see the code belowfor an example.


@Field



private String name;

@Field@Persistent(defaultFetchGroup = "false")private Set book;

...}

Using DataNucleus annotations

DataNucleus JDO annotations can be used for enhancing DDEs. These annotations will be taken into considerationby DataNucleus and override the metadata that MDS generates. For example the @javax.jdo.Unique annotation canbe used in order to mark fields in an entity as unique. Refer to the DataNucleus documentation for more informationon using those annotations.

DDE service interfaces

DDEs can define their own interfaces that extend the default service interface that will be used for generating MDSservices. The service will be published under that interface, and thanks to inheritance, it will also expose type safemethods from the base service. Here is an example of defining an interface for a ‘Patient’ DDE:

public interface PatientDataService extends MotechDataService {

}

Thanks to this declaration type safe access to methods of the interface will be gained, the generic parameter Patientwill be inserted for the returned/parameter values.

This way of defining services for DDEs also allows to define additional lookups on the service. These lookups aredefined as plain method declarations with annotations and their implementation will be generated at runtime by MDS.The lookup method must be annotated with a @Lookup annotation. Method parameters should be marked with@LookupField annotation in order to connect the parameter with the actual entity field.

Note: If the @LookupField annotation is not present, MDS will fall back to an attempt to recognize the methodparameter name, take note that this requires debug information at runtime, so you have to compile your classes appro-priately.


/** This lookup finds a single patient based on the field ’name’.

* So invoking this method like this: byName("John") will

* return the patient with the name "John".

*/@LookupPatient byName(@LookupField(name = "name") String name);

/** The count method. Note that if this method is not defined,

it will be generated automatically from the lookup above.

*/long countByName(String name);

/*


http://www.datanucleus.org/products/datanucleus/jdo/annotations.html


* Same as above, but returns multiple results.

*/@LookupList byName2(@LookupField(name = "name") String name);

/** Same as above, but with QueryParams. Note that if this method is not defined,

it will be generated automatically from the lookup above.

*/@LookupList byName2(@LookupField(name = "name") String name, QueryParams queryParams);

}

The type of the parameter must match the type of the field, unless its one of the two special types:

Range - ranges can be used for looking up values that fall within the given range. An example is a range of dates.Range consist of min and max values, it is possible to provide only one of these values so there will be no boundaryon the second end.


/** Looks up patients for which the date of birth falls in the supplied range of

* values. Example of usage:

byDateOfBirth(new Range(DateTime.now().minusYears(30), DateTime.now().minusYears(10)));

* this returns patients born between 30 and 10 years ago.

*/@LookupList byDateOfBirth(@LookupField(name = "dob") Range dobRange);

}

Set - Doing lookups by sets is also possible. Instead of providing a single value, you provide a set of values. If aninstance field matches one of the values, that is considered a hit(basically this is logical OR matching).


/** Looks up patients which name matches one of the values from the set.

* Usage example:

** byName(new HashSet(Arrays.asList("Tom", "John", "Bob")));

** This will return patients named Tom, John or Bob.

*/@LookupList byName(@LookupField(name = "name") Set names);

}

Lookups can also use custom operators. The operator is inserted between the field name and the lookup parameter inthe JDO query generated for the lookup. The default symbol is ‘=’ - the equality sign, however different operatorscan also be used. Both JDO QL operators and methods can be used for lookups. If an operator like “



/** Does a matches() lookup on the name field.

* Because matches() is used, a regex pattern can be passed as the parameter.

*/@LookupList byName(@LookupField(name = "name", customOperator = "matches()") String name);

}

Note: The list of standard JDO operators that can be used in lookups is defined as constants in the classorg.motechproject.mds.util.Constants.Operators.

Defining editable lookups for DDE entities

One way to define lookups for DDE entities is to include a mds-lookups.json file in module resource directory.The file should be a valid array of EntityLookups class objects. Every lookup defined in the file will be addedonly once, so even after user had deleted lookup it won’t be recreated during module or MOTECH restart. This givesthe user complete control over those lookups without any restrictions. The unique identifier of every lookup is itsentity class name and lookup name combination. This is the intended way for modules to define lookups that shouldbe made editable by the end user. Backend code should not depend on these lookups.

Example mds-lookups.json file.

[{

"entityClassName" : "org.motechproject.tasks.domain.Task","lookups" : [

{"lookupName" : "Find Task by Owner","singleObjectReturn" : false,"exposedViaRest" : false,"lookupFields" : [

{"name" : "owner","type" : "VALUE","customOperator" : "\u003d\u003d","useGenericParam" : false

}],"readOnly" : false,"methodName" : "findTaskByOwner","fieldsOrder" : ["owner"

]}

]}

]

Including the example json in Tasks module will result in adding lookup for Task entity that will return all tasks thatare owned by the specified user.



Programmatic usage of DDE entities

All that has to be done in order to use a DDE is to retrieve the service for its interface. Because of the nature of DDEs,their classes are available during compile time. The service reference can be then retrieved using the standard OSGifacilities:

public PatientService getPatientService() {BundleContext bundleContext = FrameworkUtil.getBundle(Patient.class).getBundleContext();ServiceReference ref = bundleContext.getServiceReference(PatientService.class);return ref == null ? null : bundleContext.getService(ref);

}

The preferred way however is to use Blueprint OSGi references. The service will be injected as a Spring bean into theSpring application context of the module and can be then used as any other bean(for example it can be @Autowiredinto other beans).

Once the service instance is obtained, the only thing left to do is to just call the right method exposed.

Note: Usually a module should provide a service layer between the end user and the data layer implemented by MDS.It is not required however and left to the implementer.

2.3.7 MEDE - MDS Enhanced Developer Defined Entities

MEDE, MDS Enhanced Developer Defined Entities, are the DDE that were enhanced by users with additional fields atruntime. In practice they are not much different from DDEs. The only difference lies in the additional fields added atruntime. These fields are not part of the class at compile time, so access to these fields has to be done using reflections.They can also be set through the MDS Data Browser, so this is a way for nontechnical users to attach their own schemato the model.

Extending DDEs through the UI

Extending DDEs through the UI is not different from manipulating the schema of EUDE entities. Refer to the docu-mentation section on creating EUDE entities for more info. In order to extend a DDE first go the MDS Schema Editorand select the DDE entity you wish to edit:



Next add the field you wish to add to the entity:

You can also add lookup to the DDE:

Finally, save your changes to trigger MDS schema regeneration and make your changes take effect(you can alsoabandon your changes if you wish):



Extending DDEs through code

Extending DDEs through code is no different from extending EUDE entities. The only difference is that the EntityDtofor the DDE has to be retrieved by providing its class name. Refer to the documentation on extending EUDE throughcode.

2.3.8 Supported field types

MDS supports multiple types



MDSType

Java type MySQL DBtype

PostgreSQLDB type

Description

Blob java.lang.Byte[] mediumblob bytea A huge binary object, used to representbinary objects such as files or images.

Booleanjava.lang.Boolean bit(1) boolean A boolean field, that can take either true orfalse as value.

Com-bobox

Based on settings:enum enum collectionjava.lang.String Stringcollection

separate tableseparate tablevarcharseparate table

separate tableseparate tablevarcharseparate table

A combobox showing users a selection ofpredefined values. It can take single ormultiple selections and can be configured totake user defined values.

java.util.Date datetime timestampwith time zone

A type representing the java.util.Date. Onlyavailable for DDE.

Date org.joda.time.LocalDate date date A type representing the LocalDate class fromthe Joda library. Does not represent time,only date.

Date-Time

org.joda.time.DateTime datetime timestampwith time zone

A type representing the DateTime class fromthe Joda library.

Dec-i-mal

java.lang.Double double doubleprecision

A decimal field number.

In-te-ger

java.lang.Integer int(11) integer An integer number.

Lo-cale

java.util.Locale varchar varchar A type representing locale. Users will beshown a locale selection dropdown for type.

Map java.util.Map Separate table Separate table A map of key-value pairs.Pe-riod

org.joda.time.Period varchar varchar A type representing the Period class from theJoda library. Represents a period in time, i.e.3 months.

String java.lang.String varchar varchar A string of characters. The max length canbe configured. For long text fields, considerusing TextArea.

TextAreajava.lang.String mediumtext text A string of characters without max length.Suited for long text fields.

Time org.motechproject.commons.date.modelTime

varchar varchar A time representation without any date ortimezone information.

Map type

You can declare map with keys and values having generic type. MDS supports the following types of generics :

• key types (String, Integer, Long)

• value types (String, Integer, Long)

If you use the supported types, the field will be stored as a separate table in a database. Otherwise the field will beserialized.

Note: In a separate table map keys will be treated as primary keys. By default max key length in InnoDB is767 bytes. When the innodb_large_prefix configuration option is enabled, this length limit is raised to 3072 bytes,for InnoDB tables that use the DYNAMIC and COMPRESSED row formats. Here you can find more details :http://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_large_prefix


http://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_large_prefix


2.3.9 History tracking for entities

MDS allows to keep track of any changes made on the instances, as well as reverting the state of an instance to aconcrete revision. Both viewing the history of an instance and reverting can be done via the code and UI. This featurewill only be available if you explicitly set, that the history tracking for your entity should be enabled. If you want toview the history for your instance via UI, simply go to the detailed view of that instance, and click on the Historybutton.

Note: If you introduce any changes to the entity definition (e.g. add or delete a field), you will still be able to viewthe state of an instance, but you will lose the ability to revert an instance (because of a schema mismatch).

Controlling whether to record history

By default MDS doesn’t keep track of the instance revisions. Most of the DDEs that come with MOTECH moduleshave the tracking of the history disabled as well. To enable history tracking for the...

• Developer Defined Entity (DDE) - You have to set the recordHistory parameter of the @Entity annotation totrue.

@Entity(recordHistory = true)

• End User Defined Entity (EUDE) - The Enable history audit option is available under the Advanced windowof an entity, in the Auditing & Revision Tracking tab



Retrieving history using code

MDS exposes an implementation of the org.motechproject.mds.service.HistoryService. To make use of it, youshould simply create a reference to that service in your blueprint:

From now on, you will be able to use the history service, just like any other Spring bean, for example, by placingthe @Autowired annotation on a field of type org.motechproject.mds.service.HistoryService. The service allowsrecording history, deleting the whole history for an instance and retrieving the historical revisions of an instance.

2.3.10 MDS Trash Bin

When an instance is deleted, it can either be removed completely or moved to the trash. In case an instance is movedto the trash, there will be an ability to view all instances that have been deleted, as well as to restore any instance fromthe trash. Users may also choose to empty the trash from time to time. All the data retention settings are available inthe MDS settings tab. If you choose to empty the trash, MDS will use the scheduler to set up a job, that runs everyspecified period and empties the trash.



To view instances that have been moved to the trash, click the View trash button, after selecting an entity in the databrowser. To restore any instance from the trash, select that instance and click Restore button on the detailed view ofthe deleted instance.

Note: If you introduce any changes to the entity definition (e.g. add or delete a field), you will lose access to all thedeleted instances of the previous schema. That means you will no longer be able to view or restore them anymore.

Using Trash using code

Similar to the HistoryService mentioned above, MDS also exposes the TrashService that allows operations on theTrash bin from the code. To use the exposed service, create a reference in your blueprint file:



Accessing the service also works the same way as with the HistoryService - treat it as any other Spring bean, forexample by placing the @Autowired annotation on the field of type org.motechproject.mds.service.TrashService.The trash service allows to place instances in trash, retrieve instances from trash, schedule the trash purging, emptythe trash and check current data retention settings.

2.3.11 The MDS Data Browser

The data browser is a place, where you can perform CRUD operations on the instances of an entity. The main windowof the data browser shows a list of all entities, grouped by modules to which they belong. From this point, you canchoose to view instances of a certain entity by clicking on the name of that entity, or add an instance of an entity bypressing the Add button, next to the entity name.

If you pick one of the entities, you will be brought to the view, showing the instances of that entity. From this view,you can perform several operations on the instances.



Button RoleBack toentity list

Brings you back to the main data browser view, listing entities

Add Brings you to the Add instance dialog, where you can add an instance of an entityLookup Allows you to view only instances that match certain criteria. The definition of these criteria are set

in the Advanced dialog on the Schema EditorFields Allows you to display only certain fields in the browser. Useful when your entity has got a lot of

fields, and you are only interested in few of themImportCSV

This option allows the import of instances from a CSV file. If there is an instance with the same idpresent both in the database and the file, it will get updated with the values from the file

ExportCSV

This option allows the export of all instances of the selected entity to the CSV file

Viewtrash

Allows to view all instances that have been moved to the trash, on the current entity schema

If you click on any instance, a detailed view for that instance will be shown. Depending on the entity definition,necessary input fields will be presented, where you can set the values for these fields. You may also choose to deletethat instance or view the revision history (if history tracking is enabled for that entity). When you are done editing aninstance, click the Save button. To abandon changes, click Cancel.

2.3.12 Data browsing settings

The data browsing settings allow to control several data browser UI options for an entity. Available options are:

• The ordering of the entity fields

• The fields to display on the UI by default

• Allow filtering by chosen field values (only available for some types)



The automatically generated fields are not displayable by default, but all other fields are. The display order is deter-mined based on the order in which they were added. No fields will be marked filterable by default.

Note: The data browser filters can currently only be generated for the Date, DateTime, LocalDate, Boolean and Listtypes.

Changing the settings through the UI

To change the data browsing settings via UI, go to the Schema Editor and select an entity for which you wish to setthe settings. Go to the Advanced view and pick the Data Browsing tab. The first section, called Display fields,contains two tables. The table to the right shows fields that have been selected to display by default. The table to theleft shows all other fields. The order of the fields in the Fields to display table corresponds to the order of the fieldsin the data browser UI. You can move fields from one table to another and change their order, using provided buttons,or by dragging the fields to their destination. The second section, named Filters allows to pick fields, for which thedata browser UI will generate filters. Please note that only fields of a certain types will be displayed. The filters aregenerated automatically and are adjusted to the field type. For example, for the date types, there will be an option toset a filter for today, this week, this month and this year, while for boolean, this will be only true and false. When youfinish making the changes, close the Advanced window and click Save changes.

Changing the settings through annotations

The data browsing settings can also be set using MDS annotations. The two annotations that allow this are @UIDis-playable and @UIFilterable. Similar to the @Field annotation, they can be placed on fields, as well as on getters andsetters. The @UIFilterable annotation will work only, when placed on the field of a supported type.

Note: If you use the @UIDisplayable annotation on any field of your entity, all other fields, that lack the annotation,will be marked as not displayable.



By default, all fields defined in the entity will be marked as displayable. The @UIDisplayable annotation allowschanging this behaviour. If at least one field is marked with the @UIDisplayable annotation, the default behaviourwill not be applied, and only annotated fields will be marked displayable. The annotation contains optional positionparameter, that allows to pick the position of the field on the data browser UI. The ordering should start with thenumber zero. Fields are not UIFilterable by default. To allow filtering by field values on the data browser, simplyannotate that field with @UIFilterable.

The following code presents the usage of the two annotations:

@Fieldprivate String externalId;

@Field@UIDisplayable(position = 0)private String name;

@Field@UIDisplayable(position = 2)@UIFilterableprivate DateTime dateTime;

@Field@UIDisplayable(position = 3)private Long priority;

@Field@UIDisplayable(position = 1)private String description;

2.3.13 The REST API

MDS REST API allows to perform CRUD operations on the instances of an entity. By default, no operations areallowed via REST, which means that an administrator, must explicitly allow an access via REST to an entity. Evenwhen an access via REST is enabled for an entity, valid MOTECH credentials must be provided in order for a requestto be processed. MDS REST API uses a BASIC access authentication method by default, but that can be changedusing dynamic security rules (can be done on a per entity basis). Moreover the standard MDS entity level security willalso apply.

REST endpoints

The general endpoint to the MDS REST operations is: http:///module/mds/rest/

The table below explains what HTTP request method are supported f

motech documentation · motech documentation, release 0.24-snapshot •notify nurse when patient...

Documents