SharePoint ワークフロー サービスの Client Side Object Model を操作する
SharePoint クライアント側オブジェクト モデル (CSOM) API を使用して ワークフロー マネージャー 1.0 のワークフロー定義とワークフロー インスタンスを作成および制御する方法を説明します。 提供:Andrew Connell、 Voitanos
注:
SharePoint 2010 ワークフローは、2020 年 8 月 1 日以降、新しいテナント用に廃止され、2020 年 11 月 1 日に既存のテナントから削除されました。 SharePoint 2010 ワークフローを使用している場合は、Power Automate またはその他のサポートされているソリューションに移行することをお勧めします。 詳細については、「SharePoint 2010 ワークフローの廃止」を参照してください。
SharePoint ワークフロー サービスの Client Side Object Model を操作する
SharePoint 2007 と SharePoint 2010 でのワークフローの実装は、バージョンが変わってもほとんど同じです。 Microsoft は、ワークフローをサイトに関連付ける機能などの新機能をいくつか SharePoint 2010 に追加し、ワークフロー オーサリング ツールの SharePoint Designer 2010 と Visual Studio 2010 を旧バージョンから改善しました。 しかしながら、ワークフロー タスクの実装、ワークフロー フォーム、ワークフロー サーバー側 API にはほとんど変更がありません。
SharePoint 2010 では、お客様がカスタマイズをサンドボックス ソリューションに移行することを奨励する機能と機能が導入されました。 これらは分離されたプロセスで実行され、オンプレミス、SharePoint が会社のサーバーにインストールされ、会社によって管理された、クラウド、またはより具体的には Office 365 の両方の種類の SharePoint 展開に優しいものでした。
SharePoint では、Microsoft によりさらに多くの機能が追加されました。これらの更新プログラムは、クラウドデプロイに向けて行われました。 具体的には、Microsoft は新しい SharePoint アプリ モデルを導入しました。このモデルは、サンドボックス ソリューションとは異なり、SharePoint プロセスでのサーバー側のコードの実行を明示的にブロックしました。 Microsoft では、クライアント側オブジェクト モデル (CSOM) などの SharePoint の既存のテクノロジも構築し、 OAuth を使用したアプリ ID のサポートなどの新機能も導入しました。
さらに、SharePoint の導入により、マイクロソフトは、製品の方向性の抜本的転換を反映したまったく新しいワークフロー アーキテクチャおよびプラットフォームを導入することになりました。
新しいアーキテクチャで最も重要な変更は、SharePoint のワークフローが SharePoint 内で実行されなくなったことです。 SharePoint は Workflow Manager 1.0 というまったく新しい実行エンジンを使用します。 ワークフロー マネージャーは、Windows Workflow Foundation ランタイムと、Windows Workflow Foundation が必要とするすべてのサービスをホストします。 ワークフローが発行されたとき、または発行済みのワークフローが開始されたときに、SharePoint は、ワークフローのエピソードを処理するワークフロー マネージャーに通知します。 リストアイテムのプロパティやユーザーのプロパティなどの SharePoint の情報をワークフローがアクセスする場合、OAuth のサポートを使用して認証し、新しく改善された REST API を使用して通信します。
ワークフロー アーキテクチャのこのような変更は、カスタム ワークフロー フォームなどに大きな影響を与えます。このことは、MSDN の記事「Visual Studio 2012 で SharePoint のカスタム ワークフロー フォームを作成する方法」で取り上げています。 この記事は、カスタム ワークフロー フォームを作成する新しいスタイルを提唱するために SharePoint に追加された複数の要素のうちのひとつに触れています。それは、CSOM への改善と、Workflow Services CSOM API の追加です。
SharePoint の Workflow Services CSOM API の概要
SharePoint 2007 と SharePoint 2010 では、ワークフロー API はサーバー側オブジェクト モデルでのみマニフェストされました。 SharePoint には、下位互換性のために SharePoint に古いワークフロー実行エンジンが含まれているので、この同じワークフロー API がまだ存在します。
しかしながら、ワークフロー マネージャーを使用する SharePoint で導入された推奨される新しいワークフロー アーキテクチャには、最新のサーバー側 API が含まれています。 SharePoint では、新しいワークフロー アーキテクチャの堅牢な API が含まれるように CSOM が拡張されました。 CSOM へのこの追加は、新しい SharePoint およびワークフロー マネージャー 1.0 のワークフロー アーキテクチャにのみ適用され、引き続き SharePoint でホストされている以前のバージョンには適用されない点に注意してください。
ワークフロー サービス CSOM API は、CSOM の残りの部分と同様に、.NET Silverlight マネージド API と JavaScript オブジェクト モデル (JSOM) と呼ばれる JavaScript API の両方に実装されています。 JSOM は、カスタム ワークフロー フォームを作成するときに開発者が使用する必要があるものです。これらのフォームは、サーバー側のコードを持つ必要のない Web フォーム ASP.NET されるためです。 したがって、ワークフロー サービス JSOM API は、ワークフローの関連付けを作成するカスタム関連付けフォームと、新しいワークフロー インスタンスを開始するための開始フォームで使用されます。
しかし、可能性はそこで止まらない。 ワークフロー サービス CSOM と JSOM は非常に堅牢で、開発者は SharePoint のワークフローでほとんど何でも実行できます。 開発者は、ワークフローの関連付けとインスタンスの作成とは別に、新しいワークフロー定義をプログラムでデプロイし、CSOM と JSOM から実行中のワークフロー インスタンスと通信することもできます。これについては、この記事の残りの部分で説明します。
この記事では、SharePoint Server 2013 のコンテキストにおけるワークフロー フォームに関するトピックを取り上げています。 ここでは、2013 年 3 月のパブリック更新プログラムを適用した SharePoint と Office Developer tools for Visual Studio 2012 を使用します。 この記事のすべての内容は、SharePoint のオンプレミスの展開と Office 365 の両方に当てはまります。
Workflow Services CSOM と JSOM API のコンポーネント
この記事では、ワークフロー サービス CSOM API に焦点を当てているため、拡張機能では JSOM API についても説明します。サーバー側の Workflow Services API については、ここでは説明しません。 ワークフロー サービス CSOM は、さまざまなタスクの実行に使用される複数の異なるサービスで構成されます。 これらのそれぞれについては、次のセクションで説明します。
注:
CSOM には存在しないが、代わりにサーバー側 API と共に存在する 1 つの追加サービスがあります。 これは、メッセージ キューとメッセージ トランスポートを管理するために使用されるメッセージング サービスです。
ワークフロー サービス CSOM および JSOM API を操作するには、開発者が、必要な参照をプロジェクト (CSOM の場合) とページ (JSOM の場合) に追加する必要があります。 どちらの実装も要件は同じです。
- 次のコア SharePoint CSOM および JSOM ライブラリを参照します。
- Microsoft.SharePoint.Client.dll
- Microsoft.SharePoint.Client.Runtime.dll
- Microsoft.SharePoint.Client.WorkflowServices.dll
- 次のワークフロー サービス CSOM および JSOM ライブラリを参照します。
- SP.js
- SP.Runtime.js
- SP.WorkflowServices.js
ワークフロー サービス マネージャー
Workflow Services CSOM API に含まれるすべてのサービスへのゲートウェイは、ワークフロー Service Managerです。 このオブジェクトは、次のセクションで説明する他のすべてのサービスのインスタンスを取得するために開発者が使用するものです。 他の CSOM API 実装と同様に、 WorkflowServicesManager はコア SharePoint CSOM に依存しているため、次の CSOM および JSOM コード例に示すように、有効なクライアント コンテキストを渡し、接続する SharePoint サイトへの参照を渡す必要があります。
CSOM: WorkflowServicesManager インスタンスの作成
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
JSOM: WorkflowServicesManager インスタンスの作成
var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web());
展開サービス
Visual Studio 2012 で、ソリューション パッケージ (.wsp) を使用して、または SharePoint アプリ (.app) としてカスタム ワークフローを作成する場合は、ワークフロー定義を作成します。 定義とは、ワークフロー プロセスやその内部に定義されているすべてのビジネス ルールおよび属性 (カスタム関連付けや開始フォームの場所など) のことです。 これらの定義は、単独では、サイト、リスト、ドキュメント ライブラリとの関連付けに関連する状況以外では実行できないためあまり使いません。 公開されてサイトで使用可能になったワークフロー定義は、新しいワークフロー関連付けを作成するページに移動すれば見ることができます (以下の図を参照)。
図 1. ワークフロー関連付けを追加する
発行されたワークフロー定義のコレクションには、デプロイ サービスからアクセスできます。 このサービスを使用すると、サイト上で現在保存および発行されているすべての定義の一覧を取得したり、保存された定義と新しい定義の両方を公開したり、既存の定義を削除したり、SharePoint Designer 2013 で作成されたワークフローで使用できるワークフロー アクションを特定したりできます。
WorkflowDeploymentService オブジェクトは WorkflowServicesManager クラスから使用できます (以下のコード例を参照)。
CSOM: WorkflowDeploymentService インスタンスの取得
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService();
JSOM: WorkflowDeploymentService インスタンスの取得
var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web());
var workflowDeploymentService = workflowServicesManager.getWorkflowDeploymentService();
購読サービス
前のセクションで説明したように、ワークフローを作成したら、そのワークフローを定義として SharePoint に公開します。 この定義を使用するには、ユーザーが、特定の SharePoint サイト、リスト、またはドキュメント ライブラリに追加メタデータと共に定義をリンクさせる関連付けを作成する必要があります。 このプロセスは、基本的に SharePoint 2010 と同じように動作しますが、SharePoint での実装はまったく異なります。 ワークフロー マネージャー 1.0 は、Microsoft Azure のサービス バス 1.0 のインスタンスを利用します。
サービス バスは、公開/購読サービス (PubSub とも呼ばれます) をサポートしているため役に立ちます。 これは、サービス バスに格納されているトピックへの公開元によるメッセージ送信を支援する非同期のメッセージング フレームワークです。 不特定多数の購読者が、特定の条件を満たすトピックにメッセージが公開されたら通知を受け取るように要求できます。
SharePoint と ワークフロー マネージャー 1.0 は、PubSub モデルを使用して関連付けを作成します。 ワークフローの関連付けは、トピックの購読として作成されます。 たとえば、ワークフロー定義の関連付けをリストに作成し、そのリストにアイテムが追加されたら自動的に開始するように設定できます。 リストにアイテムが追加されると、SharePoint が、サービス バスのトピックにメッセージを送信するワークフロー マネージャー 1.0 にイベントを公開します。 そして、メッセージが評価され、登録されている購読にイベントが通知されます。 購読されている関連付けが見つかったら、ワークフローが開始されます。 このプロセスのしくみの詳細については、MSDN の記事「 SharePoint ワークフローの基礎」を参照してください。
これで、ワークフロー関連付けが、現在なぜ API 内の (つまり密かに) 購読と呼ばれているか明確になったはずです。 ワークフロー サービス CSOM の購読サービスでは、既存の関連付けおよび購読の探索、関連付けおよび購読の作成/削除、イベント通知要求を行うことができます。
WorkflowSubscriptionService オブジェクトは、次のコード例に示すように WorkflowServicesManager クラスを使用して使用できます。
CSOM: WorkflowSubscriptionService インスタンスの取得
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowSubscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();
JSOM: WorkflowSubscriptionService インスタンスの取得
var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web());
var workflowSubscriptionService = workflowServicesManager.getWorkflowSubscriptionService();
インスタンス サービス
最後に取り上げるサービスはインスタンス サービスです。 このサービスを使用すると、ワークフロー インスタンスの開始、中断、再開、終了、取り消しなど、ワークフロー インスタンスで複数のタスクを実行できます。 また、デバッグ情報を収集したり、現在実行中のすべてのワークフローと既に完了しているワークフローを列挙したりすることもできます。 最後に、このサービスを使用して、この記事の後半で説明するように、現在実行中のワークフローにイベントを発行できます。
WorkflowInstanceService オブジェクトは、次のコード例に示すように WorkflowServicesManager クラスを使用して使用できます。
CSOM: WorkflowInstanceService インスタンスの取得
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowInstanceService = workflowServicesManager.GetWorkflowInstanceService();
JSOM: WorkflowInstanceService インスタンスの取得
var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web());
var workflowInstanceService = workflowServicesManager.getWorkflowInstanceService();
相互運用サービス
以前のバージョンの SharePoint (特に SharePoint 2007 と SharePoint 2010) では、SharePoint は Windows Workflow Foundation ランタイムをホストしました。 前に説明したように、Microsoft は、SharePoint の外部でワークフロー ランタイムをホストする ワークフロー マネージャー 1.0 への依存関係を導入することで、SharePoint のこのアプローチから離れています。 その結果、ワークフローは SharePoint 内で実行および管理されなくなります。代わりに、SharePoint はワークフロー管理と実行の責任をワークフロー マネージャー 1.0 に任せられます。
ただし、下位互換性を提供するために、Microsoft は、Windows Workflow Foundation ランタイム エンジンを保持することで、SharePoint 内で SharePoint 以前のスタイルのワークフローをホストする従来のモデルを保持しました。 そのため、SharePoint 2010 で作成されたすべてのワークフローは、引き続き SharePoint 環境で想定どおりに実行されます。 さらに、Microsoft には新しいアクティビティ InvokeSharePointWorkflow が含まれており、SharePoint ワークフローで使用して、SharePoint に含まれる SharePoint 2010 ワークフロー ホスト内の既存のワークフローを開始できます。 これにより、以前のバージョンから移行された既存のワークフロー投資を利用できます。
注:
InvokeSharePointWorkflow アクティビティは CSOM メソッド StartWorkflow のラッパーです。
SharePoint ワークフロー サービス CSOM にも、開発者がレガシ ワークフローを相互運用できる特別なサービスが含まれています。 InteropService を使用すると、ワークフローを開始および停止したり、ワークフローを実行するためのイベント通知を有効または無効にしたりできます。
WorkflowDeploymentService オブジェクトは、次の CSOM および JSOM コード例に示すように、WorkflowServicesManager クラスを使用して使用できます。
CSOM: InteropService インスタンスの取得
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowInteropService = workflowServicesManager.GetWorkflowInteropService();
JSOM: InteropService インスタンスの取得
var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web());
var workflowInteropService = serviceManager.getWorkflowInteropService();
例: ワークフロー サービス CSOM のシナリオ
以下のセクションでは、ワークフロー サービス CSOM のさまざまなサービスを使用して、カスタム ソリューションで一般的なタスクを実行する方法について説明します。
インストールされているワークフローをすべて取得する
ワークフロー サービス CSOM のその他のサービスではたいてい、以前公開されたワークフロー定義への参照を取得する必要があります。 一般に、ワークフロー定義は ID (GUID) で参照されます。
発行されたすべてのワークフロー定義の一覧を取得するには、まず GetWorkflowDeploymentService メソッドを使用してデプロイ サービスのインスタンスを取得します。 次に、 EnumerateDefinitions(Boolean) メソッドを使用してすべてのワークフロー定義のコレクションを取得します。 以下にコード例を示します。
// connect to the workflow services via a CSOM client context
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
// connect to the deployment service
var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService();
// get all installed workflows
var publishedWorkflowDefinitions = workflowDeploymentService.EnumerateDefinitions(true);
clientContext.Load(publishedWorkflowDefinitions);
clientContext.ExecuteQuery();
// display list of all installed workflows
foreach (var workflowDefinition in publishedWorkflowDefinitions) {
Console.WriteLine("{0} - {1}", workflowDefinition.Id.ToString(), workflowDefinition.DisplayName);
}
関連付けと購読をすべて取得する
新しいワークフロー インスタンスを開始するには、まず、既存のワークフロー関連付けへの参照を取得する必要があります。 以下の例では、前のコード例に基づいて、サイト内の特定のワークフロー定義に関するすべてのワークフロー関連付けのリストを取得する方法を示します。
上記の例を使用してワークフロー定義を取得したら、 GetWorkflowSubscriptionService メソッドを使用してサブスクリプション サービスのインスタンスを作成します。 次に、 EnumerateSubscriptionsByDefinition メソッド (ワークフロー定義の ID を渡します) を使用して、指定したワークフローに対して存在するすべての関連付けのリストを取得します。 ワークフロー関連付けの取得に使用できるメソッドは、以下を含めていくつかあります。
- EnumerateSubscriptions
- EnumerateSubscriptionsByDefinition
- EnumerateSubscriptionsByEventSource
- EnumerateSubscriptionsByList
次のコード例は、関連付けとサブスクリプションの取得を示しています。
// connect to the workflow services via a CSOM client context
var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
// connect to the deployment service
var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService();
// get all installed workflows
var publishedWorkflowDefinitions = workflowDeploymentService.EnumerateDefinitions(true);
clientContext.Load(publishedWorkflowDefinitions);
clientContext.ExecuteQuery();
// find the first workflow definition
var firstWorkflowDefinition = publishedWorkflowDefinitions.First();
// connect to the subscription service
var workflowSubscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();
// get all workflow associations
var workflowAssociations = workflowSubscriptionService.EnumerateSubscriptionsByDefinition(firstWorkflowDefinition.Id);
clientContext.Load(workflowAssociations);
clientContext.ExecuteQuery();
foreach (var association in workflowAssociations) {
Console.WriteLine("{0} - {1}",
association.Id, association.Name);
}
ワークフロー関連付けを作成する
新しいワークフロー関連付けの作成 (購読とも呼ばれます) では、実際に関連付けを SharePoint に公開する前にさらなる作業が必要になります。 これは、各購読に付加情報 (通常は関連付けページで収集されます) を含める必要があるためです。 このメタデータには以下が含まれます。
- 関連付けが基づくワークフロー定義の ID。
- ワークフロー関連付けが作成される SharePoint サイト、リスト、またはドキュメント ライブラリの ID。
- 関連付けの表示名。
- スタートアップ オプション (リスト アイテムが追加または更新されたときの開始方法が手動か自動か)。
- その関連付けに関するすべての履歴リスト メッセージを格納するリストの ID。
- その関連付けに関するすべてのタスクを格納するリストの ID。
- 必要に応じて、ワークフローに送信する必要がある名前/値のペアのコレクション。 これは、通常カスタム関連付けフォームから渡されるフィールドです。
カスタム ワークフロー関連付けを作成する
カスタム関連付けを作成するには、まず GetWorkflowSubscriptionService メソッドを使用して、サブスクリプション サービスへの参照を取得します。
// connect to the deployment service var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService(); // get all installed workflows var publishedWorkflowDefinitions = workflowDeploymentService.EnumerateDefinitions(true); clientContext.Load(publishedWorkflowDefinitions); clientContext.ExecuteQuery(); // find the first workflow definition var firstWorkflowDefinition = publishedWorkflowDefinitions.First(); // connect to the subscription service var workflowSubscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();WorkflowSubscription クラスの新しいオブジェクト インスタンスを作成します。
以下のコード例に示すように、 WorkflowSubscription オブジェクトに必要なプロパティを設定します。 この例では、コード コメントで各プロパティ設定について説明しています。 読みやすくなるように、CSOM ワークフロー サービスに関係のないプロパティは省略されています。 省略されているプロパティは以下のとおりです。
listId。 関連付けが作成されるリストの ID。
historyListId。 その関連付けに関するすべての履歴リスト メッセージを格納するリストの ID。
taskListId。 その関連付けに関するすべてのタスクを格納するリストの ID。
作成したサブスクリプションは、次のコード例に示すように PublishSubscriptionForList メソッドを使用して SharePoint に発行する必要があります。
// create a new association / subscription
WorkflowSubscription newSubscription = new WorkflowSubscription(clientContext) {
DefinitionId = firstWorkflowDefinition.Id,
Enabled = true,
Name = "New Workflow Association"
};
var startupOptions = new List<string>();
// automatic start
startupOptions.Add("ItemAdded");
startupOptions.Add("ItemUpdated");
// manual start
startupOptions.Add("WorkflowStart");
// set the workflow start settings
newSubscription.EventTypes = startupOptions;
// set the associated task and history lists
newSubscription.SetProperty("HistoryListId", workflowHistoryListId.ToString());
newSubscription.SetProperty("TaskListId", workflowTaskListId.ToString());
// OPTIONAL: add any association form values
newSubscription.SetProperty("Prop1","Value1");
newSubscription.SetProperty("Prop2","Value2");
// create the association
workflowSubscriptionService.PublishSubscriptionForList(newSubscription, listId);
clientContext.ExecuteQuery();
すべてのワークフロー インスタンスを取得する
ワークフロー サービスのインスタンス サービスを使用して、SharePoint サイト、リスト、またはドキュメント ライブラリで実行中のワークフロー インスタンスをすべて表示することもできます。 返されるインスタンス オブジェクトには、最終更新日時、現在の状態、前回実行時に発生したエラーなど、インスタンスに関する情報が含まれています。 また、カスタム開始フォームからワークフローに送信された名前/値のペアのコレクションも含まれます。
これを行うには、まず GetWorkflowInstanceService メソッドを使用してインスタンス サービスへの参照を取得します。 WorkflowInstanceService には、実行中のワークフロー インスタンスのコレクションを取得するためのさまざまなメソッドが用意されています。
- 列挙します。 ワークフローの関連付け (つまりサブスクリプション) をパラメーターとして受け入れ、指定した関連付けに基づいて作成されたすべてのインスタンスを取得するために使用できます。
- EnumerateInstancesForSite 。元の WorkflowServiceManager オブジェクトの作成時に設定された SharePoint サイトで開始されたすべてのワークフロー インスタンスのリストを取得します。
- EnumerateInstancesForListItem 。 リスト ID とアイテム ID を受け入れます。このメソッドを使用して、特定のリスト アイテムに作成されたすべてのワークフロー インスタンスを取得します。
これらの各メソッドには、代替 *WithOffset() メソッド ( EnumerateWithOffset など) もあります。 コレクション全体を操作すると煩雑になる場合は、この代替メソッドを使用してワークフロー インスタンスのサブセットを取得できます。 ワークフロー インスタンスの数を数えるには、 CountInstances メソッドまたは CountInstancesWithStatus メソッドを使用します。
以下のコード例に、ワークフロー インスタンスを取得する方法を示します。
// connect to the instance service
var workflowInstanceService = workflowServicesManager.GetWorkflowInstanceService();
// get all instances
var workflowInstances = workflowInstanceService.EnumerateInstancesForListItem(listId, listItemId);
foreach (var instance in workflowInstances)
{
Console.WriteLine("{0} - {1} - {2}",
instance.Id.ToString(),
instance.LastUpdated,
instance.Status.ToString());
}
ワークフロー インスタンスを開始する
ワークフロー関連付けの新しいインスタンスを開始するには、前の例で示した手順の多くを繰り返す必要があります。 リストまたはドキュメント ライブラリ内のアイテムでワークフローを開始するには、まず、ワークフローの関連付けとリスト内のアイテムの ID への参照を取得します。 情報の名前と値のペアのコレクションは、起動時にワークフローに送信できます。 これは、ワークフローを開始するユーザーからデータを収集するために使用されるカスタム開始フォームがある場合に発生します。 その後、空のコレクションであっても、ワークフローまたはワークフローを開始するときに、コレクションを渡すと、開始に失敗し、エラーが返されます。
前の例からビルドし、 GetWorkflowInstanceService メソッドを使用して、ワークフロー インスタンス サービスのインスタンスを取得します。 次に、以下の 2 つのメソッドのいずれかを呼び出してワークフローを開始します。 一方のメソッドはサイトでワークフローを開始し、もう一方のメソッドはリスト アイテムでワークフローを開始します。
- StartWorkflow 。 元の WorkflowServicesManager オブジェクトの作成時に設定された SharePoint サイトでワークフローを開始します。 このメソッドを使用する場合は、ワークフロー関連付け、および開始フォームにある追加のスタートアップ プロパティを渡す必要があります。
- StartWorkflowOnListItem 。 特定のリスト アイテムでワークフローを開始します。 このメソッドを使用するには、 StartWorkflow メソッドで必要なパラメーター値に加えて、目的のリスト アイテムの ID を渡す必要があります。
以下のコード例に、ワークフロー インスタンスを開始する方法を示します。
// connect to the deployment service
var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService();
// get all installed workflows
var publishedWorkflowDefinitions = workflowDeploymentService.EnumerateDefinitions(true);
clientContext.Load(publishedWorkflowDefinitions);
clientContext.ExecuteQuery();
// find the first workflow definition
var firstWorkflowDefinition = publishedWorkflowDefinitions.First();
// connect to the subscription service
var workflowSubscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();
// get all workflow associations
var workflowAssociations = workflowSubscriptionService.EnumerateSubscriptionsByDefinition(firstWorkflowDefinition.Id);
clientContext.Load(workflowAssociations);
clientContext.ExecuteQuery();
// find the first association
var firstWorkflowAssociation = workflowAssociations.First();
// connect to the instance service
var workflowInstanceService = workflowServicesManager.GetWorkflowInstanceService();
// start the workflow
var startParameters = new Dictionary<string, object>();
workflowInstanceService.StartWorkflowOnListItem(firstWorkflowAssociation, listItemId, startParameters);
clientContext.ExecuteQuery();
実行中のワークフローにメッセージとイベントを公開する
SharePoint で追加されたもう 1 つの強力な機能は、実行中のワークフロー インスタンスにカスタム イベントを発行する機能です。 これらのワークフローには、ワークフローに発行される特定のイベントをリッスンする アクティビティ WaitForCustomEvent を含めることができます。 イベントには、アクティビティが変数として格納できるメッセージの一部として文字列を含めることもできます。
ワークフロー サービス CSOM を使用するクライアントからイベントを公開するには、まず、イベントの公開先となる具体的なワークフロー インスタンスへの参照を取得します。 次に、インスタンス サービスを使用して、 PublishCustomEvent メソッドを使用してイベントを発行します。 このメソッドを使用する場合は、以下のコード例に示すように、目的のインスタンス、イベント名、オプションのペイロードを渡す必要があります。
// connect to the instance service
var workflowInstanceService = workflowServicesManager.GetWorkflowInstanceService();
// get all instances
var workflowInstances = workflowInstanceService.EnumerateInstancesForListItem(listId, listItemId);
var targetInstance = workflowInstances.First();
// publish custom event
instanceService.PublishCustomEvent(targetInstance, "AdHocMaintenanceRequest", "Flat Tire");
clientContext.ExecuteQuery();
ワークフローでメッセージを受信するには、 WaitForCustomEvent アクティビティを追加し、[ プロパティ ] ウィンドウを使用して、アクティビティがリッスンしているイベントの名前に EventName プロパティを設定します (上の例では、"AdHocMaintenanceRequest" という文字列になります)。 次 に、 Result プロパティを、図 2 に示すように、イベントのペイロードが格納される変数に設定します。
図 2. EventName の入力と結果の出力
このカスタム イベント公開の手法については、MSDN のコード サンプル「SharePoint: Route Workflows to States Depending on Actions and Events」で説明されています。
結論
Microsoft は SharePoint 2007 プラットフォームにワークフローを導入し、ワークフロー プラットフォームは SharePoint 2010 でほとんど変更されていませんでした。 これは、SharePoint ワークフローのカスタム フォームに関しても当てはまります。 一方、SharePoint では、ワークフロー プラットフォームとアーキテクチャに多くの変更が導入されました。
SharePoint のワークフローの主な改善点の 1 つは、完全なワークフロー サービス API が含まれるように CSOM が拡張されたことです。 これにより開発者は、ワークフロー定義、関連付け、購読を相互運用させたり、ワークフローのインスタンスを作成して操作することができます。