目次


External Data Service の概説

IBM Content Navigator における External Data Service の概要と構成方法を解説し、ユース・ケースに基づいてその機能について詳しく紹介します。

Comments

External Data Service とは

External Data Service (以下 EDS) はユーザーがコンテンツ・リポジトリーにおけるデータおよびメタデータを拡張、またはオーバーライドするためのサービスを定義します。EDS を使用して、データベース、JSON ファイルなどでユーザーが定義したデータを動的に取得し、コンテンツ・リポジトリーのプロパティー・フィールドを拡張またはオーバーライドすることによって、IBM Content Navigator (以下 ICN) のユーザー・インターフェースをカスタマイズできます。

EDS は以下のような機能を提供しています。

  • 選択リストの表示 (たとえば、ドロップダウン・リストの項目)
  • 別のプロパティー・フィールドの値に依存した選択リストの表示
  • フォーマットの検査
  • デフォルト値の設定
  • 最小値と最大値の設定
  • プロパティーのステータスの設定
    • 必須、読み取り専用、非表示

これらの機能については、ユース・ケースに基づいて後の節で詳しく説明します。

EDS を使用する利点は、ユーザー・インターフェースのプロパティー・フィールドをカスタマイズするために ICN のソース・コードを変更する必要がないということです。またユーザーが定義したデータやサービスは,ICN のソース・コードと分離されているため、ICN のアップグレードや変更の影響を受けません。

EDS は以下の操作に使用されます。

  • ドキュメントの追加とフォルダーの作成
  • ドキュメントのリポジトリーへのチェックイン
  • プロパティーの値の追加と編集
  • 検索条件の設定
  • ワークフローの起動など

ICN アーキテクチャー

以下の ICN のアーキテクチャー図にあるように EDS は EDS プラグインとカスタム外部データ・サービス (以下、外部データ・サービス) の二つのコンポーネントで構成されています。

図 1. ICN のアーキテクチャー

EDS プラグインは、上で紹介した EDS の機能 (たとえば選択リストの表示など) を ICN で動作させる機能を提供します。また、ICN に外部データ・サービスを登録するためのユーザー・インターフェースを提供します。

外部データ・サービスは、ICN を使用するユーザーが、各自の環境に合わせて実装できます。ICN には簡単なサンプルの外部データ・サービスが含まれています。このサンプルの外部データ・サービスはデータ・ストアとして JSON ファイルを使用しています。実際にはデータ・ストアとして、データベースを使用することも可能です。

EDS のデータフロー

以下のダイアグラムは EDS のリクエストとレスポンス、つまりデータの流れを示します。

図 2. EDS のデータフローの例

EDS プラグインは、ユーザーがダイアログを開いた時や、ユーザー・インターフェースでプロパティーの値を変更した時に呼ばれます。EDS プラグインのサービスは外部データ・サービスにリクエストを送って、クラスとそのクラスのプロパティーに関する情報を取得し、リポジトリー上の基本情報と結合してからクライアントに送ります。

EDS の REST API

EDS には、オブジェクト・タイプの一覧の取得とオブジェクト・タイプの詳細の取得の二つのサービスがあり、外部データ・サービスの開発者はこの二つのサービスを実装する必要があります。

- オブジェクト・タイプの一覧の取得: 外部データ・サービスを提供するクラス、項目タイプ、またはワークフローのリストを返します。

リクエスト:
GET /types?repositoryId=<リポジトリー ID>
レスポンス:
{
    "types": [
        {
            "symbolicName": "<コンテント・クラス、項目タイプ、またはフロー>"
        },
        ... ...
    ]
}

このサービスは、リポジトリー ID を指定して GET リクエストで呼び出されます。この例のレスポンスは、symbolicName の配列です。このリストは、外部データ・サービスがサポートするすべてのクラスが含まれている必要があります。

- オブジェクト・タイプの詳細の取得: このサービスは、前の手順で作成したサービスに含まれている各々のクラスに対して、そのクラスのプロパティーに関する情報を返します。

リクエスト:
POST /type/<クラス名>
{
    "repositoryId": "<リポジトリーID>",
    "objectId": "<オブジェクトGUID、またはPID>",
    "requestMode": "<リクエスト・モード>",
    "externalDataIdentifier": "<サービスの識別子>",
    "properties": [
        {
            "symbolicName": "<プロパティー名>",
            "value": <現在の値>
        },
        ... ...
    ],
    "clientContext": {
        "userid": "<ユーザーID>",
        "locale": "<クライアント・リクエストのロケール>",
        "desktop": "<デスクトップのID>"
    }
}

オブジェクト・タイプの詳細の取得には以下のようなリクエスト・モードがあります。

  • initialNewObject – 新しいオブジェクトを作成する時 (ドキュメントの追加やフォルダーの作成を行うためのダイアログを開いた時など)
  • initialExistingObject – 既存のオブジェクトを編集する時 (オブジェクトのプロパティーの編集を行うためのダイアログを開いた時など)
  • inProgressChanges – プロパティーを変更した時 (依存するプロパティーが存在する場合のみ)
  • finalNewObject – 新しいオブジェクトの情報をリポジトリーに保存する時 (ドキュメントの追加やフォルダーの作成のためのダイアログが閉じる時など)
  • finalExistingObject – 既存のオブジェクトに対する編集をリポジトリーに保存する時

また、externalDataIdentifier に指定した文字列は、次に外部データ・サービスが呼び出された時に、リクエスト JSON の externalDataIdentifier パラメータとして渡されますので、前回の呼び出しの情報を保持しておきたい場合などに利用することができます。

レスポンス:
{
    "externalDataIdentifier": "<サービスの識別子>", 
    "properties": [{
        "symbolicName": "<プロパティー>",
        "value": <新しい値>,
        "customValidationError": "<検査エラーのメッセージ>",
        "customInvalidItems": [0,3,4,8], // 無効なマルチ値
        "displayMode": "<readonly、またはreadwrite>",
        "required": <true、またはfalse>,
        "hidden": <true、またはfalse>,
        "maxValue": <最大値のオーバーライド>,
        "minValue": <最小値のオーバーライド>,
        "maxLength": <最大の長さ>,
        "choiceList": {
            "displayName": "<表示名>",
            "choices": [{
                "displayName": "<表示名>",
                "value": <値>
            },{
                "displayName": "<表示名>",
                "value": <値>
            },
                ... ...
            ]
        },
        "hasDependentProperties": <true、またはfalse>
   },
        ... ...
]}

このサービスは、クラス名、リポジトリー ID、オブジェクト ID、リクエスト・モード、プロパティーなどを指定して、POST リクエストで呼び出されます。この例のレスポンスは、リクエストされたクラスのシンボル名、検査エラーのメッセージ、表示モード、最大値、最小値、選択リストなどのプロパティー情報です。

EDS とサンプル外部データ・サービスの構成

ICN における EDS とサンプル外部データ・サービスの構成は以下の手順で行います。(この手順では ICN 2.0.2、Rational Application Developer (以下、RAD) 8.0.4 と WebSphere Application Server (以下、WAS) 8.5 を想定しています。)

1. ICN に付属しているサンプル外部データ・サービスのサンプル・プロジェクトを RAD のワークスペースにインポートします。

1-1. RAD のワークスペース上で「ファイル」メニューから「インポート」を選択します。

1-2. 「インポート」ウィザードが表示されたら、「一般」から「既存プロジェクトをワークスペースへ」を選択し、「次へ」をクリックします。

1-3. 「ルート・ディレクトリー」として ICN インストール・ディレクトリー下の以下のフォルダーを指定し、「プロジェクト」欄に「sampleEDSService」が表示されたら、「プロジェクトをワークスペースにコピー」をチェックして「終了」をクリックします。

<IBM Content Navigator のインストール先>/samples/sampleEDSService
図 3. sampleEDSService プロジェクトのインポート

インポートされた sampleEDSService プロジェクトは以下の図のような構造になります。

図 4. sampleEDSService プロジェクトの構造

「マーカー」ビューに「JSON の問題」が表示されている場合は、以下の手順を実行します。

1-4. sampleEDSService プロジェクトを選択し、「ファイル」メニューから「プロパティー」を選択します。

1-5. 「プロパティー」ダイアログが表示されたら、左のツリー・ビューから「リソース」を選択し、「テキスト・ファイル・エンコード」を「コンテナーから継承」から「その他」に変更し、ドロップダウン・リストから「UTF-8」を選択して「OK」をクリックします。

図 5. テキスト・ファイル・エンコードの指定

「マーカー」ビューに「Java のビルド・パスの問題」 が表示されている場合は、以下の手順を実行します。

1-6. sampleEDSService プロジェクトを選択し、「ファイル」メニューから「プロパティー」を選択します。

1-7. 「プロパティー」ダイアログが表示されたら、左のツリー・ビューから「Java のビルド・パス」を選択します。

1-8. 「プロジェクト」タブを選択し、「navigator」プロジェクトを選択して「削除」をクリックします。

1-9. 「ライブラリー」タブを選択し、「j2ee.jar」を選択して「削除」をクリックします。

1-10. 「外部 JAR の追加」をクリックし、Web アプリケーション・サーバーのインストール・ディレクトリー下にある j2ee.jar を指定し「OK」をクリックします。

図 6. 外部 j2ee.jar をライブラリーに追加

1-11. 「マーカー」ビューにエラーが表示されていないことを確認します。

2. sampleEDSService プロジェクト下の build.xml の Ant ビルドを実行し、sampleEDSService.war を作成します。

2-1. sampleEDSService プロジェクト下の build.xml を開きます。

2-2. 以下の行を探し、value の値を Web アプリケーション・サーバーのインストール・ディレクトリー下の j2ee.jar を含むフォルダーに書き換えます。

<property name="dir_j2ee_lib" value="../navigator/build/lib/j2ee"/> <!-- change this to the directory containing J2EE jars -->

2-3. build.xml を右クリックし、「実行」から「Ant ビルド」を選択してビルドを実行します。

図 7. build.xml を実行

2-4. 「コンソール」ビューに「BUILD SUCCESSFUL」と表示され、ビルドが成功したことを確認します。

2-5. sampleEDSService プロジェクト下の sampleEDSService.war を選択し、「ファイル」メニューから「プロパティー」を選択し、最終変更日時からファイルが更新されたことを確認します。

3. 作成した sampleEDSService.war を Web アプリケーション・サーバーの管理コンソールからサーバーにデプロイします。デプロイする時、コンテキスト・ルートは「/sampleEDSService」と入力します。

図 8. コンテキスト・ルートの設定

以下のような URL を Web ブラウザーに指定すると、sampleEDSService プロジェクト下の ObjectTypes.json ファイルに記述されているクラス名が返ってくることで、正しく構成されたかを確認できます。

http://<ホスト名>:<ポート番号>/sampleEDSService/types

4. ICN の「管理ビュー」で EDS プラグインを構成します.

4-1. ICN の「管理ビュー」で「プラグイン」をクリックし、右のプラグイン画面から「新規プラグイン」をクリックします。

図 9. 新規プラグインの追加

4-2. ICN に付属している edsPlugin.jar (EDS プラグイン) ファイルのパスを「JAR ファイルのパス」に指定し、「ロード」ボタンをクリックします。

<IBM Content Navigator のインストール先>/plugins/edsPlugin.jar
図 10. 外部データ・サービスの設定

4-3. edsPlugin.jar ファイルがロードされたら、「外部データ・サービス URL」に、前のステップで行ったサンプル外部データ・サービスのデプロイ先の URL を指定します。

例えば、http://<ホスト名>:<ポート番号>/sampleEDSService と指定します。

4-4. 「保存して閉じる」をクリックします。

サンプル外部データ・サービスを使用したユース・ケース

次に外部データ・サービスとして、ICN の製品に同梱されている sampleEDSService をカスタマイズし、銀行の振込取引を例として、EDS の機能を詳しく説明します。

銀行業務では、紙に記入された振込や送金などの取引内容をオペレーターがシステムに手入力することがあります。もしオペレーターの入力にミスがあった場合、後で修正するには多大なコストがかかります。その銀行の状況に合わせた外部データ・サービスを開発することにより、入力が必要な部分を選択リストに変更したり、入力された値のフォーマットを検証したり、入力値の最大値、最小値などの制限を設けるなど、入力ミスを抑止する効果が期待できます。

ここでは、コンテンツ・リポジトリーとして IBM FileNet P8 (以下、FileNet P8) を使用します。

以下にサンプル外部データ・サービスの設定と動作確認の手順について説明します。

1. FileNet P8 上に、振込時に使われる「振込 (シンボル名: Transfer)」というクラスを定義し、クラスのプロパティーとして以下のプロパティーを定義します。クラスとプロパティーの定義方法については「参考文献」に書いてある FileNet P8 の資料を参照してください。

「振込」クラスのプロパティー:
プロパティ名シンボル名値の型
振込金額TransferAmountFloat
振込方法TransferMethodString
振込依頼人口座番号SenderAccountNumberString
振込先銀行名ReceivingBankString
振込先銀行コードReceivingBankCodeString
振込先支店名ReceivingBranchString
振込先口座番号RecipientAccountNumberString
振込元銀行名SendingBankString
振込元支店名SendingBranchString
オペレーターBankOperatorString

作成された「振込」クラスは以下のようになります。

図 11. 「振込」クラス

2. ここでは、「振込」クラスにのみ EDS を使用するので、sampleEDSService プロジェクトの ObjectTypes.json を編集し、以下のように EDS を使用するクラスの名前を変更します。

例:ObjectTypes.json
[
	{"symbolicName": "Transfer"}
]

3. Transfer_PropertyData.zip をダウンロードして、その中の Transfer_PropertyData.json を sampleEDSService プロジェクトの src フォルダーの下にコピーします。

4. sampleEDSService プロジェクトの下にある build.xml の Ant ビルドを実行し、更新された sampleEDSService.war を Web アプリケーション・サーバーに再デプロイします。

5. デプロイが完了したら、ICN の「参照ビュー」にアクセスし、「ドキュメントの追加」ボタンをクリックし、表示された「ドキュメントの追加」ダイアログの「クラス」ドロップ・ダウンから「振込み」クラスを選択して、EDS の動作を確認します。

図 12. 「ドキュメントの追加」のダイアログ

以下に、Transfer_PropertyData.json で記述した JSON データと「ドキュメントの追加」ダイアログのプロパティー・フィールドを参照して、EDS の各々の機能について説明します。
 

選択リスト

プロパティー・フィールドに対して、ユーザーは自分が持っているデータを用いて、ICN のコードを変更する必要なしに、選択リストを表示できます。Transfer_PropertyData.json の以下の部分で選択リストを指定しています。

{
	"symbolicName": "ReceivingBank",
	"choiceList": {
		"displayName": "振込先銀行名",
		"choices": [{
			"displayName": "こうとう銀行",
			"value": "koutouBank"
		},{
			"displayName": "しぶや銀行",
			"value": "shibuyaBank"
		},{
			"displayName": "ちゅうおう銀行",
			"value": "tyuouBank"
		}]
	},
	・・・
}

symbolicName」には、プロパティー・フィールド名「ReceivingBank」を指定し、「choices」には選択リストの項目を「displayName」と「value」のペアで指定します。これによって振込先銀行名の値は、「こうとう銀行」、「しぶや銀行」、「ちゅうおう銀行」の選択リストとして表示されます。

図 13. 選択リスト

依存関係の選択リスト

あるプロパティーに表示する選択リストを、別のプロパティーで選択された値によって変更することができます。

Transfer_PropertyData.json の以下の部分で依存関係の選択リストを指定しています。

{
	"symbolicName": "ReceivingBank",
	"choiceList": {
		"displayName": "振込先銀行名",
		"choices": [{
			"displayName": "こうとう銀行",
			"value": "koutouBank"
		},{
			"displayName": "しぶや銀行",
			"value": "shibuyaBank"
		},{
			"displayName": "ちゅうおう銀行",
			"value": "tyuouBank"
		}]
	},
	"hasDependentProperties": true
},{
	"symbolicName": "ReceivingBranch",
	"dependentOn": "ReceivingBank",
	"dependentValue": "koutouBank",
	"choiceList": {
		"displayName": "こうとう銀行の支店名リスト",
		"choices": [{
			"displayName": "おうぎばし支店",
			"value": "ougibashiBranch"
		},{
			"displayName": "しののめ支店",
			"value": "shinonomeBranch"
		},{
			"displayName": "とよす支店",
			"value": "toyosuBranch"
		}]
	}
},{
	"symbolicName": "ReceivingBranch",
	"dependentOn": "ReceivingBank",
	"dependentValue": "shibuyaBank",
	"choiceList": {
		"displayName": "しぶや銀行の支店名リスト",
		"choices": [{
			"displayName": "えびす支店",
			"value": "ebisuBranch"
		},{
			"displayName": "せんだがや支店",
			"value": "sendagayaBranch"
		},{
			"displayName": "はつだい支店",
			"value": "hatsydaiBranch"
		}]
	}
},{
	"symbolicName": "ReceivingBranch",
	"dependentOn": "ReceivingBank",
	"dependentValue": "tyuouBank",
	"choiceList": {
		"displayName": "ちゅうおう銀行の支店名リスト",
		"choices": [{
			"displayName": "ぎんざ支店",
			"value": "ginzaBranch"
		},{
			"displayName": "にほんばし支店",
			"value": "nihonbashiBranch"
		},{
			"displayName": "はこざき支店",
			"value": "hakozakiBranch"
		}]
	}
}

hasDependentProperties」に true を指定することで、「ReceivingBank」の値に依存するプロパティーがあることを宣言します。「ReceivingBranch」の「dependentOn」に 「ReceivingBank」を指定することで、「ReceivingBranch」は、「ReceivingBank」の値に依存することを示します。「dependentValue」に「koutouBank」を指定して、「ReceivingBank」の値が「koutouBank」の時のみ、その後に記述した「choiceList」の値を表示することを示します。

例えば、振込先銀行名のリストから「こうとう銀行」が選ばれたときには、振込先支店名の選択リストは「おうぎばし支店」、「しののめ支店」、「とよす支店」となりますが、「しぶや銀行」が選ばれたときには、「えびす支店」、「せんだがや支店」、「はつだい支店」が振込先支店名の選択リストとして表示されます。

図 14. 依存関係の選択リスト

デフォルト値の設定

ある特定のプロパティーにデフォルト値を指定できます。

例えば、振込元銀行名、振込元支店名は、既に決まっていて変更する必要がない場合は、以下のように「initialValue」に 「ちよだ銀行」、「まるのうち支店」などの値を指定します。これらの指定により、プロパティー・フィールドは予め入力された状態になります。

{
	"symbolicName": "SendingBank",
	"initialValue": "ちよだ銀行"
},{
	"symbolicName": "SendingBranch",
	"initialValue": "まるのうち支店"
}

また、特定のプロパティーの値に基づいて、別のプロパティーの値を自動的に変更することも可能です。例えば、以下のように「dependentOn」、「dependentValue」および「value」を指定することで、振込先銀行名リストから「こうとう銀行」が選ばれると、振込先銀行コードに自動的に「X001」が入力されます。

{
	"symbolicName": "ReceivingBankCode",
	"dependentOn": "ReceivingBank",
	"dependentValue": "koutouBank",
	"value": "x001"
},{
	"symbolicName": "ReceivingBankCode",
	"dependentOn": "ReceivingBank",
	"dependentValue": "shibuyaBank",
	"value": "x002"
},{
	"symbolicName": "ReceivingBankCode",
	"dependentOn": "ReceivingBank",
	"dependentValue": "tyuouBank",
	"value": "x003"
}
図 15. デフォルト値の設定

フォーマットの検査

EDS の強力な機能の一つは、入力された値に対してユーザーが独自の検査機能を実装できることです。この振込の例では、振込依頼人の口座番号は決まった形式のものである必要があります。

ユーザーが振込依頼人口座番号のプロパティーに間違った形式で入力した場合、検査が実行され、その結果としてエラーが表示され、正しい形式をヒントとして表示します。検査のルールは、正規表現で指定できますが、エスケープして指定する必要があります。

以下のように検査のルールは「format」に、エラーメッセージに表示される正しい形式のヒントは「formatDescription」に指定します。

{
	"symbolicName": "SenderAccountNumber",
	"format": "\\d{3}-\\d{6}",
	"formatDescription": "nnn-nnnnnn",
}
図 16. フォーマットの検査

最大値と最小値の設定

入力される値の最小値と最大値を設定できます。

整数、浮動小数点、または日付のプロパティーに対して、EDS を使って最大値または最小値を指定することが可能です。制限事項が一つあり、EDS が使用しているリポジトリーで定義されている最小値または最大値の制限を緩和することはできません。たとえば、リポジトリー内の最小値が 100 の場合、EDS では最小値を 150 に指定することはできますが、50 を指定することはできません。

この振込の例では、一回の取引金額の最大値と最小値を設定し、入力ミスを抑止したり、一回の取引の金額を制御したりすることができます。

もし、指定された最大値を超える入力が行われた場合は、検査の結果、以下のようなメッセージが表示されます。また、ユーザーがフィールド名の「振込金額」の後に表示されている ”?” マークをマウスでポイントすることで、そのフィールドに入力できる最大値、最小値の値が表示されます。

この機能は「maxValue」に最大値、「minValue」に最小値を指定して設定します。

{
	"symbolicName": "TransferAmount",
	"maxValue": 100000000000,
	"minValue": 100000
}
図 17. 最大値と最小値の検証
図 18. 最大値と最小値のヒント

読み取り専用の設定

あるプロパティーに読み取り専用のステータスを設定します。

例えば、固定の値であるべきプロパティーにユーザーが間違って異なる値を入力できないようにするには、正しいデフォルト値を指定して、そのプロパティーを読み取り専用にします。この例では「BankOperator」に対して、「initialValue」に「豊洲 智子」を、「displayMode」に「readonly」を指定することで読み取り専用に設定できます。

{
	"symbolicName": "BankOperator",
	"initialValue": "豊洲 智子",
	"displayMode" : "readonly"
}
図 19. 読み取り専用の設定

必須項目の設定

あるプロパティーが必須フィールドになるように設定できます。

プロパティーにこの設定を行うと、そのフィールドが必須であることを示すために、フィールド名にアスタリスクが表示されます。そのフィールドに値が指定されない限り、ユーザーは次のステップまたは次のページに進むことができせん。例えば、振込方法が“現金”の場合、振込依頼人口座番号は不要ですが、振込方法が“口座”、または“口座と現金”の場合は、振込依頼人口座番号のフィールドは必須フィールドに設定する必要があります。この機能は「required」に true を指定することで設定できます。サンプル JSON は、次に説明する非表示ステータス設定機能と合わせて次の節に記述してあります。

図 20. 必須項目の設定

非表示ステータス設定

ある特定のプロパティーを非表示にすることができます。

例えば、振込方法が“現金”である場合、継続の“振込依頼人口座番号”プロパティーを非表示にします。

この機能は「hidden」に true を指定することで設定できます。

{
	"symbolicName": "TransferMethod",
	"choiceList": {
		"displayName": "振込方法",
		"choices": [{
			"displayName": "現金",
			"value": "cash"
		},{
			"displayName": "口座",
			"value": "account"
		},{
			"displayName": "口座と現金",
			"value": "accountAndCash"
		}]
	},
	"hasDependentProperties": true
},{
	"symbolicName": "SenderAccountNumber",
	"dependentOn": "TransferMethod",
	"dependentValue": "account",
	"hidden": false,
	"required": true
},{
	"symbolicName": "SenderAccountNumber",
	"dependentOn": "TransferMethod",
	"dependentValue": "accountAndCash",
	"hidden": false,
	"required": true
},{
	"symbolicName": "SenderAccountNumber",
	"dependentOn": "TransferMethod",
	"dependentValue": "cash",
	"hidden": true,
	"required": false
}

まとめ

本稿では ICN における EDS について、ユース・ケースに基づいてその機能と構成などについて詳しく解説しました。ICN ユーザーは EDS を使用することで、自分の環境に合わせてプロパティー・フィールドを容易にカスタマイズできます。 さらに、ICN の基本機能だけではなく、ICN 上の他のプラグインや ICN をベースとして構築されるアプリケーションでも EDS 機能の呼び出しが可能なので、EDS をサポートするプラグインやアプリケーションのカスタマイズにも EDS が利用できます。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Web development, Information Management, Java technology
ArticleID=956628
ArticleTitle=External Data Service の概説
publish-date=12122013