コネクタ開発ツールキット

概要

コネクタ開発ツールキットは、Bonita BPM Studio から独立した Bonita BPM コネクタの実装とテストのための一連のツールです。
このツールキットを使用して実装したコネクタは、Bonita BPM コネクタと同様に Bonita BPM Studio または Bonita BPM Portal 内で使用できます。

このツールキットは、Java IDE、依存性管理ツール（Maven） 、ユニット テスト フレームワーク（JUnit, Mockito, AssertJ）などの業界標準のツールを使用しています。コネクタの開発者にとって、次の利点があります：

  • 実装のために、任意のJava IDEを使用できますから、すべての構成設定オプションにアクセスでき、リファクタリングなどの便利な機能を使用することができます。
  • コネクタの単体テスト、統合テストの実行、CI （継続的統合）プラットフォームを使用したビルドの自動化が行えます。
  • いつでも再生成が可能になるため、コネクタ ウィザードのリファクタリングを簡単にします。
  • Mavenの機能を組み込むことにより、依存性の管理とコネクタ アーティファクトのバージョン管理を簡単にします。

インスタレーション

前提条件

このツールキットを使用して Bonita BPM コネクタの開発とテストを行うには、次のソフトウェアのインストールが必要になります。

  • Java 7 または、それ以降
  • Maven 3.2.x または、それ以降

インスタレーションの手順

  1. Customer Portal からこのツールキットをダウンロードします。
  2. ツールキットを一時的なインスタレーション フォルダに自己解凍します。
  3. Windowｓ ユーザーは install.bat、 Mac または Linux ユーザーは install.sh を実行します。
  4. インストーラーが終了したら、もはや一時的なインスタレーション フォルダは必要ないので削除します。

新しいコネクタ定義の作成

  1. コマンド ウィンドウを開いて、あなたのコネクタ定義を置くフォルダに移動します。
  2. 次のコマンドの実行を準備（Windows ユーザー: 行末のバック スラッシュを削除し、それぞれが単一行になるように編集）します。
    mvn archetype:generate \
    -DinteractiveMode=false \
    -DarchetypeGroupId=com.bonitasoft.connector.definition \
    -DarchetypeArtifactId=bonita-connector-definition-archetype \
    -DarchetypeVersion=1.0 \
    -DgroupId=com.mycompany.connectors \
    -DartifactId=myFirstConnector \
    -Dversion=1.0.0

    コマンドの実行の前に、次のパラメータ値を更新します。

    パラメータ 説明
    archetypeVersion ツールキットのバージョンと一致させる必要があります
    groupId Maven プロジェクトのグループ id
    artifactId Maven プロジェクトのアーティファクト id と Bonita BPM コネクタ定義の id
    version Maven プロジェクトのバージョンと Bonita BPM コネクタ定義のバージョン
  3.  コマンドを実行します。artifactId と名付けられた新しいフォルダが生成され、次のコネクタ定義プロジェクト ファイルがその中に置かれます。
    <artifactId>/
    src/main/resources/
    category-icon.png
    connector_definition.xml
    connector-icon.png
    pom.xml
  4. src/main/resources/connector definition.xml ファイルを構成設定し、コネクタウィザードページに入力、ウィジット、出力を定義します。（詳細は、Connector widget reference を参照）
  5. オプションとして、 src/main/resources フォルダ内のコネクタのアイコンとカテゴリを変更します。

新しいコネクタ実装の作成

１つのコネクタ定義は複数の実装を保持できますからこのセクションで説明したステップは、その複数分を繰り返します。
すべての実装は、定義プロジェクト フォルダ下に置きます。

警告: この定義プロジェクト フォルダ下に置かれていないコネクタ実装は、コンパイルされません。
  1. コマンド ウィンドウを開いて、あなたのコネクタ定義を含むフォルダに移動します。
  2. 次のコマンドの実行を準備（Windows ユーザー: 行末のバックスラッシュを削除し、それぞれが単一行になるように編集）します。
    mvn archetype:generate \
    -DinteractiveMode=false \
    -DarchetypeGroupId=com.bonitasoft.connector.implementation \
    -DarchetypeArtifactId=bonita-connector-implementation-archetype \
    -DarchetypeVersion=1.0 \
    -DgroupId=com.mycompany.connectors \
    -DartifactId=myFirstConnectorImpl \
    -Dversion=1.0.0 \
    -DdefinitionId=myFirstConnector \
    -DdefinitionVersion=1.0.0

    コマンドの実行の前に、次のパラメータ値を更新します。

    パラメータ 説明
    archetypeVersion ツールキットのバージョンと一致させる必要があります
    groupId Maven プロジェクトのグループ id と Bonita BPM コネクタ実装のJava package
    artifactId Maven プロジェクトのアーティファクト id と Bonita BPM コネクタ実装の id
    version Maven バージョン id と Bonita BPM コネクタ実装のバージョン
    definitionId コネクタ定義の artifactId と一致させる必要があります
    definitionVersion コネクタ定義のバージョンと一致させる必要があります
  3. コマンドを実行します。コネクタ実装プロジェクトを含む artifactId と名付けられた新しいフォルダが生成されます。
  4. このコネクタ実装プロジェクト フォルダ内で次のコマンドを実行します。
    mvn bonita-connector-definition:generate

    この定義の構成設定を基にコネクタのアブストラクト定義クラスが生成されます。

    <artifactId>/src/main/java/<groupId>/Abstract<ConnectorDefinitionArtifactId>.java
    注意: その後、コネクタ定義の構成設定を変更した場合は、その変更を適用するため、このコマンドを再実行します。
    アブストラクト定義クラスが再生成され、以前のパージョンを上書きします。
  5. コネクタ実装プロジェクト フォルダ内で、次のコマンドを実行します。
    mvn bonita-connector-implementation:generate

    コネクタ実装とテスト クラスのスタブが生成されます。

    src/main/java/<groupId>/<artifactId>.java
    src/test/java/<groupId>/<artifactId>Tests.java
    警告: このコマンドは最終段階まで再実行しないでください。なぜなら、あなたの実装とテストクラスはリセットされるからです。
  6. コネクタ実装とテスト クラスを完了します。
  7. コネクタのパッケージ化の準備ができたら、コネクタ実装プロジェクト フォルダ内で、このコマンドを実行します。
    mvn package

    Bonita BPM Studio でインポート可能なコネクタ zip ファイルが生成されます。

    /target/<artifactId>-<version>-dist.zip

ウィジットの種類とパラメータ

次のウィジットの種類がコネクタにサポートされています。

ウィジット 説明
Text テキスト フィールド
Password
TextArea 複数行のテキスト フィールド
Checkbox 単一のチェックボックス
RadioGroup ラジオボタンのグループ
Select ドロップダウン
Array 利用者がカスタマイズ可能な行と列を持つ編集可能テーブル
ScriptEditor スクリプトを入力するための複数行テキストエリア
List 利用者が要素を追加/削除できるリスト
Group １つ以上のウィジットを含む折りたたみ可能なエリア

 

これは Bonita BPM Studio で使用可能な一連のコネクタ ウィジットと同じものです。

ウィジットはセッティング パラメータで構成設定されます。その内、必須パラメータとオプション パラメータ はすべてのウィジットタイプに共通です。 いくつかのタイプには特定のウィジットプロパティもあります。それらはこのページの最後にリストしています。

ウィジットに共通する必須パラメータ

パラメータ 説明
id ユニークなウィジットのid
label ウィジットの横に表示されるテキスト
widgetType ウィジットの種類。Text, Password, TextArea, Checkbox, RadioGroup, Select, Array, ScriptEditor, List, Group のいずれかをセット
javaType このウィジットの値をアサインするために使用される Java データ型。Group ウィジットに対しはサポートされない

ウィジットに共通するオプション パラメータ

パラメータ 説明 デフォルト値
mandatory このウィジットは必須か否かを示すブールアン フラグ true
defaultValue このウィジットにアサインされるデフォルト値 n/a
description ウィジットの横の情報アイコンで表示されるマウスオーバーのテキスト。この description がない場合は表示されない n/a

次は、Text ウィジットの構成設定の例です：

<widget>
<id>firstName</id>
<label>First name</label>
<widgetType>Text</widgetType>
<javaType>java.lang.String</javaType>
<mandatory>true</mandatory>
<defaultValue>John</defaultValue>
<description>Your first name</description>
</widget>

RadioGroup ウィジットのパラメータ

パラメータ 必須 説明 デフォルト値
choices yes ラジオボタン グループのリスト値。各値は “choice” タグで指定 n/a
orientation no ウィジット値の配置。HORIZONTAL または VERTICAL のいずれか VERTICAL

次は、3項目選択のRadioGroup ウィジットの構成設定の例です：

<widget>
<id>radioGroup</id>
<label>RadioGroup widget</label>
<javaType>java.lang.String</javaType>
<widgetType>RadioGroup</widgetType>
<choices>
<choice>Choice1</choice>
<choice>Choice2</choice>
<choice>Choice3</choice>
</choices>
<orientation>VERTICAL</orientation>
</widget>

Select ウィジットのパラメータ

パラメータ 必須 説明 デフォルト値
items yes このウィジットのリスト値。各値は “choice” タグで指定 n/a

次は、３項目選択のSelect ウィジットの構成設定の例です：

<widget>
<id>select</id>
<label>Select widget</label>
<javaType>java.lang.String</javaType>
<widgetType>Select</widgetType>
<items>
<item>Item1</item>
<item>Item2</item>
<item>Item3</item>
</items>
</widget>

Array ウィジットのパラメータ

Array ウィジットで指定するパラメータはすべて必須で、１つの”arrayOptions” の親タグの下に置く必要があります。

パラメータ 説明
cols テープル内の初期の列数
rows テープル内の初期の行数。行のないテーブルは -1 の値で示す（列のヘッダーだけが表示される）。
fixedCols テーブルの列数を利用者によって変更できるか否かを示すブールアン フラグ。”true”をセットした場合は、列の追加/削除はできません。
fixedRows テーブルの行数を利用者によって変更できるか否かを示すブールアン フラグ。”true”をセットした場合は、行の追加/削除はできません。
colsCaption 列ヘッダーのキャプションのリスト。各キャプションは”colsCaption” タグで指定。

次は、２列と任意の行数のArray ウィジットの構成設定の例です：

<widget>
<id>array</id>
<label>Array widget</label>
<javaType>java.util.List</javaType>
<widgetType>Array</widgetType>
<arrayOptions>
<cols>2</cols>
<rows>-1</rows>
<fixedCols>true</fixedCols>
<fixedRows>false</fixedRows>
<colsCaptions>
<colsCaption>Header 1</colsCaption>
<colsCaption>Header 2</colsCaption>
</colsCaptions>
</arrayOptions>
</widget>

List ウィジットのパラメータ

パラメータ 必須 説明 デフォルト値
showDocuments no 値のリスト内で利用者が Bonita BPM ドキュメントを選択できるか否かを示すブールアン フラグ false

次は、 List ウィジットの構成設定の例です：

<widget>
<id>list</id>
<label>List widget</label>
<javaType>java.util.List</javaType>
<widgetType>List</widgetType>
<showDocuments>true</showDocuments>
</widget>

Group ウィジットのパラメータ

注意: グループ ウィジットは共通の “javaType” パラメータをサポートしません。

パラメータ 説明
collapsed  デフォルトでグループを折りたたむか否かを示すブールアン フラグ
widgets グループ内に含むウィジットのリストを指定

次は、別の２つのウィジットを内包するGroup ウィジットの構成設定の例です：

<widget>
<id>credentials</id>
<widgetType>Group</widgetType>
<label>User credentials</label>
<collapsed>true</collapsed>
<widgets>
<widget>
<id>login</id>
<javaType>java.lang.String</javaType>
<mandatory>true</mandatory>
<widgetType>Text</widgetType>
<label>Login</label>
</widget>
<widget>
<id>password</id>
<javaType>java.lang.String</javaType>
<mandatory>true</mandatory>
<widgetType>Password</widgetType>
<label>Password</label>
</widget>
</widgets>
</widget>