cxas-configurable-dashboards

CCAI Insights Configurable Dashboards Skill

This skill guides you in authoring, refining, validating, and synchronizing Contact Center AI (CCAI) Insights Configurable Dashboards.

CCAI Insights Configurable Dashboards allow users to build customizable, multi-tab reporting views with rich visualization widgets (Score Cards, Bar/Line charts, Pie charts, Tables, Sankey diagrams) powered by Vega-Lite specifications and SQL queries against conversation metrics.

---

1. Overview & Declarative YAML Schema

Dashboards are defined declaratively in dashboards.yaml:

version: "1.0"
project_id: "your-gcp-project-id"
location: "us-central1"

dashboards:

• dashboard_id: "executive_kpis" display_name: "Executive Contact Center KPIs" description: "High-level summary of inbound call volumes, virtual agent containment, and quality." date_range: relative: quantity: 7 unit: "DAY"

  root_container: display_name: "Root" widgets: - container: display_name: "Overview Tab" description: "Operational summary metrics" widgets: # Tile 1: Total Volume Scorecard - chart: display_name: "Total Conversations" chart_visualization_type: "SCORE_CARD" width: 4 height: 3 data_source: generative_insights: sql_query: "SELECT COUNT(DISTINCT conversation_id) AS total_calls FROM conversations" chart_spec: mark: "text" encoding: text: {field: "total_calls", type: "quantitative"}

        # Tile 2: Top Contact Drivers Bar Chart
        - chart:
            display_name: "Top Contact Drivers"
            chart_visualization_type: "BAR"
            width: 8
            height: 6
            data_source:
              generative_insights:
                sql_query: >-
                  SELECT issue_category, COUNT(1) AS volume
                  FROM conversations
                  WHERE issue_category IS NOT NULL
                  GROUP BY 1
                  ORDER BY volume DESC
                  LIMIT 10
                chart_spec:
                  mark: "bar"
                  encoding:
                    x: {field: "volume", type: "quantitative", title: "Calls"}
                    y: {field: "issue_category", type: "nominal", sort: "-x", title: "Category"}
  

### Core Structural Requirements

1. **Root Container Constraint** (`ValidateDashboardStructure`):
   - Every dashboard must have a `root_container`.
   - Direct widgets in `root_container` **must all be `Container` widgets** representing tabs/sections.
2. **Widgets within Tabs**:
   - Each tab container contains child widgets (`container` for sub-grouping, `chart` for visualizations, or `chart_reference` for linked charts).
3. **Chart Visualizations**:
   - `chart_visualization_type`: `SCORE_CARD`, `BAR`, `LINE`, `AREA`, `PIE`, `SCATTER`, `TABLE`, `SANKEY`.
   - `data_source`: Contains `generative_insights` with `sql_query` and Vega-Lite `chart_spec`.

______________________________________________________________________

## 2. Vega-Lite & SQL Recipes

Refer to:
- [Dashboard SQL Cookbook & Conversations Schema Reference](references/dashboard_sql_cookbook.md) for the complete BigQuery table schema column definitions, modes, descriptions, and SQL recipes.
- [Vega-Lite Cookbook](references/vega_cookbook.md) for visualization marks, encodings, and chart templates.

### Common Patterns

- **Scorecard (Single KPI)**:
  ```yaml
  chart_visualization_type: "SCORE_CARD"
  data_source:
    generative_insights:
      sql_query: "SELECT COUNT(1) AS total FROM conversations"
      chart_spec:
        mark: "text"
        encoding:
          text: {field: "total", type: "quantitative"}

• Time Series Trend (Line Chart):

  chart_visualization_type: "LINE"
  data_source:
    generative_insights:
      sql_query: "SELECT DATE(start_time) AS date, COUNT(1) AS calls FROM conversations GROUP BY 1"
      chart_spec:
        mark: "line"
        encoding:
          x: {field: "date", type: "temporal"}
          y: {field: "calls", type: "quantitative"}
  

---

3. Step-by-Step Workflow

Step 1: Ingest Requirements

• Ask the user what operational metrics, KPIs, or tabs they need (e.g. Agent QA performance, Containment %, Top Contact Drivers, CSAT trends).
• Identify the target GCP project ID and location.

Step 2: Draft or Edit Declarative YAML

• Create or update dashboards.yaml in the user's workspace.
• Structure tabs inside root_container.widgets.
• Add scorecards, bar charts, and line charts with matching Vega-Lite specs and SQL queries.

Step 3: Compare with Active Remote Dashboards (diff)

Run diff to preview additions, modifications, and deletions:

uv run cxas insights diff-dashboards --file dashboards.yaml

Step 4: Dry-Run Deploy

Verify planned operations against GCP without mutating resources:

uv run cxas insights push-dashboards --file dashboards.yaml --dry-run

Step 5: Push to GCP

Deploy new and updated dashboards to Contact Center AI Insights:

uv run cxas insights push-dashboards --file dashboards.yaml

If deleting obsolete remote dashboards:

uv run cxas insights push-dashboards --file dashboards.yaml --force

---

4. CLI Command Reference

• Pull Remote Dashboards:

  uv run cxas insights pull-dashboards --parent projects/PROJECT_ID/locations/LOCATION [--out dashboards.yaml]
  

• Diff Dashboards:

  uv run cxas insights diff-dashboards --file dashboards.yaml
  

• Push / Sync Dashboards:

  uv run cxas insights push-dashboards --file dashboards.yaml [--dry-run] [--force]
  

• List Dashboards:

  uv run cxas insights list-dashboards --parent projects/PROJECT_ID/locations/LOCATION
  

• Get Dashboard:

  uv run cxas insights get-dashboard --dashboard-name projects/PROJECT_ID/locations/LOCATION/dashboards/DASHBOARD_ID
  

• Delete Dashboard:

  uv run cxas insights delete-dashboard --dashboard-name projects/PROJECT_ID/locations/LOCATION/dashboards/DASHBOARD_ID