SharePoint ワークフロー サービスの Client Side Object Model を操作するWorking with the SharePoint Workflow Services Client Side Object Model

SharePoint クライアント側オブジェクト モデル (CSOM) API を使用して ワークフロー マネージャー 1.0 のワークフロー定義とワークフロー インスタンスを作成および制御する方法を説明します。 提供元: Andrew ConnellAndrewConnell.comDemonstrates how to use the SharePoint client-side object model (CSOM) API to create and control Workflow Manager 1.0 workflow definitions and instances. Provided by: Andrew Connell, AndrewConnell.com

SharePoint ワークフロー サービスの Client Side Object Model を操作するWorking with the SharePoint Workflow Services Client Side Object Model

SharePoint 2007 と SharePoint 2010 でのワークフローの実装は、バージョンが変わってもほとんど同じです。Microsoft は、ワークフローをサイトに関連付ける機能などの新機能をいくつか SharePoint 2010 に追加し、ワークフロー オーサリング ツールの SharePoint Designer 2010 と Visual Studio 2010 を旧バージョンから改善しました。しかしながら、ワークフロー タスクの実装、ワークフロー フォーム、ワークフロー サーバー側 API にはほとんど変更がありません。The implementation of workflows in SharePoint 2007 and SharePoint 2010 remained largely the same from version to version. Microsoft did add some new functionality in SharePoint 2010, such as the ability to associate workflows with sites, and improved the workflow authoring tools, SharePoint Designer 2010 and Visual Studio 2010, from their predecessors. However, the implementation of workflow tasks, workflow forms, and the workflow server-side APIs remains largely unchanged.

SharePoint 2010 では、カスタマイズをセキュリティで保護されたソリューションに簡単に移動できる機能が取り入れられました。これらの機能は、分離プロセスで実行され、どちらのタイプの SharePoint 展開でも (社内でもクラウドでも) 使いやすいものでした。社内の場合は、会社のサーバーに SharePoint をインストールし、会社が管理していました。また、クラウドとは、すなわち Office 365 のことです。In SharePoint 2010, Microsoft introduced features and capabilities that encouraged customers to move their customizations into sandboxed solution. These would run in an isolated process and were friendly to both types of SharePoint deployments: on-premises, where the SharePoint was installed on company servers and maintained by the company , and to the cloud, or more specifically, Office 365.

SharePoint では、さらに多くの機能が追加されました。これらの更新はクラウド展開志向となっています。具体的には、新しい SharePoint アプリ モデルが導入されました。これは、セキュリティで保護されたソリューションとは異なり、サーバー側コードが SharePoint プロセスで実行されるのを明示的にブロックするという点でセキュリティで保護されたソリューションより進んだ機能となります。また、クライアント側オブジェクト モデル (CSOM) などの既存テクノロジが SharePoint に構築され、 OAuth によるアプリ ID のサポートなどの新機能が導入されています。In SharePoint, Microsoft added even more capabilities; these updates were oriented toward cloud deployments. Specifically, Microsoft introduced the new SharePoint app model, which went further than the sandboxed solution in that, unlike sandboxed solution, they explicitly blocked server-side code from running in the SharePoint process. Microsoft also built up existing technologies in SharePoint, such as the client-side object model (CSOM), and introduced new capabilities, like support for app identities using OAuth.

さらに、SharePoint の導入により、マイクロソフトは、製品の方向性の抜本的転換を反映したまったく新しいワークフロー アーキテクチャおよびプラットフォームを導入することになりました。And then, with the introduction of SharePoint, Microsoft introduced an entirely new workflow architecture and platform that reflect fundamental shifts in the product direction.

新しいアーキテクチャで最も重要な変更は、SharePoint のワークフローが SharePoint 内で実行されなくなったことです。The most prominent change in the new architecture is that workflow execution in SharePoint no longer takes place in SharePoint. SharePoint は Workflow Manager 1.0 というまったく新しい実行エンジンを使用します。Instead, SharePoint uses a completely new execution engine: Workflow Manager 1.0. ワークフロー マネージャーは、Windows Workflow Foundation ランタイムと、Windows Workflow Foundation が必要とするすべてのサービスをホストします。Workflow Manager hosts the Windows Workflow Foundation runtime and all the necessary services required by Windows Workflow Foundation. ワークフローが発行されたとき、または発行済みのワークフローが開始されたときに、SharePoint は、ワークフローのエピソードを処理するワークフロー マネージャーに通知します。When a workflow is published, or a new instance of a published workflow is started, SharePoint notifies Workflow Manager, which in turn processes the workflow episodes. リストアイテムのプロパティやユーザーのプロパティなどの SharePoint の情報をワークフローがアクセスする場合、OAuth のサポートを使用して認証し、新しく改善された REST API を使用して通信します。When the workflow access information in SharePoint, such as list item properties or user properties, it authenticates using the OAuth support and communicates over new and improved REST APIs.

ワークフロー アーキテクチャのこのような変更は、カスタム ワークフロー フォームなどに大きな影響を与えます。このことは、MSDN の記事「Visual Studio 2012 で SharePoint のカスタム ワークフロー フォームを作成する方法」で取り上げています。These changes in the workflow architecture had significant impacts in certain areas, such as custom workflow forms, as discussed in the MSDN article How to: Create Custom SharePoint Workflow Forms with Visual Studio 2012. この記事は、カスタム ワークフロー フォームを作成する新しいスタイルを提唱するために SharePoint に追加された複数の要素のうちのひとつに触れています。それは、CSOM への改善と、Workflow Services CSOM API の追加です。This article touches on one of the things that Microsoft added to SharePoint to support the new style of creating custom workflow forms: the improvements to the CSOM and addition of the Workflow Services CSOM API.

SharePoint の Workflow Services CSOM API の概要Introduction to the Workflow Services CSOM API in SharePoint

SharePoint 2007 と SharePoint 2010 では、ワークフロー API はサーバー側オブジェクト モデルにのみ現れていました。SharePoint には、この同じワークフロー API が依然として存在しています。これは、下位互換性を維持する目的で SharePoint に SharePoint の古いワークフロー実行エンジンが含まれているためです。In SharePoint 2007 and SharePoint 2010, the workflow API was manifested only in the server-side object model. In SharePoint, this same workflow API is still present, since SharePoint includes the old workflow execution engine in SharePoint for backward compatibility.

しかしながら、ワークフロー マネージャーを使用する SharePoint で導入された推奨される新しいワークフロー アーキテクチャには、最新のサーバー側 API が含まれています。SharePoint では、新しいワークフロー アーキテクチャの堅牢な API が含まれるように CSOM が拡張されました。CSOM へのこの追加は、新しい SharePoint およびワークフロー マネージャー 1.0 のワークフロー アーキテクチャにのみ適用され、引き続き SharePoint でホストされている以前のバージョンには適用されない点に注意してください。However, the new and preferred workflow architecture introduced with SharePoint that uses Workflow Manager includes a brand new server-side API. In SharePoint, Microsoft extended the CSOM to include a robust API for the new workflow architecture. Note that this addition to the CSOM only applies to the new SharePoint and Workflow Manager 1.0 workflow architecture, not the legacy version that is still hosted by SharePoint.

ワークフロー サービス CSOM API は、他の CSOM と同様に .NET Silverlight マネージ API と JavaScript API (JavaScript オブジェクト モデル (JSOM) と呼ばれます) の両方に実装されます。JSOM は、開発者がカスタム ワークフロー フォームを作成する場合に使用しなければならないものです。これは、カスタム ワークフロー フォームが、サーバー側コードを含めてはいけない ASP.NET Web フォームとなるためです。したがって、ワークフロー サービス JSOM API は、ワークフロー関連付けを作成する場合はカスタム関連付けフォームで使用され、新しいワークフロー インスタンスを開始する場合は開始フォームで使用されます。The Workflow Services CSOM API, like the rest of the CSOM, is implemented both in a .NET Silverlight managed API and a JavaScript API known as the JavaScript Object Model (JSOM). JSOM is what developers must use when creating custom workflow forms as those forms will be ASP.NET web forms that must not have any server-side code. Thus the Workflow Services JSOM API is used in custom association forms to create workflow associations as well as on initiation forms to start new workflow instances.

しかし、可能性はこれにとどまりません。ワークフロー サービス CSOM および JSOM は非常に堅牢であり、開発者は SharePoint のワークフローについてはほぼ何でもできます。ワークフロー関連付けとワークフロー インスタンスの作成に加えて、新しいワークフロー定義をプログラムで展開したり、CSOM や JSOM から実行中のワークフロー インスタンスと通信したりすることもできます。詳細については、この記事の後半で説明します。However, the possibilities do not stop there. The Workflow Services CSOM and JSOM is very robust and enables developers to do almost anything with workflows in SharePoint. Aside from creating workflow associations and instances, developers can also programmatically deploy new workflow definitions and even communicate with running workflow instances from the CSOM and JSOM, as is discussed in the remainder of this article.

この記事では、SharePoint Server 2013 のコンテキストにおけるワークフロー フォームに関するトピックを取り上げています。This article focuses on the topic of workflow forms in the context of SharePoint Sever 2013. ここでは、2013 年 3 月のパブリック更新プログラムを適用した SharePoint と Office Developer tools for Visual Studio 2012 を使用します。It is based on the SharePoint with the March 2013 Public Update applied and Office Developer Tools for Visual Studio 2013. この記事のすべての内容は、SharePoint のオンプレミスの展開と Office 365 の両方に当てはまります。Everything in this article applies to both SharePoint on-premises deployments as well as Office 365.

Workflow Services CSOM と JSOM API のコンポーネントWorkflow Services CSOM and JSOM API components

この記事では、ワークフロー サービス CSOM API に焦点を当てます。また、その延長線上で JSOM API についても言及します。サーバー側ワークフロー サービス API についてはここでは触れません。ワークフロー サービス CSOM は、さまざまなタスクを実行するのに使用される各種サービスで構成されます。以下のセクションではこれらのサービスについて説明します。This article focuses on the Workflow Services CSOM API and thus, by extension, the JSOM API as well; the server side Workflow Services API is not discussed here. The Workflow Services CSOM consists of several different services that are used to perform different tasks. Each of these is discussed in the following sections.

注意

CSOM には存在せず、代わりにサーバー側 API と共に存在するその他のサービスが 1 つあります。それはメッセージング サービスです。このサービスは、メッセージ キューとメッセージ転送の管理に使用されます。There is one additional service that is not present in the CSOM, but is present instead with the server-side API. This is the Messaging Service, which is used to manage message queuing and message transport.

ワークフロー サービス CSOM および JSOM API を操作するには、開発者が、必要な参照をプロジェクト (CSOM の場合) とページ (JSOM の場合) に追加する必要があります。どちらの実装も要件は同じです。To work with the Workflow Services CSOM and JSOM APIs, developers must add the necessary references to their projects (in the case of CSOM) and pages (in the case of JSOM). Both implementations have the same requirements:

  • 次のコア SharePoint CSOM および JSOM ライブラリを参照します。Reference the core SharePoint CSOM and JSOM libraries:

    • Microsoft.SharePoint.Client.dllMicrosoft.SharePoint.Client.dll

    • Microsoft.SharePoint.Client.Runtime.dllMicrosoft.SharePoint.Client.Runtime.dll

    • Microsoft.SharePoint.Client.WorkflowServices.dllMicrosoft.SharePoint.Client.WorkflowServices.dll

  • 次のワークフロー サービス CSOM および JSOM ライブラリを参照します。Reference the Workflow Services CSOM and JSOM libraries:

    • SP.jsSP.js

    • SP.Runtime.jsSP.Runtime.js

    • SP.WorkflowServices.jsSP.WorkflowServices.js

ワークフロー サービス マネージャーWorkflow Service Manager

ワークフロー サービス CSOM API に含まれるすべてのサービスへの入り口となるのがワークフロー サービス マネージャーです。このオブジェクトは、以下のセクションで説明する他のすべてのサービスへのインスタンスを取得するために開発者が使用するものです。他の CSOM API 実装と同様に、 WorkflowServicesManager もコア SharePoint CSOM に依存しています。したがって、以下の CSOM と JSOM のコード例に示すように、接続する SharePoint サイトに有効なクライアント コンテキストと参照を渡す必要があります。The gateway to all services included in the Workflow Services CSOM API is the Workflow Service Manager. This object is what developers use to obtain instances to all the other services described in the following sections. Similar to other CSOM API implementations, the WorkflowServicesManager has a dependency on the core SharePoint CSOM and, therefore, you must pass in a valid client context and reference to the SharePoint site you want to connect to, as shown in the following CSOM and JSOM code examples.

CSOM: WorkflowServicesManager インスタンスの作成CSOM: Creating a WorkflowServicesManager instance


var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web); 

JSOM: WorkflowServicesManager インスタンスの作成JSOM: Creating a WorkflowServicesManager instance


var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web()); 

展開サービスDeployment service

Visual Studio 2012 で、ソリューション パッケージ (.wsp) を使用して、または SharePoint アプリ (.app) としてカスタム ワークフローを作成する場合は、ワークフロー定義を作成します。定義とは、ワークフロー プロセスやその内部に定義されているすべてのビジネス ルールおよび属性 (カスタム関連付けや開始フォームの場所など) のことです。これらの定義は、単独では、サイト、リスト、ドキュメント ライブラリとの関連付けに関連する状況以外では実行できないためあまり使いません。公開されてサイトで使用可能になったワークフロー定義は、新しいワークフロー関連付けを作成するページに移動すれば見ることができます (以下の図を参照)。When you create custom workflows using Visual Studio 2012, either using a solution package (.wsp) or as a SharePoint app (.app), you are creating workflow definitions. A definition is the workflow process and all business rules and attributes defined within it, such as the location of custom association and initiation forms. On their own, these definitions are not very useful because they cannot be run outside the context of an association with a site, list, or document library. The workflow definitions published and available in a site can be found by going to the page where a new workflow association can be created, as shown in the following figure.

図 1. ワークフローの関連付けを追加しますFigure 1. Add a workflow association

図 1. ワークフローの関連付けを追加します

公開されたワークフロー定義のコレクションは、展開サービスからアクセスできます。このサービスでは、現在サイトで保存および公開されているすべての定義のリストを取得できます。また、保存されている定義と新しい定義の両方を公開したり、既存の定義を削除したりすることもできます。SharePoint Designer 2013 で作成されたワークフローで使用できるワークフロー アクションを決定することも可能です。The collection of published workflow definitions is accessible through the deployment service. This service enables you to get a list of all currently saved and published definitions on the site, as well as to publish both saved and new definitions, remove existing definitions, and determine what workflow actions are available to SharePoint Designer 2013-authored workflows.

WorkflowDeploymentService オブジェクトは WorkflowServicesManager クラスから使用できます (以下のコード例を参照)。The WorkflowDeploymentService object is available through the WorkflowServicesManager class, as shown in the following code examples.

CSOM: WorkflowDeploymentService インスタンスの取得CSOM: Obtaining a WorkflowDeploymentService instance


var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowDeploymentService = workflowServicesManager.GetWorkflowDeploymentService(); 

JSOM: WorkflowDeploymentService インスタンスの取得JSOM: Obtaining a WorkflowDeploymentService instance


var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web()); 
var workflowDeploymentService = workflowServicesManager.getWorkflowDeploymentService();

購読サービスSubscription service

前のセクションで説明したように、ワークフローを作成したら、そのワークフローを定義として SharePoint に公開します。この定義を使用するには、ユーザーが、特定の SharePoint サイト、リスト、またはドキュメント ライブラリに追加メタデータと共に定義をリンクさせる関連付けを作成する必要があります。このプロセスは、基本的に SharePoint 2010 と同じように動作しますが、SharePoint での実装はまったく異なります。ワークフロー マネージャー 1.0 は、Microsoft Azure のサービス バス 1.0 のインスタンスを利用します。Recall from the previous section that you create workflows and publish them to SharePoint as definitions. To use these definitions, a user must create an association that links the definition to a specific SharePoint site, list, or document library along with additional metadata. This process basically works and behaves the same way in SharePoint 2010 but the implementation in SharePoint is very different. Workflow Manager 1.0 takes advantage of an instance of Microsoft Azure Service Bus 1.0.

サービス バスは、公開/購読サービス (PubSub とも呼ばれます) をサポートしているため役に立ちます。これは、サービス バスに格納されているトピックへの公開元によるメッセージ送信を支援する非同期のメッセージング フレームワークです。不特定多数の購読者が、特定の条件を満たすトピックにメッセージが公開されたら通知を受け取るように要求できます。Service Bus is instrumental because it supports the publication and subscription service (also known as PubSub). This is an asynchronous messaging framework that supports a publisher sending a message to a topic stored in Service Bus. Any number of subscribers can request to be notified when a message is published to that topic that meets specific criteria.

SharePoint と ワークフロー マネージャー 1.0 は、PubSub モデルを使用して関連付けを作成します。ワークフローの関連付けは、トピックの購読として作成されます。たとえば、ワークフロー定義の関連付けをリストに作成し、そのリストにアイテムが追加されたら自動的に開始するように設定できます。リストにアイテムが追加されると、SharePoint が、サービス バスのトピックにメッセージを送信するワークフロー マネージャー 1.0 にイベントを公開します。そして、メッセージが評価され、登録されている購読にイベントが通知されます。購読されている関連付けが見つかったら、ワークフローが開始されます。このプロセスの動作の詳細については、MSDN の記事「 SharePoint ワークフローの基盤」をご覧ください。SharePoint and Workflow Manager 1.0 use the PubSub model to create associations. Workflow associations are created as subscriptions on topics. For instance, an association for workflow definition may be created on list and set to start automatically when items are added to the list. When an item is added to the list, SharePoint publishes an event to Workflow Manager 1.0, which it sends to the Service Bus topic. The message is evaluated and the registered subscriptions are notified of the event. The subscribed association is found and the workflow is started. For more information about how this process works, see the MSDN article, SharePoint workflow fundamentals.

これで、ワークフロー関連付けが、現在なぜ API 内の (つまり密かに) 購読と呼ばれているか明確になったはずです。ワークフロー サービス CSOM の購読サービスでは、既存の関連付けおよび購読の探索、関連付けおよび購読の作成/削除、イベント通知要求を行うことができます。This should clarify, then, why workflow associations are now called subscriptions within the API (that is, under the covers). You can use a Subscription Service in the Workflow Services CSOM to explore existing associations and subscriptions, create and delete associations and subscriptions, and request to be notified of events.

WorkflowSubscriptionService オブジェクトは WorkflowServicesManager クラスから使用します (以下のコード例を参照)。The WorkflowSubscriptionService object is available through the WorkflowServicesManager class, as shown in the following code examples.

CSOM: WorkflowSubscriptionService インスタンスの取得CSOM: Obtaining a WorkflowSubscriptionService instance


var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowSubscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();

JSOM: WorkflowSubscriptionService インスタンスの取得JSOM: Obtaining a WorkflowSubscriptionService instance


var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web()); 
var workflowSubscriptionService = workflowServicesManager.getWorkflowSubscriptionService();

インスタンス サービスInstance service

最後に取り上げるのはインスタンス サービスです。このサービスでは、ワークフロー インスタンス (開始、中断、再開、終了、キャンセルなどのワークフロー インスタンス) を使用してさまざまなタスクを実行できます。また、デバッグ情報を収集したり、現在実行中のワークフローと既に完了したワークフローをすべて列挙したりすることもできます。最後に、このサービスを使用して、現在実行中のワークフローにイベントを公開できます。詳細については後述します。The final service that we'll cover is the instance service. You can use this service to perform several tasks with workflow instances, such as starting, suspending, resuming, terminating, and cancelling workflow instances. You can also use it to collect debug information, as well as enumerate through all currently running workflows, as well as those that have already completed. Finally, you can use this service to publish events to workflows that are currently running, as we'll see later in this article.

WorkflowInstanceService オブジェクトは WorkflowServicesManager クラスから使用できます (以下のコード例を参照)。The WorkflowInstanceService object is available through the WorkflowServicesManager class, as shown in the following code examples.

CSOM: WorkflowInstanceService インスタンスの取得CSOM: Obtaining a WorkflowInstanceService instance


var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowInstanceService = workflowServicesManager.GetWorkflowInstanceService();

JSOM: WorkflowInstanceService インスタンスの取得JSOM: Obtaining a WorkflowInstanceService instance


var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web()); 
var workflowInstanceService = workflowServicesManager.getWorkflowInstanceService();

相互運用サービスInterop service

SharePoint の旧バージョン (具体的には SharePoint 2007 と SharePoint 2010) では、Windows Workflow Foundation ランタイムがホストされていました。前述したように、SharePoint ではこの方法から脱却し、SharePoint の外部でワークフロー ランタイムをホストするワークフロー マネージャー 1.0 への依存を採用しています。したがって、ワークフローは SharePoint の内部で実行も管理もされなくなりました。ワークフローの管理と実行は、代わりにワークフロー マネージャー 1.0 が担うことになります。In previous versions of SharePoint, specifically SharePoint 2007 and SharePoint 2010, SharePoint hosted the Windows Workflow Foundation runtime. As previously explained, Microsoft moved away from this approach in SharePoint by introducing a dependency on Workflow Manager 1.0, which hosts the workflow runtime outside of SharePoint. Consequently, workflows are no longer executed and managed within SharePoint; instead, SharePoint hands off workflow management and execution responsibilities to Workflow Manager 1.0.

ただし、下位互換性を保つため、Windows Workflow Foundation ランタイム エンジンを維持することで、SharePoint の内部で SharePoint 以前のスタイルのワークフローをホストするレガシ モデルにも対応しています。したがって、SharePoint 2010 で作成されたワークフローはすべて、SharePoint 環境でも期待どおりに実行されます。また、 InvokeSharePointWorkflow という新しいアクティビティも含まれています。これを、SharePoint ワークフローで使用すると、SharePoint に含まれている SharePoint 2010 ワークフロー ホストで既存のワークフローを開始することができます。これにより、旧バージョンから移行した既存のワークフロー投資を利用できるようになります。However, to provide backward compatibility, Microsoft retained the legacy model of hosting pre-SharePoint-style workflows within SharePoint by keeping the Windows Workflow Foundation runtime engine. Therefore, all workflows created in SharePoint 2010 will still run as expected in a SharePoint environment. In addition, Microsoft included a new activity, InvokeSharePointWorkflow, which can be used in a SharePoint workflow to start an existing workflow in the SharePoint 2010 workflow host that is included in SharePoint. This allows you to take advantage of existing workflow investments migrated from previous versions.

注意

InvokeSharePointWorkflow アクティビティは CSOM メソッド StartWorkflow のラッパーです。Note: The InvokeSharePointWorkflow activity is a wrapper for the CSOM method, StartWorkflow .

SharePoint ワークフロー サービス CSOM にも、開発者がレガシ ワークフローを相互運用できる特別なサービスが含まれています。 InteropService では、ワークフローの開始/停止や、実行中のワークフローに関するイベント通知の有効化/無効化が可能です。The SharePoint Workflow Services CSOM also includes a special service that enables developers to interact with these legacy workflows. The InteropService lets you start and stop workflows, as well as enable and disable event notifications for running workflows.

WorkflowDeploymentService オブジェクトは WorkflowServicesManager クラスから使用できます (以下の CSOM と JSOM のコード例を参照)。The WorkflowDeploymentService object is available through the WorkflowServicesManager class, as shown in the following CSOM and JSOM code examples.

CSOM: InteropService インスタンスの取得CSOM: Obtaining an InteropService instance


var clientContext = new ClientContext(siteCollectionUrl);
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var workflowInteropService = workflowServicesManager.GetWorkflowInteropService();

JSOM: InteropService インスタンスの取得JSOM: Obtaining an InteropService instance


var clientContext = SP.ClientContext.get_current();
var workflowServicesManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context, context.get_web()); 
var workflowInteropService = serviceManager.getWorkflowInteropService();

例: ワークフロー サービス CSOM のシナリオExample: Workflow Services CSOM scenarios

以下のセクションでは、ワークフロー サービス CSOM のさまざまなサービスを使用して、カスタム ソリューションで一般的なタスクを実行する方法について説明します。The following sections demonstrate how to use the different services in the Workflow Services CSOM to perform common tasks in custom solutions.

インストールされているワークフローをすべて取得するGet all workflows installed

ワークフロー サービス CSOM のその他のサービスではたいてい、以前公開されたワークフロー定義への参照を取得する必要があります。一般に、ワークフロー定義は ID (GUID) で参照されます。Most of the other services in the Workflow Services CSOM require that you get references to the workflow definition that was previously published. Workflow definitions are usually referenced by their IDs, which are GUIDs.

公開されたすべてのワークフロー定義のリストを取得するには、まず、 GetWorkflowDeploymentService メソッドを使用して展開サービスのインスタンスを取得します。次に、 EnumerateDefinitions(Boolean) メソッドを使用してすべてのワークフロー定義のコレクションを取得します。以下にコード例を示します。To get a list of all the published workflow definitions, first get an instance of the deployment service by using the GetWorkflowDeploymentService method. Then, retrieve the collection of all workflow definitions by using the EnumerateDefinitions(Boolean) method. Here is example code:


// 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);
}

関連付けと購読をすべて取得するGet all associations and subscriptions

新しいワークフロー インスタンスを開始するには、まず、既存のワークフロー関連付けへの参照を取得する必要があります。以下の例では、前のコード例に基づいて、サイト内の特定のワークフロー定義に関するすべてのワークフロー関連付けのリストを取得する方法を示します。To start a new workflow instance, you need to first get a reference to an existing workflow association. Building on the previous code example, the following example demonstrates how to get a list of all workflow associations for a specific workflow definition in a site.

上記の例を使用してワークフロー定義を取得したら、 GetWorkflowSubscriptionService メソッドを使用して購読サービスのインスタンスを作成します。次に、 EnumerateSubscriptionsByDefinition メソッド (ワークフロー定義の ID を渡します) を使用して、指定したワークフローに対して存在するすべての関連付けのリストを取得します。ワークフロー関連付けの取得に使用できるメソッドは、以下を含めていくつかあります。Once you have obtained a workflow definition using the example above, use the GetWorkflowSubscriptionService method to create an instance of the subscription service. Next, use the EnumerateSubscriptionsByDefinition method (passing in the ID of a workflow definition) to get a list of all the associations that exist for the specified workflow. Note that there are several methods available for getting workflow associations, including the following:

以下のコード例に、関連付けと購読を取得する方法を示します。The following code example demonstrates getting associations and subscriptions.


// 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);
}

ワークフロー関連付けを作成するCreating a workflow association

新しいワークフロー関連付けの作成 (購読とも呼ばれます) では、実際に関連付けを SharePoint に公開する前にさらなる作業が必要になります。これは、各購読に付加情報 (通常は関連付けページで収集されます) を含める必要があるためです。このメタデータには以下が含まれます。Creating a new workflow association, which can also be referred to as a subscription, requires additional effort before actually publishing the association to SharePoint. This is because each subscription needs to have additional information, which is usually collected on the association page. This metadata includes the following:

  • 関連付けが基づくワークフロー定義の ID。The ID of the workflow definition the association is based on.

  • ワークフロー関連付けが作成される SharePoint サイト、リスト、またはドキュメント ライブラリの ID。The ID of the SharePoint site, list or document library the workflow association is created on.

  • 関連付けの表示名。The display name of the association.

  • スタートアップ オプション (リスト アイテムが追加または更新されたときの開始方法が手動か自動か)。The startup options (whether started manually or automatically when a list item is added or updated).

  • その関連付けに関するすべての履歴リスト メッセージを格納するリストの ID。The ID of the list that will store all history list messages for this association.

  • その関連付けに関するすべてのタスクを格納するリストの ID。The ID of the list that will store all tasks for this association.

  • 必要に応じて、ワークフローに送信する必要がある名前/値のペアのコレクション。これは、通常カスタム関連付けフォームから渡されるフィールドです。Optionally, a collection of any name/value pairs that should be sent to the workflow. These are the fields that are usually passed in from a custom association form.

カスタム ワークフロー関連付けを作成するCreating a custom workflow association

  1. カスタム関連付けを作成するには、まず、 GetWorkflowSubscriptionService メソッドを使用して購読サービスへの参照を取得します。To create a custom association, first use the GetWorkflowSubscriptionService method to get a reference to the subscription service.

// 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();
  1. WorkflowSubscription クラスの新しいオブジェクト インスタンスを作成します。Create a new object instance of the WorkflowSubscription class.

  2. 以下のコード例に示すように、 WorkflowSubscription オブジェクトに必要なプロパティを設定します。この例では、コード コメントで各プロパティ設定について説明しています。読みやすくなるように、CSOM ワークフロー サービスに関係のないプロパティは省略されています。省略されているプロパティは以下のとおりです。Set the required properties on the WorkflowSubscription object, as illustrated in the following code example. In the example, code comments explain each of the property settings. Note that some properties that are not relevant to CSOM workflow services have been left out for readability. These properties have been omitted:

  3. listId。関連付けが作成されるリストの ID。listId. The ID of the list on which the association is created.

  4. historyListId。その関連付けに関するすべての履歴リスト メッセージを格納するリストの ID。historyListId. The ID of the list that stores all history list messages for the association.

  5. taskListId。その関連付けに関するすべてのタスクを格納するリストの ID。taskListId. The ID of the list that will store all tasks for the association.

  6. 作成されたら、以下のコード例に示すように、 PublishSubscriptionForList メソッドを使用して SharePoint に購読を公開する必要があります。Once created, the subscription must be published to SharePoint using the PublishSubscriptionForList method, as demonstrated in the following code example:


// 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();

すべてのワークフロー インスタンスを取得するGet all workflow instances

ワークフロー サービスのインスタンス サービスを使用して、SharePoint サイト、リスト、またはドキュメント ライブラリで実行中のワークフロー インスタンスをすべて表示することもできます。返されるインスタンス オブジェクトには、最終更新日時、現在の状態、前回実行時に発生したエラーなど、インスタンスに関する情報が含まれています。また、カスタム開始フォームからワークフローに送信された名前/値のペアのコレクションも含まれます。You can also use the Workflow Services instance service to view all workflow instances that are running on a SharePoint site, list, or document library. The instance object that is returned contains information on the instance, such as when it was last updated, the current status, and any errors that may have occurred when it ran previously. Additionally, it provides a collection of name/value pairs that were submitted to the workflow from the custom initiation form.

これを行うには、まず、 GetWorkflowInstanceService メソッドを使用してインスタンス サービスへの参照を取得します。 WorkflowInstanceService には、実行中のワークフロー インスタンスのコレクションを取得するためのさまざまなメソッドが用意されています。To do this, start by using the GetWorkflowInstanceService method to get a reference to the instance service. Note that the WorkflowInstanceService provides several methods for obtaining the collection of running workflow instances:

  • Enumerate 。ワークフロー関連付け (すなわち購読) をパラメーターとして受け取ります。指定した関連付けに基づいて作成されたすべてのインスタンスを取得する場合に使用できます。Enumerate . Accepts a workflow association (that is, a subscription) as a parameter, and can be used to get all the instances that have been created based on the specified association.

  • EnumerateInstancesForSite 。元の WorkflowServiceManager オブジェクトの作成時に設定された SharePoint サイトで開始されたすべてのワークフロー インスタンスのリストを取得します。EnumerateInstancesForSite : Gets a list of all workflow instances that have been started on the SharePoint site that was set when creating the original WorkflowServiceManager object.

  • EnumerateInstancesForListItem 。リスト ID とアイテム ID を受け取ります。このメソッドでは、特定のリスト アイテムで作成されたすべてのワークフロー インスタンスを取得できます。EnumerateInstancesForListItem . Accepts a list ID and item ID; use this method to get all workflow instances that have been created on a specific list item.

これらの各メソッドには、代替の *WithOffset() メソッド (たとえば EnumerateWithOffset ) もあります。コレクション全体を操作すると煩雑になる場合は、この代替メソッドを使用してワークフロー インスタンスのサブセットを取得できます。ワークフロー インスタンスの数を数えるには、 CountInstances メソッドまたは CountInstancesWithStatus メソッドを使用します。Each of theses methods also has an alternate *WithOffset() method (for example, EnumerateWithOffset ). These alternative methods allow you to get a subset of the workflow instances in cases where working with the entire collection would be cumbersome. To get a count of the number of workflow instances, use the CountInstances method, or the CountInstancesWithStatus method.

以下のコード例に、ワークフロー インスタンスを取得する方法を示します。The following code example illustrates getting workflow instances:


// 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());
}

ワークフロー インスタンスを開始するStart a workflow instance

ワークフロー関連付けの新しいインスタンスを開始するには、前の例に示した数多くのステップを繰り返す必要があります。リストのアイテムまたはドキュメント ライブラリでワークフローを開始するには、まず、ワークフロー関連付けへの参照、およびリストのアイテムの ID を取得します。ワークフローが開始されたら、情報の名前/値のペアのコレクションをワークフローに送信できます。これができるのは、ワークフローを開始するユーザーからデータを収集するのに使用されるカスタム開始フォームが存在する場合です。ワークフローが開始されたらコレクションを渡します (空のコレクションの場合も同様です)。渡さなかった場合は、ワークフローの開始が失敗し、エラーが返されます。Starting a new instance of a workflow association involves repeating many of the steps that have been demonstrated in the previous examples. To start a workflow on an item in a list or document library, first obtain a reference to the workflow association and the ID of the item in the list. A collection of name/value pairs of information can be sent to the workflow when it is started. This happens when there is a custom initiation form that is used to collect data from the user starting the workflow. Then pass in a collection, even if it is an empty collection, when starting the workflow or the workflow will fail to start and return an error.

前の例に基づいて、 GetWorkflowInstanceService メソッドを使用してワークフロー インスタンス サービスのインスタンスを取得します。次に、以下の 2 つのメソッドのいずれかを呼び出してワークフローを開始します。一方のメソッドはサイトでワークフローを開始し、もう一方のメソッドはリスト アイテムでワークフローを開始します。Building from previous examples, use the GetWorkflowInstanceService method to get an instance of the workflow instance service. Next, start the workflow by calling one of two methods. One starts workflows on a site, while the other starts a workflow on a list item.

  • StartWorkflow 。元の WorkflowServicesManager オブジェクトの作成時に設定された SharePoint サイトでワークフローを開始します。このメソッドを使用する場合は、ワークフロー関連付け、および開始フォームにある追加のスタートアップ プロパティを渡す必要があります。StartWorkflow . Starts a workflow on the SharePoint site that was set when creating the original WorkflowServicesManager object. When using this method, you must pass in the workflow association and any additional startup properties present on the initiation form.

  • StartWorkflowOnListItem 。特定のリスト アイテムでワークフローを開始します。このメソッドを使用するには、 StartWorkflow メソッドで必要なパラメーター値に加えて、目的のリスト アイテムの ID を渡す必要があります。StartWorkflowOnListItem . Starts a workflow on a specific list item. Using this method requires you to pass in the ID of the desired list item, in addition to other parameter values required by the StartWorkflow method.

以下のコード例に、ワークフロー インスタンスを開始する方法を示します。The following code example demonstrates how to start a workflow instance.


// 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();

実行中のワークフローにメッセージとイベントを公開するPublishing messages and events to running workflows

SharePoint に追加されたもう一つの強力な機能は、実行中のワークフロー インスタンスにカスタム イベントを公開する機能です。実行中のワークフローには、 WaitForCustomEvent アクティビティを含めることができます。このアクティビティは、ワークフローに公開される特定のイベントをリッスンします。また、イベントには、メッセージの一部として文字列を含めることもできます。このアクティビティでは、この文字列を変数として格納できます。Another powerful feature that was added in SharePoint is the ability to publish custom events to running workflow instances. These workflows can have an activity, WaitForCustomEvent, which listens for a specific event to be published to the workflow. The event can also contain a string as part of the message, which the activity can store as a variable.

ワークフロー サービス CSOM を使用するクライアントからイベントを公開するには、まず、イベントの公開先となる具体的なワークフロー インスタンスへの参照を取得します。次に、インスタンス サービスを使用し、 PublishCustomEvent メソッドでイベントを公開します。このメソッドを使用する場合は、以下のコード例に示すように、目的のインスタンス、イベント名、オプションのペイロードを渡す必要があります。To publish an event from the client using the Workflow Service CSOM, first get a reference to the specific workflow instance that the event should be published to. Then, using the instance service, publish the event using the PublishCustomEvent method. When using this method, you must pass in the desired instance, event name, and an optional payload, as shown in the following code example.


// 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" という文字列になります)。さらに、図 2 に示すように、イベントのペイロードが格納される変数に Result プロパティを設定します。To receive the message in the workflow, add a WaitForCustomEvent activity and, using the Properties window, set the EventName property to the name of the event the activity is listening for (in the example above, this would be the string, "AdHocMaintenanceRequest"). Then, set the Result property to the variable in which the event's payload is stored, as shown in Figure 2.

図 2. EventName の入力と結果の出力Figure 2. Input EventName and output Result

図 2. EventName の入力と結果の出力

このカスタム イベント公開の手法については、MSDN のコード サンプル「SharePoint: Route Workflows to States Depending on Actions and Events」で説明されています。This technique of publishing a custom event is demonstrated in the MSDN Code Sample: SharePoint: Route Workflows to States Depending on Actions and Events.

結論Conclusion

Microsoft は、SharePoint 2007 プラットフォームにワークフローを導入しました。SharePoint 2010 では、このワークフロー プラットフォームにほとんど変更はありませんでした。これは、SharePoint ワークフローの独自のフォームについても同じでした。これに対し、SharePoint では、ワークフロー プラットフォームとワークフロー アーキテクチャが大幅に変更されました。Microsoft introduced workflows into the SharePoint 2007 platform, and the workflow platform remained largely unchanged in SharePoint 2010. This was also true when it came to Custom Forms in SharePoint workflows. SharePoint, on the other hand, introduced many changes to workflow platform and architecture.

SharePoint のワークフローの主な改善点の 1 つは、完全なワークフロー サービス API が含まれるように CSOM が拡張されたことです。これにより開発者は、ワークフロー定義、関連付け、購読を相互運用させたり、ワークフローのインスタンスを作成して操作することができます。One of the major improvements to workflows in SharePoint is the expansion of CSOM to include a complete Workflow Services API. This addition enables developers to interact with workflow definitions, associations, and subscriptions, and to create and interact with instances of these workflows.

関連項目See also