Salesforceレポートでカラムが表示されない原因と対処法【完全ガイド】

Salesforceのレポートを作成しているとき、「追加したはずのカスタムフィールドがカラム候補に出てこない」「レポートビルダーのフィールド一覧に表示されない」という問題に直面した経験はないでしょうか。この問題は、Salesforce管理者や開発者が日常的に遭遇するトラブルのひとつです。

原因は複数考えられますが、体系的にチェックすれば必ず解決できます。本記事では、レポートでカラムが表示されない5つの主要な原因と、それぞれの具体的な対処手順を解説します。

#原因1: FLS（Field-Level Security）が未設定

レポートでカラムが見えない原因として最も多いのが、FLS（Field-Level Security）の未設定です。Salesforceでは、フィールドを作成しただけではユーザーにアクセス権が付与されません。FLSでフィールドへの参照権限が設定されていない場合、レポートビルダーのフィールド一覧にそもそも表示されません。

特に注意が必要なのは、Metadata APIやsf CLIを使ってデプロイしたフィールドです。SalesforceのUIからフィールドを作成した場合は、作成ウィザードの途中でFLSを設定できますが、Metadata APIでデプロイした場合はFLSが自動設定されません。.field-meta.xml にFLSの定義が含まれていなければ、どのProfileやPermissionSetからもアクセスできない「見えないフィールド」になります。

#確認手順

1. Setup > Object Manager から対象オブジェクトを選択
2. 「Fields & Relationships」で該当フィールドを開く
3. 「Set Field-Level Security」ボタンをクリック
4. 各ProfileやPermissionSetで「Visible」にチェックが入っているか確認

#対処方法

PermissionSetを使ってフィールドの参照権限を付与します。Profileでの設定も可能ですが、Salesforceの推奨はPermissionSet経由での権限管理です。

Setup > Permission Sets > 対象のPermissionSet > Object Settings > 対象オブジェクト
→ 該当フィールドの「Read Access」にチェック

sf CLIで一括設定する場合は、.permissionset-meta.xml にフィールド定義を追加してデプロイします。

<fieldPermissions>
    <field>CustomObject__c.CustomField__c</field>
    <editable>false</editable>
    <readable>true</readable>
</fieldPermissions>

FLSの仕組みや設計の詳細については、Salesforceの「見えないフィールド」を解消するFLS完全ガイドもあわせてご覧ください。

#原因2: レポートタイプにフィールドが未追加

カスタムレポートタイプを使っている場合、フィールドをレポートタイプのレイアウトに明示的に追加する必要があります。標準レポートタイプ（「取引先と取引先責任者」など）では、オブジェクトの全フィールドが自動で含まれます。しかし、カスタムレポートタイプではレイアウトに追加したフィールドのみがレポートビルダーに表示されます。

#確認手順

1. Setup > 「Report Types」で検索
2. 対象のカスタムレポートタイプを選択
3. 「Edit Layout」をクリック
4. 画面下部の「Fields Available for Reports」セクションに該当フィールドがあるか確認

#対処方法

「Fields Available for Reports」の右側にある「Add fields related via lookup」や、オブジェクトのフィールド一覧から該当フィールドをドラッグ＆ドロップでセクションに追加します。追加後、レポートビルダーを再度開くとフィールドが表示されます。

レポートタイプに含まれるオブジェクトが複数ある場合（A to Bのリレーション）、どのオブジェクト経由のフィールドかを正しく指定しているかも確認してください。

#原因3: PermissionSet/Profileの割当不足

FLSを正しく設定したPermissionSetが存在していても、そのPermissionSetがユーザーに割り当てられていなければ意味がありません。「FLSは設定した、でも見えない」という場合はこのケースを疑ってください。

#確認手順

1. Setup > Users > 対象ユーザーを選択
2. 「Permission Set Assignments」セクションで、該当のPermissionSetが割り当てられているか確認

#対処方法

UIから手動で割り当てるか、sf CLIで以下のコマンドを実行します。

sf org assign permset --name MyPermissionSet --target-org myOrg

複数ユーザーへの一括割当が必要な場合は、PermissionSetGroupを作成し、グループ単位で管理するのが効率的です。

#原因4: Lookupフィールドの参照方法

Lookupフィールド（参照関係フィールド）をレポートで使う際に、参照方法を誤っているケースがあります。たとえば Account__c というLookupフィールドをレポートのグルーピングに使いたい場合、Lookupフィールド自体（ID値）ではなく、参照先オブジェクトの表示用フィールドを指定する必要があります。

具体的には、Account__c ではなく Account__c.Name のように、Lookup先オブジェクトのフィールドを指定します。レポートビルダーのUI上では、Lookupフィールドを展開すると参照先のフィールドが一覧表示されるので、そこから選択してください。

#Analytics APIを使う場合

Salesforce Analytics APIで PATCH /analytics/reports/{id} を呼ぶ場合も同様です。reportMetadata.groupingsDown には、Lookup経由のフィールドAPIName（例: Account__c.Name）を設定します。

{
  "reportMetadata": {
    "groupingsDown": [
      {
        "name": "Account__c.Name",
        "sortOrder": "Asc",
        "dateGranularity": "None"
      }
    ]
  }
}

Lookupフィールド自体のAPIName（Account__c）を指定すると、グルーピングに失敗するか、ID値でグルーピングされてしまいます。

#原因5: Analytics APIでのカラム上書き事故

Salesforce Analytics APIを使ってレポートをプログラム的に操作している場合に起きやすいトラブルです。PATCH /analytics/reports/{id} エンドポイントで detailColumns を更新する際、このフィールドは差分更新ではなく全体置換として動作します。

つまり、新しいカラムだけを配列に入れてPATCHすると、既存のカラムがすべて消えてしまいます。

#正しい手順

1. まず GET /analytics/reports/{id}/describe で現在のレポート定義を取得
2. reportMetadata.detailColumns の既存配列に新しいカラムを追加
3. 既存カラム + 新規カラムの完全なリストで PATCH を実行

// 既存のレポート定義を取得
const describe = await fetch(`/analytics/reports/${reportId}/describe`);
const metadata = describe.reportMetadata;

// 既存カラムに新しいカラムを追加
const updatedColumns = [
  ...metadata.detailColumns,
  "CustomObject__c.NewField__c"
];

// 完全なリストでPATCH
await fetch(`/analytics/reports/${reportId}`, {
  method: "PATCH",
  body: JSON.stringify({
    reportMetadata: {
      detailColumns: updatedColumns
    }
  })
});

この「全体置換」の仕様は、reportFilters や groupingsDown など他のプロパティでも同様です。Analytics APIでレポートを操作する際は、常に「取得→マージ→更新」のパターンを守ってください。

#トラブルシューティングのフローチャート

レポートでカラムが表示されない場合、以下の順序で確認すると効率的に原因を特定できます。

1. フィールドが存在するか確認 → Tooling APIまたはObject Managerでフィールドの存在を確認します。存在しない場合はフィールド自体が未作成またはデプロイ失敗です。
2. SOQLでアクセスできるか確認 → Developer ConsoleやVSCodeから SELECT CustomField__c FROM CustomObject__c LIMIT 1 を実行します。エラーになる場合はFLSが未設定です（原因1）。
3. レポートビルダーのフィールド一覧に表示されるか確認 → 表示されない場合はレポートタイプの設定を確認してください（原因2）。
4. レポートにカラムを追加できるか確認 → フィールド一覧には表示されるがカラムに追加できない場合は、PermissionSetの割当を確認してください（原因3）。
5. グルーピングに使えるか確認 → Lookupフィールドの場合は参照先のフィールドを指定しているか確認してください（原因4）。

大半のケースは、ステップ2のFLS確認で原因が判明します。

#まとめ

Salesforceレポートでカラムが表示されない場合の5つの原因を整理します。

• FLS未設定: 最も多い原因。Metadata APIデプロイ時は特に注意。PermissionSetで参照権限を付与する
• レポートタイプにフィールド未追加: カスタムレポートタイプではレイアウトへの明示的な追加が必要
• PermissionSet/Profile未割当: FLSを設定してもユーザーへの割当がなければ無効
• Lookupフィールドの参照方法誤り: Lookupフィールド自体ではなく、参照先オブジェクトのフィールドを指定する
• Analytics APIでのカラム上書き: detailColumnsは全体置換。必ず既存カラムとマージしてPATCHする

予防策として、フィールド作成時にFLSの設定をセットで行うフローを標準化すること、そしてPermissionSetの設計をプロジェクト初期に決めておくことが有効です。CI/CDパイプラインに .permissionset-meta.xml のデプロイを組み込むことで、フィールド作成とFLS設定の漏れを防止できます。

#aileadのSalesforce連携について

aileadでは、Salesforceのカスタムオブジェクトにプロダクト利用データを日次で自動連携しています。対話データの構造化結果やヘルススコア、利用傾向といった情報をSalesforceのレポートやダッシュボードで可視化できるため、営業組織のデータドリブンな意思決定を支援します。

Salesforceとのデータ連携やレポート活用についてご相談がありましたら、お気軽にお問い合わせください。