Overview
Lightning Reports define how Salesforce data is queried, grouped, filtered, and displayed. Each report is a single .report-meta.xml file placed under reports/<FolderName>/ within the project's source directory (check sfdx-project.json → packageDirectories[].path for the source root).
Critical Rules (Read First)
TOP DEPLOYMENT KILLERS — check these BEFORE generating any report:
- Grouping fields in columns — Fields in
<groupingsDown>or<groupingsAcross>must NEVER also appear in<columns> - Wrong column names — Column names are report-type-specific. ALWAYS call MCP tools to verify (see
references/column-names.md) - Wrong scope — LeadList uses
org, notorganization - Filter column dot notation — Filter
<column>values use FLAT names (INDUSTRY,TYPE) NOT dot notation (ACCOUNT.INDUSTRYis INVALID) - Multi-value picklist filters — Use ONE
<criteriaItems>with comma-separated<value>(e.g.,Technology,Financial Services). Do NOT split into multiple criteriaItems with booleanFilter
Rule 1: Format Determines Required Elements
Rule 2: Use Platform Column Names
Report metadata uses platform report column names, NOT raw API field names. ALWAYS call get_metadata_type_sections or get_metadata_type_context to confirm valid column names. See references/column-names.md for common mappings per report type.
Rule 3: Valid Report Type Required
<reportType> must be a standard API name (e.g., Opportunity, AccountList, CaseList, LeadList, AccountContactRole) or a deployed custom report type developer name.
Rule 4–5: Chart & Aggregates Require Summary/Matrix
Charts and <aggregateTypes> (Sum, Average, etc.) only work in Summary and Matrix reports.
Rule 6–8: Limits
- Max 3 cross-filters per report, each with up to 5 criteria items
<filterLogic>must reference all filters sequentially (e.g.,1 AND (2 OR 3))- Joined reports: 2–5 blocks, each block format must be Summary or Matrix (not Tabular)
Rule 9: Folder Structure
Reports must live inside a folder with a corresponding folder metadata file:
Determine <sourceDir> from sfdx-project.json (commonly force-app/main/default, but this is configurable).
Rule 10–11: Date Columns & Scope
- Date columns use platform names (
CLOSE_DATE, notCloseDate) - LeadList scope is
org; Opportunity/AccountList/CaseList useorganization
Rule 12–13: Description & Groupings
<description>max 255 characters- Grouping fields must NOT appear in
<columns>— automatic deployment failure
Rule 14: Folder Metadata Requires <sharedTo>
Rule 15: Valid Date Intervals Only
Use INTERVAL_CURRENT for "this quarter", INTERVAL_CURY for "this year", INTERVAL_LAST30 for last 30 days. Do NOT use INTERVAL_CURQ — it is not valid. See references/date-intervals.md for the full list.
Top-Level Elements
Filter Syntax
Multi-value picklist: Use ONE criteriaItem with comma-separated values:
Common operators: equals, notEqual, lessThan, greaterThan, contains, startsWith, includes, excludes, isBlank, notBlank. Full list in references/filter-operations.md.
Generation Workflow
- Gather Requirements — object, fields, groupings, filters, chart needs
- Determine Format — no groupings → Tabular; row groupings → Summary; row + column → Matrix; multiple objects → Joined
- Identify Column Names — call
get_metadata_type_sectionsMCP tool to get valid platform column names for the report type - Author Metadata — start from closest example in
examples/and adapt - Create Folder — generate folder directory +
<FolderName>-meta.xmlwith<folderShares> - Validate — run through
references/verification-checklist.md
