Tech Dynamics 365 (CRM)

Microsoft Dynamics 365 (CRM) を中心とした技術情報を提供しています。

【API紹介】formContext.data.entity編

こんにちは。

今回から、複数回に分けてDynamics 365 (CRM) で使用可能なAPIの紹介を行っていきたいと思います。

紹介にあたり、基本的には以下の様なポリシーに沿って記事を更新していければと考えています。
・全ての関数を紹介するわけではなく、比較的使用頻度が高く、使えそうな関数に絞る。
・どのようなシーンで利用できそうか、具体的な説明をできる限り紹介する。
APIの構文やパラメータを紹介しつつ、実際に動くソースコードを書いてみる。

記念すべき第1回目は、『formContext.data.entity』の中から5つの関数を紹介します。


formContext.data.entity の概要

Microsoft社のAPI一覧では以下の様に説明されていますが、要するに「フォーム(OnLoad、OnSave)やフィールド(OnChange)のイベントハンドラーで使ってね」ということです。

ページに表示されるレコードに固有の情報を取得するプロパティとメソッド、save メソッド、およびフォームに含まれるすべての属性のコレクションを提供します。 属性データは、フォーム上のフィールドによって表される属性に制限されています。


エンティティ名を取得 (getEntityName)

『getEntityName』は、レコードのエンティティの論理名を返す関数です。
エンティティの論理名を使用するような処理(FetchXMLの構文作成等)で、利用できるかと思います。

構文

formContext.data.entity.getEntityName();

パラメータ
(特になし)

戻り値
エンティティの論理名を文字列型で返却します。
例えば、取引先企業のフォーム上で実行した場合は、「account」が返却されます。

関数の使用例
[JavaScript]

function GetEntityName (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // エンティティの論理名を取得して表示
    alert("論理名は「" + formContext.data.entity.getEntityName() + "」です。");
}

[実行結果]
f:id:westcoastline:20200207160235p:plain

参考ページ
モデル駆動型アプリの getEntityName (クライアント API 参照) - PowerApps | Microsoft Docs


レコードを参照する検索値を取得 (getEntityReference)

『getEntityReference』は、レコードを参照する検索値(entityType、id、name)を返す関数です。
レコードのGUIDや名前を使用するような処理(FetchXMLの構文作成等)や、検索フィールドにレコードを設定する処理で利用できるかと思います。

構文

formContext.data.entity.getEntityReference();

パラメータ
(特になし)

戻り値
レコードの情報をオブジェクト型で返却します。返されたオブジェクトには、次の3つの属性が含まれています。

属性 説明
entityType エンティティの論理名を文字列で返却。(例:account)
id レコードのGUIDを文字列で返却。(例:E1D9D1DE-BC47-EA11-A812-000D3A415E1C)
name レコードの名前を文字列で返却。(例:株式会社ABC)

関数の使用例
[JavaScript]

function GetFormContext (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // レコードの情報を取得して表示
    var reference = formContext.data.entity.getEntityReference();
    alert(
        "論理名は「" + reference.entityType + "」です。\nGUIDは「" + reference.id + "」です。\nレコード名は「" + reference.name + "」です。"
    );
}

[実行結果]
f:id:westcoastline:20200207163033p:plain

参考ページ
モデル駆動型アプリの getEntityReference (クライアント API 参照) - PowerApps | Microsoft Docs


レコードのGUIDを取得 (getId)

『getId』は、レコードのGUIDを返す関数です。
レコードのGUIDを使用するような処理(FetchXMLの構文作成等)で利用できるかと思います。

構文

formContext.data.entity.getId();

パラメータ
(特になし)

戻り値
レコードのGUIDを返却します。

関数の使用例
[JavaScript]

function GetId (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // レコードのGUIDを取得して表示
    alert("GUIDは「" +  formContext.data.entity.getId() + "」です。");
}

[実行結果]
f:id:westcoastline:20200207165351p:plain

参考ページ
モデル駆動型アプリの getId (クライアント API 参照) - PowerApps | Microsoft Docs


フィールドの変更を検知 (getIsDirty)

『getIsDirty』は、フォーム内のフィールドに変更が加えられているかどうかをtrue/falseで返却する関数です。
フォーム内のいずれかのフィールドに変更が加えられている場合に「true」を返却するため、例えばフィールドに変更が加えられたタイミングでアラートを出すような処理などに利用できるかと思います。

構文

formContext.data.entity.getIsDirty();

パラメータ
(特になし)

戻り値
フォーム内のフィールドが変更されている場合は「true」、そうでない場合は「false」を返却します。

関数の使用例
[JavaScript]

function GetIsDirty (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // フィールド更新の有無を取得して結果を表示
    if (formContext.data.entity.getIsDirty() === true) {
        alert("更新されたフィールドがあります。");
    } else if (formContext.data.entity.getIsDirty() === false) {
        alert("更新されたフィールドはありません。");
    } else {
        return;
    }
}

[実行結果]
※とあるフィールドのOnChangeイベントに、上記JavaScriptの関数を設定して値を変更
f:id:westcoastline:20200207171558p:plain

参考ページ
モデル駆動型アプリの getIsDirty (クライアント API 参照) - PowerApps | Microsoft Docs


レコードを保存する (save)

『save』は、レコードの内容を保存することができる関数です。
[上書き保存] のボタンを押したり、[Ctrl] + [S] キーで保存するような操作をJavaScriptから実行させることができるため、様々なシーンで利用できる便利な関数かと思います。
また保存後にフォームを閉じたり、新規作成フォームを開いたりすることも可能です。

構文

formContext.data.entity.save(saveOption);

パラメータ

種類
必須
説明
saveOption String No (指定無し):レコードの保存処理のみを実施
saveandclose:レコードを保存後、フォームを閉じる
saveandnew:レコードを保存後、新規作成フォームを開く

戻り値
(特になし)

関数の使用例
[JavaScript]

function save (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    // 保存して新規作成フォームを開く
    formContext.data.entity.save("saveandnew");
}

[実行結果]
画像はありませんが保存処理が実行された後、新規作成フォームが自動で開きます。

参考ページ
モデル駆動型アプリにおける save (Client API リファレンス) - PowerApps | Microsoft Docs


縦長な記事になってしまいましたが、使えそうな関数に絞ってきれいにまとめることができたような気がします。
個人的には、APIの具体的な使い方を紹介してくれたり、ソースコードのサンプルを掲載してくれているサイトって重宝しているので、このブログもそうなれたらな、と思う今日この頃です。