> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/reporting-and-data/reporting-web-application.md).

# Reporting Web Application

The reporting web application is a browser-based tool for report administrators and facility report administrators. It lets you pick a region and site, view reports on screen, narrow them with filters, and download them as Excel files. Administrators can also assign reporting roles, site access and BI dashboard access to users.

## Signing in

The reporting web application has no sign-in form of its own. It uses the same account as the main SPICE web application.

1. Open the reporting web application address given to you by your administrator.
2. If you are not signed in, you are redirected to the main SPICE web application to sign in. After signing in you are returned to the reporting application.
3. Your name and role are shown at the top right. Select your name to open the menu and choose **Logout** when you are finished.

Your account needs a reporting role (see [Roles and access](#roles-and-access)). If you open a page your role cannot use, you are taken back to your home page.

## Roles and access

| Role                          | Starting page                                                                                | Can open                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Report super administrator    | List of regions                                                                              | Sites and reports of any region they choose                            |
| Report administrator          | List of regions, or straight to the region's reports, depending on how the account is scoped | Region-wide reports, all sites in the region, user and role assignment |
| Facility report administrator | List of sites they are assigned to                                                           | Site reports and, where configured, monthly submission                 |
| Facility report user          | List of sites they are assigned to                                                           | Facility summary reports                                               |

What a user sees is limited by role: only the regions and sites they are allowed to work with appear in the lists.

## Navigating by region and site

1. **Choose a region.** Users with access to several regions start on a page of region cards. Select a card to continue. Use **Load More** if the list is long.
2. **Choose a site.** The **Sites** page lists the sites in the region with name, city or town, and phone number. Use the search box to find a site by name, then select the view icon (**Site View**) on its row.
3. **Choose a report.** The report list for the site shows one card per report type. Select a card to open it.

The breadcrumb at the top shows where you are and lets you step back to the region or site list.

For community-based programmes, the report list is shown at region level instead of site level (see [Community programme reports](#community-programme-reports)). In those programmes you may be asked to choose a community health worker when opening a site.

## Report types

Which cards you see depends on the programme type configured for your region.

### Facility-based programme reports

| Report                                                       | What it shows                                                                                                                                                                | Filters                                                    |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Screened Patients                                            | People screened at the site: name, gender, phone number, confirmed diagnosis, whether referred for further assessment, and date created.                                     | Start and end date, gender, diagnosis, referred assessment |
| Enrolled Patients                                            | People enrolled in care: name, gender, phone number, provisional and confirmed diagnosis, and date created.                                                                  | Start and end date, gender, diagnosis                      |
| Assessment Report                                            | People who have had assessments: diagnosis, last and next blood pressure and blood glucose assessment dates, and assessment category.                                        | Start and end date, gender, diagnosis                      |
| User Performance                                             | Counts of activity per staff member: screening, enrolment, blood pressure and blood glucose assessments, medical review, nutrition and lifestyle, lab test and prescription. | Start and end date, user role                              |
| Prescription Medication                                      | Monthly prescription report, listed by year and month.                                                                                                                       | Year and month                                             |
| Patient Status Report                                        | Monthly report of patient status, listed by year and month.                                                                                                                  | Year and month                                             |
| Daily activity register, permanent register, monthly summary | Standard register and summary reports prepared per site as Excel files.                                                                                                      | Date (daily) or year and month                             |

The standard register and monthly summary cards appear only for regions where the programme has switched on standard-format reporting. See [Exports & National Reporting](https://spice.docs.medtroniclabs.org/reporting-and-data/exports-and-national-reporting.md).

### Community programme reports

For community-based programmes the report list is shown at region level and includes:

| Report                         | What it shows                                                                                                                                                              | Filters                                                   |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Supervisor report              | Services delivered by each community-health supervisor in the selected period (for example antenatal, postnatal and non-communicable disease services, and registrations). | Start and end date, geographic area                       |
| Community health worker report | Services delivered by each community health worker, with the name of the supervisor they work under.                                                                       | Start and end date, geographic area, user role, user name |
| Coverage (restricted)          | Per-supervisor coverage: number of active community health workers, villages, households, members and services, with a detail view that breaks services down by type.      | Start and end date, search                                |

Which of these appear for a user is controlled by report privileges on their account. The coverage report is available only to users with an additional elevated platform role.

## Filtering and searching

Patient-list reports (Screened, Enrolled, Assessment, User Performance) show a **Filters** panel on the left.

* **Start Date** and **End Date**: both must be set to apply a date filter. The end date cannot be before the start date.
* **Gender**: tick one or both options.
* **Diagnosis**: tick one or more diagnosis options to limit the list.
* **Assessment**: tick **Referred Assessment** to list only people referred for further assessment.
* **User Roles** (User Performance only): tick the staff roles to include.
* **Reset** (the reset icon at the top of the panel) clears all filters.

The list refreshes as soon as you change a filter, and shows ten rows per page. The region, site and user lists have a search box above the table.

Monthly reports (Prescription Medication, Patient Status, monthly summary) use a **By Year** and **By Month** selector, and the daily register uses **By Date**. Without a selection, the most recent months available are listed.

## Viewing and downloading reports

### Patient-list reports

1. Apply any filters you need.
2. Select **Export**. The button is disabled when the list is empty.
3. An Excel (`.xlsx`) file containing everything that matches your current filters, not only the visible page, is downloaded. A **Report downloaded successfully** message confirms it.

### Monthly and daily reports

Each row in the list (one per month or day) has two icons:

* **View** opens the report on screen in a spreadsheet viewer.
* **Download** saves the report as an Excel file named after the site, the report and the period.

If no report exists for the chosen period you see a *Report not found* message. Some reports are prepared by scheduled jobs, so the latest period may not be available until the next run.

### Community reports

Choose the date range and geographic filters, then select **Export** to download an Excel file named with the report name and date range.

## Managing users, roles and sites

Users with the report administrator role can assign reporting roles and site access to other users on the **Users** page.

1. Select the region in the drop-down at the top of the table.
2. Search for the person by email, or page through the list. The table shows name, email and role level.
3. Select the role icon on the person's row (tooltip **Assign Role** or **Manage Role**).
4. In the dialog, choose between role-wide access and **Site Specific Access**. For site-specific access, choose the sites the user can report on; one site is marked as their primary site.
5. Select **Assign** (or **Remove** to withdraw a role) and confirm. A **User role updated successfully** message appears.

## BI dashboard access

If your deployment includes the optional analytics stack (see [Data Pipeline & Analytics](https://spice.docs.medtroniclabs.org/reporting-and-data/data-pipeline-and-analytics.md)), report administrators can grant a user access to the BI dashboards from the same **Users** page.

1. Find the user as described above.
2. Select the dashboard icon on their row.
3. Tick the dashboard set(s) the person should see. There are two sets: a main programme dashboard, and a second set that includes the first. Selecting the second automatically selects the first.
4. Select **Assign** (or **Save** when editing existing access).

The reporting web application only manages who has access. The dashboards themselves open in the BI dashboard tool, not inside this application.

## Duplicate patient review

A duplicate-profile review screen is not yet available in the reporting web application. Duplicate detection and merging are handled by separate batch jobs; see [Exports & National Reporting](https://spice.docs.medtroniclabs.org/reporting-and-data/exports-and-national-reporting.md#duplicate-patient-jobs).

## About page

The application has a public **Info** page that lists the build version of the reporting web application and its reporting backend. It is intended for support staff checking which version is deployed.
