アクターフィルターの作成

アクターフィルターは、Bonita BPM 内の２つの部分、「定義」と「実装」に実装されます。これによって、定義の変更なしに実装の変更を可能にします。単一の定義に対しいくつかの実装を作成できます。製品で提供されているアクターフィルターのリストは、ここを参照してください。

アクターフィルターはコネクタの一種で、コネクタと同じスキーマ ファイルを使用し同様の方法で作成されています。[開発] メニュー、[アクターフィルター] サブメニューで開始されるウィザードを使用しながら、Bonita BPM Studio で新しいアクターフィルターの「定義」または「実装」を定義できます。新しいアクターフィルターの「定義」または「実装」を外部で作成し、Bonita BPM Studio にインポートすることもできます。

このページは、アクターフィルターの「定義」または「実装」を作成し、Bonita BPM Studio にインポートする方法を説明します。

アクターフィルターの定義
アクターフィルターの実装
アクターフィルターのテスト
Bonita BPM Studio へのアクターフィルターのインポート
アクターフィルターを使用するプロセスの構成設定とデプロイ

アクターフィルターの定義

アクターフィルターの定義は、アクターフィルターの外部インターフェイス、つまりコネクタ利用者に対する可視化（アクターフィルターの構成設定ウィザード）と Bonita BPM エンジンに対する可視化（入力と出力）をコントロールします。アクターフィルターの定義は次のファイルで構成されます。

  • 構成設定ウィザードを定義する XML ファイル
  • アクターフィルターを表すアイコンとして使用される画像を含むファイル
  • ウィザードをサポートする各言語のプロパティ ファイル

次のセクションで定義要素を説明します。この定義を作成するには、Bonita BPM Studio も使用できます。

アクターフィルターの構成設定ウィザードの定義

アクターフィルターの構成設定ウィザードを定義するXMLファイルは、アクターフィルター（アイコンを含む）を特定するヘッダー情報（ウィザードページとその入力と出力のための情報）定義を含みます。この定義は、http://documentation.bonitasoft.com/ns/connector/definition/6.0/connector-definition-descriptor.xsd 内に定義されたスキーマに従います。下表にその定義項目をリストします。

繰り返し数 説明
id 1 アクターフィルターの定義の識別子。内部で使用されウィザードまたは Bonita BPM Studio には表示されない。ユニークである必要がある。
version 1 アクターフィルター定義のバージョン。アクターフィルター Id に対しユニークである必要がある。
icon 0 or 1 アイコン画像を含むファイル名
category 1 アクターフィルターを分類するためのカテゴリで、このカテゴリでアクターフィルターがグループ化される。オプションで、このカテゴリにアイコン画像を持たせることができる。
input 0 or more アクターフィルターに渡される入力データ。各入力はユニークな名前と Java type を持つ。オプションとして、デフォルト値を設定できる。
output 0 or more アクターフィルターからプロセスに渡される出力データ。各出力はユニークな名前と Java type を持つ。
page 0 or more ウィザード内のページ。ページはユニークな Id を持つ。ページは１つ以上のウィジットで構成される。ファイル内に出現するウィジットの定義順にそのウィジットを表示することでページが組み立てられる。
widget 1 or more per page 入力に関連するページ内部の要素。ウィジットはユニークなId、入力名、データ型を持つ、次のウィジットの種類を使用可能: text, password, text area, check box, radio button group, select (drop-down list), array, group, script editor, and list.
jarDependency 0 or more 依存性は問題のないウィザード実行を満足させる必要がある。

ページとウィジットの定義はアクターフィルターに要求され、Bonita BPM Studio 内部で使用されるか、または構成設定されます。

次は、 initiator manager アクターの XML 定義の例です:

<?xml version="1.0" encoding="UTF-8"?>
<definition:ConnectorDefinition xmlns:definition="http://www.bonitasoft.org/ns/connector/definition/6.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <id>initiator-manager</id>
      <version>1.0.0</version>
      <icon>initiator-manager.png</icon>
      <category id="process" icon="process.gif" ></category>

      <input name="autoAssign" type="java.lang.Boolean" mandatory="false" defaultValue="true" />

      <page id="config">
            <widget id="autoAssign" inputName="autoAssign" xsi:type="definition:Checkbox" ></widget>
      </page>
</definition:ConnectorDefinition>

これは、ブールアンの入力が１つあり、フィルターによってタスクがユーザーId を自動アサインするかどうかを判断します。構成設定ウィザードには、１つのページがあり、１つのウィジットを包含している場合の例です。

言語プロパティ ファイル

ウィザードに表示されるテキストはページとウィジットを分離して定義されます。これは１つのアクターフィルター定義が複数の言語をサポートできることを意味しています。

各言語には、カテゴリ名、アクターフィルター名、アクターフィルター定義、各ウィザードページの名前と説明、各入力ウィジットの名前と説明などのプロパティがあります。

デフォルトの言語プロパティ ファイルは、 actorfilter-id_version.properties （actorfilter-id は アクターフィルターのId 、version はアクターフィルターのバージョン） の命名規則で命名されています。 他の言語をサポートするため、追加のプロパティ ファイルを追加することができます。これらの追加ファイルは、 actorfilter-id_lang_version.properties（ lang はプロパティファイルの言語を識別）の命名規則で命名します。この言語は、Bonita BPM Studio でサポートされている言語でなければなりません。例えば、initiator manager の日本語のプロパティファイルは、initiator-manager-1.0.0_ja.properties と命名します。Bonita BPM Studio の利用者がアクターフィルターの構成設定ウィザードを起動したとき、そのウィザードは、Bonita BPM Studioで現在設定されている言語で表示されます。その言語のプロパティ ファイルがない場合は、デフォルトの言語ファイル（英語）が使用されます。

これは、initiator manager アクターフィルターの英語プロパティの例です:

process.category = Process
connectorDefinitionLabel = Initiator manager
connectorDefinitionDescription = Manager of the initiator of the process
config.pageTitle = Configuration
config.pageDescription = Configuration of the process initiator-manager filter
connexionConfigPage.pageDescription = Choose here if you want to automatically assign the task to this actor
autoAssign.label = Assign task automatically
autoAssign.description = The task will be claimed automatically by the resolved user

アクターフィルターの実装

アクターフィルターの実装は、 XML リソース ファイルと Java クラスで構成されます。指定したアクターフィルターの定義に関連付けて任意の数の実装を作成できます。しかしながら、１つのプロセスにおいては、アクターフィルターの定義とアクターフィルターの実装は１対１の関係です。

アクターフィルターの実装リソース ファイル

リソースファイルには、次の事項を定義します。

  • 実装対象のアクターフィルター定義の id とバージョン
  • アクターフィルター実装の Id とバージョン
  • 実装で要求される一連の依存性

このリソースファイルは、 http://documentation.bonitasoft.com/ns/connector/definition/6.0/connector-implementation-descriptor.xsd で定義されたスキーマに従います。

次の例は、initiator manager アクターフィルター実装リソースファイルのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<implementation:connectorImplementation xmlns:implementation="http://www.bonitasoft.org/ns/connector/implementation/6.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <definitionId>initiator-manager</definitionId>
      <definitionVersion>1.0.0</definitionVersion>
      <implementationClassname>org.bonitasoft.userfilter.initiator.manager.ProcessinitiatorManagerUserFilter</implementationClassname>
      <implementationId>initiator-manager-impl</implementationId>
      <implementationVersion>1.0.0</implementationVersion>
      <jarDependencies>
            <jarDependency>bonita-userfilter-initiator-manager-impl-1.0.0-SNAPSHOT.jar</jarDependency>
      </jarDependencies>
</implementation:connectorImplementation>

アクターフィルターの実装 Java クラス

この Java クラスは、 org.bonitasoft.engine.filter.AbstractUserFilterclass を実装し、ExecutionContext のエンジンを使用する必要があります。次のメソッドを実装する必要があります。

  • validateInputParameters ： アクターフィルターの構成設定がしっかり定義されているかチェックする
  • 指定したアクター名に関連するすべてのユーザーのId リストを取得するフィルターのカスタム ロジック
  • shouldAutoAssignTaskIfSingleResult ： フィルターが１ユーザーだけを返す場合、タスクにそのユーザーをアサインする

API のメソッド、関連するオブジェクトの詳細は、 Javadoc を参照してください。

アクターフィルターのサンプル コード

次のコードは、initiator manager アクターフィルターのサンプルコードです。

public class ProcessinitiatorManagerUserFilter extends AbstractUserFilter {

    @Override
    public void validateInputParameters() throws ConnectorValidationException {
    }

    @Override
    public List<Long> filter(final String actorName) throws UserFilterException {
        try {
            final long processInstanceId = getExecutionContext().getParentProcessInstanceId();
            long processInitiator = getAPIAccessor().getProcessAPI().getProcessInstance(processInstanceId).getStartedBy();
            return Arrays.asList( getAPIAccessor().getIdentityAPI().getUser(processInitiator).getManagerUserId());
        } catch (final BonitaException e) {
            throw new UserFilterException(e);
        }
    }

    @Override
    public boolean shouldAutoAssignTaskIfSingleResult() {
        final Boolean autoAssignO = (Boolean) getInputParameter("autoAssign");
        return autoAssignO == null ? true : autoAssignO;
    }

}

アクターフィルターのテスト

アクターフィルターのテストは、次の３段階があります。

  1. アクターフィルターをビルドします。あなたが Maven を使用している場合は、定義用と実装用の ２つのプロジェクトを作成します。mvn clean install のコマンドを使用し、Bonita BPM Studio にインポートするアーティファクトをビルドします。これは zip file を作成します。
  2. アクターフィルターを Bonita BPM Studio にインポートする。 [開発] メニューから [アクターフィルター]  > [インポート….] を選択し、インポートする zip ファイルを選択します。
  3. プロセスでアクターフィルターをテストする。最小限のプロセスを作成し、タスクにアクターフィルターを追加します。Bonita BPM Studio でプロセスを構成設定しそれを起動します。アクターフィルターによって発生する何らかのエラーメッセージを確認するため、プロセスエンジンのログ（[ヘルプ] メニューを通じて参照可能） をチェックします。

Bonita BPM Studio へのアクターフィルターのインポート

  1. 定義と実装で使用されるファイルを含む zip ファイルを作成します。
  2. Bonita BPM Studio の [開発] メニューに進んで、[アクターフィルター]  > [ アクターフィルターをインポート….] を選択します。
  3.  zip ファイルをアップロードします。

これで、インポートされたアクターフィルターはアクターフィルターを追加するためのダイアログで使用可能になります。

[開発] メニューのオプションを使用してアクターフィルターをエクスポートすることも可能です。アクターは zip ファイルとしてエクスポートされ、他の Bonita BPM Studio にインポートすることができます。

アクターフィルターを使用するプロセスの構成設定とデプロイ

Bonita BPM Studio でアクターフィルターを使用するプロセスを構成設定するとき、この定義と実装を指定します。プロセスの依存性として 何らかの依存性を指定する必要もあります。アクターフィルターが構成設定に指定された後、デプロイ用のプロセスをビルドしたとき、その構成設定を参照してアクターフィルターのコードをそのビジネス アーカイブ（bar ファイルのこと）に含めます。