Dynamics CRM 2011: Xrm.Utility の紹介

Article
04/04/2013

みなさん、こんにちは。

今回は開発者の方向けの情報として、スクリプトで利用できる Xrm.Utility
を紹介します。こちらの機能は Update Rollup 8 で提供されましたが、先日
公開された Visual Studio 向けのScript Template でもサポートされました。

情報元 : https://msdn.microsoft.com/ja-jp/library/jj602956.aspx

Xrm.Utility

Microsoft Dynamics CRM 2011 および Microsoft Dynamics CRM Online で
スクリプトを開発をしている場合、Xrm.Page オブジェクトモデルを利用でき、
コンテキストやフォームの要素、また読み込まれているデータへアクセス
が容易に行えます。

Xrm.Utility は Xrm.Page とは異なる名前空間であり、目的も異なります。
Xrm.Utility は以下の関数を提供します。

openEntityForm: エンティティフォームを開くことができます。
openWebResource: Web リソースを開くことができます。

window.open との最大の違いは、特定の環境や状況でユーザーが
ログインの為の認証を聞かれないことと、開いたフォームのサイズや
見た目が通常のフォームと同等であることです。また日本語環境では
文字列を URL Encode する必要がない点も重要です。

利用条件

Xrm.Utility はフォームやリボンスクリプト等、スクリプトをサポートする
ページで利用できます。Web リソース内で利用する場合は、
ClientGlobalContext.js.aspx を読み込んでください。

openEntityForm 関数

エンティティフォームを開く関数です。以下の引数を取ります。

name : エンティティの論理名です。
id : 開きたいレコードの GUID です。省略した場合新規フォームが開きます。
parameters : 複数フォームの場合、開きたいフォームの GUID を指定したり、
開いたフォームの初期値を渡すことができます。その他にもカスタムの
クエリ文字列を渡すことが可能ですが、この場合フォーム側でカスタム
クエリ文字列を受け付けるようにする必要があります。次回紹介します。

例えば以下のコードは新規の取引先企業フォームを開き、また
初期値として名前と電話番号を設定しています。

var parameters = {};
parameters["name"] = "XrmUtility テスト";
parameters["telephone1"] = "(425) 555-1234";
Xrm.Utility.openEntityForm("account", null, parameters);

このコードにより開かれるフォームのアドレスを確認すると、以下のように
日本語部分がエンコードされています。

name%3dXrmUtility%2520%25E3%2583%2586%25E3%2582%25B9%25E3%2583%2588

openWebResource 関数

Web リソースを開くことができます。以下の引数を取ります。

webResourceName : 開きたい Web リソース名です。
webResourceData : Web リソースに渡すパラメータです。
width : 開くウィンドウの幅です。
height : 開くウィンドウの高さです。

上記の通りただ開くだけでなくパラメーターも渡せますので、完全な
機能が利用できます。Web リソースへのパラメータの受け渡しの
詳細はまた紹介します。

まとめ

今回は既に日本語化されている SDK の記事から、利用頻度が
高いと思われるものを紹介しました。今後も既に日本語化されて
いる SDK であっても重要なものはブログでも紹介いたします。

‐ Dynamics CRM サポート中村憲一郎

Dynamics CRM 2011: Xrm.Utility の紹介

Additional resources