The Reports Hub v2 module (Version 2.0) is a critical component of the Nimbly Audit Admin application, designed to provide users with a centralized and efficient way to generate, manage, and download various types of reports. Its primary purpose is to offer insights derived from the data collected within the platform, enabling users to track progress, identify trends, and make data-driven decisions.
Main Functionalities:
Report Generation: Users can generate different kinds of reports based on a comprehensive set of filters.
Filtering: A robust filtering system allows users to specify criteria such as date ranges, report types (e.g., [Schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md), Issue, Inventory), report formats, and other entity-specific parameters.
Saved Filters: Users can save frequently used filter combinations for quick access and reuse.
Report Status Tracking: The module displays the status of requested reports (e.g., Pending, Processing, Completed, Failed), allowing users to monitor their progress.
Report Download: Successfully generated reports can be downloaded in various formats (e.g., CSV, PDF).
Report Limits: The system includes functionality to manage and display limits related to report generation.
Location within Application:
The Reports Hub v2 is accessible via the path /reportsHub. The primary UI for this module is rendered by the ReportsHub.tsx component, which is typically wrapped within a page-level component like DownloadManagerPage.tsx (Note: while /admin/downloadManager also exists and might use similar components or even AnalyticsSisenseDownloadManagerPage for certain organizations, this documentation focuses on the /reportsHub V2 implementation).
Main UI Components:
The user interface of the Reports Hub is primarily composed of three key React components:
ReportsHub (src/components/reportshub/ReportsHub.tsx): The main container component that orchestrates the layout, including the header, filter [visibility](../Settings/Data Visibility/DataVisibilityOverview.md) controls, and embeds the filter and table components.
ReportsHubFilters (src/components/reportshub/filters/ReportsHubFilters.tsx): This component houses all the filtering options, allowing users to define the parameters for the reports they wish to generate.
ReportsHubTable (src/components/reportshub/reportshubTable/ReportsHubTable.tsx): This component is responsible for displaying the list of generated or requested reports, along with their status and available actions (like download).
This document will delve into the detailed technical aspects of these functionalities and components.
2. Screens and Navigation
The Reports Hub v2 module is designed as a single-page application (SPA) experience within the broader Nimbly Audit Admin interface. Users navigate to this dedicated section to perform all report-related tasks.
2.1 Main Reports Hub Screen
Path:/reportsHub
This is the direct URL slug that loads the Reports Hub v2 interface.
Reference in code: The routing for this path is defined in src/routes/admin-routes.js:
Primary Component: While DownloadManagerPage.tsx is specified in the route, the core user interface and logic for Reports Hub v2 are encapsulated within src/components/reportshub/ReportsHub.tsx. DownloadManagerPage likely acts as a wrapper.
ReportsHub.tsx (GitHub: src/components/reportshub/ReportsHub.tsx) is responsible for the overall layout and integrates the filtering and table display functionalities.
Uses:
Unified Interface: Provides a central location for all actions related to report generation and retrieval.
Filtering Data: Users can apply various filters to narrow down the data for their reports.
Initiating Report Generation: Users can trigger the generation of new reports based on their selected criteria.
Monitoring Report Status: The screen displays a list of requested reports, showing their current status (e.g., pending, processing, completed, failed).
Downloading Reports: Users can download successfully generated reports directly from this screen.
Managing Report Settings: Access to functionalities like saved filters and report generation limits.
2.2 Modals
Several modal dialogs are used within the Reports Hub to handle specific actions or display information without navigating away from the main screen. These are typically triggered by user interactions:
Accessed via the “Reports Limit” button in the header. This modal is used to display and potentially configure limits related to report generation (e.g., maximum number of reports, date range restrictions).
Displayed when a user clicks on the “View Parameter” link for a specific report in the table. This modal shows the exact filter criteria that were used to generate that particular report.
These components ensure that related actions and information are presented contextually, enhancing the user experience by maintaining the overall screen context.
3. Core Functionality - Filtering Reports
The Reports Hub v2 offers a comprehensive set of filters to allow users to precisely define the data they need for their reports. These filters are primarily managed within the ReportsHubFilters.tsx component and its sub-components.
The filter area can be toggled (shown/hidden) using the “Filters” button in the Reports Hub header, a functionality managed by the parent ReportsHub.tsx component.
Description: A single-select dropdown allowing users to choose the main category of the report.
Options (based on ReportType enum in ReportHub.types.ts):
[SCHEDULE](../Schedule/Schedule Listing/ScheduleListingOverview.md): For reports related to scheduled audits/visits.
[INVENTORY](../Inventory/InventoryOverview.md): For reports related to inventory data.
ISSUE: For reports focused on tracked issues.
(ALL is also in the enum, but might be used internally or for broader queries rather than a direct user choice for specific report generation).
Behavior: The selection here often dictates the availability and relevance of other filters.
Date Range:
Description: A calendar input allowing users to specify a start and end date for the data to be included in the report.
Component: CalendarPresetDateRangePickerInput
Schedule Status: (Enabled when Report Type is [SCHEDULE](../Schedule/Schedule Listing/ScheduleListingOverview.md))
Description: A single-select dropdown to filter reports based on the status of schedules.
Options (based on ScheduleStatus enum): COMPLETED, MISSED.
Issue-Specific Filters: (Enabled when Report Type is ISSUE)
Issue Source: Multi-select.
Issue Status: Multi-select.
Issue Approval Status: Multi-select.
Issue Priority: Multi-select.
Issue Severity: Multi-select.
Hierarchy/Assignment Filters:
Departments: Multi-select for choosing one or more departments.
Sites: Multi-select for choosing sites. Disabled if no department is selected. Populated based on selected departments.
Users (Auditors): Multi-select for choosing users. Disabled if no department is selected. Populated based on selected departments.
Questionnaires: Multi-select for choosing questionnaires. Disabled if Report Type is [INVENTORY](../Inventory/InventoryOverview.md) or no department is selected.
Image Validation Result: (Enabled when Report Type is [SCHEDULE](../Schedule/Schedule Listing/ScheduleListingOverview.md) and Object Detection feature is available)
Description: Multi-select to filter based on the outcome of image validation.
Options (based on ImageValidationType enum): PASSED, FAILED.
3.2 Download and Report Structure Options (DownloadOptions.tsx and ReportTypes.tsx)
Description: Radio buttons allowing users to choose between a “Basic” or “Advanced” report structure. This affects how questions and answers are laid out in the report.
Basic: Includes only questions and their corresponding responses, with questions as column headers.
Advanced: Encompasses all details, including questionnaire configuration, with questions organized as rows.
This is distinct from the main “Report Type” (Schedule, Issue, etc.).
Attachments Options: (DownloadOptions.tsx)
Description: Radio buttons to include or exclude attachments in the downloaded report.
Options: With Attachments, Without Attachments.
Behavior: Can be disabled (e.g., if [Schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) Status is MISSED).
File Bundle Format: (DownloadOptions.tsx)
Description: Radio buttons to determine if the output should be individual report files or a single consolidated file.
Options: Individual, Consolidated.
3.3 Saved Filters Functionality
The Reports Hub allows users to save and reuse frequently used filter combinations.
Saving Filters:
After selecting desired filter criteria, users can click the “Save Filter” link (icon: MdOutlineBookmarkAdd).
Selecting a filter set from this dropdown applies the saved criteria to the current filter inputs.
3.4 Search Action
Button: A “Search” button (type FilledButton) is present in ReportsHubFilters.tsx.
Action:
When clicked, it triggers the fetchReportsCountAsync.request() Redux action.
This action is responsible for fetching a count of reports that match the currently applied filter criteria. This can serve as a preview of how many results the report generation might yield.
The button is disabled if a search/count is already in progress (reportsHub?.reportsCount?.isLoading) or if essential filters for the selected report type are not yet filled (controlled by isSearchable logic in ReportsHubFilters.tsx).
4. Core Functionality - Viewing and Managing Reports
Once filters are applied and a search is performed (or reports are otherwise populated), the ReportsHubTable.tsx component displays the list of report requests and generated reports.
The table provides a comprehensive overview and allows users to interact with their reports. If no reports are found matching the criteria, an empty state message with an icon (EmptyReportIcon) is displayed, prompting the user to adjust filters.
4.1 Table Columns
The table is configured with the following columns (columnConfigs in ReportsHubTable.tsx):
Report Type (type):
Displays the main type of the report (e.g., Schedule, Issue, Inventory).
Supports sorting.
Requested On (requestedOn):
Shows the date and time when the report generation was initiated.
This modal shows the detailed filter criteria and download options used for that specific report, including: Module, Report Status, Image Validation Result, Issue Source, Department, Site, Users, Questionnaire, Report Format, Report Type (Basic/Advanced), Attachments (Yes/No), and File Bundle Format.
No of Reports (reportsCount):
Indicates the number of individual reports included or generated by this request.
Supports sorting.
Reports Date (reportsDate):
Displays the date relevant to the report’s data content (e.g., the period covered by the report).
Request Status (requestStatus):
Shows the current status of the report generation request.
Download: Opens the report file (downloadURL or downloadURLPDF) in a new tab.
Preview Attachments: (Visible if isWithAttachments is true and report type is ‘report-completed’ or ‘issue’) Navigates to the Gallery page (/[gallery](../Gallery/GalleryOverview.md)) with pre-filled filters based on the report’s parameters to show associated attachments.
If status is failed:
Retry: Attempts to regenerate the report by calling fetchRetryDownloadReport service and then refreshes the table.
If status is other (e.g., queued, process):
No Option: A disabled button indicating no immediate actions are available.
4.2 Table Features
Pagination:
The table uses a Pagination component to navigate through multiple pages of reports if the total number of reports exceeds the limit per page.
The handlePageIndex function (from useReportTableSelector hook) is called when the page index changes.
Sorting:
Users can sort the table by “Report Type”, “Requested On”, and “No of Reports” columns by clicking on the column headers.
The handleSortField function (from useReportTableSelector hook) manages the sort logic. The current sort field and direction are stored in reportsHub.reportsTable.sortFields and reportsHub.reportsTable.sortDirections in the Redux state.
This modal is intended to display information about any limitations on report generation, such as maximum number of concurrent reports, daily limits, or data retention policies for generated reports. The exact details of what is displayed or configured here would require inspecting the content and logic of LimitSpecificationModal.tsx.
5. Data Flow and State Management (High-Level)
The Reports Hub v2 module leverages Redux for centralized state management, ensuring a predictable and traceable data flow. All data related to filters, report lists, loading states, and UI interactions are stored within the reportsHub slice of the Redux store.
The initialState defined in reportsHub.reducer.ts provides a blueprint of the state:
filters: An object holding the current values for all selected filter criteria (e.g., reportType, scheduleStatus, [departments](../Departments/DepartmentOverview.md), startDate, endDate, reportFormat, isWithAttachments, isConsolidated, isReportBasic).
tableType: Stores the type of table currently being viewed (e.g., from ReportType enum).
reportsTable: An object containing:
reportsList: Holds the array of report documents (docs), pagination details (limit, page, totalDocs, totalPages).
isLoading: Boolean flag indicating if the report list is currently being fetched.
limit, page: Current pagination settings.
sortDirections, sortFields: Current sorting parameters.
reportsCount: An object containing:
data: Stores the result from fetchReportsCountAsync (e.g., { reportsCount, recordsCount, attachmentsCount, isExist }).
isLoading: Boolean flag for the count fetching process.
isSuccess: Boolean flag indicating if the count fetch was successful.
showLimitSpec: Boolean, controls visibility of the “Limit Specification” modal.
isNewCustomFilterModalOpen: Boolean, controls visibility of the “New Custom Filter” modal.
customFilters: An array to store saved filter configurations.
isCustomFilterLoading: Boolean, true when saved filters are being fetched.
isSavedFilter: Boolean, indicates if a saved filter is currently applied.
isFilterOpen: Boolean, controls visibility of the main filter panel.
5.2 Key Actions
Numerous actions are defined to manage this state. They can be categorized as:
Filter Update Actions (Synchronous):
setFilterDates(startDate, endDate)
setSingleSelect(key, value): For dropdowns like Report Type, Schedule Status, Report Format.
setMultiSelect(key, value): For multi-select fields like Departments, Sites, Users, etc.
setRadioValue(key, value): For radio button options like Attachments, File Bundle Format, Basic/Advanced Report Type.
setReportType(key, value): Specifically for the main report type, also resets related dependent filters.
resetFilters(): Resets all filter values to their initial state.
setCustomFilter(customFilter): Applies a saved filter set.
Asynchronous Data Fetching Actions (using createAsyncAction from typesafe-actions):
On success, dispatches FETCH_REPORTS_FILTERS_SUCCESS with the list of saved filters.
On failure, dispatches FETCH_REPORTS_FILTERS_FAILURE.
UI State Actions:
setLimitSpec(boolean): Toggles the limit specification modal.
setCustomFilterModal(boolean): Toggles the new custom filter modal.
setIsFilterOpen(boolean): Toggles the main filter panel visibility.
setPageIndex(page) & setPageSort(direction, field): For table pagination and sorting.
5.3 High-Level Data Flow Example (Generating a Report)
sequenceDiagram
actor User
participant FiltersUI as ReportsHubFilters
participant ReduxActions as Redux Actions
participant ReduxStore as Redux Store
participant APIService as API Service
participant TableUI as ReportsHubTable
User->>FiltersUI: Selects various filter options (date, type, etc.)
FiltersUI->>ReduxActions: dispatch(setSingleSelect(...))
ReduxActions->>ReduxStore: Update filter values in state
User->>FiltersUI: Clicks "Search" button
FiltersUI->>ReduxActions: dispatch(fetchReportsCountAsync.request())
ReduxActions->>APIService: Request report count
APIService-->>ReduxActions: Respond with count details
ReduxActions->>ReduxStore: dispatch(fetchReportsCountAsync.success(data))
ReduxStore-->>FiltersUI: Updated state (report count displayed)
User->>FiltersUI: Clicks "Download" (or similar, assuming this triggers main report gen)
FiltersUI->>ReduxActions: dispatch(fetchReportsHubTableAsync.request()) (or a specific download action)
ReduxActions->>APIService: Request report generation / list
note right of APIService: API processes, generates report, stores it, returns status/list.
APIService-->>ReduxActions: Respond with report list/status
ReduxActions->>ReduxStore: dispatch(fetchReportsHubTableAsync.success(data))
ReduxStore-->>TableUI: Updated state (report list, statuses)
TableUI->>User: Displays updated report list and statuses.
User->>TableUI: Clicks "Download" action on a completed report
TableUI->>APIService: Request direct download URL or file
APIService-->>User: Delivers report file
This flow illustrates how user interactions trigger actions, which modify the Redux store. Components subscribe to store updates and re-render accordingly, providing a reactive user experience. Asynchronous operations like API calls are handled typically by middleware (e.g., Redux Saga or Thunk, though not explicitly detailed here, createAsyncAction implies such a setup) which dispatches further actions upon completion or failure.
6. API Endpoints
The Reports Hub v2 module interacts with several backend APIs to fetch data, initiate report generation, and manage custom filters. These are primarily called from src/services/reportshub.service.ts.
The base URLs referenced are appengineURL (public-facing) and appengineInternalURL (internal services). Authentication is handled via Firebase tokens, sometimes exchanged for an internal token.
deleteSavedFilter service (e.g., from UI managing saved filters like SavedFiltersDropdown.tsx)
Note on Endpoints:
The specific endpoint for fetchReportCount, fetchDownloadReport, and fetchRetryDownloadReport is dynamically determined based on the selected filters.reportType (Schedule, Issue, Inventory) and, in the case of Schedule, filters.scheduleStatus (Completed, Missed).
Authentication for these APIs is handled by passing a Firebase Auth token in the Authorization header. For some internal endpoints, this Firebase token might be exchanged for an internal service token.
Error handling typically involves showing a toast notification to the user.
7. Key Components and Their Roles (Detailed)
This section provides a more in-depth look at the primary React components that make up the Reports Hub v2 module. Understanding the role of each component is key to understanding the overall architecture and data flow.
Overall Layout Orchestration: This component serves as the top-level container for the Reports Hub UI. It defines the main structure, including a header, the filter area, and the space for the reports table.
Header Management: Renders the “Reports” title, a “Filters” toggle button (icon MdFilterList), and a “Reports Limit” button.
Filter Panel Visibility: Manages the isFilterOpen state (from Redux store, via useSelector) to conditionally render the ReportsHubFilters component. The handleFilterToggle function dispatches the setIsFilterOpen action.
“Reports Limit” Modal Trigger: The “Reports Limit” button’s onClick handler (handleLimitSpec from useReportFilterSelector hook, which likely dispatches setLimitSpec(true)) is responsible for triggering the display of the LimitSpecificationModal.
Integration of Core Sub-components:
Embeds ReportsHubFilters when isFilterOpen is true.
Always embeds ReportsHubTable, which is responsible for displaying the actual report data.
Key State/Props Handled (Managed via Redux and Hooks):
isFilterOpen (from Redux state.reportsHub): Controls the visibility of the filter section.
handleLimitSpec (from useReportFilterSelector hook): Function to open the “Reports Limit” modal.
handleFilterToggle (local function): Dispatches Redux action to toggle filter visibility.
Interactions:
Acts as a parent component to ReportsHubFilters and ReportsHubTable.
Relies on Redux for state related to filter visibility (isFilterOpen) and modal display triggers.
Uses useReportFilterSelector hook to access actions/selectors related to filter operations (like opening the limit modal).
Central Hub for Filtering: This component acts as the main container for all user-facing filter controls.
Integration of Filter Sub-Components: It embeds and organizes various specific filter components:
GeneralFilters.tsx: For core report criteria like report type, date ranges, and entity selections.
DownloadOptions.tsx: For output format, attachment preferences, and file bundling.
Saved Filters Management:
Includes the SavedFiltersDropdown.tsx component to allow users to select previously saved filter configurations.
Provides a “Save Filter” link (MdOutlineBookmarkAdd icon) that triggers the handleNewFilterModal(true) function (from useReportFilterSelector hook), which in turn opens the NewCustomFilterModal.tsx.
Search Functionality:
Renders the “Search” button.
The button’s onClick handler dispatches the fetchReportsCountAsync.request() Redux action to get a count of matching reports.
The button’s disabled state is managed based on reportsHub?.reportsCount?.isLoading (to prevent multiple clicks while loading) and an isSearchable memoized value (which checks if all required filters for the selected report type are filled).
Modal Integration:
Renders ReportDownloadModal.tsx (likely for showing progress/status of report downloads, though its direct trigger might be from initiating a download elsewhere).
Renders LimitSpecificationModal.tsx conditionally based on reportsHub?.showLimitSpec state (toggled by ReportsHub.tsx).
Renders NewCustomFilterModal.tsx (visibility controlled by reportsHub.isNewCustomFilterModalOpen state, set via handleNewFilterModal).
Key State/Props Handled (Managed via Redux and Hooks):
reportsHub.filters (from Redux state.reportsHub): Accesses the current filter values for determining isSearchable and other logic.
reportsHub.reportsCount.isLoading (from Redux): Used to disable the Search button during count fetch.
reportsHub.showLimitSpec (from Redux): Controls conditional rendering of LimitSpecificationModal.
handleNewFilterModal (from useReportFilterSelector hook): Function to open the “New Custom Filter” modal.
Interactions:
Serves as a parent to GeneralFilters, DownloadOptions, and SavedFiltersDropdown.
Dispatches Redux actions for fetching report counts.
Manages the presentation of modals related to download, limits, and saving custom filters.
Provides Core Filter Inputs: This component is responsible for rendering the primary set of filters that users interact with to define their report criteria.
Dynamic Filter Availability: Many filters within this component are conditionally enabled or disabled based on the selection made in the main “Report Type” filter. For example, “Schedule Status” is only relevant if “Report Type” is “Schedule”.
Data Population for Selects: It utilizes several custom hooks to populate the options for various dropdowns:
useReportDataOptions: Fetches and maps data for dynamic options like Departments (departmentMap, departmentOptions), Sites (siteMap, siteOptions), Users (userMap, userOptions), and Questionnaires (questionnaireMap, questionnaireOptions).
useReportConstOptions: Provides constant options for filters like Report Type (reportTypeMap), Schedule Status (scheduleStatusMap), Issue-related statuses/priorities/severities, Image Validation (imageValidationMap), and Issue Source (issueSourceMap).
State Interaction:
Reads current filter values from the Redux store (filters = useSelector((state: RootState) => state.reportsHub.filters)).
Uses action dispatching functions obtained from the useReportFilterSelector hook (handleSingleSelect, handleMutltiSelect, handleDateChange, handleReportType) to update the Redux store when filter values change.
Key Filter Components Rendered:
Report Type:SingleSelect component for selecting the main report category. Changing this (handleReportType) also resets dependent filters.
Schedule Status:SingleSelect for schedule completion status.
Issue Source:FilterField (multi-select) for the source of issues.
Image Validation Result:FilterField (multi-select) for image validation outcomes.
Departments, Sites, Users, Questionnaires:FilterField components (multi-select) for selecting organizational entities. Site, User, and Questionnaire selectors’ options are often dependent on the selected Department(s).
Date Range:CalendarPresetDateRangePickerInput for selecting start and end dates.
Interactions:
Acts as a child of ReportsHubFilters.tsx.
Heavily interacts with the Redux store via selectors (to get current filter values and feature flags like objectDetectionFeatureAccess) and actions (to update filter values).
Relies on useReportDataOptions and useReportConstOptions hooks to provide necessary data for dropdowns.
Defines Report Layout Style: This component provides radio button options for users to choose between a “Basic” or “Advanced” report structures. This selection influences how questions and answers are organized in the final report output, rather than selecting the main report category (like Schedule, Issue).
UI Presentation:
Displays a “Report Type” sub-header with a tooltip explaining the difference between Basic and Advanced reports.
Uses custom-styled RadioContainer and Radio components for the selection.
State Interaction:
Reads the current selection from filters.isReportBasic in the Redux store.
Uses the handleRadioValue function (from useReportFilterSelector hook) to dispatch an action that updates filters.isReportBasic in the Redux store when a user makes a selection.
Key Filter Components Rendered:
Two Radio buttons:
“Basic”: Sets isReportBasic to true.
“Advanced”: Sets isReportBasic to false.
Interactions:
Typically embedded within DownloadOptions.tsx.
Interacts with the Redux store to get and set the isReportBasic filter value.
Controls Output File Settings: This component groups options related to the final output format and packaging of the report.
Integration of Report Structure Selection: It embeds the ReportTypes.tsx component (for Basic/Advanced selection).
State Interaction:
Reads current filter values from filters in the Redux store (e.g., filters.reportFormat, filters.isWithAttachments, filters.isConsolidated).
Uses handleSingleSelect and handleRadioValue functions (from useReportFilterSelector hook) to update these values in Redux.
Uses reportFormatMap (from useReportConstOptions hook) to populate the “Report Format” dropdown.
Key Filter Components Rendered:
Report Format:SingleSelect dropdown for choosing the file type (e.g., PDF, Excel from ReportFormat enum).
ReportTypes.tsx Component: Embedded for Basic/Advanced report structure selection (see 7.4).
Attachments Options: Radio buttons (With Attachments / Without Attachments) for filters.isWithAttachments. This can be disabled based on other filter conditions (e.g., filters.scheduleStatus === ScheduleStatus.MISSED).
File Bundle Format: Radio buttons (Individual / Consolidated) for filters.isConsolidated.
Interactions:
Acts as a child of ReportsHubFilters.tsx.
Interacts with the Redux store for managing filter states related to download preferences.
Displays Report Requests: This is the primary component for rendering the list of generated and pending reports in a tabular format.
Column Configuration: Defines the table structure, including columns for Report Type, Requested On, File Parameters, No of Reports, Reports Date, Request Status, and Action. (Detailed in Section 4.1).
Custom Cell Rendering: Utilizes custom rendering functions for several columns:
customRequestedOnCell: Formats the timestamp and includes timezone.
customViewParameterCell: Renders a “View Parameter” link which, when clicked, updates local component state (filterParams) to trigger the ViewParamsModal.
CustomRequestStatusCell: Renders the status with appropriate styling.
CustomActionCell: Renders a dropdown with actions like Download or Retry.
Data Fetching and Display:
Uses the useInitialFetch hook to trigger an initial data load.
Relies on the useReportTableSelector hook to get mappedTableData (processed data for the table) and handlers for pagination (handlePageIndex) and sorting (handleSortField).
Pagination: Integrates a Pagination component, using reportsHub.reportsTable.reportsList from Redux for total items, current page, etc.
Sorting: Allows sorting by Report Type, Requested On, and No of Reports. Sort state (sortFields, sortDirections) is managed in Redux.
Empty State: Displays an “No Report Yet” message with an icon (EmptyReportIcon) if reportsHub.reportsTable.reportsList.docs is empty.
Modal Trigger (View Parameters): Manages the filterParams local state, which is used to conditionally render the ViewParamsModal and pass the selected row’s data to it.
Key State/Props Handled:
filterParams (local React state): Stores the row data for the report whose parameters are to be viewed in a modal.
reportsHub (from Redux state.reportsHub): Accesses reportsTable.reportsList for data and pagination, and reportsTable.sortFields/sortDirections for sorting details.
Uses CustomRequestStatusCell and CustomActionCell for specific column rendering.
Interacts heavily with Redux (via selectors) and associated custom hooks (useInitialFetch, useReportTableSelector) for data and table operations.
The ReportsType.tsx component (from ./ReportsType - note this is different from filters/ReportTypes.tsx) is rendered above the table, possibly to display some information about the currently viewed report types or overall table context.
7.7 Custom Cell - Request Status (CustomRequestStatusCell.tsx)
Displays Report Status Visually: This component is responsible for rendering the requestStatus column in the ReportsHubTable. It translates a status string (e.g., “process”, “complete”) into a styled button-like element with text and a background color corresponding to the status.
Status Mapping: The getStatusInfo(status) function within this component maps status strings to bgColor and statusText:
process→ “In Progress” (Yellow)
queued→ “Queued” (Gray)
complete→ “Completed” (Green)
failed→ “Failed” (Red)
Default → ”-” (No specific background)
Key State/Props Handled:
row.value.status (passed by Table component): The status string for the current report row.
Interactions:
Used as a customCellRender function within the columnConfigs of ReportsHubTable.tsx.
Provides Contextual Actions: Renders the “Action” column in ReportsHubTable, offering users a dropdown menu (ellipsis icon HiDotsVertical) with actions relevant to the report’s status.
Conditional Action Rendering: The available actions change based on value.status (the report’s status):
complete status:
“Download”: Opens the report file (value.downloadURL or value.downloadURLPDF).
“Preview Attachments”: (If value.isWithAttachments is true and report type is ‘report-completed’ or ‘issue’) Navigates to the Gallery page (/[gallery](../Gallery/GalleryOverview.md)) with query parameters constructed from the report’s details to display associated attachments.
failed status:
“Retry”: Calls the fetchRetryDownloadReport(row) service function to attempt report regeneration and then dispatches fetchReportsHubTableAsync.request() to refresh the table.
Other statuses (e.g., queued, process):
“No Option” (disabled button).
Navigation: Uses useHistory hook from react-router-dom for the “Preview Attachments” functionality.
Service Calls: Directly invokes fetchRetryDownloadReport service for the retry action.
Redux Dispatch: Dispatches fetchReportsHubTableAsync.request() action via useDispatch hook to refresh table data after a retry.
Key State/Props Handled:
row.value (passed by Table component): An object containing all data for the current report row, including status, downloadURL, downloadURLPDF, reportFormat, isWithAttachments, [sites](../Sites/SitesOverview.md), [departments](../Departments/DepartmentOverview.md), auditors, [questionnaires](../Questionnaires/QuestionnairesOverview.md), startDate, endDate, dJobID.
Interactions:
Used as a customCellRender function within the columnConfigs of ReportsHubTable.tsx.
Interacts with reportshub.service.ts (for retrying downloads).
Displays Report Generation Details: This modal is shown when a user clicks the “View Parameter” link in the ReportsHubTable. Its purpose is to provide a read-only summary of all the filter criteria and download options that were used to generate that specific report instance.
Data Transformation for Display:
It receives rowData (the data for the selected report) as a prop.
It uses selectors (useSelector) to get current mappings for IDs to names (e.g., users, [sites](../Sites/SitesOverview.md), [questionnaires](../Questionnaires/QuestionnairesOverview.md) from Redux state).
It employs helper functions like getStatusInfo (from CustomRequestStatusCell), mapValuesToOptions (to convert stored IDs to human-readable labels using maps from useReportConstOptions and useDepartmentOptions), getSiteName, getUserName, getQuesName to format the data for display.
Structure: The modal displays information in sections:
Download Options: Report Format, Report Type (Basic/Advanced - from rowData.value.reportTypeBasicAdv), Attachments (Yes/No), File Bundle Format (Consolidated/Individual).
Key State/Props Handled:
rowData (prop): The complete data object for the report whose parameters are being viewed.
handleClear (prop): A function passed from ReportsHubTable to close the modal (by setting filterParams to null in the parent).
Accesses various parts of Redux state (users, [sites](../Sites/SitesOverview.md), questionnaireByProps.data, featureAccess, departmentMap, etc.) to enrich the display of IDs with names.
Interactions:
Rendered conditionally by ReportsHubTable.tsx based on the filterParams local state of the table component.
Purely a display component once shown; its primary interaction is being closed.
Provides Feedback on Download Initiation: This modal likely appears after a user clicks a final “Download” or “Generate Report” button (e.g., after the “Search” for counts and confirmation).
Shows Report Request Status: It is expected to display information about the report generation request, such as:
Confirmation that the request has been submitted.
The number of reports being generated (reportsCount?.data?.reportsCount).
The number of records included (reportsCount?.data?.recordsCount).
Actions:
“Go to Reports Hub Table”: Navigates the user to the main reports table, likely to see the status of their request.
“Download More Reports”: Closes the modal and allows the user to start a new report request.
Triggering Download Service: This modal, or the action that opens it, is responsible for calling the fetchDownloadReport() service from reportshub.service.ts to actually initiate the backend report generation process. It also dispatches resetReportCount() to clear the previous search counts and fetchReportsHubTableAsync.request() to refresh the table data.
Key State/Props Handled:
reportsCount.data (from Redux state.reportsHub): Used to display the count of reports and records.
showReportDownloadModal (from Redux state.reportsHub): Controls the visibility of this modal.
handleReportDownloadModal (from useReportFilterSelector hook): Function to close the modal.
handleGotoReportsHubTable (from useReportFilterSelector hook): Function to navigate to the reports table.
Interactions:
Rendered conditionally by ReportsHubFilters.tsx (or potentially another component that triggers report generation).
Dispatches Redux actions to reset counts, refresh the table, and control its own visibility.
Initiates the actual report generation via a service call.
Displays Report Generation Limits: Shown when the “Reports Limit” button in ReportsHub.tsx is clicked.
Informs User of Constraints: This modal’s primary role is to inform the user about any configured limitations on report generation (e.g., maximum reports per day, concurrent report limits, data range restrictions). The exact content is based on configuration and LimitContent.tsx.
Content: Dynamically renders content based on LimitContent.tsx which might fetch or display predefined limit information.
Saves Current Filter Set: Appears when the user clicks the “Save Filter” link in ReportsHubFilters.tsx.
Prompts for Filter Name: Allows the user to enter a name for their current filter configuration.
Handles Save Operation:
On clicking “Save”, it constructs a payload with the filterName, the current filters from Redux state, and module: "reportshub".
Calls the saveReportsCustomFilter service to persist the filter.
On success, it dispatches fetchReportsFilterAsync.request() to refresh the list of saved filters and closes the modal using handleNewFilterModal(false).
Displays error toasts on failure.
Key State/Props Handled:
filterName (local React state): Stores the name entered by the user.
Lists and Applies Saved Filters: Provides a dropdown menu for users to select and apply previously saved custom filters.
Fetches Saved Filters: Dispatches fetchReportsFilterAsync.request() on component mount (inside useEffect) to load the list of saved filters.
Handles Filter Selection: When a user selects a filter from the dropdown, it dispatches the setCustomFilter(selectedFilter.filters) action to apply the chosen filter criteria to the main filter state and setIsSavedFilter(true).
Handles Filter Deletion:
Provides a delete icon next to each saved filter.
Clicking delete calls the deleteSavedFilter service.
On successful deletion, it dispatches fetchReportsFilterAsync.request() to refresh the list.
Clearing Applied Saved Filter: Offers an option (e.g., “All Reports” or similar) to clear the currently applied saved filter, which dispatches resetFilters() and setIsSavedFilter(false).
Key State/Props Handled:
customFilters (from Redux state.reportsHub): The list of saved filters to display.
isCustomFilterLoading (from Redux): To show a loading state.
isSavedFilter (from Redux): To indicate if a saved filter is currently active.
filters (from Redux): The current main filter state.
Interactions:
Embedded within ReportsHubFilters.tsx.
Interacts heavily with Redux for fetching, applying, and managing the state of saved filters.
Interacts with reportshub.service.ts to delete saved filters.
[end of reportshub.md]
7.14 Key Hooks
Several custom React hooks are central to the functioning of the Reports Hub, encapsulating reusable logic for data selection, manipulation, and side effects.
Purpose: This hook is primarily used within filter-related components. It provides memoized selectors to access filter state from Redux and action dispatchers bound to specific filter update logic (e.g., handleSingleSelect, handleMutltiSelect, handleDateChange, handleReportType, handleRadioValue, handleLimitSpec, handleNewFilterModal, handleReportDownloadModal, handleGotoReportsHubTable). It centralizes how components interact with the filter part of the Redux store.
Purpose: Used by ReportsHubTable.tsx, this hook provides memoized data derived from the Redux state for table display (mappedTableData). It also supplies event handlers for table interactions like pagination (handlePageIndex) and sorting (handleSortField), which typically dispatch Redux actions to update table state.
Purpose: This hook is called in ReportsHubTable.tsx. It’s designed to trigger an initial data fetch (likely fetchReportsHubTableAsync.request()) when the component mounts or when key dependencies (like page index, sort parameters, or main table type filter) change, ensuring the table displays relevant data.
Purpose: Used in GeneralFilters.tsx, this hook is responsible for fetching or deriving data needed to populate dynamic filter dropdowns, such as lists of departments, sites, users (auditors), and questionnaires. It often transforms raw data into a format suitable for select components (BaseSelectOptionType).
Purpose: Also used in GeneralFilters.tsx and other filter components, this hook provides predefined, constant options for various filters. This includes mappings for report types, schedule statuses, issue statuses, priorities, severities, report formats, and image validation results, converting enum-like structures or constant objects into BaseSelectOptionType lists for dropdowns.
These hooks play a vital role in separating concerns, improving performance through memoization, and making components cleaner by abstracting away complex state access or data transformation logic.
[end of reportshub.md]
8. External Packages/Libraries
The Reports Hub v2 module leverages several external npm packages to provide its functionality, ranging from UI rendering and state management to utility functions. Below is a list of key libraries and their primary uses within this module.
Package Name
Purpose in Reports Hub
Example Usage File(s)
react
Core library for building the user interface components.
All .tsx files (e.g., ReportsHub.tsx, ReportsHubFilters.tsx)
react-redux
Official React bindings for Redux, used for connecting components to the Redux store (useSelector, useDispatch).
Most components interacting with global state (e.g., ReportsHub.tsx, GeneralFilters.tsx, ReportsHubTable.tsx)
redux
(Implicit via react-redux & typesafe-actions) Core state management library.
reportsHub.reducer.ts, reportsHub.action.ts
typesafe-actions
Simplifies writing type-safe Redux actions and reducers.
reportsHub.action.ts, reportsHub.reducer.ts
react-i18next
Internationalization library for translating UI text (useTranslation hook).
CustomActionCell.tsx (for gallery navigation), reportshub.service.ts (for API query params)
react-toastify
Library for displaying toast notifications (e.g., for success or error messages from API calls).
reportshub.service.ts
uuid
For generating universally unique identifiers (UUIDs).
reportshub.service.ts (for dJobID in report requests)
components/global/*
While not external, these are shared internal components like Table, Pagination, Select, Tooltip, Modal etc. that are extensively used.
Various ReportsHub components.
This list is not exhaustive of every single dependency but highlights the major ones that directly contribute to the features and functionality of the Reports Hub module.
[end of reportshub.md]
9. Visualizations (Mermaid Diagrams)
Mermaid diagrams are used here to visualize component relationships and common interaction flows within the Reports Hub module.
9.1 Component Diagram
This diagram illustrates the primary UI components and their hierarchical relationships.
graph TD
A[ReportsHub /reportsHub] --> B(ReportsHub.tsx);
B --> B1[ReportsHubHeader];
B --> C{isFilterOpen?};
C -- Yes --> D[ReportsHubFilters.tsx];
C -- No --> E_Hidden[(Filters Hidden)];
B --> F[ReportsHubTable.tsx];
D --> D1[GeneralFilters.tsx];
D --> D2[DownloadOptions.tsx];
D2 --> D2a[filters/ReportTypes.tsx Basic-Advanced];
D --> D3[SavedFiltersDropdown.tsx];
D --> D4[Search Button];
D --> D5[Save Filter Link];
F --> F1[Table Component];
F --> F2[Pagination Component];
F --> F3[ViewParamsModal.tsx];
F --> F4[CustomRequestStatusCell.tsx];
F --> F5[CustomActionCell.tsx];
F --> F6[reportshubTable/ReportsType.tsx Display];
subgraph Modals
M1[ReportDownloadModal.tsx]
M2[LimitSpecificationModal.tsx]
M3[NewCustomFilterModal.tsx]
M4[ViewParamsModal.tsx]
end
D --- M1;
D --- M2;
D --- M3;
F --- M4;
style B fill:#f9f,stroke:#333,stroke-width:2px,color:#000
style D fill:#ccf,stroke:#333,stroke-width:2px,color:#000
style F fill:#cfc,stroke:#333,stroke-width:2px,color:#000
style Modals fill:#eee,stroke:#333,stroke-width:2px,color:#000
Description of Component Diagram:
The main ReportsHub.tsx component contains the header, conditionally renders ReportsHubFilters.tsx, and always renders ReportsHubTable.tsx.
ReportsHubFilters.tsx groups various filter input components like GeneralFilters.tsx, DownloadOptions.tsx (which itself includes filters/ReportTypes.tsx), and controls for saved filters and search.
ReportsHubTable.tsx uses a generic Table and Pagination component and employs custom cell renderers and the ViewParamsModal.
Several modals (ReportDownloadModal, LimitSpecificationModal, NewCustomFilterModal) are primarily associated with interactions within ReportsHubFilters, while ViewParamsModal is triggered from ReportsHubTable.
9.2 Sequence Diagram: User Applies Filters, Searches, and Initiates Download
This diagram shows a typical user flow from selecting filters to initiating a report download.
sequenceDiagram
actor User
participant RHFilters as ReportsHubFilters.tsx
participant RHUI as ReportsHub.tsx
participant Redux as Redux Store / Actions
participant APIService as reportshub.service.ts
participant RHTable as ReportsHubTable.tsx
User->>RHFilters: Modifies filter inputs (date, type, etc.)
RHFilters->>Redux: dispatch(setFilterAction(newValue))
Redux-->>RHFilters: Store updated, UI reflects changes
User->>RHFilters: Clicks 'Search' button
RHFilters->>Redux: dispatch(fetchReportsCountAsync.request())
Redux->>APIService: fetchReportCount()
APIService-->>Redux: Report count details
Redux->>Redux: dispatch(fetchReportsCountAsync.success(data))
Redux-->>RHFilters: Store updated with counts (e.g., displayed to user)
User->>RHFilters: Clicks 'Download Report' button (or similar action in ReportDownloadModal)
RHFilters->>Redux: dispatch(showReportDownloadModal(true))
Redux-->>RHUI: ReportDownloadModal becomes visible
Note over User, RHUI: User confirms download in ReportDownloadModal
RHUI->>APIService: fetchDownloadReport() with current filters
APIService-->>Redux: (Indirectly) Report generation acknowledged / queued
APIService-->>RHUI: Toast message ('Report request sent successfully')
RHUI->>Redux: dispatch(fetchReportsHubTableAsync.request())
Redux->>APIService: fetchReportList()
APIService-->>Redux: Updated list of reports (new request is 'Queued' or 'Processing')
Redux-->>RHTable: Store updated, table refreshes to show new request
loop Periodically Check Status
RHTable->>Redux: dispatch(fetchReportsHubTableAsync.request())
Redux->>APIService: fetchReportList()
APIService-->>Redux: Updated list with current statuses
Redux-->>RHTable: Table updates statuses (e.g., 'Processing' -> 'Completed')
end
User->>RHTable: Sees 'Completed' status, clicks 'Download' action
RHTable->>window: window.open(report.downloadURL)
Description of Sequence Diagram:
User interacts with ReportsHubFilters.tsx, changing filter values, which dispatch actions to update the Redux store.
User clicks “Search”. ReportsHubFilters.tsx dispatches fetchReportsCountAsync.request(). The service fetches counts, and the store is updated.
User decides to proceed with downloading/generating the report (this might be via a button in ReportsHubFilters or after confirming in ReportDownloadModal).
The fetchDownloadReport() service is called. A success toast is shown.
An action fetchReportsHubTableAsync.request() is dispatched to refresh the main reports table, which will now show the newly requested report, typically in a “Queued” or “Processing” state.
The table might periodically refresh (or be manually refreshed) to update statuses.
Once a report is “Completed”, the user can click a download link in the ReportsHubTable.tsx (via CustomActionCell.tsx) to open the actual file.
These diagrams provide a visual summary of the module’s structure and key operational flows.
[end of reportshub.md]