Add Suite app documentation, templates, and Askama config
- Add askama.toml for template configuration (ui/ directory)
- Add Suite app documentation with flow diagrams (SVG)
- App launcher, chat flow, drive flow, tasks flow
- Individual app docs: chat, drive, tasks, mail, etc.
- Add HTML templates for Suite apps
- Base template with header and app launcher
- Auth login page
- Chat, Drive, Mail, Meet, Tasks templates
- Partial templates for messages, sessions, notifications
- Add Extensions type to AppState for type-erased storage
- Add mTLS module for service-to-service authentication
- Update web handlers to use new template paths (suite/)
- Fix auth module to avoid axum-extra TypedHeader dependency
2025-11-30 21:00:48 -03:00
# Analytics - Dashboards
2025-11-30 22:33:54 -03:00
> **Your business intelligence center**
---
## Overview
Analytics is the data visualization and reporting app in General Bots Suite. Track key metrics, build custom dashboards, generate reports, and get AI-powered insights about your business. Analytics turns your data into actionable information.
---
## Interface Layout
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Analytics [+ Widget] [Export] [⚙️] [×
├──────────────┬──────────────────────────────────────────────────────────┤
│ │ │
│ DASHBOARDS │ Sales Overview Dashboard May 2025 │
│ ─────────── │ ════════════════════════════════════════════════════ │
│ │ │
│ ★ Overview │ ┌─────────────────┐ ┌─────────────────┐ │
│ Sales │ │ Total Revenue │ │ New Customers │ │
│ Marketing │ │ │ │ │ │
│ Support │ │ $2.4M │ │ 47 │ │
│ HR │ │ ▲ 15% │ │ ▲ 23% │ │
│ │ └─────────────────┘ └─────────────────┘ │
│ ─────────── │ ┌─────────────────┐ ┌─────────────────┐ │
│ │ │ Conversion Rate │ │ Avg Deal Size │ │
│ REPORTS │ │ │ │ │ │
│ ─────────── │ │ 24.5% │ │ $12,400 │ │
│ 📊 Weekly │ │ ▲ 3.2% │ │ ▼ 5% │ │
│ 📊 Monthly │ └─────────────────┘ └─────────────────┘ │
│ 📊 Quarterly│ │
│ │ ┌───────────────────────────────────────────────────┐ │
│ ─────────── │ │ Revenue Trend │ │
│ │ │ $ │ │
│ [+ New] │ │ 3M│ ╭─────╮ │ │
│ │ │ │ ╭────╯ ╰────╮ │ │
│ │ │ 2M│───╯ ╰───╮ │ │
│ │ │ │ ╰──── │ │
│ │ │ 1M│ │ │
│ │ │ └─────────────────────────────────────────── │ │
│ │ │ Jan Feb Mar Apr May │ │
│ │ └───────────────────────────────────────────────────┘ │
│ │ │
└──────────────┴──────────────────────────────────────────────────────────┘
```
---
## Features
### Dashboard Overview
Dashboards are collections of widgets that display your data visually.
**Default Dashboards:**
| Dashboard | What It Shows |
|-----------|---------------|
| **Overview** | Key metrics across all areas |
| **Sales** | Revenue, deals, pipeline |
| **Marketing** | Campaigns, leads, conversion |
| **Support** | Tickets, response time, satisfaction |
| **HR** | Headcount, hiring, retention |
---
### Creating a Dashboard
**Step 1: Click "+ New" in the sidebar**
```
┌─────────────────────────────────────────┐
│ Create Dashboard [×
├─────────────────────────────────────────┤
│ │
│ Dashboard Name: │
│ ┌─────────────────────────────────┐ │
│ │ Q2 Performance │ │
│ └─────────────────────────────────┘ │
│ │
│ Description (optional): │
│ ┌─────────────────────────────────┐ │
│ │ Key metrics for Q2 2025 │ │
│ └─────────────────────────────────┘ │
│ │
│ Template: │
│ ○ Blank │
│ ○ Sales Template │
│ ○ Marketing Template │
│ ● Copy from existing... │
│ [Sales Overview ▼] │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Create │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
**Step 2: Add Widgets**
Click ** + Widget** and choose a visualization type.
---
### Widget Types
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Add Widget [×
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ NUMBERS │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ┌───┐ │ │ ▲ 15% │ │ 85% │ │
│ │ │123│ │ │ ─────── │ │ ████░░ │ │
│ │ └───┘ │ │ vs last │ │ │ │
│ │ Number │ │ Comparison │ │ Progress │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ CHARTS │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ╭──╮ │ │ █ │ │ ╱╲ │ │ ┌──┬──┐ │ │
│ │ ───╯ ╰── │ │ █ █ │ │ ╱
│ │ │ │ █ █ █ │ │ ╱
│ │ Line │ │ Bar │ │ Area │ │ Pie │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ TABLES & LISTS │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ┌─┬─┬─┐ │ │ 1. ████ │ │ ● Item A │ │
│ │ ├─┼─┼─┤ │ │ 2. ███ │ │ ● Item B │ │
│ │ └─┴─┴─┘ │ │ 3. ██ │ │ ● Item C │ │
│ │ Table │ │ Leaderboard│ │ List │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ SPECIAL │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ [Map] │ │ ════════ │ │ ✨ AI │ │
│ │ ● ● │ │ ▓▓▓▓░░░░ │ │ Insights │ │
│ │ ● │ │ ════════ │ │ │ │
│ │ Geography │ │ Heatmap │ │ AI Summary │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
### Configuring Widgets
After selecting a widget type, configure the data source:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Configure Widget: Line Chart [×
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Title: │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Monthly Revenue │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ DATA SOURCE │
│ ─────────── │
│ Source: [Sales Database ▼] │
│ Table: [transactions ▼] │
│ │
│ AXES │
│ ──── │
│ X-Axis: [date ▼] Group by: [Month ▼] │
│ Y-Axis: [amount ▼] Aggregate: [Sum ▼] │
│ │
│ FILTERS │
│ ─────── │
│ [+ Add Filter] │
│ │ status = "completed" [×
│ │ date >= "2025-01-01" [×
│ │
│ PREVIEW │
│ ─────── │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ $ │ │
│ │ 3M│ ╭─────╮ │ │
│ │ │ ╭────╯ ╰────╮ │ │
│ │ 2M│───╯ ╰───╮ │ │
│ │ 1M│ ╰──── │ │
│ │ └─────────────────────────────── │ │
│ │ Jan Feb Mar Apr May │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Save │ │ Cancel │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
### Key Metric Cards
Display important numbers with context:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Total Revenue │ │ Active Users │ │ Support Tickets │ │
│ │ │ │ │ │ │ │
│ │ $2,456,000 │ │ 1,234 │ │ 45 │ │
│ │ │ │ │ │ │ │
│ │ ▲ 15.3% │ │ ▲ 8.2% │ │ ▼ 12% │ │
│ │ vs last month │ │ vs last month │ │ vs last month │ │
│ │ │ │ │ │ (Good!) │ │
│ │ ████████░░ │ │ ██████░░░░ │ │ ██░░░░░░░░ │ │
│ │ Goal: $3M │ │ Goal: 2,000 │ │ Goal: < 50 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
**Color Indicators:**
| Color | Meaning |
|-------|---------|
| 🟢 Green (▲) | Positive trend / On target |
| 🔴 Red (▼) | Negative trend / Below target |
| 🟡 Yellow (─) | No change / Needs attention |
| ⚪ Gray | No comparison available |
---
### AI Insights ✨
Let AI analyze your data and surface insights:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ ✨ AI Insights [Refresh] │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 📈 TRENDS │
│ ────────── │
│ • Revenue has grown 15% month-over-month for 3 consecutive months │
│ • Customer acquisition cost decreased by $50 this quarter │
│ • Enterprise segment is outperforming SMB by 2x │
│ │
│ ⚠️ ALERTS │
│ ───────── │
│ • Churn rate increased to 5.2% (was 4.1% last month) │
│ • Support ticket volume up 23% - may need more staff │
│ • Marketing spend efficiency dropped in paid social │
│ │
│ 💡 RECOMMENDATIONS │
│ ───────────────── │
│ • Focus on enterprise sales - highest ROI segment │
│ • Investigate churn increase in mid-market customers │
│ • Consider reallocating paid social budget to email │
│ │
│ 🎯 PREDICTIONS │
│ ───────────── │
│ • Projected Q2 revenue: $7.8M (±5%) │
│ • Expected to hit annual target by October │
│ • Staffing need: +2 support agents by July │
│ │
│ [Ask AI a Question] [Generate Report] [Share Insights] │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
**Ask the AI:**
```
You: Why did revenue spike in March?
AI: March revenue increased 28% due to three factors:
1. Enterprise Deal Closure - Three large deals ($150K+)
that were in pipeline since Q4 closed in March
2. Annual Renewals - 15 customers renewed annual
contracts (worth $320K total)
3. Product Launch - The new feature release drove
12 new mid-market signups
The spike is partially seasonal (end of Q1) and
partially due to the product launch timing.
```
---
### Reports
Generate and schedule reports:
**Creating a Report**
1. Click ** + New** under Reports
2. Select report type
3. Configure data and format
4. Schedule delivery (optional)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Create Report [×
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Report Name: │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Weekly Sales Report │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ CONTENT │
│ ─────── │
│ ☑ Include dashboard: [Sales Overview ▼] │
│ ☑ Include AI insights │
│ ☐ Include raw data tables │
│ │
│ DATE RANGE │
│ ────────── │
│ ○ Last 7 days │
│ ● Last 30 days │
│ ○ This quarter │
│ ○ Custom range: [____] to [____] │
│ │
│ FORMAT │
│ ────── │
│ ○ PDF │
│ ● Interactive (Web) │
│ ○ Excel │
│ ○ PowerPoint │
│ │
│ SCHEDULE (Optional) │
│ ──────── │
│ ☑ Schedule automatic delivery │
│ Frequency: [Weekly ▼] │
│ Day: [Monday ▼] │
│ Time: [9:00 AM ▼] │
│ Send to: [team@company .com, ceo@company .com] │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Preview │ │ Save │ │ Cancel │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
### Data Sources
Connect Analytics to various data sources:
| Source Type | Examples |
|-------------|----------|
| **Databases** | PostgreSQL, MySQL, SQLite |
| **Files** | Excel, CSV, JSON |
| **APIs** | REST endpoints, GraphQL |
| **Apps** | CRM, Support, Calendar data |
| **Bot Data** | Conversation logs, user data |
**Adding a Data Source**
1. Go to **Settings** → **Data Sources**
2. Click ** + Add Source**
3. Select source type
4. Enter connection details
5. Test and save
```
┌─────────────────────────────────────────┐
│ Data Sources [×
├─────────────────────────────────────────┤
│ │
│ Connected Sources: │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 🗄️ Main Database ✓ │ │
│ │ PostgreSQL - 15 tables │ │
│ │ Last sync: 5 min ago │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 📊 Sales Data ✓ │ │
│ │ Excel - sales_2025.xlsx │ │
│ │ Last sync: 1 hour ago │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 🤖 Bot Analytics ✓ │ │
│ │ Internal - Conversations │ │
│ │ Real-time │ │
│ └─────────────────────────────────┘ │
│ │
│ [+ Add Data Source] │
│ │
└─────────────────────────────────────────┘
```
---
### Sharing Dashboards
Share dashboards with your team:
1. Click **Share** on any dashboard
2. Set permissions
3. Copy link or invite by email
```
┌─────────────────────────────────────────┐
│ Share Dashboard [×
├─────────────────────────────────────────┤
│ │
│ "Sales Overview" Dashboard │
│ │
│ Share with: │
│ ┌─────────────────────────────────┐ │
│ │ Add people or groups... │ │
│ └─────────────────────────────────┘ │
│ │
│ People with access: │
│ ┌─────────────────────────────────┐ │
│ │ You (Owner) [Owner ▼] │ │
│ │ Sales Team [View ▼] │ │
│ │ john@company .com [Edit ▼] │ │
│ └─────────────────────────────────┘ │
│ │
│ Link sharing: │
│ ○ Off - Only specific people │
│ ● On - Anyone with link can view │
│ │
│ ┌─────────────────────────────────┐ │
│ │ https://analytics.bot/d/abc123 │ │
│ └─────────────────────────────────┘ │
│ [Copy Link] │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Done │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
---
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `R` | Refresh dashboard |
| `F` | Toggle fullscreen |
| `E` | Edit mode |
| `N` | New widget |
| `D` | Duplicate widget |
| `Delete` | Delete selected widget |
| `Ctrl+S` | Save dashboard |
| `Ctrl+P` | Print / Export PDF |
| `Ctrl+F` | Find / Filter |
| `/` | Quick search |
| `←` `→` | Navigate dashboards |
| `Escape` | Exit edit mode |
---
## Tips & Tricks
### Dashboard Design
💡 **Keep it simple** - 5-7 widgets per dashboard is optimal
💡 **Most important metrics at top** - Follow the F-pattern reading
💡 **Use consistent colors** - Same metric = same color across widgets
💡 **Group related widgets** - Keep sales metrics together
### Data Tips
💡 **Set up daily sync** for data sources that change frequently
💡 **Use filters** to let viewers customize their view
💡 **Add comparison periods** (vs last month, vs last year)
💡 **Include goals/targets** to show progress
### AI Tips
💡 **Ask "why" questions** - AI excels at explaining trends
💡 **Request predictions** for planning
💡 **Use AI for anomaly detection** - "What's unusual this month?"
💡 **Generate executive summaries** before board meetings
---
## Troubleshooting
### Dashboard not loading
**Possible causes:**
1. Data source disconnected
2. Query timeout
3. Permission issues
**Solution:**
1. Check data source status in Settings
2. Reduce date range or add filters
3. Verify you have dashboard access
4. Refresh the page
---
### Data not updating
**Possible causes:**
1. Sync schedule not running
2. Source data hasn't changed
3. Cache showing old data
**Solution:**
1. Click Refresh on the dashboard
2. Check data source sync status
3. Go to Settings → Clear cache
4. Verify source data has new records
---
### Charts showing wrong numbers
**Possible causes:**
1. Filter applied incorrectly
2. Wrong aggregation method
3. Date range mismatch
**Solution:**
1. Check widget filters
2. Verify aggregation (Sum vs Count vs Average)
3. Confirm date range matches expectations
4. Edit widget and review query
---
### Export not working
**Possible causes:**
1. Dashboard too large
2. Browser blocking download
3. Permission restrictions
**Solution:**
1. Try exporting individual widgets
2. Check browser download settings
3. Use a different export format
4. Contact administrator for permissions
---
## BASIC Integration
Use Analytics in your bot dialogs:
### Query Metrics
```basic
revenue = GET METRIC "total_revenue" FOR "this month"
lastMonth = GET METRIC "total_revenue" FOR "last month"
growth = ((revenue - lastMonth) / lastMonth) * 100
TALK "Revenue this month: $" + FORMAT(revenue, "#,##0 ")
TALK "Growth: " + FORMAT(growth, "#0 .0") + "%"
```
### Generate Reports
```basic
HEAR period AS TEXT "Which period? (weekly/monthly/quarterly)"
report = GENERATE REPORT "Sales Summary" FOR period
TALK "Here's your " + period + " sales report:"
SEND FILE report.pdf
TALK "Key highlights:"
TALK report.summary
```
### Get AI Insights
```basic
insights = GET INSIGHTS FOR "Sales Dashboard"
TALK "Here are today's insights:"
FOR EACH insight IN insights.trends
TALK "📈 " + insight
NEXT
TALK "Alerts:"
FOR EACH alert IN insights.alerts
TALK "⚠️ " + alert
NEXT
```
### Create Dashboard Widget
```basic
widget = NEW OBJECT
widget.type = "line_chart"
widget.title = "Daily Active Users"
widget.source = "bot_analytics"
widget.xAxis = "date"
widget.yAxis = "active_users"
widget.dateRange = "last 30 days"
ADD WIDGET widget TO "Overview Dashboard"
TALK "Widget added successfully"
```
### Scheduled Reports
```basic
' This dialog runs on a schedule
report = GENERATE REPORT "Weekly Metrics" FOR "last 7 days"
recipients = ["ceo@company .com", "team@company .com"]
FOR EACH email IN recipients
SEND EMAIL TO email
SUBJECT "Weekly Metrics Report - " + TODAY
BODY "Please find attached the weekly metrics report."
ATTACHMENT report.pdf
NEXT
LOG "Weekly report sent to " + COUNT(recipients) + " recipients"
```
---
## See Also
- [Research App ](./research.md ) - Deep dive into data questions
- [Paper App ](./paper.md ) - Create reports from insights
- [How To: Monitor Your Bot ](../how-to/monitor-sessions.md )
- [Talk to Data Template ](../../chapter-02/templates.md )
