Report Agent App Overview
Generate custom workforce reports by describing what you need in plain English — the AI handles the query building, data retrieval, chart selection, and export formatting automatically.
What is the Report Agent?
The Report Agent is an AI-powered reporting assistant inside MangoApps Workforce. Instead of building reports manually through complex query builders or spreadsheets, managers and admins describe the data they need in natural language — “Show me headcount by department” or “Generate an attendance report for this month” — and the agent instantly produces formatted tables, auto-selected charts, and exportable data.
Under the hood, the agent uses semantic search and LLM-powered query parsing to match requests to the right data domain, translate natural language into structured query DSLs, execute the query against live business data, and render rich HTML previews. Reports can be saved for reuse, shared with colleagues, scheduled for automatic delivery, and exported in multiple formats.
The Report Agent integrates directly with Ask AI — any report generated in the Ask AI sidebar can be opened as a full report, saved to the library, or refined through conversational follow-ups.
Core Value Proposition:
- 🤖 Natural Language Queries — Describe data needs in plain English; the AI translates to structured queries automatically
- 📊 Auto-Visualizations — Charts (bar, line, pie, doughnut, area) are suggested and rendered based on the data shape
- 💾 Saved Report Library — Save, favorite, duplicate, and share reports with team members
- ⏰ Scheduled Delivery — Automate recurring reports via email, webhook, or SFTP on daily, weekly, monthly, or quarterly cadences
At a Glance
| 🤖 Natural Language | 📊 Auto-Charts | 💾 Saved Reports | 📤 Multi-Format Export |
|---|---|---|---|
| Ask in plain English, get structured data | Bar, line, pie, doughnut, area, table | Save, favorite, share, duplicate | CSV, Excel, PDF, JSON |
| ⏰ Scheduled Reports | 🔍 5 Data Domains | 🔗 Ask AI Integration | 📱 Mobile Support |
|---|---|---|---|
| Daily, weekly, monthly, quarterly | Employee, attendance, shifts, performance, service desk | Generate reports from sidebar chat | View, run, and favorite on mobile |
Perfect For:
- 👥 Managers — Get quick team analytics: headcount, attendance trends, shift coverage, performance ratings
- 🏢 HR / Admin — Run workforce reports, configure data domains, manage sharing policies, schedule compliance reports
- 📊 Analysts — Save frequently-used report configurations, export data in bulk, automate recurring deliveries
How It Works
Report Generation Flow
┌────────────────────────────────────────────────────────────────────────┐
│ REPORT GENERATION FLOW │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ QUERY │──▶│ AI PARSING │──▶│ EXECUTE │──▶│ RENDER │ │
│ │ Input │ │ & Matching │ │ Query │ │ Results │ │
│ └──────────┘ └──────────────┘ └──────────────┘ └───────────┘ │
│ │ │ │ │ │
│ User types a Semantic search Query DSL is Table + │
│ natural language matches to best executed against chart HTML │
│ description data domain tool live business rendered │
│ + LLM parses DSL data with stats │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ REFINE │──▶│ SAVE │──▶│ EXPORT │──▶│ SCHEDULE │ │
│ │ Report │ │ Report │ │ Download │ │ Delivery │ │
│ └──────────┘ └──────────────┘ └──────────────┘ └───────────┘ │
│ │ │ │ │ │
│ "Filter for Save to library CSV, Excel, Daily/weekly/ │
│ Engineering" with visibility PDF, or JSON monthly auto- │
│ modifies the settings download delivery via │
│ previous query (private/shared) email/webhook │
│ │
└────────────────────────────────────────────────────────────────────────┘
Ask AI Integration
┌────────────────────────────────────────────────────────────────────┐
│ ASK AI ↔ REPORT AGENT │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Ask AI │───▶│ Context │───▶│ Reporting Agent │ │
│ │ Sidebar │ │ Router │ │ (Agentic LLM) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
│ │ │ │ │
│ User asks a Router detects Agent picks the │
│ reporting reporting intent right tool, parses │
│ question and delegates query, executes │
│ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ HTML │◀───│ Render │◀───│ Query Result │ │
│ │ Preview │ │ Service │ │ (data + chart) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
│ │ │
│ Preview shows table, chart, row count, and action buttons: │
│ [Open Full Report] [Save Report] [Export CSV] │
│ │
└────────────────────────────────────────────────────────────────────┘
Key Features
🤖 Natural Language Report Generation
Describe the data you need in plain English and the AI agent translates your request into a structured query, selects the appropriate data domain, and executes it against live business data.
| Capability | Description |
|---|---|
| Semantic Query Matching | Uses pgvector embeddings and keyword indexing to match queries to the best reporting tool across five data domains |
| LLM-Powered Parsing | GPT-4o-mini translates natural language into structured query DSLs with columns, filters, grouping, metrics, and sorting |
| Natural Date Normalization | Understands phrases like “this quarter,” “last 30 days,” “since January” and converts them to date ranges |
| Conversational Refinement | Follow up with “filter for Engineering” or “group by location instead” to modify the previous report without starting over |
| Error Recovery | Provides user-friendly suggestions when a query can’t be matched or parsed |
Example Queries:
- “Show me headcount by department”
- “Generate an attendance report for this month”
- “What are the top performers this quarter?”
- “List shifts with coverage gaps next week”
- “Show open service desk tickets by priority”
Use Case — Quick Team Analytics:
A manager opens Ask AI and types “Show me hours worked by employee this month.” The agent matches to the attendance domain, parses the date range, and returns a table with employee names, total hours, and overtime — plus a suggested bar chart. The manager clicks “Open Full Report” to see the complete data set and exports it to Excel.
💡 Pro Tip: Use conversational follow-ups to refine reports. After getting headcount by department, type “now filter for just Engineering and sort by tenure” — the agent modifies the existing query rather than starting from scratch.
📊 Chart Visualization
The Report Agent automatically suggests and renders chart types based on the data structure. Charts are rendered using Chart.js in both the Ask AI preview and the full report view.
| Chart Type | Best For |
|---|---|
| Bar Chart | Comparing values across categories (headcount by department, hours by team) |
| Line Chart | Trends over time (attendance over weeks, performance scores by quarter) |
| Pie / Doughnut | Proportional breakdowns (department distribution, status composition) |
| Area Chart | Cumulative trends with filled regions |
| Table View | Detailed row-level data with sortable columns |
| Capability | Description |
|---|---|
| Auto-Suggest | Chart type is inferred from query shape (grouping + metrics = bar, time series = line, proportions = pie) |
| Chart Themes | Three built-in themes: Modern, Classic, Minimal — configurable per business |
| PDF Charts | Native Prawn-drawn charts in PDF exports (not screenshots — true vector graphics) |
| Preview in Ask AI | Compact chart + table preview rendered inline in the Ask AI sidebar |
💾 Saved Reports Library
Save any generated report to your personal library for quick re-runs, sharing, and scheduling.
| Capability | Description |
|---|---|
| Save from Ask AI | One click to save a report generated in the Ask AI sidebar to your library |
| Save from Preview | Reports opened via “Open Full Report” can be saved with a name, description, and visibility |
| Re-Run on Demand | Run any saved report to get fresh data with the same query configuration |
| Favorites | Mark frequently-used reports as favorites for quick access |
| Duplicate | Clone any report (including shared reports) to create a customized copy |
| Templates | Admins can mark reports as templates that appear in the template gallery |
| Search & Filter | Filter reports by ownership (mine, shared, favorites), data domain, or search by name |
| Sorting | Sort by name, creation date, last updated, or run count |
| Pagination | Reports list paginates at 20 per page |
Visibility Levels:
| Level | Who Can See |
|---|---|
| Private | Only the report creator |
| Shared | Creator + specific users added by ID |
| Public | All users in the business with report access |
👥 Report Sharing
Share reports with colleagues so they can view and run them without recreating the query configuration.
| Capability | Description |
|---|---|
| Share with Users | Add specific users by searching within the business — shared users get view + run access |
| Unshare | Remove individual users from a shared report’s access list |
| Automatic Visibility | Sharing automatically sets the report visibility to “shared” |
| Auto-Revert | Removing the last shared user automatically reverts visibility to “private” |
| Admin Override | Business admins can access all reports regardless of visibility settings |
💡 Pro Tip: Share a report with your entire team’s managers so everyone can run the same “Weekly Team Attendance” report with fresh data each time.
📤 Multi-Format Export
Export reports in four formats with configurable business-level controls for which formats are available.
| Format | Description |
|---|---|
| CSV | Standard comma-separated values with quoted fields and UTF-8 encoding |
| Excel | CSV with UTF-8 BOM for Excel compatibility, title row, metadata row, and truncation notices for large datasets (100K+ rows) |
| Professional PDF with business branding, summary metrics, native Prawn-drawn charts (bar, line, pie), and paginated data table (up to 500 rows) | |
| JSON | Structured JSON with column metadata, typed data, and optional pretty-printing |
| Capability | Description |
|---|---|
| Per-Format Toggle | Admins can enable/disable CSV, Excel, and PDF exports independently |
| Row Limits | Configurable maximum rows per query (default: 10,000) prevents runaway queries |
| Date Formatting | Dates formatted as YYYY-MM-DD, datetimes as YYYY-MM-DD HH:MM |
| Boolean Formatting | Boolean values display as “Yes” / “No” in exports |
| Array Handling | Array values are joined with commas in CSV/Excel exports |
⏰ Scheduled Reports
Automate recurring report generation and delivery on configurable schedules.
| Capability | Description |
|---|---|
| Schedule Types | Daily, weekly (pick day of week), monthly (pick day of month), quarterly |
| Delivery Methods | Email (with attachment), webhook (HTTPS POST with JSON payload), or download-only |
| Export Formats | CSV, Excel, PDF, or JSON — selected per scheduled report |
| Timezone Support | Schedule times honor the user’s configured timezone |
| Link to Saved Reports | Optionally link a scheduled report to an existing saved report — query DSL auto-populates |
| Enable / Disable | Toggle scheduled reports on or off without deleting them |
| Run Now | Manually trigger an immediate run of any scheduled report |
| Auto-Disable | Reports are automatically disabled after 5 consecutive failures to prevent noise |
| Failure Notifications | Email notification sent to the report owner when a scheduled run fails |
| Disabled Notifications | Email notification when a report is auto-disabled due to excessive failures |
| Idempotency | Job skips execution if the report ran within the last 5 minutes to prevent duplicates |
| Retry with Backoff | Failed jobs retry up to 3 times with exponential backoff |
Delivery Methods in Detail:
| Method | How It Works |
|---|---|
| Sends the exported file as an attachment to one or more email recipients. Validates email format on save. | |
| Webhook | POSTs a JSON payload (report ID, name, Base64-encoded file, timestamp) to a public HTTPS endpoint. Supports custom Authorization headers. Private IPs are blocked for security. |
| Download | Generates and stores the report — no external delivery. Useful for audit trails. |
Use Case — Automated Weekly Headcount Report:
An HR admin creates a saved report for “Headcount by Department” and schedules it for every Monday at 8:00 AM. The report runs automatically, exports as Excel, and is emailed to the HR distribution list. If the report fails three weeks in a row, it auto-disables and notifies the admin.
🔍 Five Data Domains
The Report Agent supports five distinct data domains, each backed by a dedicated reporting tool with domain-specific columns, metrics, filters, and grouping options.
| Domain | Tool Class | Example Queries |
|---|---|---|
| Employee | EmployeeReportingTool |
Headcount by department, tenure distribution, hire trends, demographics |
| Attendance | AttendanceReportingTool |
Hours worked, overtime analysis, late arrivals, absence patterns |
| Shifts | ShiftsReportingTool |
Shift coverage, scheduling gaps, assignment counts, staffing levels |
| Performance | PerformanceReportingTool |
Rating distributions, goal completion, top performers, review status |
| Service Desk | ServiceDeskReportingTool |
Ticket volumes, SLA compliance, resolution times, satisfaction scores |
Each domain can be independently enabled or disabled per business through the admin settings. When a domain is disabled, its reports are hidden from the library and the agent won’t match queries to it.
📱 Mobile Support
The Report Agent includes mobile web views for on-the-go report access inside the native MangoApps iOS/Android app.
| Capability | Description |
|---|---|
| Reports List | Browse saved reports with filter (mine, shared, favorites), search, and infinite scroll |
| Report Detail | View report metadata, last run summary, and run history |
| Run Reports | Execute any accessible report and see the row count result |
| Toggle Favorites | Mark/unmark reports as favorites directly from the mobile list |
| Scheduled Reports | View list of scheduled reports with status, filter by enabled/disabled |
| Scheduled Detail | View schedule configuration and last run summary |
⚙️ Admin Settings
Administrators configure the Report Agent through a dedicated settings page with granular controls.
| Setting Group | Options |
|---|---|
| Agent Toggle | Enable/disable the reporting agent globally for the business |
| Chart Configuration | Default chart theme (Modern, Classic, Minimal), auto-suggest charts toggle |
| Data Domains | Enable/disable each of the 5 data domains independently |
| Report Sharing | Enable/disable saved reports, enable/disable report sharing, max saved reports per user (default: 50) |
| Export Options | Toggle CSV, Excel, and PDF export formats independently |
| Performance Limits | Max rows per query (default: 10,000), preview rows in Ask AI (5/10/15/20), query caching toggle and TTL |
| Analytics & Feedback | Detailed audit log, collect user feedback, show AI reasoning toggles |
Interaction Tracking & Analytics
Every interaction with the Report Agent is tracked for analytics, debugging, and learning.
| Metric | Description |
|---|---|
| Reports Run | Count of reports executed by the current user this month |
| Saved Reports | Total saved reports owned by the current user |
| Avg Response Time | Average agent response time over the last 30 days |
| Popular Tools | Most-used data domains in the last 30 days across the business |
| Success Rate | Percentage of successful report generations over a configurable period |
| Daily Usage | Day-by-day interaction counts for trend analysis |
| Common Queries | Most frequently asked report queries for template suggestions |
The dashboard shows recent reports, shared reports, popular data domains, and quick usage stats at a glance.
Architecture Overview
┌──────────────────────────────────────────────────────────────────┐
│ REPORT AGENT ARCHITECTURE │
├──────────────────────────────────────────────────────────────────┤
│ │
│ Entry Points: │
│ ┌───────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Ask AI │ │ Report Agent │ │ Scheduled │ │
│ │ Sidebar │ │ Dashboard │ │ Report Job │ │
│ └─────┬─────┘ └──────┬────────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Agents::ReportingAgent │ │
│ │ - handle_request() → execute_with_tools() │ │
│ │ - Tools: generate, refine, export, list │ │
│ └───────────────────┬──────────────────────────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌────────────┐ │
│ │ Semantic │ │ Enhanced │ │ Report │ │
│ │ Report │ │ Query │ │ Schema │ │
│ │ Matcher │ │ Parser │ │ Embeddings │ │
│ └───────────┘ └───────────┘ └────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ Reporting Tool (per domain) │ │
│ │ Employee | Attendance | Shifts | │ │
│ │ Performance | Service Desk │ │
│ └────────────────────┬─────────────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ HTML │ │ Export │ │ PDF │ │
│ │ Renderer │ │ Service │ │ Generator │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
Access Control
| Role | Capabilities |
|---|---|
| Super Admin | Full access: all reports, all settings, all scheduled reports, all domains |
| Admin | Full access: all reports, settings, scheduled reports, all domains |
| Manager | Generate reports, save/share/export, create scheduled reports, view team data |
| Member | No access by default. Can be granted via allowed_roles configuration |
Reports enforce strict business scoping — all queries filter by the current business, and cross-business data access is prevented at both the model and controller layers. Shared reports verify access at both the query scope level and individual record level.
Navigation
The Report Agent app includes a sidebar with four navigation tabs:
| Tab | Icon | Description | Access |
|---|---|---|---|
| Dashboard | fa-chart-pie |
Overview with recent reports, shared reports, popular tools, usage stats | All authorized users |
| Reports | fa-file-alt |
Saved custom reports library with search, filter, and sort | All authorized users |
| Scheduled Reports | fa-calendar-check |
Automated report delivery management | Managers and above |
| Settings | fa-cog |
App configuration and domain controls | Admins only |
Tips & Best Practices
- Start broad, then refine — Ask for a general report first (“headcount by department”), then use follow-up messages to add filters, change grouping, or narrow the date range
- Save frequently-used reports — Save any report you run more than once. Re-running a saved report is faster than re-typing the query
- Use scheduled reports for compliance — Set up weekly or monthly reports for attendance, performance reviews, or staffing levels and have them delivered automatically
- Leverage sharing — Share standard reports (like “Monthly Headcount”) with your management team so everyone uses the same data definition
- Export strategically — Use CSV for data analysis in spreadsheets, PDF for stakeholder presentations, JSON for integrations
- Check the dashboard — The dashboard shows your most popular data domains and recent activity, helping you discover what reports your team runs most
Related Features
| Feature | Relationship |
|---|---|
| Ask AI | Report Agent is accessible through the Ask AI sidebar — generate reports conversationally |
| Workforce Bots | Bots can reference reporting data in automated workflows |
| Employee Data Management | Employee domain reports pull from the employee data module |
| Time & Attendance | Attendance domain reports pull from time tracking data |
| Shift Scheduling | Shifts domain reports pull from scheduling data |
| Performance Management | Performance domain reports pull from review and goal data |
| Service Desk | Service desk domain reports pull from ticket and SLA data |
