Technical Introduction to In-App Reports & DHIS 2 Integration

Owned by Benn Simon
Last updated: Feb 04, 2022
4 min read

The purpose of this document is to outline the requirements for successful sync of reports from an opensrp app to opensrp server then to DHIS2 instance.

Getting started

  • Integrate the reporting module to your app https://github.com/OpenSRP/opensrp-client-reporting

    • Add it to your dependencies in the projects' build.gradle file

    • Add the following lines to your Application Class

      • // Init Reporting library ReportingLibrary.init(context, getRepository(), null, BuildConfig.VERSION_CODE, BuildConfig.DATABASE_VERSION);

    • Add the required repositories from the reporting lib to your Apps Repository file

      • IndicatorRepository.createTable(database); IndicatorQueryRepository.createTable(database); DailyIndicatorCountRepository.createTable(database); //create the hia2Report table that stores the report before sync and updated the sync status after sync EventClientRepository.createTable(database, Hia2ReportRepository.Table.hia2_report, Hia2ReportRepository.report_column.values());

    • Depending on your implementation you may need to add code for the following screens,

      • Dally Tallies, Draft Monthly and Sent Monthly fragments

        • To get examples of the code you can view the code for the following project

    • To add queries for your indicators, you will need to add a file called indicator-definitions.yml

      • The .yml file has the following structure

      • indicators: - key: "ME_MAT_Child_HIV_Status_Unknown" description: "Maternity Child HIV Status Unknown" indicatorQuery: "SELECT count(*) from maternity_child WHERE child_hiv_status = 'Unknown' and '%s' = strftime('%Y-%m-%d', event_date)" grouping: "maternity" - key: "ME_MAT_Child_HIV_Status_Exposed" description: "Maternity Child HIV Status Exposed" indicatorQuery: "SELECT case when nvp_administration = 'No' THEN 'No_NVP' when nvp_administration = 'Yes' THEN 'NVP_Started' else 'Null' END NVP, count(1) from maternity_child WHERE child_hiv_status = 'Exposed' and '%s' = strftime('%Y-%m-%d', event_date)" isMultiResult: true expectedIndicators: - "ME_MAT_Child_HIV_Status_Exposed_No_NVP" - "ME_MAT_Child_HIV_Status_Exposed_NVP_Started" grouping: "maternity"

        • grouping is optional if your app has only one module integrated

        • key is used to identify the indicators (they have no spaces and special characters conventionally) , with some mapping from the strings file during render you can show a more readable key/text.

        • description is additional information of the indicator

        • indicatorQuery is the object that hold the query, in this field the following placeholder %s , is preserved for today's date in Y-m-d sqlite date format. The query has to have a daily filter since the queries are aggregated upto monthly level.

        • In this file you can have simple queries which return one result or multi-result query that does the vice versa.

    • To start building daily tallies for queries in the indicator-definitions.yml file add the following code in your AppRepository.java file.

      • This will add the indicators to the hia2_indicators table. Checkout an example of a HIA2IndicatorsRepository in the following repositories or

      • Then add a call to a job as such below to begin the task of creating reports from the last time the job run.

      •  

  • Syncing reports to the server then to DHIS 2

    • Opensrp server provides the following api for adding reports

    • The following is the structure of the payload expected

      •  

    • A json object inside the reports array looks like so

      •  

    • To generate the following payload you will need the following.

      • Create or use an existing report in DHIS 2 instance, use the report name as the reportType in the payload above. To check if your report exists use the following api

      • locationId, formSubmissionId, reportDate, providerId, dateCreated(optional), duration are generated within the app.

      • The hia2Indicators are the monthly tallies of the report for a particular month (an aggregation of daily tallies)

        • For a successful sync to DHIS 2 you will need the categoryOptionCombo ,dhisId and value as the required fields. To get these attributes one can export from a DHIS 2 instance using the following tool.

        • For Giz Malawi the mapping for indicatorCode is done within the app using a csv with the following structure …

          •  

  • At this point you should be done and left with debugging