Understanding the Reporting module's terminology
This module is completely integrated with the reporting module and hence interacts with it very closely. To understand what is happening in this module, the user needs to have some basic knowledge of reporting module.
Let us take an example and understand the working : consider we need two sample reports such as (a) People in WHO stages disaggregated by sex and age. (b) New patients disaggregated by CD4 count.
- WHO Stage 1 – Disaggregated by [Sex-Age][Male, Female – Child, Teen, Middle, Old]
- WHO Stage 2 – Disaggregated by [Sex-Age] [Male, Female – Child, Teen, Middle, Old]
- New Patients – Disaggregated by [CD4 count][CD4>250,CD4<250]
Each case is finally a report in OpenMRS and for creating the report there are some basic blocks such as Indicators , Dimensions, Data Set Definitions and Base cohort. The following image will explain how each part is divided and how they constitute a report.
As indicated in the above diagram.
- WHO stages and New patients which constitute the main part of the report are categorized as indicator cohorts.
- The Combo's such as [Sex-Age] and [CD4 count] are categorized as Data set definitions.
- Each individual component in the combo's such as Sex, Age , CD4 count are grouped as Dimensions. They in turn are divided into Dimension options such as [Male, Female] for Sex, [Child, Teen, Middle Aged, Senior Citizens ] for Age and [CD4>250, CD4<250] for CD4 count.
- The parameters such as Location , Start and End date are usually considered as Base cohort reducing the report base. Which can be customized to a specific cohort based on user preference.
What is actually happening?
- OpenMRS objects are colored blue.
- DHIS2 objects are colored yellow.
- The arrows indicate sets of DHIS2 and OpenMRS objects that relate to each other.
The places where the user interaction is necessary is mapping
- Org unit mapping to OpenMRS locations
- Data elements to Indicator Cohorts
- Options to Dimension value Cohorts
- Mapping the base cohort(optional)
- Entering the parameters for the report.
The interactions such as reports generation , report data transmission and mapping of sets not mentioned above are done automatically using the API.
Module Usage Guide
The following are the screenshots of the module and they describe the usage and different functions available for the user to perform.
1.Server Administration page :
To Add a Server :
- Click on "Add New" button. A new window will open on the screen to enter the details as shown in the below figure.
2. Enter the valid details as shown in the below figure. Name Must be unique as it will separate each DHIS server. The url, username and password are the details of the DHIS server. Transport is where the results/reporting data will be sent.
3. Click on Save and the server is created.
To Edit a Server :
- Click on the (paper and pencil) symbol under the Actions column in the server Administration page to edit the server.
- Change the details you would like to and click on save.
To Test the connection details :
Use this option right after entering the details of the server and confirm if the details are valid.
- Click on (lightning) symbol under the actions column.
- The connection status will be shown.
To Update the metadata :
Use this option right after you enter the server details and test the connection. And if there is any change in the data structure of the DHIS server.
- Click on (download) symbol under the actions column.
- The data will be updated.(or the error details will be displayed)
To Delete the Server :
- Click on (trash can) symbol to delete the server.
- Click on OK on the confirmation message.
2. Location Mapping page(Click on(map icon) in the Server Administration Page) :
- Left side list represents the list of Org units.
- Right side list represents list of OpenMRS locations.
- The table in between the lists is where the mapping is managed.
Mapping an Org unit to OpenMRS locations :
To a single Org Unit multiple OpenMRS locations can be mapped.
- Select the org unit you would like to map from the list of Org units.
- Click on the Right side pointing arrow in between the org unit list(left side list) and the Location Mapping table.
- The Org unit will get added to the list. By default the latest added org unit will be auto selected and the radio button would be selected right beside it.
- Now select the OpenMRS location from the OpenMRS location list (right side list) you would like to map to the org unit.
- Click on the Left side pointing arrow in between the Locations list(right side list) and the locations mapping table.The location will be added in the right side column of the corresponding cell of the Org Unit.
Deleting a Mapping :
- Clicking on the next to the OpenMRS location in the locations mapping table will unmap the location mapped to the specific Org Unit.
- Clicking on the next to the Org Unit in the locations mapping table will remove the Org unit from the table and all the mappings it is related to are also removed.
3. Report Template Page(Click on(screwdriver and wrench) in the Server Administration Page) :
- This page is automatically generated as the metadata is updated and if any relevant report templates exist in the DHIS server.
- The Top table represents the list of Report templates of the DHIS server and their details.
- The bottom table represents the list of Data Elements(Indicator Cohorts) and Options(Dimension cohorts) to be mapped to the respective cohorts in the report templates.
Editing a Report :
Initially only editing of Report name is available. Later selection of Base cohort will be available.By default the base cohort is always set to All patients.
- Click on the "Edit Reports" button under the Actions column in the Report templates table (Top table).
- A popup window is displayed where the Name of the report can be changed. Change the name and click on Save.
Mapping Data Elements(Indicator Cohorts)/Options(Dimension Cohorts) :
This can be done either by clicking on the data element/option name in the Data Elements and Options Table (bottom table). OR you can click on the "Map Data Elements"/"Map Options" button and map them from the Map Data Elements/Map Options page where a more clear representation of what mapping is happening is given. But mapping is kept directly here for convenience.
- Click on the data element/Option you would like to map from the Data Elements and Options Table (bottom table) 's Data Element/Option column .
- A popup appears as shown and a drop down is shown for selecting from the list of cohorts available for mapping.
- Select the one that matches the criteria and click on save.
- If no cohort matches the criteria then select the Create New Cohort button right next to the list of available cohorts. This will take you to the Cohorts page of Reporting Module where you can create a cohort and select it from the list in the drop down.
- The mapping can be seen clearly in the Map Data elements/Map Options page.
4. Map Data Elements Page :
- This page is an exclusive page for the data elements of a report and gives a better picture of the mapping as it shows which data elements are mapped and the cohort they are mapped to.
Mapping the Data Element :
The process of mapping is the same as shown in the Mapping of Data Elements in the 3.Report Templates Page section. Click on the(edit) button and follow the process.
After the mapping is done the mapped cohort is shown as below.
5. Map Options Page :
- This page is an exclusive page for the options of a report and gives a better picture of the mapping as it shows which options are mapped and the cohort they are mapped to.
Mapping the Option :
The process of mapping is the same as shown in the Mapping of Options in the 3.Report Templates Page section.Click on the(edit) button and follow the process.
After the mapping is done the mapped cohort is shown as below.
6. Run Reports Page(Click on the run reports link under the Integration Management heading in the Admin Page) :
- When a report is completely mapped it is shown in this list of run reports. (A report is said to be completely mapped when all the Data elements and options of the report are mapped to their respective cohorts).
Running a Report :
- Click on the (play icon) under the actions column for the respective report you would like to run.
- A popup asking for the Location and start date will appear.
- Select the location from the list of Org Units you have mapped earlier from the Location mapping page from the drop down.
- Enter the Start date as to when the report data must be based on and click on Submit the end date is calculated based on the frequency of the report.
7. Manage Results Page (Click on(folder icon) in the Server Administration Page) :
- This shows the list of results related to the run reports pertaining to the server.
- The user can view the result ,send the result and delete the result from this page.
View the Result :
- Click on the "View Report" button under the Actions column.
- A new page will be opened showing the results of the report.
Send the Result :
- Click on the "Send Report" button under the Actions column.
- This will send the report result to the Email/Url provided in the Server details.
Delete the Result :
- Click on the "Delete Report" button under the Actions column.
- The report data will be permanently deleted This action is not irreversible.