{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Within the OpenMRS Webapp","type":"text"}]},{"type":"paragraph","content":[{"text":"Everything is delivered from the database in the form of objects: Patient, User, Concept, etc java objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can fetch/save these objects using what we call \"services\" (PatientService, UserService, ConceptService).","type":"text"}]},{"type":"paragraph","content":[{"text":"You can get the services at any point by calling Context.getPatientService(), .getUserService(), etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"To print out the names of all the patients in the system:","type":"text"}]},{"type":"codeBlock","content":[{"text":"List patients = Context.getPatientService().getAllPatients();\nfor (Patient patient : patients) {\n System.out.println(\"Patient: \" + patient.getGivenName() + \" \" + patient.getFamilyName());\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"In an External Application using web services","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Web Services","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25520618"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"In an External Application","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":" We no longer test this use case so you may experience difficulties trying to use this approach. Please see ","type":"text"},{"text":"Web Services","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882"}}]},{"text":" as an alternative.","type":"text"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"The openmrs-api-xxx.jar file can be used in stand-alone java applications. There are three simple steps you need to follow:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Choose an option below for including the openmrs jar(s) and dependencies","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Fire up OpenMRS by calling: Context.startup(, , , getProperties());","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You need to surround any units of work with Context.openSession() (which startup() calls for you) and Context.closeSession()","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Authenticate into OpenMRS by calling: Context.authenticate(username, password);","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should be able to call into the Context and work with the services.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example","type":"text"}]},{"type":"codeBlock","content":[{"text":"public static void main(String[] args) {\n File propsFile = new File(OpenmrsUtil.getApplicationDataDirectory(), \"openmrs-runtime.properties\");**\n Properties props = new Properties();\n OpenmrsUtil.loadProperties(props, propsFile);\n Context.startup(\"jdbc:mysql://localhost:3306/db-name?autoReconnect=true\", \"openmrs-db-user\", \"3jknfjkn33ijt\", props);\n try {\n Context.openSession();\n Context.authenticate(\"admin\", \"test\");\n List patients = Context.getPatientService().getPatients(\"John\");\n for (Patient patient : patients) {\n System.out.println(\"Found patient with name \" + patient.getPersonName() + \" and uuid: \" + patient.getUuid());\n }\n ...\n }\n finally {\n Context.closeSession();\n }\n}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"(the first 4 lines only have to be done once at startup. The rest are per request)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Using the API 1.8.0+ Jar (maven based)","type":"text"}]},{"type":"paragraph","content":[{"text":"OpenMRS introduced ","type":"text"},{"text":"Maven","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25520545"}}]},{"text":" in 1.8. The easiest way to use the OpenMRS API is to also use maven for your project. Once you do that, simply use these in your pom.xml","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\torg.openmrs.api\n\topenmrs-api\n\t${openMRSVersion}\n\tjar\n\tprovided\n\n\n\torg.openmrs.api\n\topenmrs-api\n\t${openMRSVersion}\n\ttest-jar\n\ttest\n\n\n\torg.openmrs.web\n\topenmrs-web\n\t${openMRSVersion}\n\tjar\n\tprovided\n\t\n\n\torg.openmrs.web\n\topenmrs-web\n\t${openMRSVersion}\n\ttest-jar\n\ttest\n\n\n\torg.openmrs.test\n\topenmrs-test\n\t${openMRSVersion}\n\tpom\n\ttest\n\n\n\torg.openmrs.tools\n\topenmrs-tools\n\t${openMRSVersion}\n\n\n\t1.8.1\n\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Using the API Jar 1.7 and below","type":"text"}]},{"type":"paragraph","content":[{"text":"The openmrs-api-xxx.jar file can be used in stand-alone java applications. There are three simple steps you need to follow:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Download/build the openmrs api jar file \"openmrs-api.****.jar\" and include it on your classpath.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Include the dependent libraries on your classpath, which you can get from ","type":"text"},{"text":"openmrs-trunk/api/pom.xml","type":"text","marks":[{"type":"link","attrs":{"href":"http://source.openmrs.org/browse/OpenMRS/trunk/api/pom.xml?hb=true"}}]},{"text":".","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Overriding OpenMRS Default Runtime Properties","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469996"}}]},{"text":" for what data you can provide to openmrs","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OpenMRS startup environment","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to start OpenMRS with all it's modules (especially necessary if \"mandatory\" modules as with OpenMRS 1.6 are present), it is not sufficient to simply include the required jar files. Choose one of the following approaches to get your app started:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start the external app with the same user, that Tomcat and the OpenMRS webapp are using.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you are using a different user, specify the Global Property ","type":"text"},{"text":"module_repository_folder","type":"text","marks":[{"type":"code"}]},{"text":" with an absolute path to the modules directory of the OpenMRS webapp.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set the working (start) dir of your external app to the OpenMRS base folder of the webapp. (This should usually be the place where the openmrs-runtime.properties is located.)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Overwrite the ","type":"text"},{"text":"application_data_directory","type":"text","marks":[{"type":"code"}]},{"text":" of the ","type":"text"},{"text":"Overriding OpenMRS Default Runtime Properties","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469996"}}]}]}]}]},{"type":"paragraph","content":[{"text":"Note that scheduled tasks can/may/will fail during initialization.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Demarcating start and end of API work","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When coding against the database API, domain objects (","type":"text"},{"text":"Patients","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25466168"}}]},{"text":", Users, etc.) provided from the API are only guaranteed to be valid between calls to ","type":"text"},{"text":"context.openSession()","type":"text","marks":[{"type":"link","attrs":{"href":"http://resources.openmrs.org/doc/org/openmrs/api/context/Context.html#openSession%28%29"}}]},{"text":" and ","type":"text"},{"text":"context.closeSession()","type":"text","marks":[{"type":"link","attrs":{"href":"http://resources.openmrs.org/doc/org/openmrs/api/context/Context.html#closeSession%28%29"}}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You needn't worry about this within a web application environment as long as you are using a filter such as ","type":"text"},{"text":"org.openmrs.web.OpenmrsFilter","type":"text","marks":[{"type":"code"}]},{"text":" (since the filter marks the boundaries around each HTTP request)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You cannot use domain objects ","type":"text"},{"text":"across","type":"text","marks":[{"type":"em"}]},{"text":" transactions (or requests) (e.g., if you loaded a ","type":"text"},{"text":"Patient","type":"text","marks":[{"type":"code"}]},{"text":" object on one web page, you must reload that object, before using it on subsequent pages)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It is the developer's responsibility to ensure that ","type":"text"},{"text":"context.closeSession()","type":"text","marks":[{"type":"link","attrs":{"href":"http://resources.openmrs.org/doc/org/openmrs/api/context/Context.html#closeSession%28%29"}}]},{"text":" is called (if not within webapp environment) to release precious resources (","type":"text"},{"text":"even","type":"text","marks":[{"type":"em"}]},{"text":" in the event of an exception)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"These transaction boundary calls are ","type":"text"},{"text":"lightweight","type":"text","marks":[{"type":"em"}]},{"text":" -- i.e., there is little penalty for calling them","type":"text"}]}]}]}],"version":1}

Browser not supported