CData Salesforce Driverで選択リストの値を一括編集する方法

CData Salesforce Driverで選択リストの値を一括編集する方法

Salesforce の選択リスト(Picklist)は、値が増えてくると設定画面で1件ずつ追加・修正するのが大変です。「値の一覧をまとめて編集して、一度に反映したい」という要望もよく聞きます。この記事では、CData Salesforce Driver のストアドプロシージャ MetadataRetrieve と MetadataDeploy を使って、選択リストの値をまとめて編集し、Salesforce に反映する手順を紹介します。基本はテキストエディタで XML を編集する方法です。値が多い場合に CSV(Excel)で編集できるスクリプトも、オプションとして紹介します。どの手順も実際の Salesforce 組織で動作を確認しています。

前提条件

  • CData JDBC Driver for Salesforce がインストールされ、ライセンスが有効になっていること

  • Salesforce に接続できること(Basic 認証または OAuth)

  • 接続するユーザーに「アプリケーションのカスタマイズ」と「API の有効化」の権限があること

  • XML を編集できるテキストエディタ(VS Code、サクラエディタなど。文字コード UTF-8 で保存できるもの)

  • 本番環境で作業する前に、Sandbox などの検証環境で試せること

  • (オプションのスクリプトを使う場合のみ)Python 3.9 以降

なぜ Metadata API を使うのか

選択リストの値は、レコードのデータではなく、項目の定義(メタデータ)の一部です。そのため、Account などのテーブルに対する UPDATE 文では変更できません。CData Salesforce Driver には、Salesforce Metadata API を呼び出す次の2つのストアドプロシージャが用意されています。

MetadataRetrieve:package.xml で指定したメタデータを、zip ファイルとしてダウンロードする

MetadataDeploy:zipファイル(package.xml とメタデータの XML)を組織にデプロイする

項目を新規作成する CreateCustomField というプロシージャもありますが、既存の選択リストの値を更新することはできません。

作業全体の流れは次のとおりです。

選択リストの値を編集してデプロイする流れ

設定手順

この記事では、カスタムオブジェクト CDataQATest__c にある選択リスト項目 SENTAKULIST__c(値は「選択肢1」〜「選択肢6」)を例に説明します。

1. 接続を作成する

JDBC URL の例です。SQL を実行できるツールであれば、DbVisualizer、DBeaver、Java のプログラムなど何を使ってもかまいません。

jdbc:salesforce:AuthScheme=Basic;User=[your_username];Password=[your_password];SecurityToken=[your_security_token];

Sandbox に接続する場合は UseSandbox=true; を追加します。動作確認には SELECT Id, Name FROM Organization が便利です。結果が1行返ってくれば、接続できています。

2. 取得対象を指定する package.xml を作成する

MetadataRetrieve は、何も指定しないとすべてのカスタムオブジェクトを取得します。取得する範囲が広すぎないように、package.xml で対象を絞りましょう。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
   <types>
      <members>CDataQATest__c</members>
      <name>CustomObject</name>
   </types>
   <version>63.0</version>
</Package>

選択リストの種類

<name> に書くメタデータ型

<members> に書く値の例

カスタム項目の選択リスト

CustomObject

Account / MyObject__c

グローバル値セット

GlobalValueSet

MyValueSet

標準項目の選択リスト(業種、リードソースなど)

StandardValueSet

Industry / LeadSource

3. MetadataRetrieve でメタデータを取得する

EXEC MetadataRetrieve
ManifestLocation = 'C:/work/picklist/package_retrieve.xml',
DownloadLocation = 'C:/work/picklist/retrieve',
SinglePackage = 'true'

実行結果の例:

Success

FullPath

true

C:\work\picklist\retrieve\retrieveResults.zip

ポイント①:パスはスラッシュ(/)で書く

SQL の文字列の中では、バックスラッシュ(\)がエスケープ文字として扱われます。C:\work\... と書くと \ が消えてしまい、「Should provide a valid retrieve manifest」というエラーになります。C:/work/... のように書くか、\\ と2つ重ねて書いてください。

ポイント②:DownloadLocation のフォルダは先に作っておく

存在しないフォルダを指定すると、zip が保存されません。

zip を展開すると、次のようなファイルが入っています。

retrieve/
├─ package.xml
└─ objects/
   └─ CDataQATest__c.object   ← オブジェクトの定義(項目・レイアウトなどすべて)

CDataQATest__c.object の中で、選択リストの定義は次のような形になっています。

<fields>
  <fullName>SENTAKULIST__c</fullName>
  <label>SENTAKULIST</label>
  <required>false</required>
  <trackTrending>false</trackTrending>
  <type>Picklist</type>
  <valueSet>
    <valueSetDefinition>
      <sorted>false</sorted>
        <value>
          <fullName>選択肢1</fullName>
          <default>false</default>
          <label>選択肢1</label>
        </value>

<!-- ...略... -->

    </valueSetDefinition>
  </valueSet>
</fields>

4. デプロイ用のフォルダを作る

取得した .object をそのままデプロイすると、オブジェクトのほかの項目やレイアウトまで上書きされてしまいます。そこで、対象の項目だけを含むデプロイ用のフォルダを別に作ります。

deploy/
├─ package.xml
└─ objects/
   └─ CDataQATest__c.object   ← 対象の項目(<fields>)だけを残したもの

package.xml には、メタデータ型 CustomField で「オブジェクト名.項目名」を指定します。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
   <types>
      <members>CDataQATest__c.SENTAKULIST__c</members>
      <name>CustomField</name>
   </types>
   <version>63.0</version>
</Package>

objects/CDataQATest__c.object は、取得した .object から SENTAKULIST__c の <fields>〜</fields> だけをコピーし、<CustomObject> で囲みます。

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <fields>
    <fullName>SENTAKULIST__c</fullName>
    <!-- 取得した .object の <fields> の中身をそのまま貼り付ける -->
  </fields>
</CustomObject>

編集する前に、このフォルダを丸ごとコピーしておきましょう(例:deploy_backup)。手順6と同じ方法で zip にしておけば、問題が起きたときにデプロイし直すだけで、有効な値を元の状態に戻せます。

5. 選択リストの値を編集する

テキストエディタで deploy/objects/CDataQATest__c.object を開き、<valueSetDefinition> の中の <value> を編集します。今回は、「選択肢2」のラベルを変更し、「選択肢7」を追加してみます。

        <value>
          <fullName>選択肢2</fullName>
          <default>false</default>
          <label>選択肢2(ラベル変更)</label>   <!-- ラベルを変更 -->
        </value>

<!-- ...略... -->

        <value>                                  <!-- 末尾に追加 -->
          <fullName>選択肢7</fullName>
          <default>false</default>
          <label>選択肢7</label>
        </value>
    </valueSetDefinition>

要素

意味

編集するときの注意

<fullName>

API 参照名(レコードに保存される値)

既存の値の fullName を変えると、別の値として扱われます(元の値は無効化されます)

<label>

画面に表示されるラベル

自由に変更できます

<default>

デフォルト値にするかどうか

true にできるのは1つだけです

  • <value> を並べた順番が、画面に表示される順番になります。

  • <value> を削除すると、その値は無効化されます(「よくある質問」を参照)。

  • ファイルは UTF-8 のまま保存してください。

6. zip にまとめる

deploy フォルダの中身(package.xml と objects フォルダ)を zip にまとめます。deploy フォルダごと圧縮するのではなく、zip を開いたときに package.xml がいちばん上に来るようにしてください。

Windows 10 / 11 に標準で入っている tar コマンドを使う例です。

tar -a -c -f deploy.zip -C deploy package.xml objects

PowerShell 7 を使う場合は、次のように実行します。

Compress-Archive -Path deploy\* -DestinationPath deploy.zip

7. MetadataDeploy でデプロイする

EXEC MetadataDeploy
FullPath = 'C:/work/picklist/deploy.zip',
SinglePackage = 'true',
RollbackOnError = 'true'

実行結果の例:

JobId

Success

Status

NumberComponentErrors

NumberComponentsDeployed

NumberComponentsTotal

0AfXX00000xxxxxXXX

true

Succeeded

0

1

1

  • RollbackOnError='true' を指定しておくと、エラーが起きたときに変更全体が取り消されます。

  • IgnoreWarnings='true' は、警告が出てもデプロイを完了させるオプションです。本番組織では指定しないでください(Salesforceの公式ドキュメントでも推奨されていません)。

  • デプロイに失敗した場合は、返ってきた JobId を使って MetadataDeployDetails を実行すると、エラーの詳細を確認できます。

オプション:スクリプトを使って CSV / Excel で編集する

値が数十件以上ある場合や、値の一覧を Excel で管理したい場合は、XML を直接編集するより CSV で編集したほうが楽です。記事末尾の「付録」のスクリプトを picklist_csv.py という名前で保存すると、手順4〜6を次の2つのコマンドで置き換えられます。

① 取得した .object から、選択リストの値を CSV に出力する

python picklist_csv.py export retrieve/objects/CDataQATest__c.object SENTAKULIST__c picklist.csv

Excel で文字化けしないよう、BOM 付き UTF-8 で出力されます。Excel で開いて、行の追加やラベルの変更をします。

fullName,label,default
選択肢1,選択肢1,false
選択肢2,選択肢2(ラベル変更),false
選択肢3,選択肢3,false
選択肢4,選択肢4,false
選択肢5,選択肢5,false
選択肢6,選択肢6,false
選択肢7,選択肢7,false

保存するときは「CSV UTF-8(コンマ区切り)」を選んでください。Shift_JIS の CSV で保存すると、日本語が文字化けします。

② 編集した CSV から、デプロイ用の zip を作成する

python picklist_csv.py build retrieve/objects/CDataQATest__c.object SENTAKULIST__c picklist.csv deploy.zip

手順4と同じく、対象の項目だけを含む package.xml と .object を作って zip にまとめます。できた deploy.zip は、手順7の MetadataDeploy でそのままデプロイできます。元に戻すための zip も、編集前の CSV から同じように作れます。

python picklist_csv.py export retrieve/objects/CDataQATest__c.object SENTAKULIST__c picklist_backup.csv
python picklist_csv.py build retrieve/objects/CDataQATest__c.object SENTAKULIST__c picklist_backup.csv deploy_backup.zip

動作確認

手順3と同じ MetadataRetrieve をもう一度実行し、取得した .object の SENTAKULIST__c の <value> を見ると、変更が反映されたかを確認できます。

        <value>
          <fullName>選択肢2</fullName>
          <default>false</default>
          <label>選択肢2(ラベル変更)</label>
        </value>

<!-- ...略... -->

        <value>
          <fullName>選択肢7</fullName>
          <default>false</default>
          <label>選択肢7</label>
        </value>

検証では、値の追加とラベルの変更が、どちらも Salesforce に反映されていました。

また、手順4でコピーしておいた編集前のフォルダから zip(deploy_backup.zip)を作ってデプロイすると、有効な値は元の状態に戻ります。ただし、追加した「選択肢7」は削除されず、無効な値として残ります(次の「よくある質問」を参照)。

よくある質問・トラブルシューティング

Q: XML から <value> を削除する(CSV から行を削除する)とどうなりますか?

A: その値は削除されず、無効化されます。検証では、デプロイする XML に含めなかった「選択肢7」が、管理画面の「無効な値」の一覧に移っていました。無効化された値は入力画面の選択肢には表示されませんが、既存のレコードに保存されている値はそのまま残ります。完全に削除したい場合は、管理画面の「無効な値」から削除してください。意図せず値が消えていないか、デプロイ前に必ず確認してください。

MetadataRetrieve で取得した XML には、無効な値が含まれません

検証で取得した .object には、有効な値だけが含まれていました。無効な値を有効に戻したい場合は、その値の <value> を XML(または CSV)に追加してデプロイし直すか、管理画面で「有効化」してください。

Q: レコードタイプを使っているオブジェクトでも、この手順で大丈夫ですか?

A: 項目に値を追加しただけでは、レコードタイプごとの「使用できる値」には含まれず、画面に表示されないことがあります。その場合は、.object の <recordTypes> → <picklistValues> も編集してデプロイする必要があります。

Q: 連動選択リストの関係も編集できますか?

A: 連動の関係は、同じ <valueSet> の中の <valueSettings>(controllingFieldValue)に定義されています。XML を直接編集すれば変更できます。オプションのスクリプトは値の一覧だけを扱うので、連動関係は変更できません。

Q: 標準項目(業種など)やグローバル値セットの値も変更できますか?

A: 仕組みは同じです。package.xml のメタデータ型を StandardValueSet や GlobalValueSet に変えて取得し、それぞれの XML の構造に合わせて編集します(オプションのスクリプトはカスタム項目向けです)。

まとめ

CData Salesforce DriverのMetadataRetrieveとMetadataDeployを使えば、通常の SQL では変更できない選択リストの値も、XML を編集してまとめて反映できます。安全に運用するためのポイントは次の3つです。

  • 対象の項目だけを含む zip を作ってデプロイする

  • デプロイする前に、元に戻すための zip を作っておく

  • 本番組織に反映する前に、Sandbox で動作を確認する

値が多い場合は、オプションのスクリプトを使って CSV(Excel)で編集することもできます。まずは検証環境で試してみてください。

付録:選択リスト ⇔ CSV 変換スクリプト(picklist_csv.py)

「オプション:スクリプトを使って CSV / Excel で編集する」で使うスクリプトです。Python 3.9 以降の標準ライブラリだけで動作します。

サブコマンド

使い方

export

python picklist_csv.py export <.objectファイル> <項目API名> <出力CSV>

build

python picklist_csv.py build <.objectファイル> <項目API名> <入力CSV> <出力zip>

"""Salesforce 選択リスト <-> CSV 変換ツール(CData Salesforce Driver の MetadataRetrieve / MetadataDeploy 用)

使い方:
  python picklist_csv.py export <.objectファイル> <項目API名> <出力CSV>
  python picklist_csv.py build  <.objectファイル> <項目API名> <入力CSV> <出力zip>

CSV の列: fullName(API参照名), label(表示ラベル), default(true/false)
"""
import copy
import csv
import io
import sys
import zipfile
import xml.etree.ElementTree as ET

NS = "http://soap.sforce.com/2006/04/metadata"
ET.register_namespace("", NS)
q = lambda tag: f"{{{NS}}}{tag}"


def find_field(object_path, field_name):
    root = ET.parse(object_path).getroot()
    for f in root.findall(q("fields")):
        if f.findtext(q("fullName")) == field_name:
            return f
    sys.exit(f"項目 {field_name} が {object_path} に見つかりません")


def export(object_path, field_name, csv_path):
    field = find_field(object_path, field_name)
    vsd = field.find(f"{q('valueSet')}/{q('valueSetDefinition')}")
    if vsd is None:
        sys.exit("valueSetDefinition がありません(グローバル値セットを参照している項目の可能性があります)")
    with open(csv_path, "w", newline="", encoding="utf-8-sig") as fp:
        w = csv.writer(fp)
        w.writerow(["fullName", "label", "default"])
        for v in vsd.findall(q("value")):
            w.writerow([v.findtext(q("fullName")), v.findtext(q("label")), v.findtext(q("default"))])
    print(f"{csv_path} に出力しました")


def build(object_path, field_name, csv_path, zip_path):
    object_name = object_path.replace("\\", "/").rsplit("/", 1)[-1].rsplit(".", 1)[0]
    field = copy.deepcopy(find_field(object_path, field_name))
    vsd = field.find(f"{q('valueSet')}/{q('valueSetDefinition')}")
    for v in vsd.findall(q("value")):
        vsd.remove(v)
    with open(csv_path, newline="", encoding="utf-8-sig") as fp:
        rows = list(csv.DictReader(fp))
    if not rows:
        sys.exit("CSV に値がありません")
    for r in rows:
        v = ET.SubElement(vsd, q("value"))
        ET.SubElement(v, q("fullName")).text = r["fullName"].strip()
        ET.SubElement(v, q("default")).text = (r.get("default") or "false").strip().lower()
        ET.SubElement(v, q("label")).text = (r.get("label") or r["fullName"]).strip()

    obj = ET.Element(q("CustomObject"))
    obj.append(field)
    ET.indent(obj, space="    ")
    obj_xml = io.BytesIO()
    ET.ElementTree(obj).write(obj_xml, encoding="UTF-8", xml_declaration=True)

    package_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="{NS}">
    <types>
        <members>{object_name}.{field_name}</members>
        <name>CustomField</name>
    </types>
    <version>63.0</version>
</Package>
"""
    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as z:
        z.writestr("package.xml", package_xml)
        z.writestr(f"objects/{object_name}.object", obj_xml.getvalue())
    print(f"{zip_path} を作成しました({len(rows)} 件の値)")


if __name__ == "__main__":
    if len(sys.argv) >= 5 and sys.argv[1] == "export":
        export(*sys.argv[2:5])
    elif len(sys.argv) >= 6 and sys.argv[1] == "build":
        build(*sys.argv[2:6])
    else:
        sys.exit(__doc__)