platform-report-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

Lightning Reports定义了Salesforce数据的查询、分组、筛选和显示方式。每个报表对应一个单独的

.report-meta.xml

文件，存放于项目源目录下的

reports/<FolderName>/

路径中（可查看

sfdx-project.json

→

packageDirectories[].path

获取源根目录）。

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
```
, not
```
organization
```
Filter column dot notation — Filter
```
<column>
```
values use FLAT names (
```
INDUSTRY
```
,
```
TYPE
```
) NOT dot notation (
```
ACCOUNT.INDUSTRY
```
is 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

部署失败头号原因 — 生成任何报表前务必检查以下内容：

列中的分组字段 —
```
<groupingsDown>
```
或
```
<groupingsAcross>
```
中的字段绝对不能同时出现在
```
<columns>
```
中
错误的列名 — 列名是特定于报表类型的。务必调用MCP工具进行验证（详见
```
references/column-names.md
```
）
错误的作用域 — LeadList使用
```
org
```
，而非
```
organization
```
筛选器列的点表示法 — 筛选器
```
<column>
```
值使用扁平名称（如
```
INDUSTRY
```
、
```
TYPE
```
），不使用点表示法（
```
ACCOUNT.INDUSTRY
```
是无效的）
多值选择列表筛选器 — 使用一个
```
<criteriaItems>
```
，其中
```
<value>
```
用逗号分隔（例如
```
Technology,Financial Services
```
）。请勿拆分为多个带booleanFilter的criteriaItems

Rule 1: Format Determines Required Elements

规则1：格式决定必填元素

Format	`<groupingsDown>`	`<groupingsAcross>`	`<block>`
`Tabular`	Not allowed	Not allowed	No
`Summary`	At least 1 (max 3)	Not allowed	No
`Matrix`	At least 1 (max 3)	At least 1 (max 3)	No
`Joined`	Not at top level	Not at top level	At least 2 (max 5)

格式	`<groupingsDown>`	`<groupingsAcross>`	`<block>`
`Tabular`	不允许	不允许	无
`Summary`	至少1个（最多3个）	不允许	无
`Matrix`	至少1个（最多3个）	至少1个（最多3个）	无
`Joined`	不允许在顶层	不允许在顶层	至少2个（最多5个）

Rule 2: Use Platform Column Names

规则2：使用平台列名

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.

报表元数据使用平台报表列名，而非原始API字段名。务必调用
get_metadata_type_sections
或
get_metadata_type_context
确认有效的列名。详见

references/column-names.md

中各报表类型的常见映射关系。

Rule 3: Valid Report Type Required

规则3：需要有效的报表类型

<reportType>

must be a standard API name (e.g.,

Opportunity

AccountList

CaseList

LeadList

AccountContactRole

) or a deployed custom report type developer name.

<reportType>

必须是标准API名称（例如

Opportunity

、

AccountList

、

CaseList

、

LeadList

、

AccountContactRole

）或已部署的自定义报表类型开发者名称。

Rule 4–5: Chart & Aggregates Require Summary/Matrix

规则4–5：图表与聚合仅支持汇总/矩阵报表

Charts and

<aggregateTypes>

(Sum, Average, etc.) only work in Summary and Matrix reports.

图表和

<aggregateTypes>

（求和、平均值等）仅在汇总报表和矩阵报表中生效。

Rule 6–8: Limits

规则6–8：限制条件

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)

每个报表最多支持3个交叉筛选器，每个筛选器最多包含5个条件项
```
<filterLogic>
```
必须按顺序引用所有筛选器（例如
```
1 AND (2 OR 3)
```
）
联合报表：包含2–5个块，每个块的格式必须为汇总或矩阵（不能是表格）

Rule 9: Folder Structure

规则9：文件夹结构

Reports must live inside a folder with a corresponding folder metadata file:

xml

<sourceDir>/reports/<FolderName>/<ReportName>.report-meta.xml
<sourceDir>/reports/<FolderName>-meta.xml

Determine

<sourceDir>

from

sfdx-project.json

(commonly

force-app/main/default

, but this is configurable).

报表必须存放在包含对应文件夹元数据文件的目录中：

xml

<sourceDir>/reports/<FolderName>/<ReportName>.report-meta.xml
<sourceDir>/reports/<FolderName>-meta.xml

从

sfdx-project.json

中确定

<sourceDir>

（通常为

force-app/main/default

，但可配置）。

Rule 10–11: Date Columns & Scope

规则10–11：日期列与作用域

Date columns use platform names (
```
CLOSE_DATE
```
, not
```
CloseDate
```
)
LeadList scope is
```
org
```
; Opportunity/AccountList/CaseList use
```
organization
```

日期列使用平台名称（
```
CLOSE_DATE
```
，而非
```
CloseDate
```
）
LeadList的作用域为
```
org
```
；Opportunity/AccountList/CaseList使用
```
organization
```

Rule 12–13: Description & Groupings

规则12–13：描述与分组

```
<description>
```
max 255 characters
Grouping fields must NOT appear in
```
<columns>
```
— automatic deployment failure

```
<description>
```
最多255个字符
分组字段绝对不能出现在
```
<columns>
```
中 — 否则会导致部署失败

Rule 14: Folder Metadata Requires

<sharedTo>

规则14：文件夹元数据需要

<sharedTo>

xml

<?xml version="1.0" encoding="UTF-8"?>
<ReportFolder xmlns="http://soap.sforce.com/2006/04/metadata">
    <folderShares>
        <accessLevel>Manage</accessLevel>
        <sharedTo>AllInternalUsers</sharedTo>
        <sharedToType>Group</sharedToType>
    </folderShares>
    <name>My Report Folder</name>
</ReportFolder>

xml

<?xml version="1.0" encoding="UTF-8"?>
<ReportFolder xmlns="http://soap.sforce.com/2006/04/metadata">
    <folderShares>
        <accessLevel>Manage</accessLevel>
        <sharedTo>AllInternalUsers</sharedTo>
        <sharedToType>Group</sharedToType>
    </folderShares>
    <name>My Report Folder</name>
</ReportFolder>

Rule 15: Valid Date Intervals Only

规则15：仅允许有效的日期间隔

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.

使用

INTERVAL_CURRENT

表示“本季度”，

INTERVAL_CURY

表示“本年”，

INTERVAL_LAST30

表示“最近30天”。请勿使用

INTERVAL_CURQ

— 该值无效。完整列表详见

references/date-intervals.md

。

Top-Level Elements

顶层元素

Element	Required	Notes
`<name>`	Yes	Report name (max 40 chars)
`<reportType>`	Yes	Report type API name
`<format>`	Yes	`Tabular` , `Summary` , `Matrix` , or `Joined`
`<scope>`	Recommended	`organization` (or `org` for LeadList)
`<columns>`	Yes	Field columns — each has `<field>` and optional `<aggregateTypes>`
`<filter>`	No	Contains `<criteriaItems>` with `<column>` , `<operator>` , `<value>`
`<groupingsDown>`	Conditional	Row groupings: `<field>` , `<dateGranularity>` , `<sortOrder>`
`<groupingsAcross>`	Conditional	Column groupings (Matrix only)
`<timeFrameFilter>`	Recommended	`<dateColumn>` , `<interval>` , optional `<startDate>` / `<endDate>`
`<chart>`	No	See `references/chart-types.md`
`<buckets>`	No	Bucket field definitions
`<crossFilters>`	No	Cross-object filters ( `with` / `without` )
`<showDetails>`	Recommended	`true` / `false`
`<showGrandTotal>`	Recommended	`true` / `false`
`<showSubTotals>`	Recommended	`true` / `false`
`<description>`	Recommended	Business purpose (max 255 chars)
`<block>`	Conditional	Joined format blocks

元素	是否必填	说明
`<name>`	是	报表名称（最多40个字符）
`<reportType>`	是	报表类型API名称
`<format>`	是	`Tabular` 、 `Summary` 、 `Matrix` 或 `Joined`
`<scope>`	推荐	`organization` （LeadList使用 `org` ）
`<columns>`	是	字段列 — 每个列包含 `<field>` 和可选的 `<aggregateTypes>`
`<filter>`	否	包含 `<criteriaItems>` ，其中包含 `<column>` 、 `<operator>` 、 `<value>`
`<groupingsDown>`	条件必填	行分组： `<field>` 、 `<dateGranularity>` 、 `<sortOrder>`
`<groupingsAcross>`	条件必填	列分组（仅矩阵报表支持）
`<timeFrameFilter>`	推荐	`<dateColumn>` 、 `<interval>` ，可选 `<startDate>` / `<endDate>`
`<chart>`	否	详见 `references/chart-types.md`
`<buckets>`	否	桶字段定义
`<crossFilters>`	否	跨对象筛选器（ `with` / `without` ）
`<showDetails>`	推荐	`true` / `false`
`<showGrandTotal>`	推荐	`true` / `false`
`<showSubTotals>`	推荐	`true` / `false`
`<description>`	推荐	业务用途（最多255个字符）
`<block>`	条件必填	联合格式的块

Filter Syntax

筛选器语法

xml

<filter>
    <criteriaItems>
        <column>STAGE_NAME</column>
        <operator>equals</operator>
        <value>Closed Won</value>
    </criteriaItems>
</filter>

Multi-value picklist: Use ONE criteriaItem with comma-separated values:

xml

<criteriaItems>
    <column>INDUSTRY</column>
    <operator>equals</operator>
    <value>Technology,Financial Services</value>
</criteriaItems>

Common operators:

equals

notEqual

lessThan

greaterThan

contains

startsWith

includes

excludes

isBlank

notBlank

. Full list in

references/filter-operations.md

xml

<filter>
    <criteriaItems>
        <column>STAGE_NAME</column>
        <operator>equals</operator>
        <value>Closed Won</value>
    </criteriaItems>
</filter>

多值选择列表： 使用一个criteriaItem，值用逗号分隔：

xml

<criteriaItems>
    <column>INDUSTRY</column>
    <operator>equals</operator>
    <value>Technology,Financial Services</value>
</criteriaItems>

常用运算符：

equals

、

notEqual

、

lessThan

、

greaterThan

、

contains

、

startsWith

、

includes

、

excludes

、

isBlank

、

notBlank

。完整列表详见

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_sections
```
MCP 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.xml
```
with
```
<folderShares>
```
Validate — run through
```
references/verification-checklist.md
```

收集需求 — 对象、字段、分组、筛选器、图表需求
确定格式 — 无分组→表格报表；行分组→汇总报表；行+列分组→矩阵报表；多对象→联合报表
确认列名 — 调用
```
get_metadata_type_sections
```
MCP工具获取对应报表类型的有效平台列名
编写元数据 — 从
```
examples/
```
中选择最接近的示例进行修改
创建文件夹 — 生成文件夹目录 + 包含
```
<folderShares>
```
的
```
<FolderName>-meta.xml
```
文件
验证 — 按照
```
references/verification-checklist.md
```
进行检查

Reference File Index

参考文件索引

File	When to read
`references/column-names.md`	Step 3 — column name mappings per report type
`references/date-intervals.md`	When setting timeFrameFilter intervals
`references/chart-types.md`	When adding a chart — all 17 types + legendPosition rules
`references/filter-operations.md`	When building filters — complete operator reference
`references/verification-checklist.md`	Step 6 — pre-deploy validation
`references/errors-and-troubleshooting.md`	When fields are missing or deployment fails
`examples/TabularOpportunitiesReport.report-meta.xml`	Tabular report template
`examples/OpportunitiesByStageReport.report-meta.xml`	Summary report with chart
`examples/OpportunitiesByStageAndQuarter.report-meta.xml`	Matrix report template
`examples/AccountsCreatedThisYear.report-meta.xml`	Filtered report with time frame

文件	阅读时机
`references/column-names.md`	步骤3 — 各报表类型的列名映射
`references/date-intervals.md`	设置timeFrameFilter间隔时
`references/chart-types.md`	添加图表时 — 全部17种类型 + 图例位置规则
`references/filter-operations.md`	构建筛选器时 — 完整运算符参考
`references/verification-checklist.md`	步骤6 — 部署前验证
`references/errors-and-troubleshooting.md`	字段缺失或部署失败时
`examples/TabularOpportunitiesReport.report-meta.xml`	表格报表模板
`examples/OpportunitiesByStageReport.report-meta.xml`	带图表的汇总报表
`examples/OpportunitiesByStageAndQuarter.report-meta.xml`	矩阵报表模板
`examples/AccountsCreatedThisYear.report-meta.xml`	带时间范围的筛选报表

platform-report-generate

Original

Translation

Overview

概述

Critical Rules (Read First)

关键规则（请先阅读）

Rule 1: Format Determines Required Elements

规则1：格式决定必填元素

Rule 2: Use Platform Column Names

规则2：使用平台列名

Rule 3: Valid Report Type Required

规则3：需要有效的报表类型

Rule 4–5: Chart & Aggregates Require Summary/Matrix

规则4–5：图表与聚合仅支持汇总/矩阵报表

Rule 6–8: Limits

规则6–8：限制条件

Rule 9: Folder Structure

规则9：文件夹结构

Rule 10–11: Date Columns & Scope

规则10–11：日期列与作用域

Rule 12–13: Description & Groupings

规则12–13：描述与分组

Rule 14: Folder Metadata Requires
`<sharedTo>`

规则14：文件夹元数据需要
`<sharedTo>`

Rule 15: Valid Date Intervals Only

规则15：仅允许有效的日期间隔

Top-Level Elements

顶层元素

Filter Syntax

筛选器语法

Generation Workflow

生成流程

Reference File Index

参考文件索引

platform-report-generate

Original

Translation

Overview

概述

Critical Rules (Read First)

关键规则（请先阅读）

Rule 1: Format Determines Required Elements

规则1：格式决定必填元素

Rule 2: Use Platform Column Names

规则2：使用平台列名

Rule 3: Valid Report Type Required

规则3：需要有效的报表类型

Rule 4–5: Chart & Aggregates Require Summary/Matrix

规则4–5：图表与聚合仅支持汇总/矩阵报表

Rule 6–8: Limits

规则6–8：限制条件

Rule 9: Folder Structure

规则9：文件夹结构

Rule 10–11: Date Columns & Scope

规则10–11：日期列与作用域

Rule 12–13: Description & Groupings

规则12–13：描述与分组

Rule 14: Folder Metadata Requires <sharedTo>

规则14：文件夹元数据需要<sharedTo>

Rule 15: Valid Date Intervals Only

规则15：仅允许有效的日期间隔

Top-Level Elements

顶层元素

Filter Syntax

筛选器语法

Generation Workflow

生成流程

Reference File Index

参考文件索引

Rule 14: Folder Metadata Requires
`<sharedTo>`

规则14：文件夹元数据需要
`<sharedTo>`