https://github.com/dhis2/camel-dhis2

Camel DHIS2 Component
https://github.com/dhis2/camel-dhis2
Last synced: about 1 year ago
JSON representation
Camel DHIS2 Component
Host: GitHub
URL: https://github.com/dhis2/camel-dhis2
Owner: dhis2
License: apache-2.0
Created: 2022-05-04T07:24:02.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2024-10-04T00:23:24.000Z (over 1 year ago)
Last Synced: 2025-04-17T10:26:11.410Z (about 1 year ago)
Language: Java
Homepage: https://developers.dhis2.org/docs/integration/camel-dhis2-component
Size: 353 KB
Stars: 7
Watchers: 10
Forks: 1
Open Issues: 6
Metadata Files:
- Readme: README.adoc
- License: LICENSE.txt
Awesome Lists containing this project

README

          = 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.0

:supportlevel: Preview

:component-header: Both producer and consumer are supported

*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]

----

    org.hisp.dhis.integration.camel

    camel-dhis2

    x.x.x

----

== URI Format

....

dhis2://operation/method[?options]

....

== Configuring Options

Camel components are configured on two separate levels:

* component level

* endpoint level

=== Configuring Component Options

The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.

Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

Configuring components can be done with the https://camel.apache.org/manual/component-dsl.html[Component DSL], in a configuration file (application.properties|yaml), or directly with Java

code.

=== Configuring Endpoint Options

Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the https://camel.apache.org/manual/Endpoint-dsl.html[Endpoint DSL] as a type safe way of configuring endpoints.

A good practice when configuring options is to use https://camel.apache.org/manual/using-propertyplaceholder.html[Property Placeholders], which allows to not hardcode urls, port numbers, sensitive information, and other settings. In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.

The following two sections lists all the options, firstly for the component followed by the endpoint.

== Component Options

The DHIS2 component supports the options listed below.

[width="100%",cols="13%,58%,4%,25%",options="header",]

|===

| Naming | Description | Default | Type

| baseApiUrl (common) | DHIS2 server base API URL | | String

| username (common) | Username of the DHIS2 user to operate as | | String

| password (common) | Password of the DHIS2 username | | String

| personalAccessToken (common) | Personal access token to authenticate with DHIS2. This option is mutually exclusive to username and password | | String

| client (advanced) | Dhis2Client is an expensive object to create. To avoid creating multiple instances, it can be set directly. | | org.hisp.dhis.integration.sdk.api.Dhis2Client

|===

== Endpoint Options

The DHIS2 endpoint is configured using URI syntax:

....

dhis2:apiName/methodName

....

with the following path and query parameters:

=== Path Parameters

[width="100%",cols="13%,74%,5%,8%",options="header",]

|===

| Naming | Description |Default | Type

| apiName (common) | *Required* What kind of operation to perform. Enum values: | | Dhis2ApiName

| methodName (common) | *Required* What sub operation to use for the selected operation | | String

|===

=== Query Parameters

[width="100%",cols="16%,46%,6%,32%",options="header",]

|===

| Naming | Description | Default | Type

| baseApiUrl (common) | DHIS2 server base API URL | | String

| inBody (common) | Sets the name of a parameter to be passed in the exchange In Body | resource | String

| client (advanced) | To use the custom client | | org.hisp.dhis.integration.sdk.api.Dhis2Client

| password (security) | Password to use for basic authentication | | String

| username (security) | Username to use for basic authentication | | String

|===

== API Parameters

The DHIS2 endpoint is an API-based component and has additional parameters based on which API name and API method is used. The API name and API method is located in the endpoint URI as the apiName/methodName path parameters:

....

dhis2:apiName/methodName

....

The API names as listed in the table below:

[width="100%",cols="15%,5%,80%",options="header",]

|===

| API Name | Type | Description

| get | Both | API for the get operation, which fetches a resource or a list resources from the server

| post | Both | API for the create operation, which creates a new resource on the server

| resourceTables | Both | API for resource and analytic operations

|===

Each API is documented in the following sections to come.

=== API: get

*Both producer and consumer are supported*

The get API is defined in the syntax as follows:

....

dhis2:get/methodName?[parameters]

....

The method(s) is listed in the table below, followed by detailed syntax for each method. (API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[cols=",,",options="header",]

|===

| Method | Alias | Description

| resource | | Retrieve a resource

| collection | | Retrieve a list of resources

|===

==== METHOD resource

Signatures:

* java.io.InputStream resource(java.lang.String path, java.lang.String fields, java.lang.String filter, org.apache.camel.component.dhis2.api.RootJunctionEnum rootJunction, java.util.Map queryParams)

The get/resource API method has the parameters listed in the table below:

[cols=",,",options="header",]

|===

| Parameter | Description | Type

| path | Resource URL path | String

| fields | Comma-delimited list of fields to fetch | String

| filter | Search criteria | String

| rootJunction | Logic junction used between filters | RootJunctionEnum

| queryParams | Custom query parameters | Map

|===

In addition to the parameters above, the get/resource API can also use any of the link:#query-parameters[Query Parameters].

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelDhis2.parameter. The inBody parameter overrides message header, i.e. the endpoint parameter inBody=myParameterNameHere would override a CamelDhis2.myParameterNameHere header.

==== METHOD collection

Signatures:

* java.util.Iterator collection(java.lang.String path, java.lang.Boolean paging, java.lang.String fields, java.lang.String filter, java.util.Map queryParams)

The get/collection API method has the parameters listed in the table below:

[width="100%",cols="17%,72%,11%",options="header",]

|===

| Parameter | Description | Type

| path | Resource URL path | String

| arrayName | JSON property name holding the array to read | String

| paging | Turn paging on/off | Boolean

| fields | Comma-delimited list of fields to fetch | String

| filter | Search criteria | String

| rootJunction | Logic junction used between filters | RootJunctionEnum

| queryParams |Custom query parameters | Map

|===

In addition to the parameters above, the get/collection API can also use any of the link:#query-parameters[Query Parameters].

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelDhis2.parameter. The inBody parameter overrides message header, i.e. the endpoint parameter inBody=myParameterNameHere would override a CamelDhis2.myParameterNameHere header.

=== API: post

*Both producer and consumer are supported*

The post API is defined in the syntax as follows:

....

dhis2:post/methodName?[parameters]

....

==== METHOD resource

Signatures:

* java.io.InputStream resource(java.lang.String path, java.lang.Object resource, java.util.Map new DataValueSet().withCompleteDate(

                    ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_INSTANT))

                                                                   .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.dhis2.org/40.2.2/api")

            .unmarshal().json(WebMessage.class)

            .choice()

            .when(exchange -> !exchange.getMessage().getBody(WebMessage.class).getStatus().equals(WebMessage.StatusRef.OK))

                .log(LoggingLevel.ERROR, "Import error from DHIS2 while saving data value set => ${body}")

            .end();

    }

}

----

* Update an organisation unit

+

[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 org.hisp.dhis.api.model.v40_2_2.WebMessage;

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: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.dhis2.org/40.2.2/api")

            .unmarshal().json(WebMessage.class)

            .choice()

            .when(exchange -> !exchange.getMessage().getBody(WebMessage.class).getStatus().equals(WebMessage.StatusRef.OK))

                .log(LoggingLevel.ERROR, "Import error from DHIS2 while updating org unit => ${body}")

            .end();

    }

}

----

* Delete an organisation unit

+

[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.WebMessage;

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:deleteResource")

            .to("dhis2://delete/resource?path=organisationUnits/jUb8gELQApl&username=admin&password=district&baseApiUrl=https://play.dhis2.org/40.2.2/api")

            .unmarshal().json(WebMessage.class)

            .choice()

            .when(exchange -> !exchange.getMessage().getBody(WebMessage.class).getStatus().equals(WebMessage.StatusRef.OK))

                .log(LoggingLevel.ERROR, "Import error from DHIS2 while deleting org unit => ${body}")

            .end();

    }

}

----

* Run analytics

+

[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.dhis2.org/40.2.2/api");

    }

}

----

* Reference DHIS2 client

+

[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.dhis2.org/40.2.2/api", "admin", "district").build();

        getCamelContext().getRegistry().bind("dhis2Client", dhis2Client);

        from("direct:resourceTablesAnalytics")

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

    }

}

----

* Set custom query parameters

+

[source,java]

----

package org.camel.dhis2.example;

import org.apache.camel.builder.RouteBuilder;

import java.util.List;

import java.util.Map;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {

        from("direct:postResource")

            .setHeader("CamelDhis2.queryParams", constant(Map.of("cacheClear", List.of("true"))))

            .to("dhis2://post/resource?path=maintenance&client=#dhis2Client");

    }

}

----
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/dhis2/camel-dhis2

Awesome Lists containing this project

README
