独自のアクションの作成
アクションと呼ばれるユーザー定義メッセージを作成することで、Dynamics 365 Customer Engagement (on-premises) の機能を拡張できます。 これらの操作に要求と応答のクラスが関連付けられ、Web API アクションが生成されます。 アクションの一般的な使用方法は、新しいドメイン特有の機能を組織の Web サービスに追加すること、または組織の複数の Web サービス メッセージ要求を 1 つの要求に結合することです。 たとえば、サポートコール センターで、作成、割り当て、および Setstate メッセージを単一の新しい「エスカレート」メッセージと結合することがあります。
アクションのビジネス ロジックには、ワークフローを使用して実行されます。 アクションを作成するときは、関連をリアルタイムワークフローが、実行パイプラインのステージ 30(コア操作)の実行が自動的に登録されます。 リアルタイム ワークフローの詳細については、ワークフローの種類 を参照してください。
アクションは Dynamics 365 for Customer Engagement の両方でサポートされますが、コードで (XAML を使用して) 操作を作成するのは、設置型および IFD 展開によってのみサポートされます。 オンラインのお客様は、Web アプリケーションで操作を対話的に作成する必要があります。
アクションの定義について
アクションはリアルタイムワークフローのような Workflow エンティティ レコードを使用して定義します。 アクションの内容および機能についてのまとめは、次の一覧に載せられています。
一つのエンティティに関連付けることも、グローバル(任意の特定のエンティティに関連付けられない場合)とすることもできます。
イベント実行パイプラインのコア操作のステージ 30 で実行されます。
イベント実行パイプラインの操作前および操作後の段階で登録されたプラグインの起動がサポートされています。
アクション ステータスをアクティブにしている間だけ、事後操作および事前操作の段階で、プラグインを登録できます。
Web API または
organization.svcおよびorganization.svc/webエンドポイントを介して使用可能です。JavaScript の Web リソースを使用して実装できます。 詳細: JavaScript の Web リソースを使用して操作を実行する
呼び出し元ユーザーのセキュリティ コンテキストで常に実行します。
プラグインのステップがアクションに登録されている間は、レコードを削除することはできません。
構成設定によって、任意に、現在のデータベース トランザクションに参加できます。
実行できるのがユーザー、部署、または組織に限定される場合、範囲はサポートされていません。 アクションは常に組織のスコープ内で実行します。
入力および出力パラメーターをサポートします。
データの変更の監査をサポートします。
オフライン クライアントではサポートされていません。
Web サービス メソッド呼び出しによって起動できます。
ワークフローから直接起動できます。
必要なアクセス許可
アクションのリアルタイム ワークフローをアクティブ化して、実行するには、リアルタイム プロセスのアクティブ化 (prvActivateSynchronousWorkflow) というセキュリティ特権が必要です。 これは、ワークフローの作成に必要な特権への追加です。
コードを使用して操作を作成する
通常、アクションは、Web アプリケーションのインターアクティブ ワークフロー デザイナを使用したカスタマイズによって実行されます。 ただし、開発者は SDK 呼び出しを使用して操作を実行して、必要に応じて、設置型または IFD サーバーを展開できます。
操作に使用するワークフロー エンティティ 属性を次の表に示します。 リアルタイム ワークフローのサンプル コードは、コードでリアルタイムでワークフローを作成する のトピックにあります。
| ワークフローの属性 | 内容 |
|---|---|
Category |
WorkflowCategory.CustomOperationに設定します。 |
SyncWorkflowLogOnError |
trueの場合、エラーがProcessSession レコードに記録されます。 非同期ワークフローとは違い、リアルタイム ワークフロー実行は、System Jobレコードに記録されません。 |
Mode |
使用されません。 |
IsTransacted |
アクションが、データベース トランザクションに参加する場合、true に設定し、それ以外の場合は、falseに設定します。 既定はtrueです。 |
UniqueName |
操作の一意の名前です。 名前は、発行者の接頭辞と"_" と一意の名前から構成されます。 |
Xaml |
操作のリアルタイム ワークフローを定義する XAML コードに設定します。 別の既存リアルタイム ワークフローを示す方法はありません。 |
入力および出力の引数の追加
アクションは、DynamicActivityProperty タイプを使用してワークフローに追加できる入力および出力の引数をサポートします。 これらの引数をアクションのワークフローに付け加えると、それらはこのアクションに関連付けられたメッセージ要求と応答クラスのプロパティになります。 たとえば、次の例は、2 つの入力引数と 1 つの出力引数の C# および XAML コードを示しています。
DynamicActivityProperty inputProperty1 = new DynamicActivityProperty { Name = "Subject", Type = typeof(InArgument<string>) };
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty { Name = "Output", Type = typeof(OutArgument<string>) };
inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));
inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));
outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));
<x:Property Name="Subject"
Type="InArgument(x:String)">
<x:Property.Attributes>
<mxsw:ArgumentRequiredAttribute Value="True" />
<mxsw:ArgumentTargetAttribute Value="False" />
<mxsw:ArgumentDescriptionAttribute Value="The subject " />
<mxsw:ArgumentDirectionAttribute Value="Input" />
<mxsw:ArgumentEntityAttribute Value="" />
</x:Property.Attributes>
</x:Property>
<x:Property Name="EntityCollection"
Type="InArgument(mxs:EntityCollection)">
<x:Property.Attributes>
<mxsw:ArgumentRequiredAttribute Value="False" />
<mxsw:ArgumentTargetAttribute Value="False" />
<mxsw:ArgumentDescriptionAttribute Value="The entity collection" />
<mxsw:ArgumentDirectionAttribute Value="Input" />
<mxsw:ArgumentEntityAttribute Value="" />
</x:Property.Attributes>
</x:Property>
<x:Property Name="Output"
Type="OutArgument(x:String)">
<x:Property.Attributes>
<mxsw:ArgumentRequiredAttribute Value="False" />
<mxsw:ArgumentTargetAttribute Value="False" />
<mxsw:ArgumentDescriptionAttribute Value="The output" />
<mxsw:ArgumentDirectionAttribute Value="Output" />
<mxsw:ArgumentEntityAttribute Value="" />
</x:Property.Attributes>
</x:Property>
プロパティに使用される名前は、引数名に一致する必要があります。なぜなら、コード生成はそれらの名前を、要求プロパティまたは応答プロパティとして定義するからです。
入力および出力の引数に対してサポートされている引数の種類を、次の表に示します。
| .NET の種類 | 引数の種類 |
|---|---|
| System.Int32 | Integer |
| System.String | String |
| EntityReference | エンティティ参照 |
| Entity | Entity |
| EntityCollection | エンティティ コレクション |
| System.DateTime | 日時 |
| System.Double | 浮動小数 |
| System.Decimal | 小数 |
| Money | 金額 |
| System.Boolean | Boolean |
| OptionSetValue | 候補リスト |
サポートされている引数属性を次の表に示します。
| 引数の属性 | 説明 |
|---|---|
| ArgumentRequiredAttribute | 引数が必要かどうかを示します。 |
| ArgumentDirectionAttribute | 引数の説明が入力または出力であるかどうかを示します。 |
| ArgumentDescriptionAttribute | 引数の説明を指定します。 |
| ArgumentEntityAttribute | エンティティで渡される場合に使用します。 |
| ArgumentTargetAttribute | この属性は自動的に生成または追加されます。 そのワークフローを実行する主エンティティを指します。 この属性はオプションで、グローバルな操作に使用します。 |
配布の操作をパッケージする
Dynamics 365 Customer Engagement (on-premises) 組織にインポートできるように操作を配布するには、Customer Engagement ソリューションに操作を追加します。 これは、Web アプリケーションを使用して、設定>カスタマイズ>ソリューションと移動して容易に実行できます。 ソリューションを作成するコードを記述できます。 ソリューションの使用に関する詳細については、拡張機能のパッケージ化および配布 を参照してください。
操作用の事前バインド型を生成する
CrmSvcUtil ツールを使用して、アプリケーション コードに含めるアクションに対する要求と応答クラスを生成することができます。 ただし、これらのクラスを生成する前に、操作をアクティブ化してください。
CrmSvcUtil.exe をダウンロードするには、Dataverse 開発ツール を参照してください。
次のサンプルは、設置型の Customer Engagement 環境でツールをコマンド ラインから実行するときの構文を示しています。 環境で実際に使用されるパラメーター値を指定してください。
CrmSvcUtil.exe /url:https://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions
次のサンプルは、Dynamics 365 for Customer Engagement のコマンド ラインから実行するときの構文を示しています。 取引先企業およびサーバーに適したパラメーター値を指定します。
CrmSvcUtil.exe /url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions
/generateActions パラメーターを使用していることに注意してください。 詳細: コード生成ツール (CrmSvcUtil.exe) を使用して事前バインド型エンティティ クラスを作成する。
実行する操作に対して生成された要求および応答クラスの事前バインドまたは遅延バインド型を使用できます。
Web API を使用してアクションを実行する
新しいアクションを作成すると、そのアクションは Web API で作成されます。 アクションがエンティティのコンテキストで作成される場合、アクションはそのエンティティにバインドされます。 それ以外の場合は、バインドされていないアクションです。 詳細: Web API アクションの使用 を参照してください。
JavaScript の Web リソースを使用して操作を実行する
すべてのシステム操作と同じように Web API を使用してアクションを実行できます。 詳細: Xrm.WebApi.online.execute
組織サービスを使用して操作を実行する
組織 Web サービスを使用し、管理コードを使用して操作を実行するには、次の手順に従います。
アプリケーションのプロジェクトで、CrmSvcUtil ツールを使用して生成された、事前バインド型ファイルの種類を含めます。
アプリケーション コードで、アクションの要求を初期化して、必要なプロパティを入力します。
Executeを呼び出し、要求を引数として渡します。
アプリケーション コードを実行する前に、操作が有効になっていることを確認します。 そうでない場合、ランタイム エラーが表示されます。
プロセスを使用して操作を実行
ワークフロー、ダイアログ、またはそのほかのプロセス アクションから任意のアクションを実行できます。 Web アプリケーションのプロセス フォームのステップの追加ドロップ ダウンで、アクションの実行アイテムを選択することで、アクティブ化されたユーザー定義アクションがプロセスで使用可能になります。 プロセス ステップにこのステップが追加されると、このステップで提供されるアクションリストから新しいユーザー定義アクション (または任意のアクション) を選択できます。 このステップでプロパティの設定を選択して、ユーザー定義アクションで必要な入力パラメーターを指定します。
Note
ユーザー定義アクションに、たとえば、Picklist、Entity、または Entity Collection などのサポートされていないパラメーターの種類が存在する場合は、そのユーザー定義アクションはアクションリストには表示されません。
プロセスからアクションを実行する機能は、Dynamics CRM Online 2015 Update 1 で導入されました。
既存の Depth プラットフォームのチェックによって、無限ループが確実に発生しないようにします。 深さの制限の詳細については、「MaxDepth」を参照してください。
長時間の操作を監視する
操作のリアルタイム ワークフローの手順の 1 つがユーザー定義ワークフロー活動の場合、そのユーザー定義ワークフロー活動が隔離されたサンドボックス ランタイム環境で実行され、サンドボックス プラグインを管理する場合と同じように、2 分間のタイムアウト制限が課されます。 ただし、操作自体にかかる全体的な時間に制限はありません。 また、ロールバックが有効で、操作がトランザクションに参加している場合、SQL Server のタイムアウトが適用されます。
チップ
ベスト プラクティスとして、長時間かかる操作は、.NET の非同期操作やバックグラウンド プロセスを使用して Dynamics 365 Customer Engagement (on-premises) 外で実行することをお勧めします。
関連項目
リアルタイム ワークフローの作成
ガイド プロセスでダイアログを使用する
イベント実行パイプライン
ビジネス プロセスを自動化するワークフローの記述
システムのカスタマイズ