{"id":19004819,"url":"https://github.com/dhis2/dhis2-java-client","last_synced_at":"2025-10-12T23:22:43.091Z","repository":{"id":42972696,"uuid":"129220764","full_name":"dhis2/dhis2-java-client","owner":"dhis2","description":"DHIS 2 API client for Java","archived":false,"fork":false,"pushed_at":"2025-04-11T16:24:51.000Z","size":942,"stargazers_count":8,"open_issues_count":1,"forks_count":10,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-04-11T17:36:43.192Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhis2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-12T08:44:23.000Z","updated_at":"2025-04-04T10:31:14.000Z","dependencies_parsed_at":"2024-01-05T19:33:59.935Z","dependency_job_id":"49f71452-c0f4-4629-9e2c-7f1d3c29f9a7","html_url":"https://github.com/dhis2/dhis2-java-client","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-java-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-java-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-java-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-java-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhis2","download_url":"https://codeload.github.com/dhis2/dhis2-java-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249288027,"owners_count":21244717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T18:24:38.994Z","updated_at":"2025-10-12T23:22:43.065Z","avatar_url":"https://github.com/dhis2.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DHIS2 Java Client\n\nDHIS2 API client for Java. The client allows you to create, update and retrieve information from DHIS2. The client is compatible with Java 17 and later JDK versions.\n\n## Getting started\n\nTo use `dhis2-java-client` with Maven you can specify the following dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.hisp\u003c/groupId\u003e\n  \u003cartifactId\u003edhis2-java-client\u003c/artifactId\u003e\n  \u003cversion\u003eLATEST\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYou can find `dhis2-java-client` and the available versions in [Maven central repository](https://mvnrepository.com/artifact/org.hisp/dhis2-java-client).\n\n## Configuration and Authentication\n\nThis section describes configuration and authentication of the client.\n\n#### Basic authentication\n\nA minimal configuration of `dhis2-java-client` where the configuration parameters refer to the base URL, username and password for the DHIS2 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:\n\n```java\nDhis2Config config = new Dhis2Config(\n    \"https://play.dhis2.org/2.39.0\", \n    \"admin\", \"district\");\n\nDhis2 dhis2 = new Dhis2(config);\n```\n\nAlternatively, to use Basic authentication you can specify the username and password of the DHIS2 account together with the base URL of the DHIS2 instance:\n\n```java\nDhis2 dhis2 = Dhis2.withBasicAuth(\n    \"https://play.dhis2.org/2.39.0\", \n    \"admin\", \"district\");\n```\n\nYou can use the username and password of a regular DHIS2 user account.\n\n### Personal access token authentication\n\nTo use personal access token (PAT)-based authentication you can specify the access token:\n\n```java\nDhis2 dhis2 = Dhis2.withAccessTokenAuth(\n    \"https://play.dhis2.org/2.39.0\", \n    \"d2pat_2bBQecgNcxrS4EPhBJuRlQkwiLr2ATnC2557514242\");\n```\n\nPATs can be created through the API or the user interface by going to Profile \u003e Settings \u003e Personal access tokens.\n\n### Cookie authentication\n\nTo use cookie-based authentication you can specify the session identifier:\n\n```java\nDhis2 dhis2 = Dhis2.withCookieAuth(\n    \"https://play.dhis2.org/2.39.0\", \n    \"5EC557E60D7E5CE8D78EEC1389592D3E\");\n```\n\nThe name of the session cookie used by the DHIS2 API is `JSESSIONID`. The value can typically be retrieved from the `Cookie` HTTP request header sent with DHIS2 API requests.\n\n### Get current user\n\nTo get the current user:\n\n```java\nMe me = dhis2.getMe();\n\nString username = me.getUsername();\nString dbLocale = me.getSettings().getDbLocale();\n```\n\n### Get user authentication\n\nTo retrieve the list of authorities granted to the authenticated user:\n\n```java\nList\u003cString\u003e authorities = dhis2.getUserAuthorization();\n```\n\n## Metadata\n\nThis section explains operations for DHIS2 metadata objects.\n\nPaging is disabled by default for query methods which return a list of objects. Paging is enabled by\ndefault for query methods which return a metadata wrapper object.\n\n### Query objects\n\nTo retrieve all org unit groups with paging disabled:\n\n```java\nList\u003cOrgUnitGroup\u003e orgUnitGroups = dhis2.getOrgUnitGroups(Query.instance());\n```\n\nTo retrieve a page of org units with a filter on the level property:\n\n```java\nList\u003cOrgUnit\u003e orgUnits = dhis2.getOrgUnits(Query.instance()\n    .addFilter(Filter.eq(\"level\", 4))\n    .addFilter(Filter.like(\"code\", \"fac\"))\n    .setPaging(1, 200));\n```\n\nTo retrieve all org units ordered descending on the name property:\n\n```java\nList\u003cOrgUnit\u003e orgUnits = dhis2.getOrgUnits(Query.instance()\n    .setOrder(Order.desc(\"name\")));\n```\n\nTo retrieve org units in a paged way with a pager object in the response:\n\n```java\nMetadata\u003cOrgUnit\u003e metadata = dhis2.getOrgUnitsPaged(Query.instance());\n\nPager pager = metadata.getPager();\nList\u003cOrgUnit\u003e orgUnits = metadata.getObjects();\n```\n\nWhen retrieving lists of objects, most 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:\n\n```java\nList\u003cProgram\u003e programs = dhis2.getPrograms(Query.instance()\n    .withExpandAssociations());\n```\n\n### Get object\n\nTo retrieve a single org unit by identifier:\n\n```java\nOrgUnit orgUnit = dhis2.getOrgUnit(\"j7gkH3hf83k\");\n```\n\n### Create object\n\nTo create an org unit:\n\n```java\nOrgUnit orgUnit = new OrgUnit();\norgUnit.setName(\"Ngelehun\");\norgUnit.setCode(\"NGLH\");\norgUnit.setPointGeometry(-11.452, 8.057);\n\nObjectResponse response = dhis2.saveOrgUnit(orgUnit);\n```\n\n### Create multiple objects\n\nTo create or update multiple objects:\n\n```java\nList\u003cOrgUnit\u003e orgUnits = CollectionUtils.list(\n    new OrgUnit(\"nEt3lFHOqYP\", \"Ngelehun\"),\n    new OrgUnit(\"gnAOCDoZUVO\", \"Kailahun\"));\n\nObjectsResponse response = dhis2.saveOrgUnits(orgUnits);\n```\n\n### Update object\n\nTo update an org unit (note that the ID property must be set):\n\n```java\nOrgUnit orgUnit = new OrgUnit();\norgUnit.setId(\"cDw53Ej8rjT\");\norgUnit.setName(\"Ngelehun\");\norgUnit.setCode(\"NGLH\");\n\nObjectResponse response = dhis2.updateOrgUnit(orgUnit);\n```\n\n### Check if object exists\n\nTo check if an object exists:\n\n```java\nboolean exists = dhis2.isOrgUnit(\"O6uvpzGd5pu\");\n```\n\n### Remove object\n\nTo remove an org unit:\n\n```java\nObjectResponse response = dhis2.removeOrgUnit(\"j7gkH3hf83k\");\n```\n\n### Get response message\n\nThe 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.\n\n```java\nObjectResponse response = dhis2.saveDataElement(dataElement);\n\nStatus status = response.getStatus();\nInteger statusCode = response.getHttpStatusCode();\nboolean success = response.getHttpStatus().is2xxSuccessful();\nString message = response.getMessage();\n```\n\n## Metadata objects\n\nThis section explains generic metadata object operations. In scenarios where dynamic handling of metadata is needed, several generic metadata objects are available.\n\n### Create object\n\nTo create a metadata object, in this case, a data element:\n\n```java\nDataElement dataElement = new DataElement();\ndataElement.setId(\"n5U1wOiyoUr\");\ndataElement.setCode(\"BCG_DOSE\");\ndataElement.setName(\"BCG doses given\");\ndataElement.setShortName(\"BCG doses given\");\ndataElement.setValueType(ValueType.INTEGER);\ndataElement.setAggregationType(AggregationType.SUM);\ndataElement.setDomainType(DataDomain.AGGREGATE);\n\nObjectResponse response = dhis2.saveMetadataObject(dataElement);\n```\n\n### Update object\n\nTo update a metadata object:\n\n```java\nObjectResponse response = dhis2.updateMetadataObject(dataElement);\n```\n\n### Get object\n\nTo retrieve a metadata object by identifier:\n\n```java\nDataElement dataElement = dhis2\n    .getMetadataObject(MetadataEntity.DATA_ELEMENT, \"n5U1wOiyoUr\");\n```\n\n### Query objects\n\nTo query metadata objects:\n\n```java\nList\u003cDataElement\u003e dataElements = dhis2\n    .getMetadataObjects(entity, Query.instance()\n        .addFilter(Filter.eq(\"id\", \"n5U1wOiyoUr\")));\n```\n\n### Remove object\n\nTo remove a metadata object:\n\n```java\nObjectResponse response = dhis2.removeMetadataObject(dataElement);\n```\n\n## Users\n\nThis section explains operations for DHIS2 users.\n\n### Get user\n\nTo get a user by ID:\n\n```java\nUser user = dhis2.getUser(\"xE7jOejl9FI\");\n```\n\nTo get a user by username:\n\n```java\nList\u003cUser\u003e users = dhis2.getUsers(Query.instance()\n    .addFilter(Filter.eq(\"username\", \"admin\")));\n```\n\n## System settings\n\nThis section explains operations for DHIS2 system settings.\n\n### Get system settings\n\nTo get system settings:\n\n```java\nSystemSettings settings = dhis2.getSystemSettings();\n```\n\n## Data values\n\nThis section explains operations for DHIS2 data values.\n\n### Save data value set\n\nTo save a data value set:\n\n```java\nDataValue dv1 = new DataValue();\ndv1.setDataElement(\"f7n9E0hX8qk\");\ndv1.setValue(\"12\");\n\nDataValue dv2 = new DataValue();\ndv2.setDataElement(\"Ix2HsbDMLea\");\ndv2.setValue(\"13\");\n\nDataValueSet dvs = new DataValueSet();\ndvs.setDataSet(\"pBOMPrpg1QX\");\ndvs.setCompleteDate(\"2014-02-03\");\ndvs.setPeriod(\"201910\");\ndvs.setOrgUnit(\"DiszpKrYNg8\");\n\ndvs.addDataValue(dv1);\ndvs.addDataValue(dv2);\n\nDataValueSetImportOptions options = DataValueSetImportOptions.instance();\n\nDataValueSetResponse response = dhis2.saveDataValueSet(dvs, options);\n```\n\n### Save data value set from file\n\nTo read a data value set from a file and save it:\n\n```java\nFile file = new File(\"/tmp/datavalueset.json\");\n\nDataValueSetImportOptions options = DataValueSetImportOptions.instance();\n\nDataValueSetResponse response = dhis2.saveDataValueSet(file, options);\n```\n\n## Events\n\nThis section explains operations for DHIS2 events.\n\n### Save events\n\nTo save a list of events:\n\n```java\nList\u003cEventDataValue\u003e dataValues = CollectionUtils.list(\n    new EventDataValue(\"oZg33kd9taw\", \"Male\"),\n    new EventDataValue(\"qrur9Dvnyt5\", \"45\"),\n    new EventDataValue(\"GieVkTxp4HH\", \"143\"),\n    new EventDataValue(\"eMyVanycQSC\", \"2021-07-02\"),\n    new EventDataValue(\"msodh3rEMJa\", \"2021-08-05\"),\n    new EventDataValue(\"K6uUAvq500H\", \"A010\"),\n    new EventDataValue(\"fWIAEtYVEGk\", \"MODDISCH\"));\n\nEvent event = new Event(\"EHlOLNtR4J0\");\nevent.setProgram(\"eBAyeGv0exc\");\nevent.setProgramStage(\"Zj7UnCAulEk\");\nevent.setOrgUnit(\"DiszpKrYNg8\");\nevent.setOccurredAt(DateTimeUtils.getDate(2021, 7, 12));\nevent.setDataValues(dataValues);\n\nEvents events = new Events(CollectionUtils.list(event));\n\nEventResponse response = dhis2.saveEvents(events);\n```\n\n### Get event\n\nTo retrieve an event:\n\n```java\nEvent event = dhis2.getEvent(\"EHlOLNtR4J0\");\n```\n\n### Remove event\n\nTo remove an event:\n\n```java\nEventResponse response = dhis2.removeEvent(event);\n```\n\n## Tracked entities\n\nThis section explains operations for DHIS2 tracked entities.\n\nTo save tracked entities:\n\n```java\nTrackedEntity trackedEntity = new TrackedEntity(\"sTXBon1B5I9\");\ntrackedEntity.setTrackedEntityType(\"nEenWmSyUEp\");\ntrackedEntity.setOrgUnit(\"DiszpKrYNg8\");\n\nTrackedEntityImportParams params = TrackedEntityImportParams.instance()\n    .setImportStrategy(ImportStrategy.CREATE_AND_UPDATE);\n\nTrackedEntityObjects objects = new TrackedEntityObjects()\n    .addTrackedEntity(trackedEntity));\n\nTrackedEntityResponse response = dhis2.saveTrackedEntityObjects(objects, params);\n```\n\n## Analytics\n\nThis section explains operations for the analytics engine.\n\n### Get analytics data\n\nTo retrieve analytics data:\n\n```java\nAnalyticsQuery query = AnalyticsQuery.instance()\n    .addDataDimension(List.of(\"fbfJHSPpUQD\", \"cYeuwXTCPkU\", \"Jtf34kNZhzP\"))\n    .addPeriodDimension(List.of(\"202501\", \"202502\", \"202503\"))\n    .addDimension(\"fMZEcRHuamy\", List.of(\"qkPbeWaFsnU\", \"wbrDrL2aYEc\"))\n    .addOrgUnitFilter(List.of(\"ImspTQPwCqd\"))\n    .setIncludeMetadataDetails(true);\n\nAnalyticsData data = dhis2.getAnalyticsData(query);\n```\n\n### Get analytics data value set\n\nTo retrieve analytics data in the data value set format:\n\n```java\nAnalyticsQuery query = AnalyticsQuery.instance()\n    .addDimension(Dimension.DIMENSION_DX, \"cYeuwXTCPkU\", \"Jtf34kNZhzP\")\n    .addDimension(Dimension.DIMENSION_OU, \"O6uvpzGd5pu\", \"fdc6uOvgoji\")\n    .addDimension(Dimension.DIMENSION_PE, \"202007\", \"202008\");\n\nDataValueSet dvs = dhis2.getAnalyticsDataValueSet(query);\n```\n\n### Write analytics data value set to file\n\nTo retrieve analytics data and write the content to the file:\n\n```java\nAnalyticsQuery query = AnalyticsQuery.instance()\n    .addDimension(Dimension.DIMENSION_DX, \"cYeuwXTCPkU\", \"Jtf34kNZhzP\")\n    .addDimension(Dimension.DIMENSION_OU, \"O6uvpzGd5pu\", \"fdc6uOvgoji\")\n    .addDimension(Dimension.DIMENSION_PE, \"202007\", \"202008\");\n\nFile file = new File(\"/tmp/data-value-set.json\");\n\ndhis2.writeAnalyticsDataValueSet(query, file);\n```\n\n## Data store\n\nThis section explains data store operations.\n\n### Save entry\n\nTo save a data store entry:\n\n```java\nDashboard dashboard = new Dashboard();\n\nResponse response = dhis2.saveDataStoreEntry(\"dashboards\", \"attendance\", dashboard);\n```\n\n### Update entry\n\nTo update a data store entry:\n\n```java\n\nResponse response = dhis2.updateDataStoreEntry(\"dashboards\", \"attendance\", dashboard);\n```\n\n### Get namespaces\n\nTo retrieve data store namespaces:\n\n```java\nList\u003cString\u003e namespaces = dhis2.getDataStoreNamespaces();\n```\n\n### Get keys in namespace\n\nTo retrieve keys for a namespace:\n\n```java\nList\u003cString\u003e keys = dhis2.getDataStoreKeys(\"dashboards\");\n```\n\n### Get data store entry\n\nTo retrieve an entry for a namespace and key:\n\n```java\nDashboard dashboard = dhis2.getDataStoreEntry(\"dashboards\", \"attendance\", Dashboard.class);\n```\n\n### Get data store entries\n\nTo retrieve a list of data store entries for a namespace and entry fields:\n\n```java\nList\u003cString\u003e fields = List.of(\"id\", \"code\", \"name\");\n\nList\u003cMap\u003cString, Object\u003e\u003e entries = dhis2.getDatastoreEntries(\"dashboards\", fields);\n```\n\n### Get metadata for entry\n\nTo retrieve metadata for a data store entry:\n\n```java\nEntryMetadata metadata = dhis2.getDataStoreEntryMetadata(\"dashboards\", \"attendance\");\n```\n\n### Remove entry\n\nTo remove a data store entry:\n\n```java\nResponse response = dhis2.removeDataStoreEntry(\"dashboards\", \"attendance\");\n```\n\n### Remove namespace\n\nTo remove a data store namespace including all entries:\n\n```java\nResponse response = dhis2.removeDataStoreNamespace(\"dashboards\");\n```\n\n## Maintenance\n\nThis section explains maintenance operations.\n\n### Clear application cache\n\nTo clear application cache:\n\n```java\nResponse response = dhis2.clearApplicationCache();\n```\n\n## Update resource tables\n\nTo start a resource tables update job:\n\n```java\nJobInfoResponse response = dhis2.updateResourceTables();\n```\n\n## System\n\nThis section explains system operations.\n\n### Get system info\n\nTo get system info:\n\n```java\nSystemInfo info = dhis2.getSystemInfo();\n\nString version = info.getVersion();\n```\n\nTo compare the system version:\n\n```java\nSystemInfo info = dhis2.getSystemInfo();\n\nSystemVersion version = info.getSystemVersion();\n\nboolean isHigher = version.isHigher(\"2.37.0\");\n```\n\n### Get job notifications\n\nTo retrieve job notifications for a job category and job identifier:\n\n```java\nList\u003cJobNotification\u003e notifications = dhis2\n    .getJobNotifications(JobCategory.ANALYTICS_TABLE, \"GxTz2OVPcYk\");\n```\n\n## Development\n\nThis section covers development of the DHIS2 Java client.\n\nPackage:\n\n```\nmvn clean package\n```\n\nRun unit tests:\n\n```\nmvn test\n```\n\nRun integration tests:\n\n```\nmvn test -Pintegration\n```\n\nRun specific integration test:\n\n```\nmvn test -Pintegration -Dtest=Dhis2ApiTest\n```\n\nTo log internal messages at info level during tests:\n\n```\nmvn test -Dlog.level.dhis2=info\n```\n\n## Deployment\n\nThe artifact will be deployed through a GitHub action to the OSSRH Maven repository when detecting a commit to master \nwhere the main version is  not a SNAPSHOT version. To trigger a deploy, make a commit to master where the main version \nis bumped to a non-SNAPSHOT version.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fdhis2-java-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhis2%2Fdhis2-java-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fdhis2-java-client/lists"}