Documentation

When working with OpenMRS outside the standard web application context, you need to manually initialize the Spring ApplicationContext and authenticate. This guide shows how to set up a standalone Java application to test OpenMRS Core API functionality.

Overview

OpenMRS relies on Spring for dependency injection and Hibernate for database operations. To use the API programmatically, you must:

Configure runtime properties
Load the Spring context
Authenticate with valid credentials
Use the API services

Step-by-Step Implementation

Set Up Application Data Directory

OpenMRS requires a dedicated directory for runtime configuration:


// Create application data directory
String appDataDir = System.getProperty("user.home") + File.separator + "openmrs-api-test";
File appDataDirectory = new File(appDataDir);
if (!appDataDirectory.exists()) {
    appDataDirectory.mkdirs();
}

Configure Runtime Properties

Create properties for database connection and application settings:


Properties runtimeProperties = new Properties();

// Set application data directory
runtimeProperties.setProperty(
    OpenmrsConstants.APPLICATION_DATA_DIRECTORY_RUNTIME_PROPERTY, 
    appDataDirectory.getAbsolutePath()
);
OpenmrsUtil.setApplicationDataDirectory(appDataDirectory.getAbsolutePath());

runtimeProperties.setProperty("connection.url", 
    "jdbc:mysql://localhost:3306/openmrs?autoReconnect=true");
runtimeProperties.setProperty("connection.username", "root");
runtimeProperties.setProperty("connection.password", "your_password");

// Disable module web features (optional)
runtimeProperties.setProperty("module.allow_web_admin", "false");

Create Runtime Properties File

Save the configuration to disk:


File runtimePropertiesFile = new File(appDataDirectory, "openmrs-runtime.properties");
if (!runtimePropertiesFile.exists()) {
    runtimeProperties.store(
        new FileOutputStream(runtimePropertiesFile), 
        "Auto-generated for testing"
    );
}

Initialize Spring Context

Load the main Spring configuration file:


Context.setRuntimeProperties(runtimeProperties);

ClassPathXmlApplicationContext applicationContext = 
    new ClassPathXmlApplicationContext("applicationContext-service.xml");

The applicationContext-service.xml file is important here as it:

Initializes all OpenMRS services (PatientService, PersonService, etc.)
Configures Hibernate session factory
Sets up validators and event listeners
Enables dependency injection

Authenticate and Use Services

Open a session, authenticate, and access services:


try {
    Context.openSession();
    Context.authenticate("admin", "Admin123");
    System.out.println("OpenMRS context initialized successfully!");

    PersonService personService = Context.getPersonService();

    Person person = new Person();
    person.setGender("M");
    
    SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
    person.setBirthdate(sdf.parse("2003-05-04"));

    PersonName name = new PersonName();
    name.setGivenName("Rahul");
    name.setFamilyName("Goyal");
    Set<PersonName> names = new TreeSet<>();
    names.add(name);
    person.setNames(names);

    PersonAddress address = new PersonAddress();
    address.setPreferred(true);
    address.setAddress1("123 Main Street");
    address.setCountry("USA");
    Set<PersonAddress> addresses = new TreeSet<>();
    addresses.add(address);
    person.setAddresses(addresses);
  
    personService.savePerson(person);
    System.out.println("Person created with ID: " + person.getPersonId());

} catch (Exception e) {
    e.printStackTrace();
} finally {
    Context.closeSession();
    applicationContext.close();
}

Key Takeaways

Runtime properties must be configured before loading Spring context
applicationContext-service.xml initializes the entire OpenMRS service layer
Authentication is required even in standalone applications
Session management (open/close) must be handled manually
TreeSet should be used for collections mapped with sort="natural"
No need to set IDs for new entities - let Hibernate generate them