Xrm.Utility (クライアント側の参照)

[アーティクル]
03/04/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Xrm.Utility オブジェクトは、現在のページには直接関連しない便利な関数のコンテナーを提供します。

これらの関数は、スクリプトをサポートするすべてのアプリケーションページで使用できます。フォームスクリプトまたはリボンコマンドで使用できます。HTML Web リソースの場合は、ClientGlobalContext.js.aspx ページを含めるときに使用できます。詳細については、「GetGlobalContext 関数および ClientGlobalContext.js.aspx (クライアント側の参照)」を参照してください。

機能

ダイアログ
alertDialog および confirmDialog を使用して、ユーザーにメッセージを表示し、応答に基づいて実行するコードを設定します。これらの関数は、window.alert や window.confirm メソッドの代わりに、Dynamics 365 モバイルクライアント (電話やタブレット PC) で使用する必要があります。
ネイティブのデバイス機能 (Dynamics 365 モバイルクライアント)
getBarcodeValue および getCurrentPosition を使用して、モバイルデバイスのネイティブのデバイス機能で、バーコード値やデバイスの現在の位置を取得します。
isActivityType
エンティティが活動エンティティかどうかを判定します。
openEntityForm
エンティティフォームを開きます。
openQuickCreate
Microsoft Dynamics CRM Online 2015 更新プログラム 1 または以降では、この関数を使用して、新しい簡易作成フォームを開きます。この関数を使用すると、属性マッピングを使用して、また特定の属性に対して、既定値を設定できます。ユーザーがレコードを保存する場合、作成されたレコードへの参照を取得できます。
openWebResource
HTML Web リソースを開きます。

ダイアログ

ダイアログには、alertDialog と confirmDialog の 2 種類があります。これらは、Dynamics 365 モバイルクライアント (電話やタブレット) を操作するスクリプトで使用するために含まれています。Dynamics 365 モバイルクライアントでは、window.alert や window.confirm のようなコードの流れをブロックする JavaScript 関数は使用できません。ユーザーにメッセージを表示する必要がある場合は、そのようなメソッドの代わりに、これらのメソッドを使用します。大きな違いは、これらのメソッドは、ユーザーが閉じるまでコードをブロックしないという点です。これらのメソッドには、ユーザーの応答に基づいて実行するコードを指定するコールバック関数パラメーターが含まれています。

注意

Dynamics 365 モバイルクライアント (電話やタブレット) では、window.alert メソッドの使用は、コールバックなしに、Xrm.Utility.alertDialog を使用するようオーバーライドされます。このメソッドはメッセージを表示しますが、window.alert のようにコードの実行をブロックすることはありません。Dynamics 365 モバイルクライアントにおける window.alert の Xrm.Utility.alertDialog へのマッピングは廃止され、次のメジャーリリースで削除されます。window.alert ではなく Xrm.Utility.alertDialog を使用するよう、現在のコードを移行する必要があります。

alertDialog

アプリケーションにより定義されたメッセージを含むダイアログボックスが表示されます。

Xrm.Utility.alertDialog(message,onCloseCallback)

パラメーター

名前	種類	必須出席者	説明
メッセージ	文字列	無効化する	ダイアログに表示するメッセージのテキストです。
onCloseCallback	関数	無効化しない	[OK] ボタンがクリックされると実行される関数です。

備考
このメソッドは、更新されたエンティティでのみ使用できます。

confirmDialog

[OK] や [キャンセル] ボタンのほかにオプションメッセージを含む確認ダイアログボックスを表示します。

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

パラメーター

名前	種類	必須出席者	説明
メッセージ	文字列	無効化する	ダイアログに表示するメッセージのテキスト
yesCloseCallback	関数	無効化しない	[OK] ボタンがクリックされると実行される関数です。
noCloseCallback	関数	無効化しない	[キャンセル] ボタンがクリックされると実行される関数です。

備考
このメソッドは、更新されたエンティティでのみ使用できます。

ネイティブのデバイス機能 (Dynamics 365 モバイルクライアント)

電話用 Dynamics 365 およびタブレット PC 用 Dynamics 365 クライアントでこれらのメソッドを使用して、モバイルビジネスユーザーが Sales、Field Service、およびそのほかの領域での利便性を向上するのを助けます。

注意

これらのメソッドは、Dynamics 365 用 2016 年 12 月の更新プログラム (オンラインおよび設置型) で導入されました。

getBarcodeValue

デバイスカメラを使用してスキャンした製品コードなどのバーコード情報を返します。

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

パラメーター

名前	型	必須出席者	説明
successCallback	機能	不可	バーコード値が返される場合に呼び出す関数。
errorCallback	機能	不可	処理が失敗したときに呼び出す関数。エラーの詳細を記述した message プロパティを持つエラーオブジェクトが渡されます。

備考
getBarcodeValue メソッドが機能するには、Dynamics 365 モバイルクライアントはデバイスカメラにアクセスする必要があり、これは既定で有効になります。

例
次のサンプルコードは、このメソッドの使用を示しています。

Xrm.Utility.getBarcodeValue().then(
    function (result) {
        Xrm.Utility.alertDialog("Barcode value: " + result);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

getCurrentPosition

デバイスの物理的場所機能を使用して、現在の場所を返します。

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

パラメーター

名前	型	必須出席者	説明
successCallback	機能	不可	現在の物理的場所情報が返される場合に呼び出す関数。次の属性の物理的場所オブジェクトは関数に渡されます。 coords: 関連する精度を伴った地理座標のセットだけでなく、高度および速度などその他の任意の属性のセットが含まれます。 timestamp: オブジェクトを取得した時間が DOMTimeStamp として表されます。
errorCallback	機能	不可	処理が失敗したときに呼び出す関数。次のプロパティを持つオブジェクトが渡されます。 code: 数値。エラーコード。 message: 文字列。エラーの詳細を記述するローカライズされたメッセージ。ユーザーの場所設定がモバイルデバイスで有効ではない場合、エラーメッセージが表示されます。以前のバージョンの Dynamics 365 モバイルクライアントを使用している場合、または物理的場所機能がモバイルデバイス上で使用できない場合、null がエラーコールバックに渡されます。

successCallback

機能

不可

現在の物理的場所情報が返される場合に呼び出す関数。次の属性の物理的場所オブジェクトは関数に渡されます。

coords: 関連する精度を伴った地理座標のセットだけでなく、高度および速度などその他の任意の属性のセットが含まれます。
timestamp: オブジェクトを取得した時間が DOMTimeStamp として表されます。

errorCallback

機能

不可

処理が失敗したときに呼び出す関数。次のプロパティを持つオブジェクトが渡されます。

code: 数値。エラーコード。
message: 文字列。エラーの詳細を記述するローカライズされたメッセージ。

ユーザーの場所設定がモバイルデバイスで有効ではない場合、エラーメッセージが表示されます。以前のバージョンの Dynamics 365 モバイルクライアントを使用している場合、または物理的場所機能がモバイルデバイス上で使用できない場合、null がエラーコールバックに渡されます。

備考
getCurrentPosition メソッドが機能するには、物理的場所機能がデバイスで有効になっている必要があり、Dynamics 365 モバイルクライアントで、既定で有効になっていないデバイスの場所へのアクセス許可が必要です。

例
次のサンプルコードは、このメソッドの使用を示しています。

Xrm.Utility.getCurrentPosition().then
    (function (location) {
        Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
           ", Longitude: " + location.coords.longitude);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

isActivityType

エンティティが活動エンティティかどうかを判定します。

Xrm.Utility.isActivityType(entityName)

パラメーター

名前

種類

必須出席者

説明

entityName

文字列

無効化する

エンティティの論理名です。
戻り値

種類

説明

Boolean

エンティティが活動エンティティである場合は true、その他の場合は false です。

名前	種類	必須出席者	説明
entityName	文字列	無効化する	エンティティの論理名です。

種類	説明
Boolean	エンティティが活動エンティティである場合は true、その他の場合は false です。

openEntityForm

パラメーターとして設定したオプションを使用して、新規または既存のエンティティレコードに対するエンティティフォームを開きます。

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

パラメーター

名前	種類	必須出席者	説明
名前	文字列	無効化する	エンティティの論理名。
id	文字列	無効化しない	一意の識別子、またはフォームで開くレコードを表す文字列。設定されていない場合、新しいレコードを作成するフォームが開きます。
パラメーター	オブジェクト	無効化しない	追加のパラメーターをフォームに渡すディクショナリオブジェクト。パラメーターが無効の場合、エラーが発生します。有効な追加のクエリ文字列パラメーターは、次のとおりです: フォーム ID: 複数のフォームが使用できるときに、使用するメインフォームの ID 値を設定します。パラメーターは、formid です。既定のフィールド ID: 新しいレコードフォームの既定値を設定します。詳細については、「フォームに渡すパラメーターを使用してフィールド値を設定する」を参照してください。 Main.aspx ページのクエリ文字列パラメーターで説明されている navbar と cmdbar パラメーター。カスタムクエリ文字列パラメーター: カスタムクエリ文字列パラメーターを受け入れるよう、フォームを構成できます。詳細については、「カスタムクエリストリングパラメーターが許可されるフォームの構成」を参照してください。
windowOptions	オブジェクト	無効化しない	Microsoft Dynamics CRM Online 2015 更新プログラム 1 またはそれ以降では、Web アプリケーションでこのオプションのパラメーターを使用して、フォームが開く方法を制御します。ブール値 openInNewWindow プロパティを true に設定した状態で、ディクショナリオブジェクトを渡すことで、新しいウィンドウでフォームを開くことができます。このパラメーターは Dynamics 365 モバイルクライアント (電話やタブレット) では無視されます。

備考
この関数を使用すると、特定の状況でもう一度ログインするよう要求されないようになります。

例
既定のフォームを使用して、新しい取引先企業レコードを開く

Xrm.Utility.openEntityForm("account");

既定のフォームを使用して、既存の取引先企業レコードを開く

Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");

特定のフォームで、既定値を設定して、新しい取引先企業レコードを開く

var parameters = {};
parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
parameters["name"] = "Test";
parameters["telephone1"] = "(425) 555-1234";
Xrm.Utility.openEntityForm("account", null, parameters);

新しいウィンドウで、既定のフォームを使用して、新しい取引先企業レコードを開く

var windowOptions = {
 openInNewWindow: true
};
Xrm.Utility.openEntityForm("account",null,null,windowOptions);

openQuickCreate

Microsoft Dynamics CRM Online 2015 更新プログラム 1 または以降では、この関数を使用して、新しい簡易作成フォームを開きます。この関数を使用すると、属性マッピングを使用して、また特定の属性に対して、既定値を設定できます。ユーザーがレコードを保存する場合、作成されたレコードへの参照を取得できます。

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

パラメーター

名前	種類	必須出席者	説明
entityLogicalName	文字列	無効化する	作成するエンティティの論理名。
createFromEntity	検索	無効化しない	マップした属性値に基づいて既定値を提供するレコードを指定します。検索オブジェクトには、以下の String プロパティが含まれます。 entityType: エンティティの論理名。 id: レコードの GUID 値を表す文字列。 name: レコードの主属性の値。
パラメーター	オブジェクト	無効化しない	フォームに追加のクエリ文字列パラメーターを渡すディクショナリオブジェクトです。無効なクエリ文字列パラメーターは、エラーを発生させます。有効な追加のクエリ文字列パラメーターは、次のとおりです: 既定のフィールド ID: 新しいレコードフォームの既定値を設定します。詳細については、「フォームに渡すパラメーターを使用してフィールド値を設定する」を参照してください。カスタムクエリ文字列パラメーター: カスタムクエリ文字列パラメーターを受け入れるよう、フォームを構成できます。詳細については、「カスタムクエリストリングパラメーターが許可されるフォームの構成」を参照してください。
successCallback	関数	無効化しない	レコードが作成されるときに呼び出される関数。この関数は、オブジェクトにパラメーターとして渡されます。このオブジェクトには、作成されたレコードを特定するために、以下のプロパティとともに、savedEntityReference プロパティが備わっています。 entityType: エンティティの論理名。 id: レコードの GUID 値を表す文字列。 name: 作成されたレコードの主属性の値。
errorCallback	関数	無効化しない	処理が失敗したときに呼び出す関数。次のプロパティを持つオブジェクトが渡されます。 errorCode: Number。エラーコード。 message: String。ローカライズされたエラーメッセージ。

備考
この関数は、Microsoft Dynamics CRM Online 2015 更新プログラム 1 またそれ以降でのみ使用できます。

これは、Web アプリケーションで、入れ子になっている簡易作成フォームは 10 までという制限があります。この制限を超えた場合、この関数は、簡易作成フォームではなく、完全なエンティティフォームを開きます。
例
このコードが取引先企業エンティティフォームで実行されると、新しい子の取引先企業を既定の名前で作成する簡易作成フォームが、取引先企業の親会社の名前を含むように設定されます。
```
var thisAccount = {
    entityType: "account",
    id: Xrm.Page.data.entity.getId()
};
var callback = function (obj) {
    console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
}
var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
    console.log(error.message);
});
```
このコードがブラウザー開発者ツール (F12 ツール) で実行されるとき、以下は、'A. Datum Corporation (sample)' という名前の取引先企業のコンテキストで実行され、新しい子の取引先企業に設定された既定の名前をユーザーが変更しないとき、そのときのコンソールへの出力を表しています。
```
Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
```

openWebResource

HTML Web リソースを開きます。

注意

この関数は Dynamics 365 モバイルクライアント (電話やタブレット) および対話型サービスハブでサポートされていません。

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

パラメーター

名前	種類	必須出席者	内容
webResourceName	文字列	無効化する	開くところの HTML Web リソースの名前。
webResourceData	文字列	無効化しない	データパラメーターに渡されるデータ。
width	数値	無効化しない	開くウィンドウの幅 (単位はピクセル)。
height	数値	無効化しない	開くウィンドウの高さ (単位はピクセル)。

戻り値
Window オブジェクト。
備考
HTML Web リソースは、HTML Web リソースへのパラメーターの引き渡しで説明されているパラメーター値を受け入れることができます。この関数は、任意のデータパラメーターの受け渡しのみを提供します。その他の有効なパラメーターの値を渡すには、それらの値を webResourceName パラメーターに追加する必要があります。
例
“new_webResource.htm” という名前の HTML Web リソースを開く
```
Xrm.Utility.openWebResource("new_webResource.htm");
```
データパラメーターのデータアイテムを 1 つだけ含む HTML Web リソースを開く
```
Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
```
データパラメーターを使用して複数の値を渡す HTML Web リソースを開く
```
var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
```
注意

これらの値は、HTML Web リソースのデータパラメーターの値から抽出する必要があります。詳細については、「サンプル: データパラメーターを使用した Web リソースへの複数の値の引き渡し」を参照してください。

HTML Web リソースによって予期されるパラメーターを含む HTML Web リソースを開く
```
Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
```
詳細については、「HTML Web リソースへのパラメーターの引き渡し」を参照してください。

高さと幅を設定して、HTML Web リソースを開く
```
Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
```

Xrm.Utility (クライアント側の参照)

機能

ダイアログ

alertDialog

confirmDialog

ネイティブのデバイス機能 (Dynamics 365 モバイルクライアント)

getBarcodeValue

getCurrentPosition

isActivityType

openEntityForm

openQuickCreate

openWebResource

関連項目

その他のリソース

Xrm.Utility (クライアント側の参照)

機能

ダイアログ

alertDialog

confirmDialog

ネイティブのデバイス機能 (Dynamics 365 モバイル クライアント)

getBarcodeValue

getCurrentPosition

isActivityType

openEntityForm

openQuickCreate

openWebResource

関連項目

その他のリソース

ネイティブのデバイス機能 (Dynamics 365 モバイルクライアント)