Working with Reports in Report Manager

This guide covers all the practical tasks you can perform in the Report Manager - from creating new reports to exporting, importing, and organizing them effectively.

Creating a New Report

Creating a report from the Report Manager sets up the basic configuration. You'll then open the report builder to add widgets and customize the layout.

Step-by-Step: Create a New Report

1. From the Report Manager, click Create Report in the top-right corner
2. The Report Settings modal opens with three tabs (Data, Design, Advanced)
3. In the Data tab, fill in the required information:
   • Report Name: Enter a descriptive name (e.g., "Q1 2024 Performance")
   • Report Slug: Automatically generated from the name (e.g., "q1-2024-performance")
     • Must be unique across all reports
     • Can only contain lowercase letters, numbers, and hyphens
     • Cannot be changed after creation
   • Report Category: Choose from dropdown:
     • Sales Reports - For revenue, orders, products, customers
     • Website Traffic - For analytics, sessions, acquisitions
   • Version Number: Start with "1.0" (format: major.minor like 1.0, 1.5, 2.0)
   • Appear In Menu: Toggle ON to show in WordPress navigation (default: ON)
   • Menu Order: Enter a number to control position (0 = first, default: 0)
4. Switch to the Design tab to customize appearance:
   • Icon: Click the icon button to open the icon picker
     • Browse 60+ Material Design icons
     • Click an icon to select it
     • The icon appears in the Report Manager card and WordPress menu
   • Color Theme: Click the color button to open the color picker
     • Choose from 16 predefined colors
     • Color is applied to the icon background and accents
5. Click Create Report at the bottom of the modal
6. You'll be redirected to the report builder where you can add widgets and content

What Happens After Creation

• The report is saved to the database with your configuration
• You're automatically redirected to the report in edit mode
• The report appears in the Report Manager
• If "Appear In Menu" is ON, it appears in WordPress navigation
• The report starts empty - you'll need to add widgets using Build Mode

Tips for Creating Reports

• Use Descriptive Names: "Monthly Sales - Electronics" is better than "Report 1"
• Plan Your Menu Order: Use increments of 10 (0, 10, 20) to allow easy insertion later
• Choose the Right Category: This determines where users find your report in the menu
• Start Simple: Create the report first, add complexity later
• Use Meaningful Icons: Pick icons that represent the report's purpose

Editing Report Settings

You can edit a report's settings at any time without affecting its widgets or data. The Report Settings modal has three tabs with different configuration options.

Opening Report Settings

1. Find the report in the Report Manager
2. Click the Settings button (gear icon) on the report card
3. The Report Settings modal opens

Data Tab: Basic Settings

The Data tab lets you modify core report properties:

Editable Fields:

• Report Name: Change the display name at any time
• Report Slug: Not editable - locked after creation to prevent broken links
• Report Category: Move between Sales Reports and Website Traffic
• Version Number: Update the version (e.g., from 1.0 to 1.1 or 2.0)
• Appear In Menu: Toggle to show/hide from WordPress navigation
• Menu Order: Change the position in the navigation menu

How to Make Changes:

1. Make your desired changes in the form fields
2. Click Update Report at the bottom
3. Changes are applied immediately
4. The modal closes automatically

Design Tab: Visual Customization

The Design tab controls the report's appearance in menus and cards:

Icon Selection:

1. Click the large icon button (shows current icon)
2. A modal opens with a grid of available icons
3. Click any icon to select it
4. The preview updates immediately
5. The modal closes automatically

Color Selection:

1. Click the color swatch button (shows current color)
2. A modal opens with color options
3. Click any color to select it
4. The icon preview updates to show the new color
5. The modal closes automatically

Saving Design Changes:

• Click Update Report to apply the new icon and color
• Changes reflect immediately in the Report Manager and WordPress menu

Advanced Tab: Expert Options

The Advanced tab has two sub-tabs for power users:

JSON Configuration Sub-tab:

• Purpose: Direct editing of the complete report configuration
• Warning: Shows a clear warning that improper editing can break the report
• Features:
  • Large text area with the entire JSON configuration
  • Real-time JSON validation (shows errors if invalid)
  • Copy button to copy JSON to clipboard
  • Apply Configuration button to save changes
• When to Use:
  • Bulk editing multiple widget properties
  • Making changes not available in the UI
  • Copying configuration snippets between reports
  • Troubleshooting report issues
• Caution: Only use if you understand JSON structure. Always export a backup first.

Performance Sub-tab:

• Purpose: View detailed performance metrics for the report
• Available After: Report has been generated at least once
• Metrics Displayed:
  • Execution Time - Total time to generate the report (seconds)
  • Memory Used - Peak memory consumption (MB)
  • Memory Usage - Percentage of PHP memory limit used
  • DB Records - Total database records processed
  • Memory Limit - Configured PHP memory limit
  • Memory Start - Memory at start of execution
  • Memory Peak - Peak memory during execution
  • Entity Execution Times - Time spent on each data entity (orders, products, etc.)
• When to Use:
  • Troubleshooting slow reports
  • Optimizing report performance
  • Identifying bottlenecks
  • Determining if you need to simplify the report

Duplicating Reports

Duplicating creates an exact copy of a report including all widgets, filters, and configurations. This is one of the most useful features in the Report Manager.

How to Duplicate a Report

1. Find the report you want to duplicate in the Report Manager
2. Click the Duplicate button (copy icon) on the report card
3. The Report Settings modal opens in "duplicate mode"
4. You'll see pre-filled settings from the original report:
   • Name will have " (Copy)" added (e.g., "Sales Overview (Copy)")
   • Slug will have "-copy" added (e.g., "sales-overview-copy")
   • All other settings match the original
5. Important: You must change the slug to be unique
   • If you keep the auto-generated slug, remove " (Copy)" from the name
   • Or create a more descriptive slug for the purpose of the duplicate
   • You'll get an error if you try to use an existing slug
6. Modify other settings as needed (name, category, menu order, etc.)
7. Click Create Report
8. The duplicate is created as a new, independent report

What Gets Duplicated

Everything is copied:

• All widgets with their complete configurations
• Row and column layout structure
• Report filters and date settings
• Widget positions and sizes
• Report metadata (category, menu order, icon, color)
• All custom settings

What doesn't transfer:

• The slug (you must create a unique one)
• Live share links (the duplicate starts with no share links)
• Performance metrics (these are specific to each report)

Common Use Cases for Duplicating

1. Monthly Report Variations

• Duplicate "Monthly Performance" at the start of each month
• Rename to "Monthly Performance - March 2024"
• Adjust date filters to the specific month
• Keep the same widget structure

2. Category-Specific Reports

• Duplicate "All Products Analysis"
• Rename to "Electronics Analysis"
• Add a category filter for Electronics
• Keep the same metrics and layout

3. Testing Changes Safely

• Duplicate an important report before making major changes
• Rename the duplicate to include "Test" or "Draft"
• Make experimental changes to the duplicate
• If successful, apply changes to the original or keep both
• Delete the test version when done

4. Using Reports as Templates

• Create a well-designed report as a template
• Duplicate it whenever you need a similar report
• Modify the duplicate for the new purpose
• Saves time compared to building from scratch

5. Customizing Default Reports

• Install a default report
• Duplicate it to create your custom version
• Modify the duplicate as needed
• Hide the original default report from the menu
• Keep the original as a reference or fallback

Exporting Reports

Exporting saves a report's complete configuration as a JSON file. This is perfect for backups, sharing, or moving reports between sites.

How to Export a Report

1. Find the report in the Report Manager
2. Click the Download button (download icon) on the report card
3. Your browser downloads a file named dashboard-config-[slug].json
4. The file is saved to your default downloads folder

What's Included in the Export

The JSON file contains:

• Report metadata (name, slug, category, version, menu order)
• Design settings (icon, color)
• All widgets with complete configurations
• Row and column layout structure
• Report filters and date range settings
• All custom properties

What's NOT included:

• Cached data or query results
• Performance metrics
• Live share links
• User-specific settings
• Temporary UI state

When to Export Reports

Regular Backups:

• Export important custom reports monthly
• Store in a safe location (cloud storage, version control)
• Provides easy recovery if something goes wrong

Before Major Changes:

• Export before restructuring a report
• Export before updating plugin (for safety)
• Export before editing JSON directly
• Gives you a rollback option

Sharing with Others:

• Share custom report designs with colleagues
• Send to clients who use Alpha Insights
• Share in community forums or support tickets
• Anyone with the JSON can import and use the report

Moving Between Sites:

• Export from staging site, import to production
• Copy reports between different WooCommerce stores
• Maintain consistent reporting across multiple sites

Importing Reports

Importing lets you install reports from JSON files - either files you exported previously or reports shared by others.

How to Import a Report

1. From the Report Manager, click Import Report in the top-right
2. A file picker dialog opens
3. Select a JSON file from your computer (must be .json extension)
4. Alpha Insights validates the file:
   • Checks that it's valid JSON
   • Verifies required fields exist (dashboard_id)
   • Checks if the slug already exists
5. An import preview modal opens showing:
   • File name and size
   • Report name
   • Dashboard ID (slug)
   • Description (if present)
   • Warning if a report with this slug already exists
6. If there's a slug collision (report already exists):
   • You'll see a warning: "Report Already Exists"
   • Message explains that importing will overwrite the existing report
   • Button text changes to "Overwrite Report" instead of "Import Report"
   • Proceed only if you want to replace the existing report
7. Click Import Report (or Overwrite Report if replacing)
8. The report is installed and the page reloads
9. The new report appears in the Report Manager

Drag and Drop Import

You can also import by dragging and dropping:

1. Click Import Report to open the import modal
2. Drag a JSON file from your computer
3. Drop it on the drop zone in the modal
4. The file is processed and validated
5. Continue with the preview and import as described above

Understanding Slug Collisions

Every report has a unique slug. When importing, if a report with the same slug already exists, you have two options:

Option 1: Overwrite the Existing Report

• Click Overwrite Report in the import modal
• The existing report is completely replaced
• Warning: Any customizations to the existing report are lost
• Use this when: Updating a report to a newer version, or intentionally replacing a report

Option 2: Cancel and Modify the JSON

• Click Cancel to close the import modal
• Open the JSON file in a text editor
• Change the "dashboard_id" field to a unique slug
• Optionally change the "name" field as well
• Save the file and import again
• Use this when: You want to keep both the existing and imported reports

Import Best Practices

• Review Before Importing: Open the JSON in a text editor to see what it contains
• Check the Slug: Avoid unintentional overwrites by verifying the slug is unique
• Export Before Overwriting: If replacing a customized report, export it first as a backup
• Test on Staging: Import experimental reports on a staging site first
• Validate Source: Only import JSON files from trusted sources

Installing Default Reports

Alpha Insights includes 20+ pre-built default reports that you can install with one click. These reports are professionally designed and ready to use.

Available Default Reports

Sales Reports Category:

• Orders - Main orders dashboard
• All Orders - Comprehensive orders list
• Products - Product performance analytics
• Products Sold - Products sold breakdown
• Customers - Customer analytics
• Customer List - Detailed customer list
• Overview - Executive dashboard
• Subscriptions - Subscription analytics
• Coupons - Coupon usage
• Taxes - Tax reporting
• Expenses - Expense tracking
• Profit & Loss Statement - Financial P&L
• Facebook - Facebook Ads integration
• Google Ads - Google Ads integration

Website Traffic Category:

• Analytics Overview - Website analytics overview
• Website Sessions - Session analytics
• Acquisitions - Traffic sources
• Acquisition Sources - Detailed source breakdown
• Campaigns - Campaign performance
• E-commerce Activity - Activity tracking
• Form Submissions - Form analytics
• Realtime Dashboard - Real-time data

Installing Individual Default Reports

1. Click the Not Installed tab in the Report Manager
2. Browse the available default reports
3. Find the report you want
4. Click Install Report on its card
5. The report is installed immediately
6. The page refreshes to show the installed report
7. The report is ready to use and appears in the WordPress menu (if configured to be visible)

Installing All Default Reports at Once

1. Click Install Default Reports in the top-right
2. A modal opens with two installation options
3. Choose your preferred method:
   • Install Only: Safe option
     • Installs only reports that don't exist yet
     • Skips reports with matching slugs
     • Preserves any customizations you've made
     • Best for: Adding new default reports without affecting existing ones
   • Install & Overwrite: Update option
     • Installs all default reports
     • Replaces existing reports with matching slugs
     • Warning: Loses all customizations to default reports
     • Best for: Updating default reports to latest versions or resetting customized defaults
4. Click your chosen button
5. The installation process runs
6. The page reloads showing all installed reports

Should You Customize Default Reports?

If You Plan to Customize:

1. Install the default report
2. Immediately duplicate it
3. Rename the duplicate (e.g., "Orders (Custom)")
4. Make your customizations to the duplicate
5. Hide the original default from the menu
6. Keep the original as a reference or reset point

Why This Approach?

• Protects your customizations from being overwritten
• Allows you to update default reports safely
• Gives you a fallback if customizations don't work
• Keeps the original as a template for future reports

Deleting Reports

Deleting permanently removes a report from your system. This action cannot be undone.

How to Delete a Report

1. Find the report in the Report Manager
2. Click the Delete button (trash icon) on the report card
3. A confirmation dialog appears with a warning
4. The dialog shows:
   • Report name you're about to delete
   • Warning that the action cannot be undone
   • Explanation that all widgets and configurations will be permanently deleted
5. Click Delete Report to confirm
6. Or click Cancel to keep the report
7. If confirmed, the report is permanently removed
8. The report card disappears from the Report Manager

What Gets Deleted

Permanently removed:

• The report configuration
• All widgets and their settings
• Row and column layout
• Report filters
• All custom settings
• Live share links associated with the report

What's not affected:

• Your actual order, product, and customer data
• Other reports
• Alpha Insights settings
• Cached data (it will rebuild as needed)

Required Reports Cannot Be Deleted

Five reports are marked as "Required" and cannot be deleted:

• Orders
• Facebook
• Google Ads
• Expenses
• Profit & Loss Statement

Why? These reports are essential to Alpha Insights functionality and certain plugin features depend on them.

What if I don't want to see a required report?

1. Click the Settings button on the required report
2. Go to the Data tab
3. Toggle off "Appear In Menu"
4. Click Update Report
5. The report is hidden from navigation but still exists

Before You Delete

Consider these alternatives:

• Hide Instead: Turn off "Appear In Menu" to remove from navigation without deleting
• Export First: Download the JSON as a backup in case you need it later
• Duplicate First: Keep a copy before deleting the original

Safe to delete when:

• You're certain you won't need the report again
• You have a backup export if it's a custom report
• The report is a test or draft version
• You've created a better replacement report

Managing Live Share Links

Live share links allow you to share reports publicly without requiring WordPress login. You can create and manage these links directly from the Report Manager.

Accessing Live Share Management

1. Find a report that has live share links (look for "Live Share Links (X)" on the card)
2. Click on the Live Share Links section
3. The Live Share Modal opens

If the report has no live share links yet:

1. You'll need to create a link first from within the report itself
2. Open the report
3. Click the Share button in the report toolbar
4. Create your first live share link
5. Return to the Report Manager to manage it

For complete details on creating and managing live share links, see the dedicated "Live Share Links" documentation.

Tips for Effective Report Organization

Naming Conventions

Use clear, consistent names that describe the report's purpose:

Good Examples:

• "Monthly Revenue Analysis"
• "Product Performance - Electronics"
• "Customer Insights - Q1 2024"
• "Weekly Ad Campaign Review"

Bad Examples:

• "Report 1"
• "Test"
• "New Dashboard"
• "Copy of Store Dashboard Copy 2"

Naming Patterns:

• [Topic] - [Time Period]: "Sales Analysis - March 2024"
• [Category] - [Focus]: "Products - Top Performers"
• [Audience] Dashboard: "Executive Dashboard"
• [Purpose] Report: "Weekly Performance Report"

Menu Order Strategy

Organize reports logically in the WordPress menu:

Use Increments of 10:

• 0 - Primary dashboard
• 10 - Secondary important report
• 20 - Third report
• This leaves room to insert reports later (e.g., 15 goes between 10 and 20)

Group Related Reports:

• 0-19: Overview and executive reports
• 20-39: Order and revenue reports
• 40-59: Product reports
• 60-79: Customer reports
• 80-99: Marketing and advertising reports

Category Organization

Choose categories thoughtfully:

Sales Reports for:

• Revenue, profit, orders
• Products and inventory
• Customers and segments
• Financial statements
• Expenses
• Advertising (Facebook, Google)

Website Traffic for:

• Visitor analytics
• Session data
• Traffic sources
• Campaign tracking (UTM)
• Page events
• Form submissions

Maintenance Habits

• Regular Cleanup: Delete unused test or draft reports monthly
• Export Important Reports: Back up custom reports quarterly
• Version Management: Update version numbers when making significant changes
• Hide Seasonal Reports: Hide off-season reports instead of deleting them
• Document Customizations: Add notes in report descriptions about what you changed

Troubleshooting Common Issues

Can't Delete a Report

Symptom: Delete button is disabled or doesn't work

Cause: The report is marked as "Required"

Solution: You cannot delete required reports (Orders, Facebook, Google Ads, Expenses, Profit & Loss Statement). Instead, hide it from the menu using the "Appear In Menu" toggle in Report Settings.

Slug Already Exists Error

Symptom: Error when creating or duplicating: "A report with this slug already exists"

Cause: Another report is using that slug

Solution:

• Change the report name (slug will auto-regenerate)
• Or manually edit the slug to make it unique
• Add suffixes like -v2, -custom, or -2024

Can't Find a Report

Symptom: Report exists but you can't see it in the menu

Cause: Report is hidden from menu

Solution:

• Go to the Report Manager
• Look for "Not Visible In Menu" status on the report card
• Click Settings and toggle "Appear In Menu" back on
• Or check the category tabs - it might be in a different category than you thought

Import Fails with Invalid JSON

Symptom: Error when importing: "Invalid JSON format"

Cause: JSON file is corrupted or malformed

Solution:

• Open the file in a text editor
• Check for syntax errors (missing brackets, commas, quotes)
• Use an online JSON validator to check the format
• If the file is corrupted, try re-exporting the original report

Lost Customizations After Update

Symptom: Your customized report reverted to default

Cause: You used "Install & Overwrite" when installing default reports

Prevention:

• Always duplicate default reports before customizing them
• Use "Install Only" option to preserve customizations
• Keep JSON backups of important custom reports

Recovery: If you have a JSON backup, import it to restore the report

Next Steps

Now that you know how to manage reports, learn more about:

• Creating Custom Reports: Build reports from scratch with widgets
• Using Report Filters: Apply advanced filtering to your reports
• Report Widgets Guide: Understand all available widget types
• Live Share Links: Create and manage public report links
• Export Features: Export report data to CSV, Excel, and PDF