Salesforceのフィールドが表示されない？ファントムフィールド問題の原因と解決法

#カスタムフィールドをデプロイしたのに「見えない」問題

Salesforceの開発や管理を担当していると、Metadata APIでカスタムフィールドをデプロイしたあとに「フィールドが見えない」という状況に遭遇することがあります。デプロイのログにはエラーがなく、Tooling APIで確認するとフィールドは確かに存在している。にもかかわらず、レポートビルダーに表示されない、SOQLで参照するとエラーになる、という不可解な現象です。

この問題は、FLS（Field-Level Security）が自動設定されないことが原因です。Setup UIでフィールドを手動作成した場合には発生しないため、Metadata APIを使い始めた開発者が最初に陥りやすい落とし穴と言えます。

本記事では、この「ファントムフィールド」問題の原因を特定する方法と、PermissionSetを活用した正しい解決手順を解説します。

#ファントムフィールドとは

ファントムフィールドとは、Tooling APIでは存在が確認できるにもかかわらず、SOQL、レポート、Schema Describe APIでは見えないカスタムフィールドのことを指します。メタデータ上は存在しているのに、ユーザーからはアクセスできない「幽霊」のような状態です。

Setup UIの「オブジェクトマネージャー」からフィールドを手動で作成した場合、Salesforceは作成者のAdminプロファイルにFLSを自動的に付与します。このため、手動作成ではファントムフィールドは発生しません。

一方、Metadata APIでフィールドをデプロイした場合、この「FLS自動付与」の仕組みが働きません。FLSが一切設定されないため、System Administratorプロファイルを含むすべてのユーザーに対してフィールドが非表示になります。デプロイ自体は成功しているのに、誰もフィールドにアクセスできないという状況が生まれます。

#症状と診断方法

ファントムフィールドが疑われる場合、以下の手順で診断できます。

Tooling APIで存在確認（ファントムでも見える）

sf data query \
  --query "SELECT Id, DeveloperName FROM CustomField WHERE TableEnumOrId = 'Lead' AND DeveloperName = 'MyField'" \
  --target-org myOrg \
  --use-tooling-api

このクエリでレコードが返る場合、フィールドのメタデータ自体は正常にデプロイされています。

SOQLでアクセス確認（FLS未設定なら失敗）

sf data query \
  --query "SELECT MyField__c FROM Lead LIMIT 1" \
  --target-org myOrg

FLSが未設定の場合、「No such column 'MyField__c'」というエラーが返るか、フィールドが無視されて結果に含まれません。

FieldDefinition APIで確認

Schema Describe APIやFieldDefinition SOQLで対象フィールドが返らない場合も、FLS未設定の典型的な症状です。Setup画面のオブジェクトマネージャーではフィールドが表示されることもありますが、フィールド一覧で「参照可能」のチェックが入っていないことを確認してください。

Tooling APIでは見えるがSOQLでは見えない、この差異がファントムフィールドの診断基準です。

#原因: Metadata APIとFLSの関係

この問題の根本原因は、Metadata APIとFLSが別のレイヤーで管理されていることにあります。

Metadata APIは「メタデータのデプロイ」を担当するAPIです。フィールドの定義（型、ラベル、API名など）を組織にデプロイしますが、セキュリティ設定は明示的に指定しない限り変更しません。

FLSは「セキュリティ設定」であり、どのプロファイルやPermissionSetのユーザーがどのフィールドを参照・編集できるかを制御します。メタデータの一部ではありますが、CustomFieldのデプロイとは独立した設定です。

Setup UIでの手動作成時にFLSが自動設定されるのは、Salesforceが管理者の利便性のために提供している「ショートカット機能」です。Metadata APIはプログラマティックなインターフェースであり、この暗黙的な動作を再現しません。つまり、FLSを明示的にデプロイしない限り、フィールドは存在するがアクセスできない状態になります。

#解決策: PermissionSetの同梱デプロイ

正しい解決策は、CustomFieldのデプロイ時にPermissionSetを同梱し、FLSを明示的に設定することです。

まず、PermissionSetのメタデータXMLを作成します。

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>MyField Access</label>
    <fieldPermissions>
        <editable>true</editable>
        <field>Lead.MyField__c</field>
        <readable>true</readable>
    </fieldPermissions>
</PermissionSet>

このPermissionSetをCustomFieldと一緒にデプロイし、対象ユーザーにアサインします。

sf project deploy start \
  -m CustomField:Lead.MyField__c \
  -m PermissionSet:MyFieldAccess \
  --target-org myOrg --wait 10

sf org assign permset \
  --name MyFieldAccess \
  --target-org myOrg

ProfileでFLSを設定する方法もありますが、Profileのデプロイは既存の権限設定を意図せず上書きするリスクがあります。PermissionSetは追加的な権限付与であるため、既存設定への影響が少なく、より安全です。

#既存のファントムフィールドを一括修正する方法

すでに本番環境にファントムフィールドが存在する場合は、対象フィールドをカバーするPermissionSetを作成してデプロイします。

手順としては、まずTooling APIで全カスタムフィールドを取得し、SOQLでアクセス可能なフィールドと突き合わせます。差分があるフィールドがファントムフィールドの候補です。該当フィールドすべてをカバーするPermissionSetを作成し、デプロイとアサインを行います。

さらに、CIパイプラインにFLSカバレッジのチェックを組み込むことで、今後のファントムフィールド発生を予防できます。デプロイ対象のCustomFieldに対して、対応するPermissionSetまたはProfile設定が含まれているかを検証するスクリプトを作成し、不足があればデプロイを失敗させる仕組みです。

#Apexテストでは検出できない落とし穴

注意すべき点として、ApexテストではこのFLS問題を検出できません。@isTestコンテキストで実行されるApexテストはSystem Modeで動作するため、FLSの制約を受けずにすべてのフィールドにアクセスできます。

つまり、テストが全件パスしていても、実際のユーザーがレポートやリストビューからフィールドにアクセスできないという状況が起こり得ます。FLSの問題はApexテストのカバレッジとは別のレイヤーで検証する必要があります。

WITH SECURITY_ENFORCED句やSecurity.stripInaccessible()を使ったテストであれば部分的に検出可能ですが、これらはRunning UserのFLSに依存するため、テストユーザーの設定によって結果が変わります。確実な予防には、デプロイ時のPermissionSet同梱と、CIでのメタデータ整合性チェックが必要です。

#まとめ

ファントムフィールド問題の原因は、Metadata APIがFLSを自動設定しないというSalesforceの仕様です。Setup UIでの手動作成とMetadata APIでのデプロイでは、FLSの扱いが根本的に異なります。

解決策は明確で、CustomFieldのデプロイ時にPermissionSetを同梱し、FLSを明示的に設定することです。Profileではなく、PermissionSetを使うことで既存権限への影響を最小限に抑えられます。また、CIパイプラインにFLSカバレッジのチェックを組み込むことで、ファントムフィールドの発生を未然に防止できます。

#aileadのSalesforce連携について

aileadでは、BigQueryからSalesforceへの日次データ連携パイプラインを構築・運用しており、カスタムオブジェクトの設計からPermissionSetの自動管理まで、一貫したSalesforce開発を行っています。対話データをSalesforceに構造化して連携することで、営業チームが日常的に使うSalesforceの画面上でデータ活用を進められる環境を提供しています。

Salesforceとの連携やデータ活用にご興味のある方は、お問い合わせからお気軽にご連絡ください。