ワークフローへのカスタム機能の組み込み

この章では、ワークフローにカスタム機能を組み込む方法を説明します。以下のトピックについて説明します。

標準タスク・フォームの拡張

各タスクには、少なくとも以下の標準アイテム・セットを表示する 1 つのタスク・フォームが関連付けられています。

そのタスクの TaskId、Owner、%Subject、および %Message という読み取り専用プロパティ
[承認] ボタン (そのタスクが未割り当ての場合)
[放棄] ボタンと [保存] ボタン (そのタスクが割り当て済みの場合)

他のボタンを追加するには (これらのボタンはそのタスクが割り当て済みの場合にのみ表示されます)、タスク要求の %Actions プロパティで、追加するボタン名のコンマ区切りリストを指定します。

他の編集可能な値を追加するには (これらの値はそのタスクが割り当て済みの場合にのみ表示されます)、タスク要求オブジェクトで次のいずれかのプロパティを設定します。

%FormFields — 表示するタスク・フォームのフィールドのリストを提供します。
タスク要求オブジェクトおよびタスク応答オブジェクトには、%FormFields プロパティがあります。タスク要求を呼び出すときに、%FormFields の値を、タスク・フォームに表示するフィールドのカンマ区切りリストに設定します。現時点では、これらはすべて単純な文字列値と見なされます (制御を強化する必要がある場合は、フォーム・テンプレートを使用)。
%FormTemplate — 表示する HTML フォーム・テンプレートを定義する Caché Server Pages (CSP) ファイルを指定します。
タスク要求オブジェクトおよびタスク応答オブジェクトには、%FormTemplate プロパティがあります。タスク要求を呼び出すときに、%FormTemplate の値を、表示するフォームを定義する CSP ファイルの名前に設定します。この CSP ページでは、フォームとコンテンツのみを定義します。HTML、HEAD、BODY の各セクションはありません。CSP ページでは、特定の JavaScript イベント・メソッドをオーバーロードできます。このフォームを処理するとき、変数 %task は現在のタスク応答オブジェクトです。

%FormFields または %FormTemplate を使用する場合は、各フィールドに表示されるデフォルト値を指定できます。そのためには、タスク要求オブジェクトの %FormValues プロパティを指定します。このプロパティは、フィールド名が添え字として使用された、文字列の配列です。このプロパティに値を追加するには、array インタフェースを使用します。

ワークフロー・エンジンでは、タスクを処理するときに、配列コレクション %FormValues を含むフォーム関連のすべてのプロパティが、タスク要求からタスク応答へコピーされます。フォーム内のフィールドの値が更新されるたびに、ワークフロー・エンジンは、タスク応答オブジェクトの %FormValues コレクションで値を更新します。

フォームには常に、%FormValues コレクションの最新の値が表示されます。これにより、特定タスク内でフォームを動的に処理できます。フォーム関連のプロパティの値を変更することにより、タスク応答コールバック・メソッドを、フォーム処理の実行方法に反映させることができます。タスク応答オブジェクトの %FormValues コレクションは、最終的なタスク応答が送り返されたときに、元の呼び出し側で使用できます。

カスタム・タスク・フォームの使用

ワークフロー・タスク用に、カスタム・フォームをユーザに対して表示できます。手順は以下のとおりです。

カスタマイズされたフォームのコンテンツを定義する HTML テンプレート・ファイルを作成します。これは Caché Server Pages (CSP) ページとして実装されるため、必要に応じて動的コンテンツを含めることができます。
タスク要求オブジェクトの %FormTemplate プロパティを、この CSP ページの名前に設定します。例えば、タスク要求をワークフロー・オペレーションに送信する <call> 文には以下のような内容が含まれます。
```
<assign property='callrequest.%FormTemplate'
        value='"MyForm.csp"'
        action='set' />
```
タスク要求オブジェクトの %FormFields プロパティを、フィールド名のカンマ区切りリストに設定します。これは、フォーム用に定義されるフィールドのリストです。以下に例を示します。
```
<assign property='callrequest.%FormFields'
        value='"Details,CustomerName"'
        action='set' />
```
フォーム・フィールドに初期値を指定する場合は、タスク要求オブジェクトの %FormValues コレクション・プロパティの対応する要素 (配列キーがフィールドの名前) を、必要な値に設定します。以下に例を示します。
```
<assign property='callrequest.%FormValues'
        value='request.CustomerName'
        action='set'
        key='"CustomerName"' />
```

前述のとおり、ワークフロー・ユーザが自身が現在所有しているタスクをレビューするたびに、関連付けられたタスク・フォームが自動的に表示されます。デフォルトでは、このフォームは、タスク要求オブジェクトの %FormFields プロパティの値で定義されるフィールドを使用して、自動的に生成されます。呼び出し側のビジネス・プロセスが、これらの値を指定します。ただし、この生成されるフォームの代わりに、カスタム設計されたテンプレートを使用する方法もあります。

ワークフロー・フォーム・テンプレートでは、標準タスク・フォームに挿入される HTML のブロックが定義されます。この HTML ブロックに含めることのできるフォーム・フィールドの数に制限はありません。これらのフィールドは、ワークフロー・タスクでユーザがアクションを実行するたびに、ワークフロー・エンジンによって自動的に送信され、処理されます。テンプレート・ファイルに含まれる HTML は、完全な HTML ドキュメントではありません。フォームのカスタム部分を表示するために必要な HTML です。具体的には、タスク・フォームによって生成される HTML は以下のようになります。

<html>
  <body>
    <form>
      —TEMPLATE CONTENTS INJECTED HERE—
    </form>
  </body>
</html>

以下のテンプレートでは、テキスト・ボックスと選択 (コンボボックス) の 2 つの HTML 入力コントロールを表示する HTML テーブルを定義します。コントロールの名前は、%FormFields プロパティで定義されているフィールドに対応します。この例では、サーバ側の式も使用して、Details プロパティの初期値を取得します。%task 変数は、常に現在のタスク応答オブジェクトに設定されています。

<!— workflow template —>
<table>
  <tr>
    <td>Details:</td>
    <td>
      <input type="text"
             name="Details"
             value="#(%task.%FormValues.GetAt("Details"))#">
    </td>
  </tr>
  <tr>
    <td>Company:</td>
    <td>
      <select name="CustomerName">
        <option value="ABC Corp">ABC Corp</option>
        <option value="XYZ Corp">XYZ Corp</option>
      </select>
    </td>
  </tr>
</table>

HTML の他に、ワークフロー・テンプレート・ファイルには、以下の Javascript コールバック関数をオプションで含めることができます。

onLoad() — ワークフロー・フォームがブラウザにロードされたときに呼び出されます。
onAction() — フォームで表示されたアクション・ボタンのいずれかをユーザがクリックしたときに呼び出されます。

これらのコールバックをワークフロー・テンプレート・ファイルに追加するには、テンプレート・ファイルの <script> タグの中に関数定義を含めます。例えば、以下のようにします。

<script language="JavaScript">
        function onLoad(form)
        {
                // form is the workflow form object
                return true;
        }

        function onAction(form,action)
        {
                // form is the workflow form object
                // action is a string containing the user's action
                // returning false will cancel this action
                return true;
        }
        </script>

タスク分配方式のカスタマイズ

タスク分配方式は、タスク応答クラスで指定されます。カスタム・タスク分配方式を実装するには、以下の操作を行います。

EnsLib.Workflow.TaskResponseOpens in a new tab のサブクラスを作成し、その OnNewTask() コールバック・メソッド (および場合によっては他のメソッド) をオーバーライドします。最初の項では、これのオプションについて詳述します。
カスタム・タスク応答クラスを必ず呼び出してください。これについては、2 つ目の項で説明します。

カスタム・タスク応答クラスの作成

EnsLib.Workflow.TaskResponseOpens in a new tab のサブクラスを作成する際には、その OnNewTask() コールバック・メソッド (および場合によっては他のメソッド) をオーバーライドします。以下では、オーバーライドできるコールバック・メソッドを列挙しています。

OnAction() — ワークリスト・フォームからユーザがアクションを選択したときに呼び出されます。通常、これはタスク終了のマーキングとなります。
OnAssign() — ユーザがタスクに関連付けられている所有権を要求したときに呼び出されます。通常、このメソッドでは割り当てが実行されます。
OnCancel() — タスクが取り消されたとき、例えばタイム・アウトしたときなどに呼び出されます。
OnFormSubmit() — このタスクに関連付けられているタスク・フォームが送信されたときに呼び出されます。
OnNewTask() — ワークフロー・エンジンで新しいタスクを受信したときに呼び出されます。通常、このメソッドでは、タスクが現在の役割のメンバに関連付けられます。
OnRelinquish() — ユーザがタスクに関連付けられている所有権の放棄を要求したときに呼び出されます。通常、このメソッドでは、タスクの割り当てが解除され、役割に含まれる他のユーザにタスクが戻されます。
OnRoleChange() — このタスクに関連付けられているユーザまたはロールの定義が変更されたとき、例えばロールに含まれるユーザのリストが変更されたときなどに呼び出されます。

EnsLib.Workflow.TaskResponseOpens in a new tab コールバック・メソッドでは、ワークフロー・エンジン (EnsLib.Workflow.EngineOpens in a new tab) で定義されている API メソッドの数を呼び出すことにより、タスクの分配が制御されます。

以下では、上記のコールバックをオーバーライドする際に使用できる EnsLib.Workflow.EngineOpens in a new tab 内のクラス・メソッドを列挙しています。

AssignTask() — 特定のユーザにタスクを割り当てます。
CompleteTask() — タスクを [Completed] としてマーキングし、呼び出し側に応答を返します。
FindLeastBusyUser() — “最もビジーでない” ユーザの名前を返します。これは、システム内で割り当てられているタスクが最も少ないユーザです。
SendTask() — 特定のユーザにタスクを送信します。
SendTaskToAll() — 現在のロールに含まれる全ユーザにタスクを送信します。
SendTaskToTitle() — 現在のロールの中で、指定したタイトルを持つ 1 人または複数のユーザにタスクを送信します。
SendTaskToTop() — 現在のロールに含まれる上位 n ユーザに、ロールの中での各ユーザのランキングに従ってタスクを送信します。
UnassignTask() — タスクの割り当てを削除します。

これらのメソッドの詳細は、"Intersystems クラス・リファレンス" を参照してください。

カスタム・タスク応答クラスの呼び出し

タスク要求メッセージには、使用する応答クラスを指定するクラス・パラメータ (RESPONSECLASSNAME) があります。このクラス・パラメータをオーバーライドするには、要求クラスの %TaskHandler プロパティを設定します。

すなわち、タスク要求で目的のタスク応答が使用されるようにするには、次の 2 つの方法があります。

必要に応じて、EnsLib.Workflow.TaskRequestOpens in a new tab のサブクラスを作成して、その RESPONSECLASSNAME パラメータをオーバーライドし、その値をカスタム・タスク応答クラスの名前に一致させます。以下に例を示します。
```
Class MyApp.MyWorkflowRequest Extends EnsLib.Workflow.TaskRequest
{

Parameter RESPONSECLASSNAME = "MyApp.MyWorkflowResponse";

}
```
次に、ワークフロー・プロセスの適切な部分でこのメッセージ・クラスを使用します。
ワークフロー・プロセス内で、ワークフロー・オペレーションを呼び出す際に、要求インスタンスの %TaskHandler プロパティの値を目的のタスク応答クラス名に設定します。以下に例を示します。
```
 set callrequest.%TaskHandler="MyApp.MyWorkflowResponse"
```