Tech Dynamics 365 (CRM)

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

【API紹介】formContext.ui編

Dynamics 365 JavaScript

こんにちは。

前回の記事では、『formContext.data.entity』の中から5つの関数を紹介しましたが、今回は『formContext.ui』から4つの関数をご紹介します。


formContext.ui の概要

Microsoft社のAPI一覧では、以下の様に説明されています。
記載内容の通り、"UIに関する情報を取得する"関数となっていますので、レコードやフィールドに対して何かしらの処理を行う訳ではなく、どちらかというとビューやリボン、フォームの情報にアクセスするための関数となっています。

ユーザー インターフェイス (UI) に関する情報を取得するプロパティおよびメソッド、およびフォームのいくつかのサブコンポーネントのコレクションを提供します。


フォーム単位に通知を行う (setFormNotification)

『setFormNotification』は、フォーム上に通知を表示する関数です。
この関数は結構有用で、フォームにアクセスしたユーザに対して情報発信したり、行った操作に対する警告をヘッダー付近に表示することができます。

構文

formContext.ui.setFormNotification(message, level, uniqueId);

パラメータ

値
種類
必須
 説明
message String Yes 表示するテキスト文を入力
level String Yes ERROR：エラーアイコンとテキスト文を表示
WARNING：警告アイコンとテキスト文を表示
INFO：情報アイコンとテキスト文を表示
uniqueId String Yes 『clearFormNotification』関数で、通知を削除する際に使用するIDを指定

戻り値
処理に成功した場合は「true」、そうでない場合は「false」を返却します。

関数の使用例
[JavaScript]

function SetFormNotification (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification("必須のフィールドは全て入力してください。", "INFO", "abc123");
}

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

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


フォーム単位の通知を削除する (clearFormNotification)

『clearFormNotification』は、フォーム上に表示された通知を削除する関数です。
この関数は、通知を表示したり非表示にしたりする処理が必要な場合に、上記で紹介した『setFormNotification』とセットで使われることが多い関数ですが、通知を常に表示しておきたい場合は利用しなくても構いません。

構文

formContext.ui.clearFormNotification(uniqueId);

パラメータ

値
種類
必須
 説明
uniqueId String Yes 『setFormNotification』関数で指定したIDを指定

戻り値
処理に成功した場合は「true」、そうでない場合は「false」を返却します。

関数の使用例
[JavaScript]

function ClearFormNotification (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification("必須のフィールドは全て入力してください。", "INFO", "abc123");
    formContext.ui.clearFormNotification("abc123");
}

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

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


フォームを閉じる (close)

『close』は、フォームを閉じる関数です。
ブラウザ自体を[×]で閉じる『Window.close』のような挙動ではなく、Dynamics 365 の画面内でフォームを閉じるような挙動となるため、例えば、とあるレコードのフォーム画面上でこの関数が実行された場合、ビューの画面に遷移するか、もしくは前に開いていたレコードのフォーム画面に遷移します。

構文

formContext.ui.close();

パラメータ
(特になし)

戻り値
(特になし)

関数の使用例
[JavaScript]

function Close (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.close();
}

[実行結果]
画像はありませんが、とあるレコード上で処理が実行された後、ビュー画面に遷移しました。

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


フォームの種類を取得する (getFormType)

『getFormType 』は、フォームの種類を取得する関数で、新規作成時(フォームタイプが"1"の場合)のみ実行させたい処理などがある場合に利用することができます。

構文

formContext.ui.getFormType();

パラメータ
(特になし)

戻り値

値 フォームの種類
0 未定義のフォームの場合
1 新規作成のフォームの場合
2 既存のフォームの場合
3 フォームが読み取り専用になっている場合
4 フォームが無効になっている場合
6 一括編集のフォームの場合

関数の使用例
[JavaScript]

function GetFormType (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    if (formContext.ui.getFormType() === 1) {
        alert("このフォームは新規作成フォームです");
    } else if (formContext.ui.getFormType() === 2) {
        alert("このフォームは既存のフォームです");
    }
}

[実行結果]
※新規作成フォームを開いた場合
f:id:westcoastline:20200212173636p:plain

※既存のフォームを開いた場合
f:id:westcoastline:20200212173643p:plain

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


UI周りの関数は、私も実案件で本当によく使う関数ばかりです。
特にフォームの種類を取得する『getFormType』関数は利用頻度が高く、OnLoadのJavaScriptの中でif分岐させて、新規作成フォームの場合のみ何かしらの処理をするようなシーンで使える関数なので、ご存知でなかった方は、これを機に使ってみてはいかがでしょうか？

【API紹介】formContext.data.entity編

Dynamics 365 JavaScript

こんにちは。

今回から、複数回に分けて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の具体的な使い方を紹介してくれたり、ソースコードのサンプルを掲載してくれているサイトって重宝しているので、このブログもそうなれたらな、と思う今日この頃です。

レコードにアクセスするためのURL

Dynamics 365

こんにちは。

今回は、レコードにアクセスするためのURLをどのように設定するべきかについてご説明します。


URLの体系

Dynamics 365 (CRM) は、他のWebサイトと比べて少し特殊なURL体系になっており、『#』以下が一見IDっぽく見えますが、このURLを貼り付けても一番最初のトップページにしか行けない仕様になっています。
https://domain.crm7.dynamics.com/tenant/main.aspx#468515678

そのため、レコードにアクセスするためには以下の様なURLを設定する必要があります。
https://{ドメイン名}/{テナント名}/main.aspx?etc={エンティティコード}&extraqs=formid%3d{フォームID}&id=%7b{レコードID}%7d&pagetype=entityrecord

なお、上記のURLは手打ちする必要はなく、レコードのフォーム画面のコマンドバーにある [リンクを電子メールで送信] をクリックすれば取得することができます。

上記内容は、Dynamics 365 (CRM) をご利用のエンドユーザの方々からよく質問される内容のため、今回ご紹介することにしました。
普通のWebサイトと同じ感覚でブラウザのURLをコピーして他の人に連携したり、お気に入りに登録しても Dynamics 365 (CRM) の場合は該当のレコードにはたどり着けないのでちょっと不便なんですよね…。