platform-report-generate

概要

Lightning Reports では、Salesforce データのクエリ、グループ化、絞り込み、表示方法を定義します。各レポートは単一の .report-meta.xml ファイルで、プロジェクトのソースディレクトリ内の reports/<FolderName>/ に配置します（ソースルートは sfdx-project.json → packageDirectories[].path で確認してください）。

重要なルール（最初にお読みください）

デプロイ失敗の主な原因 — レポートを生成する前に、以下を確認してください：

1. グループ化項目を列に含める — <groupingsDown> または <groupingsAcross> 内の項目を <columns> に含めてはいけません
2. 列名が間違っている — 列名はレポートタイプごとに異なります。必ず MCP ツールを呼び出して確認してください（references/column-names.md を参照）
3. スコープが間違っている — LeadList では organization ではなく org を使用します
4. フィルター列のドット表記 — フィルターの <column> 値にはフラット名（INDUSTRY、TYPE）を使用します。ドット表記（ACCOUNT.INDUSTRY は無効）は使用しません
5. 複数値の選択リストフィルター — カンマ区切りの <value>（例：Technology,Financial Services）を指定した <criteriaItems> を1つ使用します。booleanFilter を使って複数の criteriaItems に分割しないでください

ルール 1：フォーマットによって必須要素が決まります

フォーマット	<groupingsDown>	<groupingsAcross>	<block>
Tabular	使用不可	使用不可	不要
Summary	1つ以上（最大3つ）	使用不可	不要
Matrix	1つ以上（最大3つ）	1つ以上（最大3つ）	不要
Joined	最上位には配置不可	最上位には配置不可	2つ以上（最大5つ）

ルール 2：プラットフォームの列名を使用します

レポートのメタデータでは、未加工の API 項目名ではなく、プラットフォームのレポート列名を使用します。有効な列名を確認するには、必ず get_metadata_type_sections または get_metadata_type_context を呼び出してください。レポートタイプごとの一般的なマッピングについては、references/column-names.md を参照してください。

ルール 3：有効なレポートタイプが必要です

<reportType> には標準 API 名（例：Opportunity、AccountList、CaseList、LeadList、AccountContactRole）またはデプロイ済みのカスタムレポートタイプの開発者名を指定する必要があります。

ルール 4～5：グラフと集計には Summary/Matrix が必要です

グラフと <aggregateTypes>（Sum、Average など）は、Summary および Matrix レポートでのみ使用できます。

ルール 6～8：制限事項

• レポートごとのクロスフィルターは最大 3つで、それぞれ最大 5つの条件項目を指定できます
• <filterLogic> では、すべてのフィルターを順番に参照する必要があります（例：1 AND (2 OR 3)）
• 結合レポート：ブロックは2～5個、各ブロックのフォーマットは Summary または Matrix（Tabular は不可）

ルール 9：フォルダー構成

レポートは、対応するフォルダーのメタデータファイルがあるフォルダー内に配置する必要があります：

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

sfdx-project.json から <sourceDir> を特定してください（一般的には force-app/main/default ですが、設定で変更できます）。

ルール 10～11：日付列とスコープ

• 日付列にはプラットフォーム名を使用します（CloseDate ではなく CLOSE_DATE）
• LeadList のスコープは org、Opportunity/AccountList/CaseList のスコープは organization です

ルール 12～13：説明とグループ化

• <description> は最大 255文字です
• グループ化項目を <columns> に含めてはいけません — デプロイは自動的に失敗します

ルール 14：フォルダーメタデータには <sharedTo> が必要です

<?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>

ルール 15：有効な日付間隔のみを使用します

「今四半期」には INTERVAL_CURRENT、「今年」には INTERVAL_CURY、「過去30日間」には INTERVAL_LAST30 を使用してください。INTERVAL_CURQ は有効ではないため、使用しないでください。一覧については references/date-intervals.md を参照してください。

トップレベルの要素

要素	必須	備考
<name>	はい	レポート名（最大40文字）
<reportType>	はい	レポートタイプの API 名
<format>	はい	Tabular、Summary、Matrix、または Joined
<scope>	推奨	organization（LeadList の場合は org）
<columns>	はい	フィールド列。各列には <field> と、任意の <aggregateTypes> を指定します
<filter>	いいえ	<column>、<operator>、<value> を含む <criteriaItems> を指定します
<groupingsDown>	条件付き	行のグループ化：<field>、<dateGranularity>、<sortOrder>
<groupingsAcross>	条件付き	列のグループ化（Matrix のみ）
<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>	条件付き	Joined 形式のブロック

フィルター構文

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

複数値の選択リスト： カンマ区切りの値を指定した criteriaItem を1つ使用します：

<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 を参照してください。

生成ワークフロー

1. 要件を収集する — オブジェクト、フィールド、グループ化、フィルター、グラフの要件
2. 形式を決定する — グループ化なし → Tabular、行のグループ化 → Summary、行と列のグループ化 → Matrix、複数のオブジェクト → Joined
3. 列名を特定する — MCP ツール get_metadata_type_sections を呼び出し、レポートタイプで有効なプラットフォーム列名を取得します
4. メタデータを作成する — examples/ 内の最も近い例を基にして調整します
5. フォルダーを作成する — フォルダーディレクトリと、<folderShares> を含む <FolderName>-meta.xml を生成します
6. 検証する — references/verification-checklist.md に従って確認します

参照ファイル一覧

ファイル	読むタイミング
references/column-names.md	手順3 — レポートタイプごとの列名マッピング
references/date-intervals.md	timeFrameFilter の間隔を設定するとき
references/chart-types.md	グラフを追加するとき — 17種類すべてと legendPosition のルール
references/filter-operations.md	フィルターを作成するとき — 演算子の完全なリファレンス
references/verification-checklist.md	手順6 — デプロイ前の検証
references/errors-and-troubleshooting.md	フィールドが見つからないとき、またはデプロイに失敗したとき
examples/TabularOpportunitiesReport.report-meta.xml	Tabular レポートのテンプレート
examples/OpportunitiesByStageReport.report-meta.xml	グラフ付き Summary レポート
examples/OpportunitiesByStageAndQuarter.report-meta.xml	Matrix レポートのテンプレート
examples/AccountsCreatedThisYear.report-meta.xml	期間指定フィルター付きレポート