【API紹介】formContext.data.entity編
こんにちは。
今回から、複数回に分けてDynamics 365 (CRM) で使用可能なAPIの紹介を行っていきたいと思います。
紹介にあたり、基本的には以下の様なポリシーに沿って記事を更新していければと考えています。
・全ての関数を紹介するわけではなく、比較的使用頻度が高く、使えそうな関数に絞る。
・どのようなシーンで利用できそうか、具体的な説明をできる限り紹介する。
・APIの構文やパラメータを紹介しつつ、実際に動くソースコードを書いてみる。
記念すべき第1回目は、『formContext.data.entity』の中から5つの関数を紹介します。
- formContext.data.entity の概要
- エンティティ名を取得 (getEntityName)
- レコードを参照する検索値を取得 (getEntityReference)
- レコードのGUIDを取得 (getId)
- フィールドの変更を検知 (getIsDirty)
- レコードを保存する (save)
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() + "」です。"); }
[実行結果]
参考ページ
モデル駆動型アプリの 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 + "」です。" ); }
[実行結果]
参考ページ
モデル駆動型アプリの 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() + "」です。"); }
[実行結果]
参考ページ
モデル駆動型アプリの 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の関数を設定して値を変更
参考ページ
モデル駆動型アプリの 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"); }
[実行結果]
画像はありませんが保存処理が実行された後、新規作成フォームが自動で開きます。