Versions Compared

Version Old Version 1 New Version Current
Changes made by

Utsav Ashish Koju

Rodolfo Melia

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Github

LocatorAPI

Change log

v.0.0.1: Planning

Setup environment

Goal

Get everything you need to build, run and further explore LocatorAPI on your local development environment or production server

Prerequisites

  • A DHIS2 server (v 2.36 or higher)

  • RO Database User: Create a user in database and provide RO permission to access dhis2 database.

  • PostGIS extension installed and enabled

Server Requirement

  • Apache Server

  • Java JDK 8

Run the site Locally

Installing LocatorAPI

  1. Download the ‘war’ file from here or from ‘release’ section in our github page.

  2. Move / upload the war file inside the webapps folder of your apache server

  3. To configure the application, please create an .env file in the root of your webapps and copy the code below and update its values as required.

    Code Block
    application.url={{host}}
application.port={{8080}}
spring.datasource.url=jdbc:postgresql://{{server}}:{{db_port}}/{{database}}
spring.datasource.username={{username}}
spring.datasource.password={{passport}}

spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.properties.hibernate.format_sql=true

Developers Documentation

App Architecture

...

API Structure

Creating new Endpoint

Spring Security

Adding new Users

...

Background

PSI, as well as many other organisation use DHIS2 as their de facto Master List of Facilities. DHIS2 provides various API endpoints to perform various operation across Org Units. DHIS API has a comprehensive documentation on how to execute DHIS2 Org Unit API operations.

When creating consumer services, PSI’s solutions require in many instances produce a list of facilities based on the current location of the user - this means listing facilities that are closest to the provided Latitude and Longitude for the user. This search operation is not present in DHIS2 API, at least in the reviewed versions (2.38, 2.39 and 2.40 dev version - reviewed in February 2023).

Additionally, when performing a search by custom attributes, it is currently no possible to specify what attribute you are doing the search on - instead it searches all of them. This is a major issue for location searching.

Last, users may want to make use of custom attributes to store an array of value (perhaps as comma delimited values). A search operation by the individual value is not supported by DHIS2 API.

Locator API - Introduction

Locator API is a self-contained API that support the retrieval or Org Units based on alternative, non-native DHIS2 API calls, in particular:

  1. Request for closest org units based on a given geo-coordinate, with the possibility to define a boundary as a ratio in Kms.

  2. Return an enumeration of Custom Org Unit Attributes values - implemented for Area and SubArea, two of the suggested custom attributes that we recommend to install as part of the Org Units.

  3. Enhance (by making precise) the search by custom attributes.*

    1. Search by single values for an specific attributes (instead of all attributes, as it currently happens)

    2. Search of a value on an array of values