mcpField
P
platform-custom-report-type-generate

platform-custom-report-type-generate

github.com/forcedotcomデータ・データベース1.1k4.0k 回インストール1 日前に更新
リポジトリ

platform-custom-report-type-generate について

Salesforce のレポート開発向けに、主オブジェクト、関連オブジェクト、利用可能な項目を定義するカスタムレポートタイプのメタデータ作成を支援するスキルです。結合方法とデプロイ検証も扱います。

主な機能

  1. 01カスタムレポートタイプメタデータの生成
  2. 02主オブジェクトと関連オブジェクトの設定
  3. 03内部結合・外部結合の選択
  4. 04オブジェクト別のレポート項目整理
  5. 05関係パスとデプロイ設定の確認

活用シーン

  1. 01カスタムオブジェクトの組み合わせに基づくレポートタイプ作成
  2. 02関連レコードのない主レコードを含めるかの制御
  3. 03レポートビルダーで選択可能な項目の整理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-custom-report-type-generate

インストール後、Claude Code で/platform-custom-report-type-generateを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

examples/
AccountProjectsWithTasks.reportType-meta.xml
AccountsWithIndustry.reportType-meta.xml
AccountsWithProjects.reportType-meta.xml
references/
category-values.md
errors-and-troubleshooting.md

詳細

仕様

Salesforce カスタムレポートタイプのメタデータに関する知識

概要

カスタムレポートタイプ（CRT）は、Salesforce レポートのデータフレームワークを定義します。プライマリオブジェクト、最大 3 つの関連オブジェクト、それらのリレーション（結合）、およびレポートビルダーで使用できる項目を指定します。

目的

  • 標準レポートタイプでは扱えないカスタムオブジェクトやカスタムリレーションをまたいだレポートを可能にします
  • レポートビルダー向けに項目を厳選します（参照をたどって取得する項目も含みます）
  • 関連レコードのないプライマリレコードを含めるか除外するか、内部結合／外部結合の動作を制御します

設定

ファイル拡張子： .reportType-meta.xml。ファイルのベース名はレポートタイプの開発者名です（例：AccountsWithProjects.reportType-meta.xml）。各 CRT は単一のファイルであり、オブジェクトフォルダー内にはネストされません。

主な要素

トップレベルの <ReportType> の子要素：

要素必須注記
<fullName>はいAPI 識別子。ファイル名と一致する必要があります。使用できるのは英字、数字、アンダースコアです。先頭は英字にする必要があり、スペース、末尾のアンダースコア、連続するアンダースコアは使用できません
<label>はいレポートタイプの選択画面に表示される、人が読みやすい名前
<description>推奨ビジネス上の「理由」を記述します。誰が使用し、何を把握するのかを明記します
<baseObject>はいプライマリオブジェクトの API 名（例：Account、Project__c）。作成後は変更できません。カスタムオブジェクトや外部オブジェクトを含む、すべてのオブジェクトがサポートされています（外部オブジェクトは API 38.0 以降）
<category>推奨レポートビルダーのカテゴリ。references/category-values.md を参照してください
<deployed>はいユーザーに公開する場合は true、作成中や反復作業中は false にします
<join>条件付き関連オブジェクトとその結合動作を追加します。より深いリレーションには、さらに <join> ブロックをネストします
<sections>推奨レポートタイプで使用できる列のグループです。必須ではありませんが、列のないレポートは実用的ではありません

<sections>（列のグループ）の子要素：

要素必須注記
<masterLabel>はいレポートビルダーに表示されるセクション見出し
<columns>条件付きセクションで公開する項目ごとに 1 つ指定します

<columns>（単一の項目）の子要素：

要素必須注記
<field>はい項目の API 名（またはドット区切りの参照トラバーサルパス）
<table>はい項目が属するオブジェクト。ベースオブジェクト名、またはドット区切りのリレーションパスを指定します
<checkedByDefault>はいレポートビルダーでこの列をデフォルトで選択する場合は true にします
<displayNameOverride>いいえレポートビルダーに表示するカスタム列ラベル。項目のデフォルトラベルを上書きします

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

ルール 1：<fullName> を指定する場合、ファイル名と一致させる必要があります

ソース形式では、fullName は Metadata から継承され、ファイル名から導出されるため、<fullName> 要素は技術的には省略可能です。リポジトリの規約では、これを含めます。<fullName> を含める場合、その値はファイル名の .reportType-meta.xml より前の部分と完全に一致する必要があります。文字と大文字・小文字の区別、アンダースコアの位置も同一にしてください。

誤り — ファイル名と <fullName> が異なります：

  • ファイル：account_projects.reportType-meta.xml
  • <fullName>AccountProjects</fullName> （不一致：ファイルでは account_projects、fullName では AccountProjects が使用されています）

正しい — ファイル名と <fullName> が一致しています：

  • ファイル：AccountProjects.reportType-meta.xml
  • <fullName>AccountProjects</fullName>
ルール 2：結合の意味 — 含めるレコードは outerJoin で制御します

各 <join> ブロックには、レポートに表示するプライマリレコードを決定する <outerJoin> 要素があります。

<outerJoin> の値動作レポートビルダーのラベル
false内部結合 — 関連レコードが少なくとも 1 件あるプライマリレコードのみ「各「A」レコードには、少なくとも 1 件の関連する「B」レコードが必要です」
true外部結合 — 関連レコードの有無にかかわらず、すべてのプライマリレコード「「A」レコードには、関連する「B」レコードがある場合とない場合があります」

指定がない場合のデフォルト： 子レコードの有無にかかわらず、すべてのプライマリレコードを表示する場合は true（外部結合）を使用します。子レコードが存在する場合にのみレポートが意味を持つ場合は、false を使用します。

ルール 3：各オブジェクトに独自の <sections> ブロックが必要です

CRT 内のすべてのオブジェクト（プライマリオブジェクトと結合された各オブジェクト）には、レポートで使用できる項目を列挙した対応する <sections> ブロックが必要です。オブジェクトのセクションがない場合、そのオブジェクトの項目はレポートビルダーに表示されません。

  • 各セクションの <masterLabel> は、レポートビルダーのセクション見出しです
  • <columns> エントリーには項目が列挙されます。各項目には <field>（API 名）と <table>（オブジェクトの API 名）が必要です
  • 参照関係をたどって取得する項目には、<field> にリレーションパスを使用します（例：<table> を所有側オブジェクトに設定し、<field> に Owner.Name を指定）
ルール 4：ラベルではなく項目の API 名を使用します

項目には正確な API 名を使用します。標準項目には定義済みの名前（Name、CreatedDate、OwnerId）を使用し、カスタム項目には Field__c を使用します。カスタムオブジェクトには __c を付ける必要があります。

誤り：

  • <field>Account Name</field>

正しい例：

  • <table>Account</table> と <field>Name</field>
ルール 5：結合オブジェクトにはリレーションパスを使用します

<join> を追加する場合、<relationship> 要素には、子オブジェクトから親オブジェクトを参照する参照項目／主従関係項目で定義されている子リレーション名を使用する必要があります。カスタムリレーションの場合、通常は __r で終わります。

誤り：

  • <relationship>Project</relationship>（カスタム子リレーションの場合）

正しい例：

  • <relationship>Projects__r</relationship>（子リレーション名）
  • <relationship>Contacts</relationship>（標準の非カスタム子リレーション）
ルール 6：結合チェーンのオブジェクト数は最大 4 個です

1 つの CRT で結合できるオブジェクトは、最大 合計 4 個です（ベースオブジェクトと、ネストした <join> ブロックを介した追加オブジェクト最大 3 個）。

ルール 7：外部結合の後に内部結合を指定することはできません

結合チェーンに外部結合（<outerJoin>true</outerJoin>）が含まれた後は、後続のネストした結合もすべて外部結合にする必要があります。シーケンスの前の方に外部結合がある場合、その後に内部結合を指定することはできません。

誤り：

<join>
    <outerJoin>true</outerJoin>        
    <relationship>Contacts</relationship>
    <join>
        <outerJoin>false</outerJoin>   
        <relationship>Assets</relationship>
    </join>
</join>

正しい例：

<join>
    <outerJoin>true</outerJoin>
    <relationship>Contacts</relationship>
    <join>
        <outerJoin>true</outerJoin>    
        <relationship>Assets</relationship>
    </join>
</join>
ルール 8：結合オブジェクトの <table> にはドット区切りのパスを使用します

<sections> 内の <table> 要素は、結合チェーンのどのオブジェクトに各列が属するかを示します。ベースオブジェクトには、オブジェクト名をそのまま使用します（例：Account）。結合オブジェクトには、ベースオブジェクトからのドット区切りリレーションパスを使用します。

チェーン内のオブジェクト<table> の値
ベース（Account）Account
最初の結合（Account → Contacts）Account.Contacts
ネストした結合（Account → Contacts → Assets）Account.Contacts.Assets
ルール 9：項目パスでは参照関係をたどることができます

<field> の値では、ドット記法を使って参照関係をたどった項目を指定できます。たとえば、Owner.Email（所有者である User のメールアドレス）や ReportsTo.CreatedBy.Contact.Owner.MobilePhone です。<table> には、開始項目を所有するオブジェクトを指定する必要があります。

ルール 10：履歴トレンド項目には _hst サフィックスを使用します

trackTrending=true の項目では、<field> と <table> 内の API 名に _hst サフィックスを使用します。

<columns>
    <checkedByDefault>false</checkedByDefault>
    <field>Field2__c_hst</field>
    <table>CustomTrendedObject__c.CustomTrendedObject__c_hst</table>
</columns>
ルール 11：デプロイ後にプライマリオブジェクトを変更することはできません

デプロイ後、CRT の <baseObject> はロックされます。プライマリオブジェクトを変更するには、新しい CRT を作成し、古いものを廃止してください。

ルール 12：autogenerated は履歴トレンド専用です

<autogenerated> 要素（API 29.0 以降）は、オブジェクトで履歴トレンドが有効になったときに Salesforce が自動作成した CRT を示します。手動作成した CRT には、手動で設定しないでください。

生成ワークフロー

ステップ 1：要件を収集する
  • 主オブジェクトの API 名（例：Account、Project__c）
  • 関連オブジェクトと、それぞれの関係（どのオブジェクトがどのオブジェクトを参照するルックアップまたは主従関係を持つか）
  • 各関係について、内部結合（子レコードが必須）か外部結合（子レコードは任意）か
  • オブジェクトごとに公開するフィールド — 全フィールドではなく、タスクに関連するフィールドを選びます
  • 対象ユーザーとカテゴリ — レポートビルダーの選択画面のどこに表示するか
  • 現時点で deployed=true としてリリースするか、作業中は deployed=false のままにするか
ステップ 2：既存の例を確認する
  • プロジェクト内の CRT パターンを確認します
  • 既存のレポートタイプを組織から取得している場合は、その構造と比較します
ステップ 3：仕様を作成する

作成を始める前に、以下を記載します。

  • fullName と label
  • baseObject
  • カテゴリと deployed の状態
  • 結合の連鎖：関連オブジェクトごとの関係名、外部結合か内部結合か
  • セクションの構成：オブジェクトごとに 1 つのセクションと、フィールドの順序付きリスト
  • 受け入れ条件：レポート実行時に表示されるレコードと、ビルダーで使用できるフィールド
ステップ 4：メタデータファイルを作成する

examples/ 内の最も近い例を基にして、ユーザーのシナリオに合わせて調整します。

  • 主オブジェクトのみ（結合なし）→ examples/AccountsWithIndustry.reportType-meta.xml
  • 外部結合（子レコードがなくても主レコードを含める）→ examples/AccountsWithProjects.reportType-meta.xml
  • ネストされた内部結合（各レベルで子レコードが必須）→ examples/AccountProjectsWithTasks.reportType-meta.xml

ファイル名は <DeveloperName>.reportType-meta.xml にします。

ステップ 5：検証する
  • XML が整形式で、名前空間が正しいこと（xmlns="http://soap.sforce.com/2006/04/metadata"）
  • <fullName> が含まれている場合、ファイル名（.reportType-meta.xml を除く）が <fullName> と一致すること
  • <baseObject> が有効な API 名であり、オブジェクトがデプロイされていること
  • すべての <relationship> で正しい子リレーション名を使用していること（カスタムの場合は __r で終わること）
  • <sections> で参照される各オブジェクトが CRT の一部（主オブジェクトまたは結合されたオブジェクト）であること
  • すべての <field> の参照先が親の <table> に存在し、ラベルではなく API 名を使用していること
  • <category> が有効な Salesforce カテゴリ値であること
  • ユーザーが CRT にすぐアクセスする必要がある場合、<deployed> が true であること

参照ファイル一覧

ファイル確認するタイミング
examples/AccountsWithIndustry.reportType-meta.xmlステップ 2／ステップ 4 — 主オブジェクトのみのテンプレート
examples/AccountsWithProjects.reportType-meta.xmlステップ 2／ステップ 4 — 外部結合のテンプレート（子レコードがなくても主オブジェクトを含める）
examples/AccountProjectsWithTasks.reportType-meta.xmlステップ 2／ステップ 4 — ネストされた内部結合のテンプレート（各レベルで子レコードが必須）
references/category-values.mdステップ 3 — ReportTypeCategory enum から有効な <category> 値を選択する場合
references/errors-and-troubleshooting.mdレポートビルダーにフィールドが表示されない場合、または結合要件が競合する場合

検証チェックリスト

共通チェック
  • ファイル拡張子が .reportType-meta.xml である
  • ファイル名が開発者名のルールを満たしている（英字で始まり、英数字とアンダースコアのみを使用し、スペース、末尾のアンダースコア、連続するアンダースコアを含まない）
  • <fullName> が含まれている場合、ファイル名と完全に一致している（文字、大小文字、アンダースコアが同じ）
  • <label> が人にとってわかりやすく、40 文字未満である
  • <description> でビジネス上の目的を説明している
  • <baseObject> に有効な API 名を使用し、そのオブジェクトがデプロイされている
  • <category> が有効な ReportTypeCategory 列挙値である
  • <deployed> が適切に設定されている（ユーザーがアクセスできるようにする場合は true、作業中の場合は false）
  • <autogenerated> を手動で設定していない（過去のトレンド用 CRT 専用）
結合チェック
  • 各 <join> で、正しい子リレーション名を使用している（参照項目の API 名ではない）
  • カスタムリレーションには __r 接尾辞を使用している
  • <outerJoin> を意図的に設定している：true = 子オブジェクトは任意、false = 子オブジェクトは必須
  • シーケンス内で、先行する外部結合の後に内部結合（<outerJoin>false</outerJoin>）がない
  • オブジェクトの合計数（ベースオブジェクトと結合オブジェクト。ネストされたものを含む）が 4 以下である
セクションチェック
  • CRT 内の各オブジェクトに対応する <sections> ブロックがある
  • 各セクションの <masterLabel> が内容を適切に表している
  • すべての <columns> に <field>（API 名）と <table>（オブジェクトの API 名またはドット区切りパス）の両方がある
  • 各列に <checkedByDefault> を設定している
  • ベースオブジェクトの <table> がオブジェクトの API 名である（例：Account）
  • 結合オブジェクトの <table> がドット区切りのリレーションパスを使用している（例：Account.Projects__r、Account.Projects__r.Tasks__r）
  • 項目参照にラベルではなく API 名を使用している。カスタム項目には __c を使用している
  • 参照項目のたどり方にドット記法（例：Owner.Email）を使用し、開始項目を所有するオブジェクトを <table> に設定している
  • 該当する場合、過去のトレンド項目の <field> と <table> の両方に _hst 接尾辞を使用している
  • セクション内に重複する項目がない

コメント

Markdown 対応