【Salesforce】グローバル値セットの無効値をMetadata APIで一括有効化する手順
Salesforce のグローバル値セットで、過去に無効化した選択肢をまとめて有効化したいことがあります。
画面から 1 件ずつ有効化する方法もありますが、対象値が多い場合や、作業前後の差分を残したい場合は、Metadata API で GlobalValueSet を取得し、XML を編集してデプロイする方が確認しやすいです。
この記事では、実際の組織名、URL、顧客名、値セット名、業務固有の選択肢名を使わずに、グローバル値セットの無効値を Metadata API で一括有効化する手順を整理します。
この記事のコマンドやファイル名は公開用に一般化しています。
<PROD_ORG_ALIAS>、<SANDBOX_ORG_ALIAS>、<GLOBAL_VALUE_SET_API_NAME> などは、実際の環境に合わせて置き換えてください。
図解
作業全体の流れは次のようになります。
変更する場所は、対象の customValue にある isActive です。
まず結論
グローバル値セットの無効値を有効化する作業は、次の流れで行います。
1. 反映先の組織から GlobalValueSet を取得する
2. 対象の customValue だけ isActive を false から true に変更する
3. git diff で差分が有効化だけになっていることを確認する
4. Sandbox または検証環境で dry-run / デプロイ確認を行う
5. 本番では validate してから quick deploy する
6. 反映後に画面または再取得で有効化されたことを確認する
ポイントは、Metadata API は値セットの一部だけをパッチするのではなく、値セットのメタデータファイルを反映するという点です。
そのため、古いファイルを使ってデプロイすると、他の人が後から追加・変更した値を意図せず戻してしまう可能性があります。
グローバル値セットとは
グローバル値セットは、複数の選択リスト項目で共通利用できる選択肢の定義です。
たとえば、複数のオブジェクトで同じ「区分」「種別」「理由」などを使いたい場合、各項目に個別の選択肢を持たせるのではなく、共通のグローバル値セットを参照させることがあります。
この選択肢には、有効・無効の状態があります。
有効な値
-> 新規入力や編集画面で選択できる
無効な値
-> 既存データには残ることがあるが、新規選択肢としては使わせない
今回の作業は、無効になっている値を再び選択できるようにする作業です。
なぜ Metadata API で作業するのか
画面で作業する場合、対象値が少なければ十分です。
一方で、対象値が多い場合は、次のような理由で Metadata API の方が向いています。
- 複数の無効値をまとめて変更できる
- 変更前後の差分を
git diffで確認できる - Sandbox で検証したファイルを本番にも使いやすい
- 作業記録として、どの値を有効化したか残しやすい
- 本番反映前に validate でデプロイ可否を確認できる
ただし、便利な分だけ注意も必要です。
GlobalValueSet の XML は、値セット全体を表します。
対象値以外の行を削除したり、古いファイルを使ったりすると、意図しない差分が発生します。
前提
この記事では、次の前提で説明します。
- Salesforce CLI が利用できる
- 作業用の Salesforce DX プロジェクトがある
- Sandbox と本番組織へログイン済み、またはログイン可能である
- Git で差分確認できる状態にしている
- 変更対象のグローバル値セット API 参照名が分かっている
この記事では、次のプレースホルダーを使います。
| プレースホルダー | 意味 |
|---|---|
<GLOBAL_VALUE_SET_API_NAME> |
グローバル値セットの API 参照名 |
<SANDBOX_ORG_ALIAS> |
検証環境の Salesforce CLI Alias |
<PROD_ORG_ALIAS> |
本番組織の Salesforce CLI Alias |
<VALIDATION_JOB_ID> |
本番検証で発行されたデプロイ Job ID |
1. 作業ブランチを用意する
まず、作業用ブランチを作成します。
git switch -c enable-global-value-set-values
すでに作業ブランチを使っている場合は、この手順は不要です。
重要なのは、作業前後の差分を後から見返せる状態にすることです。
2. 対象組織から GlobalValueSet を取得する
反映先に近い組織から、対象のグローバル値セットを取得します。
sf project retrieve start \
--metadata GlobalValueSet:<GLOBAL_VALUE_SET_API_NAME> \
--target-org <SANDBOX_ORG_ALIAS>
本番へ直接反映する作業では、本番に存在する最新のメタデータを確認することも重要です。
sf project retrieve start \
--metadata GlobalValueSet:<GLOBAL_VALUE_SET_API_NAME> \
--target-org <PROD_ORG_ALIAS>
取得後、通常は次のようなファイルが作成または更新されます。
force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml
3. 取得したファイルをバックアップする
作業前の状態をすぐ戻せるように、編集前ファイルをバックアップしておきます。
mkdir -p backup
cp \
force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
backup/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml.before
Git 管理している場合でも、作業記録としてバックアップを残すと確認しやすくなります。
4. XML の isActive を変更する
取得した XML を開き、対象の customValue を探します。
無効値は、次のように isActive が false になっています。
<customValue>
<fullName>Sample_Value</fullName>
<default>false</default>
<label>Sample Value</label>
<isActive>false</isActive>
</customValue>
有効化する場合は、対象値だけ true に変更します。
<customValue>
<fullName>Sample_Value</fullName>
<default>false</default>
<label>Sample Value</label>
<isActive>true</isActive>
</customValue>
対象の無効値をすべて有効化してよい場合は、エディタの検索で次を探します。
<isActive>false</isActive>
置換後は次の形になります。
<isActive>true</isActive>
ただし、すべての無効値を本当に有効化してよいかは、必ず業務側と確認してください。
「今回の対象は一部の値だけ」という場合は、一括置換ではなく、対象の fullName と label を確認しながら個別に変更します。
5. 差分を確認する
編集後、必ず差分を確認します。
git diff -- \
force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml
確認するポイントは次のとおりです。
| 確認項目 | 見る理由 |
|---|---|
isActive 以外が変わっていないか |
意図しない値名、ラベル、並び順変更を防ぐ |
| 対象外の値を有効化していないか | 業務上使わせない値を戻さないため |
| 値セット全体が古くなっていないか | 他者の変更を上書きしないため |
| 削除差分が出ていないか | 値セットから選択肢を消さないため |
理想的な差分は、次のように false が true に変わるだけです。
- <isActive>false</isActive>
+ <isActive>true</isActive>
6. Sandbox で dry-run する
まずは Sandbox でデプロイ可能か確認します。
sf project deploy start \
--source-dir force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
--target-org <SANDBOX_ORG_ALIAS> \
--dry-run \
--test-level NoTestRun
Sandbox 側でも本番と同じテスト条件で確認したい場合は、RunLocalTests を指定します。
sf project deploy start \
--source-dir force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
--target-org <SANDBOX_ORG_ALIAS> \
--dry-run \
--test-level RunLocalTests
dry-run が成功したら、必要に応じて Sandbox に実際に反映します。
sf project deploy start \
--source-dir force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
--target-org <SANDBOX_ORG_ALIAS> \
--test-level NoTestRun
反映後、設定画面または対象の選択リスト項目で、対象値が選択できることを確認します。
7. 本番反映前に validate する
本番では、いきなり反映せず、まず validate します。
sf project deploy validate \
--source-dir force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
--target-org <PROD_ORG_ALIAS> \
--test-level RunLocalTests
成功すると、デプロイ Job ID が返ります。
Validated Deploy Request
Job ID | 0Afxxxxxxxxxxxxxxx
この Job ID を控えておきます。
本番組織の運用ルールによっては、RunLocalTests ではなく RunSpecifiedTests を指定する場合もあります。
sf project deploy validate \
--source-dir force-app/main/default/globalValueSets/<GLOBAL_VALUE_SET_API_NAME>.globalValueSet-meta.xml \
--target-org <PROD_ORG_ALIAS> \
--test-level RunSpecifiedTests \
--tests <TEST_CLASS_NAME>
テストレベルは、組織のリリースルールに合わせて決めます。
8. 本番へ quick deploy する
validate が成功したら、Job ID を使って quick deploy します。
sf project deploy quick \
--job-id <VALIDATION_JOB_ID> \
--target-org <PROD_ORG_ALIAS>
直近の検証結果を使う運用であれば、次の指定もできます。
sf project deploy quick \
--use-most-recent \
--target-org <PROD_ORG_ALIAS>
ただし、複数人で作業している環境では、別の検証 Job を拾わないように --job-id を明示する方が安全です。
9. 反映後に確認する
本番反映後は、画面または再取得で確認します。
画面で確認する場合は、対象のグローバル値セットを開き、該当する値が有効になっていることを確認します。
再取得で確認する場合は、次のように本番から取り直します。
sf project retrieve start \
--metadata GlobalValueSet:<GLOBAL_VALUE_SET_API_NAME> \
--target-org <PROD_ORG_ALIAS> \
--output-dir verify-prod
取得したファイルで、対象値の isActive が true になっていることを確認します。
<customValue>
<fullName>Sample_Value</fullName>
<default>false</default>
<label>Sample Value</label>
<isActive>true</isActive>
</customValue>
作業記録に残すとよい情報
公開記事には実名を書きませんが、社内の作業記録には次の情報を残すと後から追いやすくなります。
| 記録項目 | 内容 |
|---|---|
| 作業日 | いつ実施したか |
| 対象組織 | Sandbox / 本番など |
| 対象メタデータ | GlobalValueSet:<GLOBAL_VALUE_SET_API_NAME> |
| 対象値 | 有効化した fullName の一覧 |
| 変更内容 |
isActive=false から true への変更 |
| 検証結果 | dry-run、validate、quick deploy の結果 |
| 反映後確認 | 画面確認または再取得確認の結果 |
記事として公開する場合は、これらを次のように匿名化します。
対象組織: <SANDBOX_ORG_ALIAS> / <PROD_ORG_ALIAS>
対象値セット: <GLOBAL_VALUE_SET_API_NAME>
対象値: Sample_Value_1, Sample_Value_2, Sample_Value_3
実際の URL、組織 ID、ユーザー名、顧客名、業務固有の選択肢名は出さなくても、手順としては十分伝えられます。
よくある注意点
反映先から取得した最新版を編集する
一番避けたいのは、古い GlobalValueSet ファイルを本番へデプロイすることです。
Metadata API のデプロイは、対象メタデータをローカルファイルの内容で更新します。
そのため、他の変更が入った後の最新版を取得せずに作業すると、意図しない上書きにつながります。
値の削除と有効化を混同しない
今回の作業は、有効化です。
選択肢を削除する作業ではありません。
やること
-> <isActive>false</isActive> を <isActive>true</isActive> にする
やらないこと
-> customValue ブロックを削除する
値を削除すると、既存データや参照項目への影響確認が別途必要になります。
すべての無効値を戻してよいとは限らない
無効化されている値には、過去に業務上の理由で使わなくなったものが含まれることがあります。
そのため、false を一括で true に置換する前に、対象値の一覧を業務担当者に確認します。
依存する選択リスト項目で見え方を確認する
グローバル値セットを有効化しても、実際に使う画面、レコードタイプ、ページレイアウト、依存関係、権限によって見え方が変わることがあります。
本番反映前の検証では、値セット単体だけでなく、利用している選択リスト項目側でも確認します。
まとめ
グローバル値セットの無効値をまとめて有効化する場合、Metadata API を使うと、変更差分を確認しながら安全に作業できます。
手順の要点は次のとおりです。
-
GlobalValueSetを対象組織から取得する - 対象の
customValueだけisActive=falseからtrueにする -
git diffで差分が有効化だけであることを確認する - Sandbox で dry-run または実反映確認を行う
- 本番では validate 後に quick deploy する
- 反映後は画面または再取得で確認する
実際の組織名や URL を公開しなくても、プレースホルダーを使えば、作業の流れ、確認観点、コマンドは十分具体的に伝えられます。