PranavNagrecha/AwesomeSalesforceSkills / skills/admin/analytics-kpi-definition
analytics-kpi-definition
VerifiedUse this skill to define, document, and validate KPI metrics for CRM Analytics — covering metric formula design, dimension selection, target-dataset modeling, benchmark setting, and the KPI register that must exist before any dashboard or lens is built. Trigger keywords: KPI definition CRM Analytics, analytics metric design, analytics target attainment, CRM Analytics measures vs dimensions, analytics benchmark. NOT for laying out the dashboard or lens itself — use admin/analytics-dashboard-design. NOT for scoping data sources, audiences, and drill-down paths — use admin/analytics-requirements-gathering.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| references/examples.md | markdown | 8.6 KB |
| references/gotchas.md | markdown | 9.1 KB |
| references/llm-anti-patterns.md | markdown | 6.4 KB |
| references/well-architected.md | markdown | 4.8 KB |
| scripts/check_analytics_kpi_definition.pyexecutable | script | 3.4 KB |
| templates/analytics-kpi-definition-template.md | markdown | 2.4 KB |
references/well-architected.md
View on GitHub# Well-Architected Notes — Analytics KPI Definition
## Relevant Pillars
- **Reliability** — A signed KPI register prevents formula disputes from invalidating delivered dashboards; KPI definitions that were built without stakeholder sign-off are frequently rejected and rebuilt at cost.
- **Operational Excellence** — The KPI register is the living documentation for all analytics metric definitions; without it, every future dashboard rebuild requires re-discovery of formulas that were never written down.
- **Security** — KPI definitions that use Opportunity or financial data must note data access and row-level security requirements; a KPI accessible to all users when it should be restricted by role hierarchy is a security misconfiguration.
- **Performance** — SAQL queries that aggregate over large datasets without proper filters are a performance risk; KPI formulas should specify filter criteria to limit dataset scan scope.
- **Scalability** — Target datasets must be designed for the reporting period cadence; a targets dataset that must be fully rebuilt for each update does not scale to long reporting histories.
## Architectural Tradeoffs
**Inline calculation vs recipe pre-aggregation:** KPI formulas can be applied at query time in SAQL (flexible but repeated per lens) or pre-aggregated in the dataset recipe (faster for fixed KPIs, less flexible). For KPIs that are queried frequently, recipe pre-aggregation is the better choice. For KPIs that vary by user-selected dimensions, SAQL query-time calculation is required.
**Fixed targets vs dimension-specific targets:** Fixed targets (one target value for the whole org) can be hardcoded in SAQL. Dimension-specific targets (targets per Owner, Region, Quarter) require a separate targets dataset joined at query time. The design choice affects how targets are maintained and updated.
## Anti-Patterns
1. **Building lenses before KPI register sign-off** — Building CRM Analytics lenses before stakeholders agree on metric formulas leads to mid-project formula changes that require complete lens rebuilds. The KPI register must be signed off before development.
2. **Storing targets inline in actuals dataset** — Adding target value columns to the actuals dataset instead of a separate targets dataset creates data model debt. Updates to targets require re-running the full actuals recipe. Separate targets datasets are the correct pattern.
3. **Confusing KPI definition with dashboard tile configuration** — KPI definition is a pre-build BA task (formula, dimensions, targets). Dashboard tile configuration (widget type, color, layout) is a development task. These must not be conflated.
## Official Sources Used
Read for this revision (2026-10-03):
- Analytics SAQL Developer Guide (Summer '26): https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/bi_dev_guide_saql.pdf. Basic Elements (case-sensitive identifiers and keywords), Comparison Operators (case-sensitive `==`, `matches`), cogroup (inner, left, right, full; quota attainment example with `coalesce()`), Aggregate Functions (`avg()`, `sum()`, `count()`, `unique()`), String Functions (`lower()`), SAQL Null Measures and Dimensions.
- Analytics Dashboard JSON Developer Guide (Summer '26): https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/bi_dev_guide_json.pdf. `measureField` formulas and the unique-count behaviour of dimension counts.
- Analytics Platform Setup Guide (Spring '26): https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/bi_admin_guide_setup.pdf. Dataset Field Limits (precision and overflow), Trending Data Limits, Localization and Internationalization (currency).
- Analytics External Data API Developer Guide (Summer '26): https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/bi_dev_guide_ext_data.pdf. Metadata JSON example and field keys, CSV format, `InsightsExternalData.Operation` values.
- Metadata API Developer Guide, Version 67.0: https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf. AnalyticsSettings (`enableWaveCustomFiscal`, `enableWaveMulticurrency`).
- Einstein Discovery REST API Developer Guide (Spring '26), local corpus: `knowledge/imports/bi-dev-guide-rest-sdd.md`. Searched for fill-rate rules; none found.
Listed in the original version and not re-read:
- Salesforce Help: Calculate Key Performance Indicators Using CRM Analytics, https://help.salesforce.com/s/articleView?id=sf.bi_kpis.htm (Salesforce Help does not fetch).
- CRM Analytics Design Principles, https://trailhead.salesforce.com/ (page retired).
- Salesforce Well-Architected Overview, https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html
## Cross-Skill References
- `admin/analytics-requirements-gathering` — upstream requirements skill that should complete before KPI definition
- `admin/saql-query-development` — downstream implementation skill using formulas from KPI register
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |