DHIS 2 Java Client

DHIS 2 API client for Java. The client allows you to create, update and retrieve information from DHIS 2. The client is compatible with Java 8 and later JDK versions.

Getting started

To use dhis2-java-client with Maven you can specify the following dependency:

<dependency>
  <groupId>org.hisp</groupId>
  <artifactId>dhis2-java-client</artifactId>
  <version>LATEST</version>
</dependency>

You can find dhis2-java-client and the available versions in Maven central repository.

Configuration and Authentication

This section describes configuration and authentication of the client.

Basic authentication

A minimal configuration of dhis2-java-client where the configuration parameters refer to the base URL, username and password for the DHIS 2 instance to connect to can be specified like this. The default authentication mechanism is Basic authentication. Note that you should not include the api part nor a trailing / in the base URL:

Dhis2Config config = new Dhis2Config(
    "https://play.dhis2.org/2.39.0", 
    "admin", "district");

Dhis2 dhis2 = new Dhis2(config);

Alternatively, to use Basic authentication you can specify the username and password of the DHIS 2 account together with the base URL of the DHIS 2 instance:

Dhis2 dhis2 = Dhis2.withBasicAuth(
    "https://play.dhis2.org/2.39.0", 
    "admin", "district");

You can use the username and password of a regular DHIS 2 user account.

Personal access token authentication

To use personal access token (PAT)-based authentication you can specify the access token:

Dhis2 dhis2 = Dhis2.withAccessTokenAuth(
    "https://play.dhis2.org/2.39.0", 
    "d2pat_2bBQecgNcxrS4EPhBJuRlQkwiLr2ATnC2557514242");

PATs can be created through the API or the user interface by going to Profile > Settings > Personal access tokens.

Cookie authentication

To use cookie-based authentication you can specify the session identifier:

Dhis2 dhis2 = Dhis2.withCookieAuth(
    "https://play.dhis2.org/2.39.0", 
    "5EC557E60D7E5CE8D78EEC1389592D3E");

The name of the session cookie used by the DHIS 2 API is JSESSIONID. The value can typically be retrieved from the Cookie HTTP request header sent with DHIS 2 API requests.

Get current user

To get the current user:

Me me = dhis2.getMe();

String username = me.getUsername();
String dbLocale = me.getSettings().getDbLocale();

Get user authentication

To retrieve the list of authorities granted to the authenticated user:

List<String> authorities = dhis2.getUserAuthorization();

Metadata

This section explains operations for DHIS 2 metadata objects.

Query objects

To retrieve all org unit groups:

List<OrgUnitGroup> orgUnitGroups = dhis2.getOrgUnitGroups();

To retrieve org units with a filter on the level in a paged way:

List<OrgUnit> orgUnits = dhis2.getOrgUnits(Query.instance()
    .addFilter(Filter.eq("level", 4))
    .addFilter(Filter.like("code", "fac"))
    .setPaging(1, 200));

To retrieve all org units ordered descending on the name property:

List<OrgUnit> orgUnits = dhis2.getOrgUnits(Query.instance()
    .setOrder(Order.desc("name")));

When retrieving lists of objects, associations to other objects will not be populated in the response by default. You can expand associations in object lists through the query object like this, e.g. for programs:

List<Program> programs = dhis2.getPrograms(Query.instance()
    .withExpandAssociations());

Get object

To retrieve a single org unit by identifier:

OrgUnit orgUnit = dhis2.getOrgUnit("j7gkH3hf83k");

Create object

To create an org unit:

OrgUnit orgUnit = new OrgUnit();
orgUnit.setName("Ngelehun");
orgUnit.setCode("NGLH");

ObjectResponse response = dhis2.saveOrgUnit(orgUnit);

Create multiple objects

To create or update multiple objects:

List<OrgUnit> orgUnits = CollectionUtils.list(
    new OrgUnit("nEt3lFHOqYP", "Ngelehun"),
    new OrgUnit("gnAOCDoZUVO", "Kailahun"));

ObjectsResponse response = dhis2.saveOrgUnits(orgUnits);

Update object

To update an org unit (note that the ID property must be set):

OrgUnit orgUnit = new OrgUnit();
orgUnit.setId("cDw53Ej8rjT");
orgUnit.setName("Ngelehun");
orgUnit.setCode("NGLH");

ObjectResponse response = dhis2.updateOrgUnit(orgUnit);

Check if object exists

To check if an object exists:

boolean exists = dhis2.isOrgUnit("O6uvpzGd5pu");

Remove object

To remove an org unit:

ObjectResponse response = dhis2.removeOrgUnit("j7gkH3hf83k");

Get response message

The various metadata object save and update methods return an instance of ObjectResponse which holds information about the operation, such as status, HTTP status, HTTP status code and a message describing the outcome.

ObjectResponse response = dhis2.saveDataElement(dataElement);

Status status = response.getStatus();
Integer statusCode = response.getHttpStatusCode();
boolean success = response.getHttpStatus().is2xxSuccessful();
String message = response.getMessage();

System settings

This section explains operations for DHIS 2 system settings.

Get system settings

To get system settings:

SystemSettings settings = dhis2.getSystemSettings();

Events

This section explains operations for DHIS 2 events.

Save events

To save a list of events:

List<EventDataValue> dataValues = CollectionUtils.list(
    new EventDataValue("oZg33kd9taw", "Male"),
    new EventDataValue("qrur9Dvnyt5", "45"),
    new EventDataValue("GieVkTxp4HH", "143"),
    new EventDataValue("eMyVanycQSC", "2021-07-02"),
    new EventDataValue("msodh3rEMJa", "2021-08-05"),
    new EventDataValue("K6uUAvq500H", "A010"),
    new EventDataValue("fWIAEtYVEGk", "MODDISCH"));

Event event = new Event("EHlOLNtR4J0");
event.setProgram("eBAyeGv0exc");
event.setProgramStage("Zj7UnCAulEk");
event.setOrgUnit("DiszpKrYNg8");
event.setOccurredAt(DateTimeUtils.getDate(2021, 7, 12));
event.setDataValues(dataValues);

Events events = new Events(CollectionUtils.list(event));

EventResponse response = dhis2.saveEvents(events);

Get event

To retrieve an event:

Event event = dhis2.getEvent("EHlOLNtR4J0");

Remove event

To remove an event:

EventResponse response = dhis2.removeEvent(event);

Data values

This section explains operations for DHIS 2 data values.

Save data value set

To save a data value set:

DataValue dv1 = new DataValue();
dv1.setDataElement("f7n9E0hX8qk");
dv1.setValue("12");

DataValue dv2 = new DataValue();
dv2.setDataElement("Ix2HsbDMLea");
dv2.setValue("13");

DataValueSet dvs = new DataValueSet();
dvs.setDataSet("pBOMPrpg1QX");
dvs.setCompleteDate("2014-02-03");
dvs.setPeriod("201910");
dvs.setOrgUnit("DiszpKrYNg8");

dvs.addDataValue(dv1);
dvs.addDataValue(dv2);

DataValueSetImportOptions options = DataValueSetImportOptions.instance();

DataValueSetResponse response = dhis2.saveDataValueSet(dvs, options);

Save data value set from file

To read a data value set from a file and save it:

File file = new File("/tmp/datavalueset.json");

DataValueSetImportOptions options = DataValueSetImportOptions.instance();

DataValueSetResponse response = dhis2.saveDataValueSet(file, options);

Analytics

This section explains operations for the analytics engine.

Get analytics data value set

To retrieve analytics data in the data value set format:

DataValueSet dvs = dhis2.getAnalyticsDataValueSet(AnalyticsQuery.instance()
    .addDimension(Dimension.DIMENSION_DX, "cYeuwXTCPkU", "Jtf34kNZhzP")
    .addDimension(Dimension.DIMENSION_OU, "O6uvpzGd5pu", "fdc6uOvgoji")
    .addDimension(Dimension.DIMENSION_PE, "202007", "202008"));

Write analytics data value set to file

To retrieve analytics data and write the content to the file:

AnalyticsQuery query = AnalyticsQuery.instance()
    .addDimension(Dimension.DIMENSION_DX, "cYeuwXTCPkU", "Jtf34kNZhzP")
    .addDimension(Dimension.DIMENSION_OU, "O6uvpzGd5pu", "fdc6uOvgoji")
    .addDimension(Dimension.DIMENSION_PE, "202007", "202008");

File file = new File("/tmp/data-value-set.json");
    
dhis2.writeAnalyticsDataValueSet(query, file);

Data store

This section explains data store operations.

Save entry

To save a data store entry:

Dashboard dashboard = new Dashboard();

Response response = dhis2.saveDataStoreEntry("dashboards", "attendance", dashboard);

Update entry

To update a data store entry:

Response response = dhis2.updateDataStoreEntry("dashboards", "attendance", dashboard);

Get namespaces

To retrieve data store namespaces:

List<String> namespaces = dhis2.getDataStoreNamespaces();

Get keys in namespace

To retrieve keys for a namespace:

List<String> keys = dhis2.getDataStoreKeys("dashboards");

Get data store entry

To retrieve an entry for a namespace and key:

Dashboard dashboard = dhis2.getDataStoreEntry("dashboards", "attendance", Dashboard.class);

Get data store entries

To retrieve a list of data store entries for a namespace and entry fields:

List<String> fields = List.of("id", "code", "name");

List<Map<String, Object>> entries = dhis2.getDatastoreEntries("dashboards", fields);

Get metadata for entry

To retrieve metadata for a data store entry:

EntryMetadata metadata = dhis2.getDataStoreEntryMetadata("dashboards", "attendance");

Remove entry

To remove a data store entry:

Response response = dhis2.removeDataStoreEntry("dashboards", "attendance");

Remove namespace

To remove a data store namespace including all entries:

Response response = dhis2.removeDataStoreNamespace("dashboards");

System

This section explains system operations.

Get system info

To get system info:

SystemInfo info = dhis2.getSystemInfo();

String version = info.getVersion();

To compare the system version:

SystemInfo info = dhis2.getSystemInfo();

SystemVersion version = info.getSystemVersion();

boolean isHigher = version.isHigher("2.37.0");

Get job notifications

To retrieve job notifications for a job category and job identifier:

List<JobNotification> notifications = dhis2
    .getJobNotifications(JobCategory.ANALYTICS_TABLE, "GxTz2OVPcYk");

Development

This section covers development of the DHIS 2 Java client.

Package:

mvn clean package

Run unit tests:

mvn test

Run integration tests:

mvn test -P integration

Run specific integration test:

mvn test -P integration -Dtest=Dhis2ApiTest

To log at info level during tests:

mvn test -Dlog.level.dhis2=info

Deployment

The artifact will be deployed through a GitHub action to the OSSRH Maven repository when detecting a commit to master where the main version is not a SNAPSHOT version. To trigger a deploy, make a commit to master where the main version is bumped to a non-SNAPSHOT version.