OpenSRP Person Address Scheme

OpenSRP can capture addresses for different roles in the system (i.e., Client, User and Provider), but the Client Address is the most captured and widely used entity, and this documentation focuses on Client address and how it is mapped with OpenMRS.

The OpenSRP application also allows one to capture multiple addresses for a person, which are distinguished by the field "addressType". Hence, each person can have only one address for each addressType. For example, Mr. Smith cannot have two addresses for addressType "usual residence"; however, he can have two addresses with addressTypes "usual residence" and "previous residence". The address scheme in OpenSRP is flexible and can be mapped to a number of different address formats across the world.

In OpenSRP, address is specified by Address class in BaseEntity. Following are the standard address fields for OpenSRP, which has to be mapped by each site. Note that these fields are not mandatory (except for addressType), but in case of any need to capture data for the field, the following variable names should be used for the field:

• addressType: MUST be specified. The unique field that identifies an address from a list of different addresses for a single person, e.g. office, usual_residence, previous_residence, birth_place, death_place, burial_place, etc. The field value is customizable but should be chosen carefully, since once the system goes live and data entry has started, addressType should not be changed, because the field value is used to generate reports based on addressType or location dimension.
• startDate: Optional. The date when person address became valid. If you want to get reports for duration of residence make sure to capture this data.
• endDate: Optional. The date when person abandoned the address. If no end date is specified system assumes current date as end date for calculating reports for durations.
• latitude: Optional. Field to capture latitude for Geo-coordinates.
• longitude: Optional. Field to capture longitude for Geo-coordinates.
• postalCode. Optional. Field to capture postal or zip code.
• state: Field is used to capture the major division in a country. This field should contain state or province part of address.
• country: Field to capture country.

Except for the fields above, everything else is dynamic and customizable according to your choice. The mapping for all other address fields is done via a hash map "addressFields". The API provides few basic fields for map but site developers can add anything according to country needs but keep in mind that for OpenMRS integration it should conform to a predefined list of fields as specified below in table.

Predefined fields are defined as enums in code and comprise of HOUSE_NUMBER, STREET, REGION, LOCALITY, SECTOR, AREA, MUNICIPALITY, VILLAGE, TOWN, SUB_DISTRICT, COUNTY, DISTRICT, CITY, GEOPOINT

Mapping with OpenMRS address

OpenMRS allows multiple addresses for a person, but its structure is more inclined to provide a basic set of predefined standard fields mappable to all addresses and some extra fields with static column names which could be labelled via front end as per requirement by implementation site. The fields provided by OpenMRS are: address1, address2, address3, address4, address5, address6, cityVillage, countyDistrict, stateProvince, country, latitude, longitude, postalCode, startDate, endDate.

Each field must be mapped to OpenSRP or OpenMRS predefined fields in XLSForm to allow data to be pushed into OpenMRS as person address. The address group is identified by person_address in instance::openmrs_entity column in the XLSForm. Each field is mapped with OpenMRS as specified by table below.

Example XLSForm:

The XLS sheet below defines a sample of four different addresses (birthplace, deathplace, usual_residence, previous_residence) with possible field names for different addresses as specified by table above.