This page outlines the process of converting OSM locations so they can be imported to Reveal.

Reveal Locations Overview

Reveal has two primary areas where locations are loaded, the OpenMRS system and the Reveal web server.

OpenMRS

Reveal utilizes the OpenMRS location hierarchy for role based access controls and it requires that we retain an accurate list of jurisdictions (national down to focus) so we can appropriately assign teams. This list is created in the OpenMRS locations user interface with a link assigned to the location ID that's in Reveal. The OpenMRS locations do not contain geographic information, just a hierarchy for role based access control.

Reveal Web Server

The Reveal web server houses all jurisdictions and locations. These locations include the valid geojson geographies, of type point, polygon or multi-polygon. Jurisdictions represent areas on the map and are tagged in the API as is_jurisdiction=true when POST or PUT these jurisdictions. Jurisdictions are able to have a parentId, so you can nest them within a hierarchy and they also act as parents to locations (residential structures, mosquito collection points, larval breeding sites, etc).

High Level Process for Loading in Locations (vision for process, though currently happening manually)

This section defines the high level process for loading in locations in both systems.

1. Get valid GeoJSON for all locations from the national level down to the focus area. These should be geometry.type=multi-polygon.
2. Update the properties in each location to ensure the hierarchy is appropriately nested (update parentId) and assign each location a unique id
3. Use Nifi to load in each location from the highest level down to the focus. Make sure to use the URL parameter is_jurisdiction=true
4. Now, all jurisdictions are loaded into Reveal, we have to load in the enumerated structures.
5. Get the extract of enumerated structures and ensure it's Valid GeoJSON
6. Update the properties on each structure to match to the correct parentId and status
7. Use Nifi to load in each location for all foci. Make sure that you don't post them with the is_jurisdiction URL parameter
8. Check the API for each focus to make sure everything properly loaded (i.e the total number of expected locations are loaded)
9. At this point, we have Reveal completely configured for locations we have to build that hierarchy in OpenMRS
10. Compile a list of all jurisdiction ids in the hierarchy with the name of each jurisdiction from Reveal. (keep this in a spreadsheet or text file)
11. Create each location along the hierarchy in OpenMRS and paste the jurisdiction id in the location tag labeled mspray_location_id
12. Create a team for each location, one level above the Focus investigation (village or sub-district) and assign users at that level
13. Now, all locations and teams are loaded into OpenMRS
14. The next steps are to create plan definitions for these locations so you can check that everything is working on the Android client (out of scope for this document)

Getting valid GeoJSON for Hierarchy

It's critical that we use a valid geographic hierarchy that can be mapped to national systems. This hierarchy is used in the Reveal web app, Android client and data warehouse. Some countries don't have this information so we need to gather it from third party sources like the world bank or Humanitarian Data Exchange. We found 3 levels of hierarchies for Thailand https://data.humdata.org/dataset/thailand-administrative-boundaries (Humdata.org). We loaded this in to Q GIS and extracted the relevant objects for the pilot sites.

Getting Enumerated Locations

The Akros team has provided us with OSM shapefiles that include the enumerated structures. We receive these files and have to convert them to valid GeoJSON with the correct properties so they can be loaded in to Reveal.