components/camel-dhis2/camel-dhis2-component/src/main/docs/dhis2-component.adoc

= DHIS2 Component
:doctitle: DHIS2
:shortname: dhis2
:artifactid: camel-dhis2
:description: Leverages the DHIS2 Java SDK to integrate Apache Camel with the DHIS2 Web API.
:since: 4.0
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: dhis2

*Since Camel {since}*

*{component-header}*

The Camel DHIS2 component leverages the https://github.com/dhis2/dhis2-java-sdk[DHIS2 Java SDK] to integrate Apache Camel with https://dhis2.org/[DHIS2]. DHIS2 is a free, open-source, fully customizable platform for collecting, analyzing, visualizing, and sharing aggregate and individual-data for district-level, national, regional, and international system and program management in health, education, and other domains.

Maven users will need to add the following dependency to their `+pom.xml+`.

[source,xml]
----
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-dhis2</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
----

== URI Format

....
dhis2://operation/method[?options]
....

// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END

== Examples

* Fetch an organisation unit by ID:
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:getResource")
            .to("dhis2:get/resource?path=organisationUnits/O6uvpzGd5pu&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .unmarshal()
            .json(org.hisp.dhis.api.model.v40_2_2.OrganisationUnit.class);
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:getResource
    steps:
      - to:
          uri: dhis2:get/resource
          parameters:
            path: organisationUnits/O6uvpzGd5pu
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
      - unmarshal:
          json:
            unmarshalType: org.hisp.dhis.api.model.v40_2_2.OrganisationUnit
----
====

* Fetch all organisation units:
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:getCollection")
            .to("dhis2:get/collection?path=organisationUnits&arrayName=organisationUnits&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .split().body()
            .convertBodyTo(org.hisp.dhis.api.model.v40_2_2.OrganisationUnit.class).log("${body}");
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:getCollection
    steps:
      - to:
          uri: dhis2:get/collection
          parameters:
            path: organisationUnits
            arrayName: organisationUnits
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
      - split:
          simple: ${body}
          steps:
            - convertBodyTo:
                type: org.hisp.dhis.api.model.v40_2_2.OrganisationUnit
            - log: ${body}
----
====

* Fetch all organisation unit codes:
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:getCollection")
            .to("dhis2:get/collection?path=organisationUnits&arrayName=organisationUnits&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .split().body()
            .convertBodyTo(org.hisp.dhis.api.model.v40_2_2.OrganisationUnit.class).log("${body}");
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:getCollection
    steps:
      - to:
          uri: dhis2:get/collection
          parameters:
            path: organisationUnits
            arrayName: organisationUnits
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
            fields: code
      - split:
          simple: ${body}
          steps:
            - convertBodyTo:
                type: org.hisp.dhis.api.model.v40_2_2.OrganisationUnit
            - log: ${body}
----
====

* Fetch users with a phone number:
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:getCollection")
            .to("dhis2://get/collection?path=users&filter=phoneNumber:!null:&arrayName=users&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .split().body()
            .convertBodyTo(org.hisp.dhis.api.model.v40_2_2.User.class)
            .log("${body}");
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:getCollection
    steps:
      - to:
          uri: dhis2:get/collection
          parameters:
            path: users
            arrayName: users
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
            filter: "phoneNumber:!null:"
      - split:
          simple: ${body}
          steps:
            - convertBodyTo:
                type: org.hisp.dhis.api.model.v40_2_2.User
            - log: ${body}
----
====

* Save a data value set
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.LoggingLevel;
import org.apache.camel.builder.RouteBuilder;
import org.hisp.dhis.api.model.v40_2_2.DataValueSet;
import org.hisp.dhis.api.model.v40_2_2.DataValue;
import org.hisp.dhis.integration.sdk.support.period.PeriodBuilder;

import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Date;
import java.util.List;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:postResource")
            .setBody(exchange -> new DataValueSet().withCompleteDate(
                    ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_LOCAL_DATE))
                                                                   .withOrgUnit("O6uvpzGd5pu")
                                                                   .withDataSet("lyLU2wR22tC").withPeriod(PeriodBuilder.monthOf(new Date(), -1))
                                                                   .withDataValues(
                                                                       List.of(new DataValue().withDataElement("aIJZ2d2QgVV").withValue("20"))))
            .to("dhis2://post/resource?path=dataValueSets&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .unmarshal().json()
            .choice()
            .when().groovy("body.status != 'OK'")
                .log(LoggingLevel.ERROR, "Import error from DHIS2 while saving data value set => ${body}")
            .end();
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:postResource
    steps:
      - setBody:
          groovy: |
            new org.hisp.dhis.api.model.v40_2_2.DataValueSet()
              .withCompleteDate(java.time.ZonedDateTime.now(java.time.ZoneOffset.UTC).format(java.time.format.DateTimeFormatter.ISO_LOCAL_DATE))
              .withOrgUnit('O6uvpzGd5pu')
              .withDataSet('lyLU2wR22tC')
              .withPeriod(org.hisp.dhis.integration.sdk.support.period.PeriodBuilder.monthOf(new Date(), -1))
              .withDataValues([new org.hisp.dhis.api.model.v40_2_2.DataValue().withDataElement('aIJZ2d2QgVV').withValue('20')])
      - to:
          uri: dhis2:post/resource
          parameters:
            path: dataValueSets
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
      - unmarshal:
          json: {}
      - choice:
          when:
            - groovy: body.status != 'OK'
              steps:
                - log:
                    loggingLevel: ERROR
                    message: Import error from DHIS2 while saving data value set => ${body}
----
====

* Update an organisation unit
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.LoggingLevel;
import org.apache.camel.builder.RouteBuilder;
import org.hisp.dhis.api.model.v40_2_2.OrganisationUnit;

import java.util.Date;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:putResource")
            .setBody(exchange -> new OrganisationUnit().withName("Acme").withShortName("Acme").withOpeningDate(new Date()))
            .to("dhis2://put/resource?path=organisationUnits/jUb8gELQApl&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .unmarshal().json()
            .choice()
            .when().groovy("body.status != 'OK'")
                .log(LoggingLevel.ERROR, "Import error from DHIS2 while updating org unit => ${body}")
            .end();
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:putResource
    steps:
      - setBody:
          groovy: |
            new org.hisp.dhis.api.model.v40_2_2.OrganisationUnit()
              .withName('Acme')
              .withShortName('Acme')
              .withOpeningDate(new Date())
      - to:
          uri: dhis2:put/resource
          parameters:
            path: organisationUnits/jUb8gELQApl
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
      - unmarshal:
          json: {}
      - choice:
          when:
            - groovy: body.status != 'OK'
              steps:
                - log:
                    loggingLevel: ERROR
                    message: Import error from DHIS2 while updating org unit => ${body}
----
====

* Delete an organisation unit
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.LoggingLevel;
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:deleteResource")
            .to("dhis2://delete/resource?path=organisationUnits/jUb8gELQApl&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api")
            .unmarshal().json()
            .choice()
            .when().groovy("body.status != 'OK'")
                .log(LoggingLevel.ERROR, "Import error from DHIS2 while deleting org unit => ${body}")
            .end();
    }
}

----
YAML::
+
[source,yaml]
----
- from:
    uri: direct:deleteResource
    steps:
      - to:
          uri: dhis2:delete/resource
          parameters:
            path: organisationUnits/jUb8gELQApl
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
      - unmarshal:
          json: {}
      - choice:
          when:
            - groovy: body.status != 'OK'
              steps:
                - log:
                    loggingLevel: ERROR
                    message: Import error from DHIS2 while deleting org unit => ${body}
----
====

* Run analytics
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:resourceTablesAnalytics")
            .to("dhis2://resourceTables/analytics?skipAggregate=false&skipEvents=true&lastYears=1&username=admin&password=district&baseApiUrl=https://play.im.dhis2.org/stable-2-40-5/api");
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:resourceTablesAnalytics
    steps:
      - to:
          uri: dhis2:resourceTables/analytics
          parameters:
            skipAggregate: false
            skipEvents: true
            lastYears: 1
            username: admin
            password: district
            baseApiUrl: https://play.im.dhis2.org/stable-2-40-5/api
----
====

* Reference DHIS2 client
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;
import org.hisp.dhis.integration.sdk.Dhis2ClientBuilder;
import org.hisp.dhis.integration.sdk.api.Dhis2Client;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        Dhis2Client dhis2Client = Dhis2ClientBuilder.newClient("https://play.im.dhis2.org/stable-2-40-5/api", "admin", "district").build();
        getCamelContext().getRegistry().bind("dhis2Client", dhis2Client);

        from("direct:resourceTablesAnalytics")
            .to("dhis2://resourceTables/analytics?skipAggregate=true&skipEvents=true&lastYears=1&client=#dhis2Client");
    }
}
----

YAML::
+
[source,yaml]
----
- beans:
  - name: dhis2Client
    type: org.hisp.dhis.integration.sdk.api.Dhis2Client
    scriptLanguage: groovy
    script: >
      org.hisp.dhis.integration.sdk.Dhis2ClientBuilder.newClient('https://play.im.dhis2.org/stable-2-40-5/api', 'admin', 'district').build()

- from:
    uri: direct:resourceTablesAnalytics
    steps:
      - to:
          uri: dhis2:resourceTables/analytics
          parameters:
            skipAggregate: true
            skipEvents: true
            lastYears: 1
            client: "#dhis2Client"
----
====

* Set custom query parameters
+
[tabs]
====
Java::
+
[source,java]
----
package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

import java.util.Map;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        from("direct:clearCache")
            .setHeader("CamelDhis2.queryParams", constant(Map.of("cacheClear", "true")))
            .to("dhis2://post/resource?path=maintenance&client=#dhis2Client");
    }
}
----

YAML::
+
[source,yaml]
----
- from:
    uri: direct:clearCache
    steps:
      - setHeader:
          name: CamelDhis2.queryParams
          groovy: "['cacheClear':'true']"
      - to:
          uri: dhis2:post/resource
          parameters:
            path: maintenance
            client: "#dhis2Client"
----
====