WebAPIでレコードを参照する (Xrm.WebApi.retrieveRecord)

こんにちは。

今回は、WebAPIを使用してレコードを参照する方法をご紹介します。

さっそくですが、以下のシナリオを想定して実装を行ってみましょう。
・「取引先担当者」エンティティの「携帯電話」フィールドに番号が入力された際に、変更前と変更後の電話番号をアラートで表示する

JavaScriptの作成

以下のWebリソースを事前に登録しておきます。
　・名前：new_RetrieveRenrakusaki.js
　・表示名：RetrieveRenrakusaki.js
　・種類：スクリプト (JScript)
　・言語：(設定なし)
　※[テキスト エディター] ボタンを押下して、以下のJavaScriptを貼り付けて保存してください。

function RetrieveRenrakusaki(executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // 携帯電話が登録されたら変更前後の番号をアラート表示
    var id = formContext._entityReference.id.guid;
    var afterTelNo = formContext.getAttribute("mobilephone").getValue();
    Xrm.WebApi.retrieveRecord("contact", id).then(
        function success(result) {
            alert(
                "携帯電話を " + result.mobilephone + " から " + afterTelNo +
                " に変更しました。"
            );
        },
        function (error) {
            alert("携帯電話の番号を参照できませんでした。");
        }
    );
}

ここでのポイントは、入力前と入力後の携帯電話の番号を取得している点です。
入力前後のフィールド値の取得については、以下の様に整理できます。

使用するAPI	取得されるフィールド値
formContext.getAttribute	クライアント側(変更後)の値
Xrm.WebApi.retrieveRecord	サーバー側(変更前)の値

レコードを参照するために『Xrm.WebApi.retrieveRecord』というAPIを使用します。
詳しい情報は以下のリファレンスを参考にしてください。
docs.microsoft.com

JavaScriptの登録

Webリソースとして登録したJavaScriptを、取引先担当者の携帯電話が変更された際に実行されるようにします。
(1) 取引先担当者エンティティのフォームエディターから、[フォームのプロパティ] をクリックします。

(2) フォーム ライブラリ内の [追加] ボタンをクリックして、先程登録したWebリソースを追加します。

(3) 携帯電話フィールドをダブルクリックして、フィールドのプロパティから[イベント] タブを開きます。

(4)イベント ハンドラー内の [追加] ボタンをクリックして、以下の様に設定を行います。
　※「実行コンテキストを最初のパラメーターとして渡す」にチェックを入れてください。

(5)フォームエディターのリボンから [保存] をクリックして保存し、その後、[公開] をクリックして設定の反映を行います。

実装は以上で完了となります。

動作確認

それでは、実際に取引先担当者画面の携帯電話フィールドに番号を入れてみましょう。
入力後、「携帯電話を {変更前の番号} から {変更後の番号} に変更しました。」というアラートがポップアップ表示されたら成功です。