SOAP Web Services

The preferred web services protocol in openmrs is REST. See the Webservices.rest Module for the most up-to-date documentation

While still in the initial phases of development, significant progress has been made on two modules that, together, provide extensive access to the OpenMRS API (>= 1.6.0) via SOAP webservices. There are two modules:

The JaxWS Web Services module is the base module that allows JaxWS webservices to be written for OpenMRS (download module or view in svn)
The JaxWS API Web Services module adds actual methods that mimic the OpenMRS API. (download module or view in svn)

What's Available Now?

The following methods are provided in the "0.1" release of webservices.jaxws.api: (view in svn):


// User methods
public UserDTO wsUserAuthenticate(String username, String password)
public UserDTO wsGetUserByUsername(String username)
public UserDTO wsGetUserByUuid(String uuid)
public UserDTO[] wsGetUserByRole(String s)

// Person methods
public PersonDTO[] wsGetAllPersons()
public PersonDTO wsGetPersonByUuid(String uuid)
public void wsAddAttributeForPerson(String uuid, String attributeTypeName, String value)
public PersonDTO wsUpdatePerson(PersonDTO personDTO, String uuid)

// Patient methods
public PatientDTO[] wsGetAllPatients()
public PatientDTO wsUpdatePatient(PatientDTO patientDTO, String uuid)
public PatientDTO[] wsGetPatients(String name, String identifier, String JSONidentifierTypeIds,
public PatientDTO[] wsGetAllPatientsAssignedToPerson(String uuid)
public PatientDTO wsGetPatientByUuid(String uuid)

public PersonDTO[] wsGetPersonsRelatedTo(String personUuid, String relationshipType, boolean asPersonA)
public RelationshipDTO[] wsGetRelationships(String fromUuid, String toUuid, String relType)

// Concept methods
public ConceptDTO wsGetConcept(String conceptUuidOrName)
public ConceptDTO wsGetConceptByUuid(String uuid)
public ConceptDTO[] wsGetConceptsByClassName(String conceptClassName)
public ConceptDTO[] wsGetConceptsByClassNameAndChar(String conceptClassName, String str)
public Boolean wsSaveConcept(ConceptDTO con)
public ConceptDTO[] wsGetConceptSetByConceptUuid(String conceptName)

// Drug methods
public Boolean wsSaveDrug(DrugDTO d)
public DrugDTO[] wsGetDrugsByConcept(ConceptDTO c)
public DrugDTO[] wsGetAllDrugs()

//Encounter methods
public EncounterDTO[] wsGetEncountersByPatientUuid(String uuid)
public EncounterDTO wsGetEncounterByUuid(String uuid)
public String wsSaveEncounter(EncounterDTO encounterDTO)
public EncounterTypeDTO[] wsGetAllEncounterTypes()

// Obs methods
public ObsDTO wsGetObsByUuid(String uuid)
public ObsDTO[] wsGetObservationsByPersonUuid(String uuid)
public ObsDTO[] wsGetVoidedObservations(String uuid)
public ObsDTO[] wsGetObsByPersonAndConceptUuids(String personUuid, int conceptUuid)
public void wsSaveObservations(ObsDTO obsDTO)
public void wsSaveComplexObservations(ObsDTO[] obsDTOs)
public void wsSaveObsAndDiscontinueOrder(ObsDTO[] obsDTOs, OrderDTO orderDTO, String discontinueConceptUuid)
public void wsUpdateObsArray(ObsDTO[] obsDTOs)
public void wsUpdateObservations(ObsDTO obsDTO, String s)
public void wsVoidObservation(ObsDTO obsDTO, String s)

// Location methods
public LocationDTO wsGetLocationByUuid(String uuid)
public LocationDTO[] wsGetLocations()

// Order methods
public OrderDTO wsGetOrderByUuid(String uuid)
public DrugOrderDTO[] wsGetMedicationOrdersForPatientByUuid(String uuid)
public OrderDTO[] wsGetOrdersForPatientByUuid(String uuid)
public void wsDiscontinueMedOrder(DrugOrderDTO dOrder)
public void wsSaveMedicationOrderForPatient(DrugOrderDTO o)
public void wsSaveComplexMedicationOrder(DrugOrderDTO[] drugOrderDTOs)

public void wsSaveOrder(OrderDTO o)
public void wsSaveLabOrder(OrderDTO o, ObsDTO[] obsDTOs)

How to install

Download and install the webservices.jaxws module
Download and install the webservices.jaxws.api module

WSDL Access

You should be able to see the WSDL for version 0.1 of webservices.jaxws.api at http://<your OpenMRS instance>/openmrs/ms/apiservices/openmrsapiservice?wsdl

Security and Permissions

Using the OpenMRS administration interface, configure the IPs of computers that you would like to have access to the webservices by adding them to the global parameter webservices.jaxws.allowed_ip_list (Administration → Manage Global Properties → webservices.jaxws.allowed_ip_list) Note that after you add the IPs and save you will need to stop and restart both webservices in the module administration interface.

Troubleshooting

It is sometimes very helpful to monitor the OpenMRS log (Administration-->View Server Log) and log file of your Tomcat instance (usually a file called 'catalina.out'). You should examine both logs because not all problems are reported to the OpenMRS log.

Known Issues

If Tomcat is shut down and re-started both modules will need to be re-started from OpenMRS module administration interface. Always start webservices.jaxws before webservices.jaxws.api. Fixed in OpenMRS v1.7+

Creating your own SOAP Web Service Methods in new Module

Option 1: JaxWS Web Services as a base

The "JaxWS Web Services" module can be used as a base module. download the webservices.jaxws module. It provides the necessary jaxws libraries for openmrs to use web services. webservices.jaxws in svn. Example configuration in your spring application context and in your config.xml file

Option 2: Package all jars into a new module

There is also an example module that actually adds a simple service (but doesn't depend on the webservices.jaxws module).moduleApplicationContextweb service class