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
      - https://github.com/OpenSRP/opensrp-client-chw-hf
      - https://github.com/OpenSRP/opensrp-client-giz-malawi
- 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.
  - // initialize from yml file ReportingLibrary reportingLibraryInstance = ReportingLibrary.getInstance(); // Check if indicator data initialised boolean indicatorDataInitialised = Boolean.parseBoolean(reportingLibraryInstance.getContext() .allSharedPreferences().getPreference(indicatorDataInitialisedPref)); boolean isUpdated = checkIfAppUpdated(); if (!indicatorDataInitialised || isUpdated) { Timber.d("Initialising indicator repositories!!"); reportingLibraryInstance.initIndicatorData(indicatorsConfigFile, database); // This will persist the data in the DB reportingLibraryInstance.getContext().allSharedPreferences().savePreference(indicatorDataInitialisedPref, "true"); reportingLibraryInstance.getContext().allSharedPreferences().savePreference(appVersionCodePref, String.valueOf(BuildConfig.VERSION_CODE)); }
  - This will add the indicators to the hia2_indicators table. Checkout an example of a HIA2IndicatorsRepository in the following repositories https://github.com/OpenSRP/opensrp-client-giz-malawi or https://github.com/OpenSRP/opensrp-client-chw-core
  - Then add a call to a job as such below to begin the task of creating reports from the last time the job run.
  - RecurringIndicatorGeneratingJob.scheduleJob(RecurringIndicatorGeneratingJob.TAG, TimeUnit.HOURS.toMinutes(6), getFlexValue(BuildConfig.DATA_SYNC_DURATION_MINUTES));

Syncing reports to the server then to DHIS 2
- Opensrp server provides the following api for adding reports
  - https://{domain}/opensrp/rest/report/add
- The following is the structure of the payload expected
  - { "reports": "[{\"dateCreated\":\"2020-08-04T15:16:55.539+03:00\",\"duration\":0,\"formSubmissionId\":\"9028b90e-be65-4ec0-91d0-86e9ba9d6c01\",\"hia2Indicators\":[{\"categoryOptionCombo\":\"pE37AYgl7bx\",\"dhisId\":\"BOAUQVmPxf3\",\"indicatorCode\":\"ME_Anti_Malaria_Treatment_Confirmed_Under_5\",\"value\":\"0\"},{\"dhisId\":\"unknown\",\"indicatorCode\":\"ME_Malaria_Cases_Presumed_Over_5\",\"value\":\"0\"}],\"locationId\":\"76bc21e4-6670-480a-8628-7fd44b1d8d14\",\"providerId\":\"chigodi\",\"reportDate\":\"2020-02-27T00:00:00.000+03:00\",\"reportType\":\"Malaria Health Facility Report\"}]" }
- A json object inside the reports array looks like so
  - { "dateCreated": "2020-08-04T15:16:55.539+03:00", "duration": 0, "formSubmissionId": "9028b90e-be65-4ec0-91d0-86e9ba9d6c01", "hia2Indicators": [ { "categoryOptionCombo": "pE37AYgl7bx", "dhisId": "BOAUQVmPxf3", "indicatorCode": "ME_Anti_Malaria_Treatment_Confirmed_Under_5", "value": "0" }, { "dhisId": "unknown", "indicatorCode": "ME_Malaria_Cases_Presumed_Over_5", "value": "0" } ], "locationId": "76bc21e4-6670-480a-8628-7fd44b1d8d14", "providerId": "chigodi", "reportDate": "2020-02-27T00:00:00.000+03:00", "reportType": "Malaria Health Facility Report" }
- 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
    - https://{dhis2-domain}/api/dataSets.json?paging=false
  - 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 …
      - id,indicatorCode,IndicatorDescription,dhisId,categoryOptionCombo,.. 2,ME_Vaccines_Age_pcv_3_Over_1_Outreach,CHD EPI PCV3 Childhood Vaccination Outreach Over 1,IQFC39nNHPX,zKLduwqZFnh,CHD EPI PCV3 Childhood Vaccination Outreach Over 1,child 3,ME_Vaccines_Age_pcv_3_Over_1_Outreach,CHD EPI PCV3 Childhood Vaccination Outreach Under 1,IQFC39nNHPX,ipKITPnwlcP,CHD EPI PCV3 Childhood Vaccination Outreach Under 1,child 4,ME_A_CHD_EPI_Immunization_sessions_cancelled_Outreach,CHD EPI Immunization sessions cancelled Outreach,QJBtQ8GfxXE,kVTGmhgf7wQ,CHD EPI Immunization sessions cancelled Outreach,child 5,ME_A_CHD_EPI_Immunization_sessions_cancelled_Static,CHD EPI Immunization sessions cancelled Static,QJBtQ8GfxXE,yqszvXV2s8u,CHD EPI Immunization sessions cancelled Static,child 6,ME_A_CHD_EPI_Immunization_sessions_planned_Outreach,CHD EPI Immunization sessions planned Outreach,Hig2nHtgfVr,kVTGmhgf7wQ,CHD EPI Immunization sessions planned Outreach,child 7,ME_A_CHD_EPI_Immunization_sessions_planned_Static,CHD EPI Immunization sessions planned Static,Hig2nHtgfVr,yqszvXV2s8u,CHD EPI Immunization sessions planned Static,child 8,ME_A_CHD_EPI_Reasons_for_cancellation,CHD EPI Reasons for cancellation,Er9t7hU2OQp,Tt7fU5lUhAU,CHD EPI Reasons for cancellation,child
At this point you should be done and left with debugging

Documentation

Technical Introduction to In-App Reports & DHIS 2 Integration

Analytics

Getting started

Related content