Salesforce スクラッチ組織の完全ガイド：開発者のための最新DXワークフロー

こんにちは、Salesforce 開発者の田中です。Salesforce プラットフォームでの開発に長年携わってきましたが、開発プロセスにおける最大の変化の一つが Salesforce DX (Developer Experience) と、その中核をなす Scratch Orgs (スクラッチ組織) の登場でした。本日は、開発者の視点から、この革新的なツールであるスクラッチ組織について、その背景からベストプラクティスまでを深く掘り下げて解説します。

背景と適用シナリオ

かつて、私たちの開発ワークフローは主に Sandbox (サンドボックス) 環境に依存していました。Developer Sandbox、Developer Pro Sandbox、Partial Copy Sandbox など、様々な種類のサンドボックスが存在しますが、共通の課題も抱えていました。

例えば、環境の準備に時間がかかること。特に、本番環境のメタデータやデータをコピーするサンドボックスのリフレッシュには、数時間から数日を要することもありました。また、複数の開発者が一つのサンドボックスを共有して開発を進めると、互いの変更が衝突（コンフリクト）し、意図しない上書きが発生することも少なくありませんでした。変更内容は組織内に直接保存されるため、バージョン管理システム（VCS）、例えば Git との連携も手作業が多く、ソースコードの追跡や管理が煩雑でした。

これらの課題を解決するために登場したのが Salesforce DX です。Salesforce DX は、ソースコードを信頼できる唯一の情報源（Source of Truth）とする「ソース駆動開発」を推進する一連のツールと手法です。その中心的な役割を担うのが、今回解説するスクラッチ組織です。

主な適用シナリオ

機能開発： 新機能やバグ修正を、他の開発者の影響を受けない完全に独立した環境で開発できます。
CI/CD パイプライン： 自動化されたテストプロセスの一環として、毎回クリーンな環境を動的に作成し、テストを実行後、破棄することができます。
パッケージ開発： 第二世代管理パッケージ（2GP）や unlocked package の開発において、名前空間を持つクリーンな環境でパッケージのバージョニングやテストを効率的に行えます。
バグの再現： 本番環境と同じ設定を持つスクラッチ組織を素早く作成し、特定のバグを再現・デバッグするのに役立ちます。

原理説明

スクラッチ組織は、一言で言えば「ソース駆動型で使い捨て可能な、設定可能な Salesforce 環境」です。従来のサンドボックスが本番組織の「コピー」であるのに対し、スクラッチ組織は設定ファイルから「新規作成」されるという点が根本的に異なります。

この仕組みを支える主要な要素は以下の通りです。

1. Dev Hub (Dev Hub 組織)

Dev Hub は、すべてのスクラッチ組織を管理・追跡する特別な権限を持つ本番組織またはトライアル組織です。どの組織を Dev Hub として使用するかを有効化すると、その組織から新しいスクラッチ組織を作成したり、既存のスクラッチ組織の一覧を確認したり、削除したりすることができます。Dev Hub は、スクラッチ組織の「親」のような存在です。

2. Salesforce CLI (SFDX)

Salesforce Command Line Interface (CLI) は、開発者がコマンドラインから Salesforce 組織を操作するための強力なツールです。スクラッチ組織の作成、ソースコードのプッシュ・プル、テストの実行、データのインポート・エクスポートなど、開発ライフサイクルのほぼすべての操作をコマンドで実行できます。これにより、手動操作を排除し、開発プロセス全体の自動化を促進します。

3. スクラッチ組織定義ファイル (project-scratch-def.json)

これがスクラッチ組織の「設計図」となるファイルです。JSON 形式で記述され、作成するスクラッチ組織のエディション（Developer, Enterpriseなど）、有効化する機能（Person Accounts, Multi-Currencyなど）、特定の組織設定（言語設定、API 設定など）を定義します。このファイルを使うことで、チーム全員が常に同じ構成のクリーンな開発環境を何度でも再現できるようになります。

典型的な開発ワークフロー

スクラッチ組織を使った開発は、以下のような流れで進みます。

認証： Salesforce CLI を使用して Dev Hub 組織にログインします。
作成： `project-scratch-def.json` ファイルを元に、CLI コマンドで新しいスクラッチ組織を作成します。
プッシュ： ローカルのプロジェクト（Apex クラス、Visualforce ページ、オブジェクト定義など）のソースコードを、作成したスクラッチ組織にデプロイ（プッシュ）します。
設定とデータ投入： 権限セットをユーザに割り当て、テスト用のサンプルデータをインポートします。
開発とテスト： スクラッチ組織内でコーディング、設定変更、単体テストなどを行います。
プル： スクラッチ組織内で行った変更（例えば、UI を使って作成した項目など）をローカルのプロジェクトに反映（プル）させます。
コミット： ローカルのソースコードの変更を Git などのバージョン管理システムにコミットします。
破棄： 開発作業が完了したら、スクラッチ組織を削除します。

このサイクルを機能単位やタスク単位で繰り返すことで、クリーンで予測可能な開発が実現します。

示例代码

ここでは、Salesforce DX プロジェクトにおける具体的なコード例を、公式ドキュメントに基づいて紹介します。

スクラッチ組織定義ファイルの例

以下は、`config/project-scratch-def.json` ファイルの一般的な例です。このファイルは、Enterprise Edition の組織を作成し、いくつかの特定の機能と設定を有効化するよう定義しています。

{
  "orgName": "DreamHouse Realty",
  "edition": "Enterprise",
  "features": ["EnableSetPasswordInApi"],
  "settings": {
    "lightningExperienceSettings": {
      "enableS1DesktopEnabled": true
    },
    "mobileSettings": {
      "enableS1EncryptedStoragePref2": false
    },
    "quoteSettings": {
        "enableQuote": true
    }
  }
}

// 詳細な解説

orgName: 作成されるスクラッチ組織の会社名を設定します。
edition: 組織のエディションを指定します。`Developer`, `Enterprise`, `Group`, `Professional`, `Personal`, `Unlimited` から選択できます。
features: 有効化したい追加機能を配列で指定します。`PersonAccounts`, `Communities`, `ServiceCloud` など、様々な機能を指定可能です。この例では、API経由でのパスワード設定を許可しています。
settings: より詳細な組織設定をオブジェクト形式で定義します。この例では Lightning Experience の有効化、モバイル設定の調整、見積もり機能の有効化を行っています。

Salesforce CLI コマンドのワークフロー

以下は、実際の開発で使われる一連の Salesforce CLI コマンドです。各コマンドには、その目的を説明するコメントを付記しています。

# 1. Dev Hub 組織にログインします。ブラウザが開き、認証を行います。
# --setalias で別名を付け、--setdefaultdevhubusername でデフォルトの Dev Hub として設定します。
sfdx auth:web:login --setalias my-dev-hub --setdefaultdevhubusername

# 2. project-scratch-def.json を元にスクラッチ組織を作成します。
# -f で定義ファイルを指定し、-a (または --setalias) で別名を付けます。
# --durationdays で有効期間（1～30日）を設定します。デフォルトは7日です。
sfdx force:org:create -f config/project-scratch-def.json -a MyScratchOrg --durationdays 7

# 3. ローカルのソースコードをスクラッチ組織にプッシュします。
sfdx force:source:push -u MyScratchOrg

# 4. 特定の権限セットをデフォルトユーザに割り当てます。
# -n で権限セット名を指定します。
sfdx force:user:permset:assign -n MyPermissionSet -u MyScratchOrg

# 5. サンプルデータをインポートします。
# SObject Tree API を使用して、関連レコードを含むデータを投入できます。
sfdx force:data:tree:import -p ./data/sample-data-plan.json -u MyScratchOrg

# 6. Apex テストを実行し、結果を人間が読みやすい形式で表示します。
sfdx force:apex:test:run --resultformat human -u MyScratchOrg

# 7. ブラウザでスクラッチ組織を開きます。
sfdx force:org:open -u MyScratchOrg

# 8. 組織で行った変更（UIでの設定変更など）をローカルにプルします。
sfdx force:source:pull -u MyScratchOrg

# 9. 作業が完了したら、スクラッチ組織を削除のキューに入れます。
sfdx force:org:delete -u MyScratchOrg -p

注：上記のコマンドや `project-scratch-def.json` の設定オプションは、Salesforce Developer の公式ドキュメントで詳細を確認できます。

注意事項

スクラッチ組織を効果的に活用するためには、いくつかの重要な注意点を理解しておく必要があります。

権限 (Permissions)

スクラッチ組織を作成するには、Dev Hub 組織にログインするユーザに適切な権限が必要です。具体的には、`Salesforce DX` 権限セットライセンスと、それに対応する権限セットがユーザに割り当てられている必要があります。これがなければ、`force:org:create` コマンドは失敗します。

API 制限 (API Limits)

Dev Hub 組織には、作成できるスクラッチ組織の数に上限があります。この上限は、Dev Hub 組織の Salesforce エディションによって異なります。

アクティブなスクラッチ組織の制限： 同時に存在できるスクラッチ組織の数。
日次スクラッチ組織作成制限： 24時間以内に作成できるスクラッチ組織の数。

現在の制限値と使用状況は、`sfdx force:limits:api:display -u ` コマンドで確認できます。大規模なチームや CI/CD パイプラインで頻繁にスクラッチ組織を作成する場合、この制限に達しないよう管理することが重要です。

有効期間とデータの永続性

スクラッチ組織は一時的な環境です。作成時に設定した有効期間（最大30日）を過ぎると自動的に削除されます。重要なデータやメタデータを永続化させたい場合は、必ずローカルのプロジェクトに `force:source:pull` し、バージョン管理システムにコミットしてください。スクラッチ組織は、永続的なデータを保管する場所ではありません。

エラー処理 (Error Handling)

`force:source:push` コマンドが失敗する一般的な原因は、メタデータの依存関係の欠如です。例えば、カスタム項目を含むページレイアウトをプッシュしようとした際に、そのカスタム項目がまだ組織に存在しない場合などです。このようなエラーを解決するには、`package.xml` やソースファイルの依存関係を正しく管理することが求められます。Unlocked Package を利用して依存関係をモジュール化することも有効な解決策です。

まとめとベストプラクティス

スクラッチ組織は、現代の Salesforce 開発に不可欠なツールです。これにより、開発者は独立したクリーンな環境で迅速に開発・テストを行い、チーム全体の生産性を飛躍的に向上させることができます。

最後に、スクラッチ組織を最大限に活用するためのベストプラクティスをいくつか紹介します。

バージョン管理システムを信頼できる唯一の情報源とする

組織の状態ではなく、Git リポジトリにあるソースコードが常に「正」であるという原則を徹底します。すべての変更はローカルで行い、バージョン管理システムにコミットし、そこから組織にプッシュするのが理想的な流れです。
セットアップを完全に自動化する

スクラッチ組織の作成、ソースのプッシュ、権限セットの割り当て、テストデータの投入といった一連のプロセスをシェルスクリプトなどにまとめて自動化しましょう。これにより、誰でもワンコマンドで一貫した開発環境を構築できるようになり、CI/CD パイプラインへの組み込みも容易になります。
タスクごとに短いライフサイクルの組織を使う

一つのスクラッチ組織を長期間使い回すのではなく、一つの機能開発や一つのバグ修正が完了したらすぐに破棄し、次のタスクでは新しいスクラッチ組織を作成することを習慣づけましょう。これにより、常にクリーンな状態から作業を開始できます。
組織の「形」を適切に定義する

`project-scratch-def.json` ファイルを慎重に設計し、開発に必要な機能や設定を正確に、しかし過不足なく定義します。これにより、開発環境と本番環境の差異に起因する問題を最小限に抑えることができます。

スクラッチ組織を使いこなすことは、Salesforce 開発者としてのスキルを一段階引き上げることにつながります。ぜひ、日々の開発業務に取り入れて、その効果を実感してください。

にゃんこのSalesforce日記

このブログを検索