Reporting Rate functional requirement specification

Summary
Reporting rate report show the percentage of facilities that are reported and those facilities that didn't reported in a given geographical area. This report is used to follow up on non-reporting and late-reporting facilities and priorities facilities in need of support or supervision. The non-reporting facilities list can also be sent via email to the district officer.

Components
Reporting rate report will provide a Google Map based geographical report that shows different shade color layer on each region of the country based on their reporting performance for a give reporting period. On the map each region will be represented by a poly shape based on Geo data of the region's boundary and the shape will be rendered on the Google Maps. The Google map layer for the district will be shaded based on the combined reporting performance of the member facilities.

The report also has a tabular report section that listed all the districts in the country with reporting performance of the member facilities.

To access this report, first the user needs to login and should have the right to access the report. Once the user browse to the report, a page with the list of report filters mentioned above will appear.

Features

• Report filters

  Name	Input type	Description
  Program	Dropdown list	Loads all programs that are active and based on user's supervisory node. It's a required field.
  Schedule	Dropdown list	Loads all program reporting schedule based on selected program. It is dependent on program selection. It's a required field.
  Year	Dropdown list	Required field and shows list of years starting from the program start data till current year in yyyy format.
  Period	Dropdown list	Required field and shows a list of periods based on schedule selection
  Indicator	Drop down list	Possible values are: Ever Reported / Total Facilities Ever Reported / Expected Facilities, Reported during period / Expected Facilities

  Table 1: Reporting filters
  
• GIS map based report

Fig 1- Reporting rate report with data

The map shows the reporting performance by of districts in the country shading with colors based on the selected program, schedule and period. If all expected facilities in the district report the district layer on the GIS map will be Green. If some of the facilities reported the shade color will be yellow If no facility reported the district color shade will be red and if no facility is expected to report - black. The following table defines the color code that represents reporting performance.

Table 2: Color representation for the map shape shades and tabular report bar.
The color shaded districts on the map report is clickable. When it gets clicked a popup will appear at the place map is clicked and will shows tabular data regarding how many facilities:-

• are expected to report,
• have reported in the selected period
• reported ever
• are found in the clicked district

Fig 3- Showing district level reporting status by clicking a give district on the GIS report
User can drag and zoom the map report and can click on the districts to see more reporting related data as described above and there is also a map legend and the bottom left of the map as it is seen in Fig 1 above.

• Scroll-able tabular report

The left section of the report will show a tabular representation of the GIS map report. The tabular report listes districts in the country with associated reporting performance data of facilities. For each district in this report, we will show how many facilities are expected to report, how many have reported and percent reported with chart and number as shown below.

Fig 4: Tabular report showing all the districts and associated reporting figures with reporting rate by percentage

On '% Reported' column, when the bar gets clicked, the following pop up will appear. The popup will show list of facilities either reported or haven't reported based on the selection on the dropdown at the bottom section of the popup. As default, the list shows all facilities either reporting or non-reporting


Fig 5: popup that appears when '% Reported' bar clicked

Apart from showing the list of facilities, the purpose of this pop up is to notify the facilities or supervisors via SMS or Email so that to send their report if they didn't or any custom message is also possible.
To send Email or SMS, one needs to click the button at the left side of the table on the respective facility.
When the email button gets clicked, the following screen will come. In each screen there is a way of sending SMS and email for the facilities whose Email address or Mobile phone number is registered in the system.

Fig 6: When the email button clicked on the popup that is shown on Fig 4.


Fig 7: sending SMS alert for the supervisors regarding non reporting facilities

Validation
When the page loads for the first time, all report filters should be un-selected except Year filter should be defaulted to the current year and Indicator filter should be defaulted to Reported during period / Expected Facilities.
To see report data in the report, the report viewer needs to select all the required filters - Program, Schedule, Year and Period. Once all the required fields are selected, the report will try to fetch data from server. If there are some un-selected filters which are required, the report won't try to load a data until all the required fields are selected.
For all required filters an asterisk sign with red color coded ({}{*}) will be seen beside the filter label.

Fetching
Once all the required fields are selected the report will automatically loads the data and one can change the report filters to fine tune the report data.

Data Formatting
On the tabular report, column values for Expected, Reported and % Reported are numbers separated by thousands separator and visually right aligned. The rest column values should be left aligned.

Exporting
On the upper side of the report there will one buttons for exporting the current report to XLS format.. When the Excel button clicked, XLS export of the tabular report section will be exported and downloaded.

eLMIS implementation
Reporting rate report on eLMIS can be accessed from UAT site at https://uat.zm.elmis-dev.org or by running eLMIS locally by checking out the source code from {+}https://bitbucket.org/elmis-tzm/open-lmis.git+ and one can follow the README.md file to quickly setup the project on local machine.
To access the report from UAT server, one needs to have a login account with role 'View Reports' attached to it.

Fig 8: Report viewing role.

After successful login, user can got to Reports > Report Status > Reporting rate by Facility on the upper navigation menu. If the report link is not there or not visible, check the report role 'View Reports' is added to the login account.


Developer Resources
The Consumption report is developed using Jasper report from PDF and XLS output and HTML and AngularJS for the HTML preview.
In the eLMIS code base, all the reports are place under module called 'reports '

Under the report module we have three folders

1. Java - Java code for fetching data from the database and transforming it to REST API
2. Resources - This folder hold compiled jasper reports
3. Template - This folder hold Jasper JRXML files. This is the place where we can find the report design to change report implementation.

How to compile report design file
To compile report files, user should navigate to the home directory of the project and issue the following command.

gradle compileJasperReport

Apart from the above command, run gradle task also compiles the report files as part of running the application. compileJasperReport compiles the jrxml files found under Template folder and move the compiled file under folder Resources.

Report End point
Under java folder listed above, we can find all the backend resources for fetching and transforming report data from db. Under this folder there a number of other dedicated folder that their name can give some meaning. Amount all the folder there is one called controller which we can find a REST controller for the starting point for most report data.
For Consumption report, the report will fetch data from org.openlmis.report.controller.GeoDataController. We can see lots of REST resource in the class but for our report we will focus on getReportingRateReport method. All export format of the report will call this resource via URL {_}http://ip:port_/gis/reporting-rate.json with parameter query string.


Call hierarchy
org.openlmis.report.controller.GeoDataController#getReportingRateReport
> org.openlmis.report.mapper.lookup.GeographicZoneReportMapper#getGeoReportingRate

How is the HTML report organised
The HTML report is designed with HTML and AngularJS. Basically all report format PDF, XLS and HTML use the same java REST endpoint to fetch a report data from the db. All HTML reports gets loaded by the following file modules/openlmis-web/src/main/webapp/public/pages/reports/main/index.html.

All report related resources like js and css files and also html partial pages will be loaded in to the above file using AngularJS routing feature.

When one browse to the consumption report URL on the site, AngularJs will load index.html page and render
modules/openlmis-web/src/main/webapp/public/pages/reports/maps/partials/reporting-rate.html partial page in to it.

If one opens and see the reporting-rate.html file its possible to see HTML section that will render the list of report filters that we saw on the screenshot. For example, to add a program filter in reporting-rate.html we can add with the following code block.

<program-filter class="form-cell horizontalFilters" required="true"></program-filter>

The above code renders the program report filter in the report page. Each report filters are composed as angular directive. One can find the list of filter directive definitions at

modules/openlmis-web/src/main/webapp/public/js/reports/shared/directives/filters.js

Each report filter that one can see in the report can be found in filters.js. Those directives calls a backend service to populate the filter control with data. The angular services that will be called by each filters and reports are found in

modules/openlmis-web/src/main/webapp/public/js/shared/services/extension-services.js

Once the report get loaded and when the report viewer selected data on all required filters, $scope.OnFilterChanged method will be called in the following js file

modules/openlmis-web/src/main/webapp/public/js/reports/maps/controller/reporting-rate-controller.js

With in this AngularJS controller method, the java REST endpoint will be called to fetch the report data.
On the report page, there are two buttons at the top of the page for exporting the report on other formats. If a user wants to export the current HTML report to PDF, he/she need to click the button with the label PDF. When that button get clicked, $scope.exportReport method of the reporting-rate-controller.js
file will be called.