====== Reports Page User Guide ======

===== Overview =====

The Reports Page is a comprehensive tool that allows you to create, manage, and schedule automated reports for monitoring your devices and sensors. This guide will walk you through the process of creating different types of reports and managing them effectively.

===== Getting Started =====

To access the Reports Page:
1. Navigate to the Reports section from the main menu
2. You will see a list of existing reports with their configurations
3. Click the **Create New Report** button to start creating a new report

===== Report Types =====

There are three types of reports available:
{{ :user_manual:reports:screenshot_337_.png?800 |}}
==== 1. Standard Report ====

**Description:** A visually-focused report that includes device images and sensor graphs.

**Best for:**
  * Monitoring device status with visual representations
  * Sharing reports with non-technical stakeholders
  * Quick visual overview of device performance

**Features:**
  * Device Images - Display device photos for identification
  * Sensor Graphs - Visual charts showing sensor data trends
  * Multiple Devices - Include multiple devices in one report
  * Automated Scheduling - Schedule recurring reports

==== 2. Advanced Report ====

**Description:** A comprehensive, data-rich report that includes detailed logs, graphs, and spreadsheet-style data.

**Best for:**
  * Detailed data analysis and troubleshooting
  * Compliance and regulatory requirements
  * In-depth review of sensor readings
  * Data export and archival

**Features:**
  * Excel Spreadsheets - Structured data tables
  * Sensor Graphs - Visual data representation
  * Data Logs - Detailed sensor readings with timestamps
  * Multiple Devices - Comprehensive multi-device reporting
  * Automated Scheduling - Schedule recurring reports

==== 3. Mapping Report ====

**Description:** A Word document-based report using pre-generated templates with customizable layouts.

**Best for:**
  * Professional documentation and presentations
  * Customizable report templates
  * Compliance documentation
  * Client reporting with branded templates

**Features:**
  * Word Documents - Professional document generation
  * Pre-Generated Templates - Ready-made report layouts
  * Customizable Mapping - Configure data placement in templates
  * Automated Scheduling - Schedule recurring reports

===== Creating a Standard Report =====

==== Step 1: Select Report Type ====

1. Click  **Create New Report**

2. Select the  **Standard Report** card

3. Click on the card to proceed to the configuration wizard

==== Step 2: Configure Report Details ====

In the **Report Details** step:

1. **Report Name** (Required)
   - Enter a descriptive name for your report (e.g., "Weekly Temperature Monitoring")
   - This name will appear in your reports list

2. **Timezone** (Required)
   - Select your preferred timezone from the dropdown
   - Default is set to Africa/Johannesburg
   - This affects how dates and times are displayed


Configure who receives the report:

1. **Add Recipients**
   - Click "Add Recipient"
   - Select users from your organization
   - You can add multiple recipients

2. **Recipient Management**
   - View all recipients in the recipients section
   - Remove recipients as needed
   - Recipients are notified via email when reports are generated

Set up automatic report generation:

1. **Enable Scheduling**
   - Toggle the schedule option if you want recurring reports
   - If disabled, report is created once

2. **Schedule Configuration**
   - **Schedule Frequency**: Select daily, weekly, monthly, or custom
   - **Time of Day**: Choose what time the report should be generated
   - **Day Selection**: 
     * For weekly: Select day(s) of the week
     * For monthly: Select day(s) of the month

3. You can add multiple schedules for the same report

4. Click **Next** when done

{{ :user_manual:reports:screenshot_338_.png? |}}

==== Step 3: Select Graphs ====

In the **Graphs** step:

1. **Add Graphs**
   - Click the "Add Graph" button
   - Select devices and sensors to include in your graphs
   - Configure the graph type (line chart, area chart, etc.)
   - Arrange multiple graphs by dragging them in order
   - You can have multiple graphs showing different sensor data

2. **Graph Configuration**
   - Each graph can display one or more sensors
   - Customize sensor colors for visual distinction
   - Reorder graphs using drag-and-drop
   - Remove graphs as needed

3. Click **Next** to proceed
{{ :user_manual:reports:screenshot_339_.png?600 |}}
{{ :user_manual:reports:screenshot_341_.png?600 |}}


===== Creating an Advanced Report =====

==== Step 1: Select Report Type ====

1. Click **Create New Report**
2. Select the **Advanced Report** card
3. Proceed to the configuration wizard

==== Step 2: Configure Report Details ====

1. **Report Name** (Required)
   - Enter a descriptive name
   - Example: "Monthly Device Performance Analysis"

2. **Timezone** (Required)
   - Select your preferred timezone
   - Affects data log timestamps
Configure report recipients:

 1. Select users to receive reports

 2. Review recipient list


Set up automatic generation (same as Standard Reports):

 1. Choose frequency and timing

 2. Add multiple schedules if needed

 3. Click **Next**

==== Step 3: Configure Data Logs ====

This step allows you to include detailed sensor data:

1. **Add Device for Logging**
   - Click "Add Device"
   - Select from available devices
   - Only devices your company has access to will be available

2. **Configure Sensors**
   - For each device, select which sensors to include
   - Select all sensors or specific ones
   - You can filter sensors for more control

3. **Reorder Data Logs**
   - Drag and drop devices to reorder them
   - Sensors within each device can also be reordered
   - Order determines how data appears in the report


==== Step 4: Add Graphs ====

Similar to Standard Reports:

1. Add one or more graphs
2. Select devices and sensors
3. Reorder graphs as needed
4. Configure graph appearance and sensor colors
5. Click **Next**


===== Creating a Mapping Report =====

==== Step 1: Select Report Type ====

1. Click **Create New Report**
2. Select the **Mapping Report** card (if you have REPORT_MAPPING_CREATE permission)
3. Proceed to the wizard

==== Step 2: Configure Report Details ====

1. **Report Name** (Required)
   - Provide a meaningful name for your mapping report

2. **Timezone** (Required)
   - Select your timezone

3. Click **Next**

==== Step 3: Select Report Template ====

1. **Choose Template**
   - Select from available pre-generated Word document templates
   - Templates define the overall structure and layout

2. **Template Preview**
   - Review template structure before proceeding
   - Ensure template matches your needs

3. Click **Next**

==== Step 4: Configure Device Mapping ====

Map your devices to template placeholders:

1. **Edit Device Mapping**
   - Associate your devices with template sections
   - Assign specific devices to specific areas in the report

2. **Map Sensors to Sections**
   - Assign sensors to data placeholders in the template
   - Control which sensor data appears where

3. Click **Next**

==== Step 5: Configure Schedule (Optional) ====

1. Set up automatic generation timing
2. Add multiple schedules if needed
3. Click **Next**

==== Step 6: Add Recipients ====

1. Select report recipients
2. Click **Finish**

===== Managing Reports =====

==== View Report List ====

The Reports Page displays all your reports in a table with:

  * **Report Name** - The name you assigned
  * **Report Type** - Standard, Advanced, or Mapping (shown as colored badges)
  * **Schedules** - Configured schedules (shows first 2, click to see all)
  * **Recipients** - Users receiving the report (shows first 2, click to see all)
  * **Actions** - Menu with available options

==== Search and Filter Reports ====

1. **Search by Name**
   - Use the search box at the top
   - Filters reports by report name

2. **Advanced Search** (if available)
   - Filter by report type
   - Filter by schedule status
   - Sort by creation date or last modified

3. **Sort Reports**
   - Click column headers to sort
   - Sort by name, type, date, etc.

==== Report Actions ====

Click the **Options Menu** (three dots) next to a report:

  * **View** - View report details and configuration
  * **Edit** - Modify report settings, add/remove devices, change recipients
  * **Duplicate** - Create a copy of this report to use as a template
  * **Download** - Download the most recent generated report
  * **Unsubscribe** - Unsubscribe yourself from report emails (available only if you're a recipient)
  * **Delete** - Remove this report permanently

==== Reorder Columns ====

1. Click the **Sort Icon** in the header
2. Drag columns to reorder their display
3. Toggle visibility of specific columns
4. Your preferences are saved

===== Report Generation =====

==== Automatic Generation ====

If you've scheduled a report:

  * Reports generate automatically at the configured time
  * Email notifications are sent to all recipients
  * Reports are archived and can be accessed anytime
  * Generation status is logged and accessible

==== Manual Generation ====

1. Go to the Reports page
2. Find the report you want to generate
3. Click **Options Menu**
4. Click **Generate Now**
5. The report will be created immediately and sent to recipients

===== Scheduling Details =====

==== Schedule Frequency Options ====

  * **Daily** - Report generates every day at specified time
  * **Weekly** - Select specific day(s) of week (e.g., Monday and Friday)
  * **Monthly** - Select specific day(s) of month (e.g., 1st and 15th)
  * **Custom** - Advanced scheduling options

==== Managing Schedules ====

To modify schedules:

1. Open the report
2. Edit the report
3. In the Schedules section:
   - Click **Edit** on a schedule to modify it
   - Click **Delete** to remove a schedule
   - Click **Add Schedule** to add another schedule
4. Save changes

===== Best Practices =====

==== Report Naming ====

Use descriptive, consistent naming conventions:
  * ✓ "Weekly Temperature Monitoring - Freezer Units"
  * ✗ "Report 1", "Data"

==== Device Selection ====

For Standard Reports:
  * Include 3-5 devices per report for optimal presentation
  * Use separate reports for different device types

For Advanced Reports:
  * Can include more devices as they're data-focused
  * Group related devices together

==== Schedule Timing ====

  * Schedule reports during off-business hours if generating large reports
  * Avoid overlapping schedules to prevent resource contention
  * Schedule weekly reports for business days, daily for critical monitoring

==== Recipients ====

  * Only add necessary recipients to reduce email volume
  * Group related recipients for specific reports
  * Regularly review and remove inactive recipients

==== Graph Configuration ====

  * Limit to 3-5 graphs per report for clarity
  * Use consistent time ranges across multiple graphs
  * Label graphs clearly with sensor information

===== Troubleshooting =====

==== Report Not Generating ====

**Issue:** Scheduled report didn't generate at expected time

**Solutions:**
  1. Verify your timezone is correct
  2. Check that at least one recipient is configured
  3. Ensure devices and sensors still exist in the system
  4. Review system logs for errors

==== Recipients Not Receiving Reports ====

**Issue:** Report recipients aren't receiving email notifications

**Solutions:**
  1. Verify recipients' email addresses are correct
  2. Check email server connectivity
  3. Confirm recipients haven't unsubscribed
  4. Verify your company's email notification settings

==== Missing Device Data ====

**Issue:** Device or sensor doesn't appear in report

**Solutions:**
  1. Verify device is assigned to your company
  2. Check device is online and transmitting data
  3. Confirm sensor exists and is configured
  4. Verify your user has permission to access the device

==== Graph Display Issues ====

**Issue:** Graphs appear empty or with no data

**Solutions:**
  1. Check selected sensors have data available
  2. Verify time range includes data
  3. Confirm device was active during reporting period
  4. Try refreshing the page and regenerating

===== Advanced Topics =====

==== Bulk Recipient Management ====

For reports with many recipients:

1. Open the report
2. Click **Edit**
3. In Recipients section, click **Bulk Add**
4. Select multiple recipients at once
5. Save changes

==== Report Playback ====

For advanced users:

  * Some reports support playback functionality
  * Click **Playback** in report options
  * View how report data changed over time

==== Custom Graph Colors ====

When configuring graphs with multiple sensors:

  * Click on a sensor in the graph configuration
  * Choose your preferred color
  * Colors help distinguish between sensors
  * Colors are consistent across regenerations

===== Tips & Tricks =====

  * **Duplicate Reports**: Use existing reports as templates by duplicating and modifying
  * **Test Schedules**: Create a test report with yourself as recipient to verify settings
  * **Export Reports**: Download reports for offline review or archival
  * **Quick Export**: Click **Download** next to any report to get most recent version
  * **Device Changes**: If you add/remove sensors, regenerate affected reports
  * **Timezone Changes**: Changing timezone only affects future reports

===== Keyboard Shortcuts ====

  * **Ctrl+N** - New Report (if focused on Reports page)
  * **Ctrl+F** - Focus search box
  * **Tab** - Navigate between form fields
  * **Enter** - Submit forms

===== Support & Help =====

For additional help:
  * Click the **Help Icon** (?) in the page header
  * Contact your system administrator
  * Check the FAQ section for common questions
  * Review system documentation for advanced configurations

===== See Also =====

  * [[user-manual:devices|Device Management Guide]]
  * [[user-manual:sensors|Sensor Configuration Guide]]
  * [[user-manual:schedules|Scheduling Overview]]
  * [[user-manual:recipients|User Management]]

----
Last Updated: 2024
For more information, visit the knowledge base or contact support.