@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/analytics/dashboard-patterns.md

@@ -0,0 +1,352 @@
+# Zoho Analytics Dashboard Patterns
+
+## Report Types
+
+| Type | Use Case | Best For |
+|------|----------|----------|
+| Chart (Bar, Line, Pie) | Trend visualization, comparisons | Sales over time, category breakdown |
+| Pivot Table | Multi-dimensional analysis | Revenue by product by region |
+| Summary View | Aggregated metrics | Monthly totals, averages |
+| Tabular Report | Detailed record listing | Transaction logs, audit trails |
+| KPI Widget | Single metric display | Revenue, conversion rate, count |
+| Dashboard | Combined views | Executive overview, ops dashboard |
+| Geo Map | Location-based data | Customer distribution, sales by state |
+
+## Scheduled Data Sync
+
+### Sync from Zoho Apps
+
+Analytics auto-syncs from CRM, Books, Creator, etc.:
+
+| Source | Sync Frequency | Config Location |
+|--------|---------------|-----------------|
+| Zoho CRM | Every 1-6 hours | Analytics > Data Sources > CRM |
+| Zoho Books | Every 2-6 hours | Analytics > Data Sources > Books |
+| Zoho Creator | Every 1-6 hours | Analytics > Data Sources > Creator |
+| Zoho Desk | Every 2-6 hours | Analytics > Data Sources > Desk |
+
+### Configuring Sync Schedule
+
+1. Go to Analytics > Setup > Data Sources
+2. Select the connected app
+3. Click "Sync Settings"
+4. Set frequency (1h, 2h, 3h, 6h, 12h, 24h)
+5. Select modules/forms to sync
+6. Choose "Full sync" or "Incremental sync"
+
+> **NOTE:** Incremental sync is faster and uses fewer API calls. Use full sync only for initial setup or after schema changes.
+
+### Manual Sync Trigger
+
+```deluge
+// Trigger Analytics sync from Deluge (useful after bulk data changes)
+try
+{
+    response = invokeUrl [
+        url: "https://analyticsapi.zoho.com/restapi/v2/workspaces/{workspace-id}/sync"
+        type: POST
+        connection: "zoho-analytics-connection"
+    ];
+    info "Analytics sync triggered: " + response;
+}
+catch (e)
+{
+    info "Sync trigger failed: " + e.toString();
+}
+```
+
+## SQL Workspace Queries
+
+Analytics supports SQL-like queries in the "Query Table" feature:
+
+### Basic Queries
+
+```sql
+-- Revenue by month
+SELECT
+    YEAR("Invoice_Date") AS year,
+    MONTH("Invoice_Date") AS month,
+    SUM("Amount") AS total_revenue,
+    COUNT("Invoice_ID") AS invoice_count
+FROM "Invoices"
+WHERE "Status" = 'Paid'
+GROUP BY YEAR("Invoice_Date"), MONTH("Invoice_Date")
+ORDER BY year DESC, month DESC
+
+-- Customer lifetime value
+SELECT
+    "Customer_Name",
+    COUNT("Invoice_ID") AS total_invoices,
+    SUM("Amount") AS lifetime_value,
+    MIN("Invoice_Date") AS first_purchase,
+    MAX("Invoice_Date") AS last_purchase,
+    DATEDIFF(MAX("Invoice_Date"), MIN("Invoice_Date")) AS customer_tenure_days
+FROM "Invoices"
+WHERE "Status" IN ('Paid', 'Sent')
+GROUP BY "Customer_Name"
+HAVING SUM("Amount") > 1000
+ORDER BY lifetime_value DESC
+```
+
+### Join Queries
+
+```sql
+-- Deals with customer payment history
+SELECT
+    d."Deal_Name",
+    d."Amount" AS deal_amount,
+    d."Stage",
+    c."Customer_Name",
+    p."Total_Paid",
+    p."Last_Payment_Date"
+FROM "Deals" d
+LEFT JOIN "Customers" c ON d."Customer_ID" = c."Customer_ID"
+LEFT JOIN (
+    SELECT
+        "Customer_ID",
+        SUM("Amount") AS "Total_Paid",
+        MAX("Payment_Date") AS "Last_Payment_Date"
+    FROM "Payments"
+    GROUP BY "Customer_ID"
+) p ON c."Customer_ID" = p."Customer_ID"
+WHERE d."Stage" NOT IN ('Closed Lost')
+ORDER BY d."Amount" DESC
+```
+
+### Window Functions
+
+```sql
+-- Running total and rank
+SELECT
+    "Sales_Rep",
+    "Month",
+    "Revenue",
+    SUM("Revenue") OVER (PARTITION BY "Sales_Rep" ORDER BY "Month") AS running_total,
+    RANK() OVER (PARTITION BY "Month" ORDER BY "Revenue" DESC) AS monthly_rank
+FROM "Monthly_Sales"
+```
+
+## Embedded Analytics in Creator
+
+### Embedding a Report
+
+```html
+<!-- In Creator widget or custom HTML -->
+<iframe
+    src="https://analytics.zoho.com/open-view/{workspace-id}/{view-id}?ZOHO_CRITERIA=%22Status%22%3D%27Active%27"
+    width="100%"
+    height="500"
+    frameborder="0">
+</iframe>
+```
+
+### Dynamic Filtering via URL Parameters
+
+```javascript
+// Widget: Embed analytics with dynamic filters
+function loadAnalyticsReport(customerId, dateRange) {
+    const baseUrl = "https://analytics.zoho.com/open-view";
+    const workspaceId = "YOUR_WORKSPACE_ID";
+    const viewId = "YOUR_VIEW_ID";
+
+    // Build criteria string
+    const criteria = encodeURIComponent(
+        `"Customer_ID" = '${customerId}' AND "Date" BETWEEN '${dateRange.start}' AND '${dateRange.end}'`
+    );
+
+    const embedUrl = `${baseUrl}/${workspaceId}/${viewId}?ZOHO_CRITERIA=${criteria}&ZOHO_HIDE_HEADER=true`;
+
+    document.getElementById("analytics-frame").src = embedUrl;
+}
+```
+
+### Using Analytics API from Deluge
+
+```deluge
+// Fetch report data programmatically
+try
+{
+    response = invokeUrl [
+        url: "https://analyticsapi.zoho.com/restapi/v2/workspaces/{workspace-id}/views/{view-id}/data"
+        type: GET
+        parameters: {
+            "criteria": "\"Status\" = 'Active'",
+            "limit": "100"
+        }
+        connection: "zoho-analytics-connection"
+    ];
+
+    data = response.toJSON();
+    rows = data.get("data");
+    info "Fetched " + rows.size() + " rows from Analytics";
+}
+catch (e)
+{
+    info "Analytics API failed: " + e.toString();
+}
+```
+
+## Sharing and Permissions
+
+### Permission Levels
+
+| Level | Can View | Can Edit | Can Share | Can Delete |
+|-------|----------|----------|-----------|-----------|
+| Read Only | Yes | No | No | No |
+| Read-Write | Yes | Yes | No | No |
+| Full Access | Yes | Yes | Yes | Yes |
+| Admin | Yes | Yes | Yes | Yes |
+
+### Sharing Patterns
+
+```
+Organization sharing:
+  - Workspace level: Share entire workspace with team
+  - View level: Share specific reports/dashboards
+  - Row-level security: Filter data by user role
+
+External sharing:
+  - Public permalink (read-only, no auth required)
+  - Embedded view (iframe, requires ZOHO_API_KEY)
+  - Email scheduled reports (PDF/CSV/Excel)
+```
+
+### Row-Level Security
+
+```sql
+-- Apply row-level filter based on logged-in user's role
+-- Configure in Analytics > Sharing > Row Level Criteria
+
+-- For sales reps: only see their own data
+"Owner_Email" = ZOHO_LOGINUSER_EMAIL
+
+-- For managers: see their team's data
+"Team" = ZOHO_LOGINUSER_ROLE
+
+-- For executives: see all data (no filter)
+-- Leave criteria blank for admin role
+```
+
+## Custom Formulas
+
+### Calculated Columns
+
+```sql
+-- Win rate percentage
+IF("Stage" = 'Closed Won', 1, 0) / COUNT("Deal_ID") * 100
+
+-- Days since last activity
+DATEDIFF(CURDATE(), "Last_Activity_Date")
+
+-- Revenue tier classification
+CASE
+    WHEN "Annual_Revenue" >= 1000000 THEN 'Enterprise'
+    WHEN "Annual_Revenue" >= 100000 THEN 'Mid-Market'
+    WHEN "Annual_Revenue" >= 10000 THEN 'SMB'
+    ELSE 'Startup'
+END
+
+-- Month-over-month growth
+("Current_Month_Revenue" - "Previous_Month_Revenue") / "Previous_Month_Revenue" * 100
+```
+
+### Aggregate Formulas
+
+```sql
+-- Weighted pipeline value
+SUM("Amount" * "Probability" / 100)
+
+-- Average deal cycle (days from creation to close)
+AVG(DATEDIFF("Closing_Date", "Created_Time"))
+
+-- Customer concentration (top customer % of revenue)
+MAX("Customer_Revenue") / SUM("Revenue") * 100
+```
+
+## Drill-Down Configuration
+
+### Setting Up Drill-Down Paths
+
+```
+Dashboard KPI: Total Revenue ($2.5M)
+    ↓ Click to drill
+Level 1: Revenue by Region (West: $1.2M, East: $800K, ...)
+    ↓ Click region
+Level 2: Revenue by Sales Rep within region
+    ↓ Click rep
+Level 3: Individual deals for that rep
+```
+
+### Configuration Steps
+
+1. Create reports for each drill level
+2. In parent report, right-click chart element > "Drill Down"
+3. Select child report
+4. Map the filter field (e.g., Region → "Region" field in child)
+5. Test drill path
+
+## Dashboard Design Best Practices
+
+### Layout Principles
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  KPI Row: 4-5 key metrics across top                     │
+│  [Revenue] [Deals Won] [Avg Deal Size] [Win Rate] [NPS] │
+├────────────────────────────┬─────────────────────────────┤
+│                            │                             │
+│  Primary Chart (60%)       │  Secondary Charts (40%)     │
+│  Revenue trend over time   │  Pipeline by stage          │
+│                            │  Top customers              │
+│                            │                             │
+├────────────────────────────┴─────────────────────────────┤
+│  Detail Table: Recent activity, upcoming renewals        │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Performance Tips
+
+1. **Limit widgets per dashboard:** 8-12 max for fast load
+2. **Use summary tables** instead of raw data for charts
+3. **Pre-aggregate** with query tables for complex calculations
+4. **Set appropriate sync frequency** - don't over-sync
+5. **Use date filters** to limit data range (last 12 months default)
+6. **Avoid cross-workspace joins** - they're slow
+
+## Scheduled Email Reports
+
+```
+Configuration:
+  Report: Monthly Revenue Dashboard
+  Recipients: leadership@company.com
+  Frequency: Monthly, 1st of month, 8:00 AM
+  Format: PDF (dashboard) + Excel (underlying data)
+  Subject: "[Auto] Monthly Revenue Report - {MONTH} {YEAR}"
+  Criteria: Last full month's data
+```
+
+### Trigger Report Email from Deluge
+
+```deluge
+// Send analytics report on demand
+try
+{
+    response = invokeUrl [
+        url: "https://analyticsapi.zoho.com/restapi/v2/workspaces/{workspace-id}/views/{view-id}/email"
+        type: POST
+        headers: {"Content-Type": "application/json"}
+        body: {
+            "to": "manager@company.com",
+            "subject": "Ad-hoc Report: " + zoho.currentdate.toString("MMM dd, yyyy"),
+            "format": "pdf",
+            "criteria": "\"Date\" >= '" + zoho.currentdate.subDay(7).toString("yyyy-MM-dd") + "'"
+        }.toString()
+        connection: "zoho-analytics-connection"
+    ];
+    info "Report email sent: " + response;
+}
+catch (e)
+{
+    info "Report email failed: " + e.toString();
+}
+```