こんにちは。Sansan CIO室の李です。

さて、前回に続いてSalesforce DX(以下、SFDX)の話です。今回はSFDXの導入手順 ¹と導入プロセスにおけるTipや注意事項について話していきたいと思います。

Reminder : この記事はSalesforce CLI v46を基準に作成しています。今後Salesforce CLIバージョンアップによって構築手順が変わる可能性があります。その時は公式ドキュメントの手順をご参照ください。

概要

前回の記事でも話しましたが、SFDXの導入・運用方法はひとつに決まっていません。事前に利用環境や要件を把握し、利用状況に適する導入モデルを決めてからアクションを取ることが大事です。

導入における色々な具体的なアクションについてSansanが強く意識したポイントは２つありました。１つ目は"なるはや"でソース管理を導入する、2つ目はチームメンバーに速く使ってもらう為、導入に伴うラーニングコストを最低限にするでした。そのポイントを踏まえて決めた導入モデルが以下です：

意思決定ポイント	選択結果
モジュール化	しない
ソース管理システム	Github
Github運用ポリシー	Github Flow
開発環境	Windows(x64) / IntelliJ IDEA＋Illuminated Cloud 2
テスト環境の立ち上げ	スクリプト実装
テストデータの移行	サードパーティーツール
デプロイ	スクラッチ組織 → `dev` : CLIコマンド `dev` → `staging` : CLIコマンド `staging` → `prod` : 変更セット

各意思決定ポイントと選択結果についてもう少々細かく説明しますと、

モジュール化は相当なリソースを要すると判断し、モジュール化しない方向 ²に決定
ソース管理システムはまだ慣れていないメンバーもいた為、一番学習リソースが豊富なGithubを選定
上と同じ理由でGithub運用ポリシーも手順が簡単なGithub Flowを選定
テスト環境の立ち上げはラーニングコストの削減を意識してスクリプトを実装
テストデータの移行作業はサードパーティーツールを利用
一部のチームメンバーにprodへのアクセス権限がない為、staging → prod だけは変更とセットでデプロイ

のように、理想的な導入モデルではなくても、実際に使う側により早く、そして分かりやすく価値を与えるような導入モデルを立てました。

導入手順 (1) - セットアップ～スクラッチ組織立ち上げ

SFDXの導入は大きく４つのステップに分かれます：

SFDXの基本セットアップ
スクラッチ組織の立ち上げ
スクラッチ組織に各種メタデータをデプロイ
バージョン管理システムにメタデータを登録

まずは前半の「基本セットアップ」から「スクラッチ組織の立ち上げ」までの詳細手順について説明します。

1. Salesforce CLIのインストール

Salesforce CLIは２つのバージョンが提供されます。公式ホームページからダウンロードできるインストーラーバージョンとnode.jsのパッケージ管理ツールである npmで提供されるバージョンです。機能面では違いはないのですが、CLIのインストールやアップデートもスクリプトで行うように決めたので、non-promptが可能なnpm バージョンを利用しています。従って、ここの説明もnpmバージョンを基準として説明します：　

node.jsをインストールし、npmからsfdx-cliをインストールしてください。
```
> npm install -g sfdx-cli 
```
インストールが完了したらコマンドプロンプトを開き、以下コマンドでインストール有無を確認してください。
```
> sfdx --version
```

注意💣インストーラーバージョンとnpmバージョンを一緒にインストールすると一部処理でコンフリクトが発生する場合があります。片方はアンインストールすることをお勧めします。

2. Dev Hub組織の有効化

スクラッチ組織を作成する為には「Dev Hub組織」の指定が必要です。Dev Hub組織とは、スクラッチ組織を管理する組織のことです。Dev Hub組織は永久組織しか有効化できないため、普通は本番環境で設定します。

情報📝 よく"サンドボックスはDev Hubに指定できないからSFDXからはアクセスできないのでは？" などと質問を受けますが、Dev Hubは"スクラッチ組織の管理"だけ関係するもので、SFDXの実行に関しては関連はありません。

Dev Hub組織は次のステップで有効化できます：

本番環境にログインします
メイン画面から「設定」画面に移動します
左側のサイドバーにあるクイック検索バーに "dev hub"と入力し、「Dev Hub」をクリックします
「Dev Hubを有効化」と「ロック解除済みパッケージ (正式リリース) と第二世代管理パッケージ (ベータ) を有効化」を有効化します

3. Dev Hubの認証

Dev Hubが有効化されたら、Dev Hubの認証を行います：　

コマンドプロンプトを開き、次のコマンドを実行します
```
> sfdx force:auth:web:login -d -a {エイリアス名}
```
少し待つとログイン画面が表示されます。本番環境のID/PWを入力してログインします
ログインが成功したら、ウェブページを閉じます
コマンドプロンプトに戻り、次のコマンドを実施してdev hub環境があることを確認します
```
sfdx force:org:list --verbose --all
```

4. ローカル環境にSFDXプロジェクトフォルダーを生成

f:id:hiyo21:20190817163728p:plain — SFDXプロジェクトフォルダーの基本構成要素

各種メタデータファイルや定義ファイルを格納するフォルダーを作成します。ここで作成したフォルダーをGitで管理することになります。　

コマンドプロンプトで任意のフォルダーを作成し、そのフォルダーへ移動します。

次のコマンドを実行します：

C:\hoge> sfdx force:project:create -n {プロジェクト名}
例）
C:\hoge> sfdx force:project:create -n hoge-project
target dir = C:\hoge\hoge-project
   create sfdx-project.json
   create README.md
   create .forceignore
   create .gitignore
   create config\project-scratch-def.json
   create .vscode\settings.json
   create .vscode\launch.json
   create .vscode\extensions.json
   create .prettierrc
   create .prettierignore
   create force-app\main\default\lwc\.eslintrc.json

5. スクラッチ組織認証用のJWTトークンを作成

作成手順のリンク

Dev Hub組織の認証はウェブログインで行いましたが、スクラッチ組織の認証方法にはもう１つの選択肢があります。それがJWTトークンを利用した認証方法です。npmバージョンのSalesforce CLIを選択した理由と同じく、JWTトークン方式はnon-promptが可能な為、JWTトークン方式を選択しました。

JWTトークンの生成はこの記事のスコープ外ですので、説明は上記リンクの公式ドキュメントをご参照ください。かなり丁寧に説明されていますので、手順に沿ってデジタル証明書と非公開鍵を生成してください。

6. JWTトークン認証用接続アプリケーションを生成

前のステップで作ったデジタル証明書と非公開鍵を利用し、スクラッチ組織の認証を行う接続アプリケーションを作成します：

prod環境(本番環境)にログインし、「設定」画面へ移動します
クイック検索バーでアプリケーションと入力し、「ビルド」> 「作成」 >「アプリケーション」に移動します
「接続アプリケーション」セクションに移動し、「新規」ボタンをクリックします
必須項目の「接続アプリケーション名」、「API 参照名」、「取引先責任者メール」を入力します
「API (OAuth 設定の有効化)」＞「OAuth 設定の有効化」チェックボックスを有効化します
「コールバック URL」に"http://localhost:1717/OauthRedirect"と入力します
「デジタル署名を使用」をチェックし、前のステップで作成したデジタル証明書 (*.crt) を選択します
「選択した OAuth 範囲」にデータへのアクセスと管理 (api), ユーザに代わっていつでも要求を実行 (refresh_token、offline_access), Web 経由のデータへのアクセスを提供 (web) を追加して「保存」をクリックします
「Manage」>「Policyを編集」をクリックします
「OAuth ポリシー」セクションで「許可されているユーザ」に管理者が承認したユーザは事前承認済みを選択し、[OK] > [保存] をクリックします
「プロファイルを管理する」をクリックし、「権限セットの管理」をクリックする。この接続アプリケーションを利用するプロファイルと権限セットを選択します

注意💣ポート番号1717を既に利用中でしたら、違うポート番号を設定してsfdx-project.jsonファイルに "oauthLocalPort" : "{新しいポート番号}" という項目を追加してください

7. スクラッチ組織定義ファイルを作成

スクラッチ組織の作成時に有効化するアドオン機能や初期設定を定義します。

定義ファイルはjson形式で、以下のような構造となっています：

{
    "orgName": "hoge",  // 組織名
    "hasSampleData": "false",  // サンプルデータを投入（標準オブジェクトのみ）
    "username": "hogeUser",  // スクラッチ組織のアドミンユーザー名
    "adminEmail": "hoge@hoge.com",  // スクラッチ組織のアドミンユーザーメールアドレス
    "edition": "Developer",  // 組織のエディション
    "country": "JP",  // 組織のデフォルト国家名
    "language": "ja",  // 組織のデフォルト言語
    "features": [  // コミュニティ、Apexデバッグ、マルチ通貨などの追加機能を有効化
        "API",
        "Communities",
        "ServiceCloud"
    ],
    "settings": {  // 組織にかかわる設定や標準機能の設定を細かく制御
        "orgPreferenceSettings": {
            "networksEnabled": true,
            "s1DesktopEnabled": true,
            "s1EncryptedStoragePref2": false
        },
        "omniChannelSettings": {
            "enableOmniChannel": true
        }
    }
}

featuresとsettings については以下の設定可能なオプションを確認し、ご利用状況に合う項目を追加してください：

注意💣 features は必要な項目のみ有効化するように注意しましょう。まだ不安定なところがあり、一部項目を有効化したらunknown errorでスクラッチ組織の生成が失敗したという報告が複数あります。

8. スクラッチ組織を生成

定義ファイルまで準備できたら、やっとスクラッチ組織が作成できます。

コマンドプロンプトでprojectフォルダーへ移動し、以下コマンドでスクラッチ組織を作成します。

C:\hoge\hoge-project> sfdx force:org:create
--definitionfile {定義ファイルのパス}
--setalias {スクラッチ組織のエイリアス名}
--durationdays 30
--wait 10
--targetdevhubusername {dev hub組織のエイリアス名}
--setdefaultusername

情報📝 durationdays : スクラッチ組織は最大30日間有効です。既存スクラッチ組織の有効期限が切れたら新しいスクラッチ組織を作りましょう。

9. JWTトークンを利用してスクラッチ組織の認証を実施

以下コマンドでスクラッチ組織の認証を行います。

C:\hoge\hoge-project> sfdx force:auth:jwt:grant
--clientid {コンシューマ鍵}
--jwtkeyfile {非公開鍵のパス}
--username {取引先責任者 メール}
--instanceurl https://test.salesforce.com
--setalias {スクラッチ組織のエイリアス名}
--setdefaultusername

clientid : ステップ#6で作成した接続アプリケーションの「コンシューマ鍵」の値を入力してください。
jwtkeyfile : ステップ#5で作成した非公開鍵のパスを入力してください。
username : ステップ#6で作成した接続アプリケーションの「取引先責任者メール」を入力してください。
instanceurl : スクラッチ組織を認証する場合はhttps://test.salesforce.comを入力してください。

注意💣 スクラッチ組織を作成した直後にJWTトークン認証を行うと失敗する場合があります。スクリプトで認証を実施する方はretry機能を組み込んでください。

10. スクラッチ組織のアクセス確認

ここまで来たら初めてのスクラッチ組織が立ち上がったということですね。では早速スクラッチ組織に接続してみましょう。スクラッチ組織は force:org:open というコマンドもしくはインスタンスURLを直接叩いて接続できます：

force:org:open コマンド実行

C:\hoge\hoge-project> sfdx force:org:open -u {スクラッチ組織のエイリアス名}

インスタンスURLの確認方法

C:\hoge\hoge-project> sfdx force:org:list --verbose

f:id:hiyo21:20190817180356p:plain

導入手順 (2) - メタデータのデプロイ～バージョン管理

上記ステップでスクラッチ組織がやっと立ち上がったのですが、スクラッチ組織を作るだけでは使い道があまりないのも事実です。それは作ったばかりのスクラッチ組織には標準メタデータしか入っていないからです。

現在Salesforce組織を運用中でしたら、多かれ少なかれ組織のカスタマイズはされていると思います。そしてそのスクラッチ組織を有効活用する為には、カスタムメタデータも入れる必要があります。

このセクションでは（現行組織から）メタデータ定義の抽出からスクラッチ組織への投入、そしてバージョン管理システムへの登録までの作業について説明します。

注意💣 オブジェクト間の結合度や外部パッケージへの依存度が高ければ高い程、メタデータ定義の編集＆スクラッチ組織への投入作業が大変になります。まだ一発で解決できる方法が存在しないので、基本Trial & Errorで進むことになります。

11. ソース組織から package.xmlを抽出

まずはメタデータを抽出する組織を選択してください。

本番環境と開発環境のメタデータが一致すればどれを選択しても問題ありませんが、開発・検証環境と本番環境で差分が存在する場合は差分に対してもスクラッチ組織に投入が必要か判断した上で組織を選択するように注意してください。

SansanではSFDX導入プロジェクトと同時並行で動いているプロジェクトが複数あることと、stagingからprodまでは従来通りに変更セットでデプロイすることからstaging環境のメタデータを抽出するようにしました。

抽出対象組織が決まったら、その組織のメタデータ定義を含んでいるpackage.xmlというファイルを取得します。package.xmlの構造や詳細な説明は公式ドキュメントをご参照ください。package.xmlを抽出する方法はいくつかありますが、Salesforce.com package.xml Builderというウェブサービスがおすすめです。

情報📝環境間のメタデータの差分を検索したい場合はSalesforce Org Compareがおすすめです。

12. インストール対象の管理パッケージバージョンIDを抽出

現在ご利用中の管理パッケージがありましたら、管理パッケージにインストールする管理パッケージを選んでください。管理パッケージの数やサイズによって、スクラッチ組織の立ち上げとメタデータ投入にかかる時間が増えてしまうので開発に関わる管理パッケージのみインストールするのが理想的です。そしてサンドボックスへのインストールが制限されている管理パッケージはスクラッチ組織にもインストールできませんので、ご注意ください。

インストールする管理パッケージが決まったらコマンドプロンプトを開き、projectフォルダーへ移動して以下コマンドを実行してください：

C:\hoge\hoge-project> sfdx force:package:installed:list -u {DevHub組織のエイリアス名}

すると、インストール済み外部パッケージのリストが表示されます。Package Version ID列のIDが実際に管理パッケージをインストールする時に必要なIDです。 f:id:hiyo21:20190818190804p:plain

13. `package.xml`を編集

ダウンロードしたpackage.xmlをそのまま使ってメタデータをデプロイすると、各種エラーでデプロイが失敗する確率が非常に高いです。よって、本当に必要なメタデータのみデプロイするよう、事前にpackage.xmlを編集します。

各環境のカスタマイズ度が違うので一律的な規則があるわけではないですが、基本的に次のアドバイスに従って編集すると、trial & error の回数はかなり減らせます。

除外対象：必須
- 管理パッケージ（管理パッケージは別途インストールする為）
- 管理パッケージがインストールするカスタムコンポーネント
- インストール対象外の管理パッケージを参照するコンポーネント（参照エラーが発生する為）
- オブジェクト設定（Settingsはスクラッチ組織定義ファイルで設定）
- 標準プロファイル
- 標準リストビュー
除外対象：推薦
- レポート＆ダッシュボード＆メールテンプレート（容量が大きく、メタデータデプロイ時に容量制限に引っかかりやすい）
- コミュニティ関連機能(Site, SitedotCom, Networkなど）

14. `package.xml`からメタデータファイルを取得

Metadata APIを利用してpackage.xmlに定義されているメタデータを取得します。

コマンドプロンプトを開き、SFDXプロジェクトフォルダーへ移動します。

次のコマンドでmetadataをZIPファイルにダウンロードします。

C:\hoge\hoge-project> sfdx force:mdapi:retrieve 
-k  { package.xmlのパス }
-r { ZIPファイルのパス } 
-u { スクラッチ組織のエイリアス名 }
-w 10

retrieveコマンドが完了したら、ZIPファイルを展開します。

注意💣1回の実行で取得できるZIPファイルの最大容量は50MBですので、全体メタデータが50MBを超える場合はpackage.xmlを分けて該当コマンドを実行してください。

15. メタデータファイルをスクラッチ組織が認識できるフォーマットに変換

上記ステップでダウンロードしたメタデータファイルをスクラッチ組織が認識できるフォーマットに変換します。

コマンドプロンプトを開き、SFDXプロジェクトフォルダーへ移動します。

次のコマンドでmetadataをZIPファイルにダウンロードします。

C:\hoge\hoge-project> sfdx force:mdapi:convert
-r {展開したメタデータファイルが入っているフォルダーパス}
-d {変換したメタデータファイルを格納するフォルダーパス}

変換したメタデータファイルをproject\force-appフォルダーへ移動します。

16. sfdx-project.json ファイルを修正

スクラッチ組織へデプロイするメタデータが揃ったら、sfdx-project.jsonに関連情報を追加します。デフォルトのsfdx-project.jsonは以下のような構造となっています：

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "46.0"
}

追加対象項目は以下です：

definitionFile : メタデータデプロイ先になるスクラッチ組織の、スクラッチ組織定義ファイルのパスを入力します。
dependencies & package : スクラッチ組織作成時に依存するパッケージを指定します。packageはpackageAliasで指定したエイリアス名を入力します。
packageAlias : ステップ#12で取得したPackage Version IDとエイリアス名を入力します。

例）

{
  "packageDirectories": [
    {
      "path": "./force-app",
      "default": true,
      "definitionFile": "C:/hoge/hoge-project/config/test-project-scratch-def.json"
    },
    {
      "dependencies": [
        {
          "package": "hogePackage"
        }
      ]
    }
  ],
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "46.0",
  "packageAliases": {
    "hogePackage": "04txxxxxxxxxxxx"
  }
}

17. 管理パッケージをインストール

sfdx-project.jsonのdependenciesで指定した管理パッケージをメタデータ移行の前にインストールします。

C:\hoge\hoge-project > sfdx force:package:install
--package { パッケージバージョンID }
--securitytype AllUsers
--noprompt
--targetusername { スクラッチ組織のエイリアス名 }
--publishwait { 終了まで待機する時間(分) }
--wait { 終了まで待機する時間(分) }

18. メタデータをスクラッチ組織へpush

管理パッケージまで全部インストールできたら、いよいよメタデータのpushだけが残っています。次の手順でメタデータをpushします。

コマンドプロンプトを開き、プロジェクトフォルダーまで移動します。

次のコマンドを実行します。

c:\hoge\hoge-project> sfdx force:source:push

スクラッチ組織にログインし、[設定] → [環境] → [リリース状況] ページにアクセスします。
デプロイが終わるまで待機します。デプロイエラーが発生しなかったら次のステップへ進んでください。
デプロイ中エラーが発生したらエラーメッセージを読み取ってエラーの原因になった問題に対応してください。

問題対応が終わったら、再度メタデータをpushしてください。多くの場合、”問題対応"はpackage.xmlを修正して、mdapi:retrieve →mdapi:convert を繰り返す作業を含むため、反復作業が多く発生すると思いますので、そのプロセスを自動化するスクリプトを組むことをおすすめします。

20. Gitのリモートレポジトリーにメタデータファイルをpush

メタデータのデプロイが成功したら、そのメタデータセットがスクラッチ組織を使った開発のベースになります。チームメンバーと共有しても良い状態なのでgitのmasterブランチにcommit & pushしておきましょう。 Githubの操作やGit運用ポリシーはこの記事のスコープ外ですので、Git運用については他のリソースを活用してください。

プラグインについて

SFDXは簡単にプラグインの開発及びインストールができる為、既に有用なオープンソースプラグインが多数公開されています。その中で、個人的に良かったと思ったプラグインをいくつか皆さんに共有しますので、公式機能では解決できない問題にぶつかった場合はチェックしてみてください。

shane-sfdx-plugins : 公式コマンドがまだ支援していない機能を補う有用なコマンドが30個以上揃っています。普通はUIでしか有効化できないコミュニティ機能の有効化ができます。
sfdx-browserforce-plugin : sfdx-project.jsonのfeature , settings でまだ設定できない項目も設定してくれるヘルパープラグインです。
sfdx-migration-automatic : スクラッチ組織にカスタムオブジェクトのテストデータを取り込む必要がある場合に有用なツールです。オブジェクト間の参照関係を保ちながらインポートすることができます。

終わりに

大分長くなりましたが、これでぜひ皆さんもSFDXの導入を検討して頂ければ幸いです。コマンドベースの説明になりましたが、スクリプトやCI/CDを組み込むと尚更便利ですので少し工数をかけて導入する価値は十分あると思います。導入準備が終わった後の課題としては、チームメンバーにSFDXの使い方や開発フローの変更点についてよく知っててもらうことが挙げられます。事前に説明会やハンズオンセッションなどを開いてよりスムーズなトランジションができるようにするとチーム全体の効率が上がると思います。

そしてこれから追加される新機能やエコシステムにも期待できますね。SalesforceはSFDXを次世代の開発スタンダードとして積極的にプッシュしていて、メージャーバージョンアップデートで新しいコマンドや機能が追加されています。発表されたばかりのWinter `20 Release Note でも新しいコマンドが追加されたことを確認しました。公式コミュニティも盛り上がっていますし、オープンソースのプラグイン開発も結構されているのでぜひ使ってみてください！

footnotes

SFDXを導入する方式には複数あり、ここで説明する方式はあくまでSansanで導入した方式ということをお知らせします。他の導入方式についてはSalesforceの公式文書をご参照してください。↩
ただ、今後大規模プロジェクトがあればそのプロジェクトの内容は別モジュールにまとめるつもりです。↩

Sansan Tech Blog

Sansanのものづくりを支えるメンバーの技術やデザイン、プロダクトマネジメントの情報を発信

Salesforce DXを導入した話 Part 2

概要

導入手順 (1) - セットアップ～スクラッチ組織立ち上げ

1. Salesforce CLIのインストール

2. Dev Hub組織の有効化

3. Dev Hubの認証

4. ローカル環境にSFDXプロジェクトフォルダーを生成

5. スクラッチ組織認証用のJWTトークンを作成

6. JWTトークン認証用接続アプリケーションを生成

7. スクラッチ組織定義ファイルを作成

8. スクラッチ組織を生成

9. JWTトークンを利用してスクラッチ組織の認証を実施

10. スクラッチ組織のアクセス確認

導入手順 (2) - メタデータのデプロイ～バージョン管理

11. ソース組織から package.xmlを抽出

12. インストール対象の管理パッケージバージョンIDを抽出

13. `package.xml`を編集

14. `package.xml`からメタデータファイルを取得

15. メタデータファイルをスクラッチ組織が認識できるフォーマットに変換

16. sfdx-project.json ファイルを修正

17. 管理パッケージをインストール

18. メタデータをスクラッチ組織へpush

20. Gitのリモートレポジトリーにメタデータファイルをpush

プラグインについて

終わりに

footnotes

概要

導入手順 (1) - セットアップ～スクラッチ組織立ち上げ

1. Salesforce CLIのインストール

2. Dev Hub組織の有効化

3. Dev Hubの認証

4. ローカル環境にSFDXプロジェクトフォルダーを生成

5. スクラッチ組織認証用のJWTトークンを作成

6. JWTトークン認証用接続アプリケーションを生成

7. スクラッチ組織定義ファイルを作成

8. スクラッチ組織を生成

9. JWTトークンを利用してスクラッチ組織の認証を実施

10. スクラッチ組織のアクセス確認

導入手順 (2) - メタデータのデプロイ～バージョン管理

11. ソース組織から package.xmlを抽出

12. インストール対象の管理パッケージバージョンIDを抽出

13. package.xmlを編集

14. package.xmlからメタデータファイルを取得

15. メタデータファイルをスクラッチ組織が認識できるフォーマットに変換

16. sfdx-project.json ファイルを修正

17. 管理パッケージをインストール

18. メタデータをスクラッチ組織へpush

20. Gitのリモートレポジトリーにメタデータファイルをpush

プラグインについて

終わりに

footnotes

13. `package.xml`を編集

14. `package.xml`からメタデータファイルを取得