目次


IBM Case Manager のカスタム・ウィジェット開発手順

カスタム・ウィジェットの開発からデプロイまでの手順についてサンプルを交えながら紹介します

Comments

はじめに

IBM Case Manager (ICM) は、ケース管理ソリューションを開発するための Web ベースのツール「Case Manager Builder」を提供しています。Case Manager Builder の機能の 1 つに、ケース管理ソリューションの各ページのユーザー・インターフェース (UI) をカスタマイズする「Page Designer」という機能があります (図 1)。この Page Designer 上でウィジェットを組み合わせたり、ページ上で使用するアクションを定義したりすることで、多様な業務プロセスの要件に柔軟に対応した UI を作成できるようになっています。

図 1. ページの UI をカスタマイズする Page Designer

Page Designer 上で利用できるウィジェットやアクションは製品が数多く提供しており、多くの要件に合わせて使用することができます。加えて、複雑な要件のため既存のウィジェットやアクションでは対応できないといった場合などは、API を使ってカスタム・ウィジェットやカスタム・アクションを開発できるようにもなっています。このカスタム・ウィジェット開発の機能は ICM の従来のバージョンからある機能ですが、バージョン 5.2 から IBM Content Navigator (ICN) をベースとしたアーキテクチャーに刷新されたことにより、カスタム・ウィジェットやカスタム・アクションの開発の方法も ICN プラグイン開発に基づいた方式に大きく変わりました。そこでこの記事では、ICM 5.2 における新しいカスタム・ウィジェットおよびカスタム・アクションの開発手順について、サンプルを交えながら詳しく紹介します。

なお、ケース管理の考え方や ICM の概要について詳しく知りたい方は、参考文献の製品紹介ページ「IBM Case Manager」や developerWorks 記事「IBM Case Manager 概説」を参照してください。

前提環境

実行環境として ICM 5.2 がすでにインストールされていることを前提とします。 ICM 5.2 のインストールおよび構成の手順については、参考文献の Knowledge Center ページ「IBM Case Manager のインストールおよび構成」を参照してください。

また、開発環境として ICN プラグインの開発環境が必要です。ICN プラグインの開発環境の詳細については、参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。この参考文献に合わせて、この記事でも Rational Application Developer (RAD) 8.0.4 を前提環境として説明します。なお、今回のサンプルのように非常にシンプルな実装で RAD 特有の機能が不要なケースでは、Eclipse 環境でも開発可能です。

カスタム・ウィジェット開発のプロジェクト

典型的なプロジェクト構成

ICM のカスタム・ウィジェット開発におけるプロジェクトの典型的な構成は、下図 2 のように、プロジェクトの中にサブ・プロジェクトを含んだ構成です。具体的には、ルート・プロジェクトの中に、ICN プラグインのプロジェクト (Java プロジェクト)、Web モジュールのプロジェクト (動的 Web プロジェクト) という 2 つのサブ・プロジェクトと、カスタム・ウィジェットの設定ファイルを集めたレジストリ用の ICMRegistry サブ・フォルダが含まれた構成になっています。それぞれのサブ・プロジェクトおよびサブ・フォルダの役割の詳細は表 1 にまとめてあります。

図 2. カスタム・ウィジェットのプロジェクトの典型的な構成
表 1. カスタム・ウィジェットのルート・プロジェクト内のサブ・プロジェクトおよびサブ・フォルダ
名前必須詳細

<ルート・プロジェクト名>Plugin

○

ICN プラグインのプロジェクト。主にプラグインやカスタム・アクションのサーバーサイドの実装を行います。
このサブ・プロジェクトは必須です。
名前は他のプラグインと重複しなければ自由につけることができますが、「<ルート・プロジェクト名>Plugin」とつけておくと分かりやすく名前の重複もしにくいため、管理しやすくなります。

<ルート・プロジェクト名>Widgets

 

カスタム・ウィジェットの Web プロジェクト。主にカスタム・ウィジェットやカスタム・アクションの JavaScript の実装を行います。
このサブ・プロジェクトは必須ではなく、場合によっては JavaScript の実装もすべて ICN プラグインのプロジェクトに含めることもできます。
こちらも名前は他の Web モジュールと重複しなければ自由につけることができますが、「<ルート・プロジェクト名>Widgets」とつけておくと分かりやすく名前の重複もしにくいため、管理しやすくなります。

ICMRegistry

○

カスタム・ウィジェットの定義ファイルなどを集めたレジストリ用のフォルダ。
名前は必ず ICMRegistry にする必要があります。
このサブ・フォルダは必須です。

このプロジェクトを Ant スクリプトによってビルドすることで、最終的には下図 3 のような ZIP ファイルのパッケージを作成します。この ZIP ファイルは、ICN プラグインのプロジェクトをビルドした JAR ファイル、Web プロジェクトをビルドした EAR ファイル、そして ICMRegistry サブ・フォルダを丸ごとそのまま含めた構成のパッケージになっています。実は、この構成の ZIP ファイルのパッケージを最終的に作成できる構成であれば、プロジェクト構成は図 2 のサブ・プロジェクトを含んだ構成にあわせなくても構いません。しかし、図 2 のようなサブ・プロジェクトを含んだ構成にしておくと、ビルド後のモジュール構成との対応がわかりやすくなり、管理もしやすくなります。

図 3. ビルドされたカスタム・ウィジェットのパッケージの構成

要件に合ったプロジェクト構成の決定

参考文献にある Redbook 「Redbook: Advanced Case Management with IBM Case Manager」や ECM コミュニティ・ブログ「IBM Case Manager V5.2.0 Custom Page Widgets and Actions Development」などでサンプルとして公開されているカスタム・ウィジェットのプロジェクトは、どれも先ほど紹介した図 2 のプロジェクト構成になっています。しかし、実際には他にもいくつかプロジェクト構成のバリエーションがあります。これらのバリエーションの中から、要件に合ったプロジェクト構成を決定するための流れをフローチャートにまとめたのが下図 4 です。

最初の分岐は「カスタム・ウィジェットの開発が必要かどうか」です。この記事では「カスタム・ウィジェットの開発」にフォーカスを当てていますが、場合によってはカスタム・ウィジェットの開発は不要でカスタム・アクションだけを開発すればよい、という要件もあるでしょう。その場合には、[タイプ ①] に示したように、単体の ICN プラグインのプロジェクトを作成してその中でカスタム・アクションを実装すればよく、先に紹介したようなサブ・プロジェクトを含んだ構成は不要になります。また、デプロイについても ICN プラグインと同じように ICN の管理者デスクトップから行うことができます。

カスタム・ウィジェットの開発が必要な場合は、次の分岐の「Web プロジェクトを使用するかどうか」に進みます。先の表 1 にあるように、カスタム・ウィジェットのサブ・プロジェクトおよびサブ・フォルダのうち、ICN プラグインのプロジェクトと ICMRegistry サブ・フォルダは必須ですが、Web プロジェクトは必須ではありません。Web モジュール部分の実装を ICN プラグインのプロジェクトに含めることで、[タイプ ②] に示したような Web プロジェクトのない構成にすることが可能です。

図 4. プロジェクトの構成を決定するためのフローチャート

では、Web プロジェクトを使用するかどうかはどのように判断すればよいのでしょうか?明確な基準はありませんが、参考までに 2 つのタイプについて長所と短所を比較したのが表 2 です。最も大きな違いは、Web プロジェクトがある場合は ICN プラグインがデプロイされるだけでなく、Web プロジェクトの EAR モジュールが ICM とは別アプリケーションとしてアプリケーション・サーバーにデプロイされるという点です。複数のモジュールがデプロイされると管理が煩雑になるため、例えば新規にシンプルな構成のカスタム・ウィジェットを開発する場合などは、Web プロジェクトがない構成の方がよいでしょう。しかし、すでに Web プロジェクトで実装したモジュールがある場合や、非常に複雑なサーバーサイドの実装が必要になり ICN プラグインに含めるのが困難な場合などは、Web プロジェクトありの構成にしたほうが開発しやすいこともあります。要件に応じて Web プロジェクトのあり・なしを選択するとよいでしょう。

表 2. カスタム・ウィジェットのプロジェクトに Web プロジェクトを含める場合と含めない場合の比較
Web プロジェクト長所短所
なし [タイプ ②]
  • ブラウザからリモートでデプロイが可能
  • すべてが ICN プラグインの中で動作するため、デプロイ後のモジュールの管理が簡単
  • 既存の Web プロジェクトがある場合には、ICN プラグインに移植する必要がでてしまう
あり [タイプ ③]
  • 既存の Web プロジェクトとしての実装がある場合は再利用が可能
  • 複雑な Web アプリケーションとしての実装が必要な場合は Web プロジェクトとして実装したほうが実装しやすい場合もある
  • ICM サーバー上の Case Manager 構成ツールでデプロイする必要がある
  • Web プロジェクトの EAR モジュールが、ICM とは別のアプリケーションとしてアプリケーション・サーバーにデプロイされるため、管理が煩雑

[タイプ ①] のカスタム・アクションのみの開発およびデプロイ手順は、基本的に ICN プラグインの開発およびデプロイ手順そのものですので、詳細については参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。この記事では、[タイプ ②] と [タイプ ③] での開発およびデプロイ手順について詳しく紹介します。まず [タイプ ②] の Web プロジェクトなしでの開発手順について詳しく説明した後、[タイプ ③] の Web プロジェクトありにした場合のタイプ ② との違いについて説明します。

サンプルのカスタム・ウィジェットの概要

この記事で作成するサンプルのカスタム・ウィジェットは、下図 5 のように、ウィジェットのプロパティで設定しておいたメッセージ (ここでは「Hello, World!」) を画面に表示するだけのシンプルなウィジェットです。

図 5. ウィジェットのプロパティで設定したメッセージを表示するサンプルのカスタム・ウィジェット

また、あわせてカスタム・アクションも作成します。こちらも下図 6 のように、アクションのプロパティで設定しておいたメッセージ (ここでは「Hello, World!」) を alert ダイアログで表示するだけのシンプルなアクションです。

図 6. アクションのプロパティで設定したメッセージを alert で表示するサンプルのカスタム・アクション

カスタム・ウィジェットの作成 ① : Web プロジェクトなしの場合

最初に、図 4 の [タイプ ②] で紹介した Web プロジェクトなしの構成でサンプルのカスタム・ウィジェットを作成します。なお、完成版はこの記事の末尾にあるダウンロードの章の ICMSampleProjects.zip ファイルの中に含まれている ICMSample プロジェクトを参考にしてください。

プロジェクトの作成

まず、ルート・プロジェクトを作成します。ここでは ICMSample という名前の Java プロジェクトを以下の手順で作成します。なお、この記事ではルート・プロジェクトを「Java プロジェクト」として作成していますが、「一般」カテゴリにある「プロジェクト」で作成しても構いません。

  1. RAD のメニューから「ファイル」 > 「新規」 > 「プロジェクト」を選択します。
  2. 「Java プロジェクト」を選択して「次へ」をクリックします。 (図 7)
  3. プロジェクト名に「ICMSample」と入力して「終了」をクリックします。 (図 8)
図 7. Java プロジェクトを選択
図 8. ICMSample プロジェクトを作成

次に、ICN プラグインのプロジェクトを、先ほどの ICMSample プロジェクトのサブ・プロジェクトとして以下の手順で作成します。ここでは、ルート・プロジェクト名が ICMSample なので、ICMSamplePlugin というプロジェクト名にします。また ICN プラグインのプロジェクトには、ICN が提供する JAR ファイルである navigatorAPI.jar をライブリーとして追加する必要があります。詳しくは参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。

  1. RAD のメニューから「ファイル」 > 「新規」 > 「プロジェクト」を選択します。
  2. 「Java プロジェクト」を選択して「次へ」をクリックします。 (図 7)
  3. プロジェクト名に「ICMSamplePlugin」と入力します。さらに ICMSample プロジェクトのサブ・プロジェクトとなるようにするために、「デフォルト・ロケーションの使用」のチェックを外して、ロケーションに以下のパスを指定して、「次へ」をクリックします。 (図 9)

    ロケーション : <ルート・プロジェクトである ICMSample プロジェクトのロケーション>\ICMSamplePlugin

  4. 「ライブラリー」タブを選択して「外部 JAR の追加」をクリックし、navigatorAPI.jar をライブラリーに追加して、「終了」をクリックします。 (図 10)
  5. ICMSamplePlugin プロジェクトが ICMSample プロジェクトのサブ・プロジェクトとして作成されたことを確認します。 (図 11)
図 9. ICMSample プロジェクトのサブ・プロジェクトになるようにロケーションを指定して ICMSamplePlugin プロジェクトを作成
図 10. ICMSamplePlugin プロジェクトのライブラリとして navigatorAPI.jar を指定
図 11. ICMSamplePlugin プロジェクトが ICMSample プロジェクトのサブ・プロジェクトとして作成されたことを確認

なお、図 11 をみると分かるように、サブ・プロジェクトとして作成した ICMSamplePlugin プロジェクトは ICMSample プロジェクト内にサブ・フォルダとして表示されるのと同時に、単独の ICMSamplePlugin プロジェクトとしてもパッケージ・エクスプローラに表示されます。この 2 つは実際には同じプロジェクトのフォルダを表示しているのでどちらで作業しても構いませんが、Java プロジェクトとして表示されている ICMSamplePlugin プロジェクトの方で開発作業を行ったほうが開発しやすいでしょう。

フォルダとファイルの作成

プロジェクトの作成が完了したら、カスタム・ウィジェットおよびカスタム・アクションの実装に必要なフォルダおよびファイルを作成します。このサンプルでは下図 12 にあるフォルダおよびファイルを作成します。各ファイルの詳細については表 3 にまとめてあります。

なお、ICMSamplePlugin プロジェクトは ICN プラグインのプロジェクトですので、参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」で紹介されている ICN プラグインのプロジェクトをあわせて参照するとより理解が深まります。

図 12. カスタム・ウィジェットおよびカスタム・アクション実装用のファイルとフォルダの作成 (Web プロジェクトなしの場合)
表 3. プロジェクト内の各ファイルの詳細 (Web プロジェクトなしの場合)
ファイル名内容
ICMRegistry フォルダ
Catalog.jsonパッケージに含まれるすべてのカスタム・ウィジェットの情報をカタログとしてまとめた JSON ファイル
ICMSampleWidget.jsonICMSampleWidget カスタム・ウィジェットの詳細情報をまとめた JSON ファイル
images/sample_icon.pngPage Designer 上で表示されるカスタム・ウィジェットのアイコン (後述の図 24 参照)
ICMSamplePlugin/src/com/ibm/icm/sample/plugin フォルダ
ICMSamplePlugin.javaICN プラグインの Plugin クラス
actions/ICMSampleAction.javaICMSampleAction カスタム・アクションの実装クラス。ICN プラグインの PluginAction クラスをベースに ICM アクション用の拡張部分を追加して実装。
ICMSamplePlugin/src/com/ibm/icm/sample/plugin/WebContent フォルダ
ICMSamplePlugin.cssICN プラグインのスタイルシート
ICMSamplePlugin.jsICN プラグインの JavaScript ファイル
ICMSamplePlugin/src/com/ibm/icm/sample/plugin/WebContent/icmsample フォルダ
action/ICMSampleAction.jsICMSampleAction カスタム・アクションの JavaScript の実装
pdwidget/templates/ICMSampleWidget.htmlカスタム・ウィジェットのテンプレート HTML
pdwidget/ICMSampleWidget.jsICMSampleWidget カスタム・ウィジェットの JavaScript の実装
resources/ICMSampleWidget.cssICMSampleWidget カスタム・ウィジェットのスタイルシート

プラグインの実装

まずは、ICN プラグインの Plugin クラスを実装します。このサンプルの Plugin クラスは、 ICMSamplePlugin サブ・プロジェクトの com.ibm.icm.sample.plugin パッケージの ICMSamplePlugin クラスで、実装はリスト 1 にあります。

基本的には ICN プラグインの Plugin クラスの一般的な実装方法をベースにしていますので、Plugin クラスとして実装が必要なメソッドの詳細などについては、参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。今回の ICM のカスタム・ウィジェット開発においてポイントとなるのは以下の 3 点です。

  • getScript メソッドおよび getCSSFileName メソッドは、このプラグインがロードされた際に自動でページに読み込みたい JavaScript ファイルおよび CSS ファイルのパスを返します。これらのファイルは、<Plugin クラスのあるパッケージ>/WebContent フォルダ以下にある必要があります。ここでは、src/com/ibm/icm/sample/plugin/WebContent フォルダ以下の ICMSamplePlugin.js ファイルおよび ICMSamplePlugin.css ファイルをそれぞれ指定しています。
  • getDojoModule メソッドは、このプラグインが提供する Dojo モジュールのパッケージ名を指定します。指定する Dojo モジュールのパッケージも先ほどの JavaScript および CSS ファイル同様、<Plugin クラスのあるパッケージ>/WebContent フォルダ以下にある必要があります。ここでは icmsample という名前を指定することで、src/com/ibm/icm/sample/plugin/WebContent/icmsample フォルダ以下の Dojo モジュールが icmsample というパッケージでロードできるようにしています。なお、このパッケージ名は、既存の Dojo パッケージや他のプラグインの Dojo モジュールのパッケージの名前と重複しないようにする必要があります。
  • getActions メソッドは、このプラグインが提供するアクションの配列を返します。これはもともと ICN のアクションを実装するためのインターフェースですが、ICM のカスタム・アクションを実装する場合も、この getActions メソッドの返り値の配列の中に実装したカスタム・アクションのインスタンスを含めて登録する必要があります。ここでは、サンプルのカスタム・アクションの実装クラスである ICMSampleAction クラスをインスタンス化して配列に含めて返しています。
リスト 1. ICMSamplePlugin クラスの実装
package com.ibm.icm.sample.plugin;

import java.util.Locale;

import com.ibm.ecm.extension.Plugin;
import com.ibm.ecm.extension.PluginAction;
import com.ibm.icm.sample.plugin.actions.ICMSampleAction;

public class ICMSamplePlugin extends Plugin {

	@Override
	public String getId() {
		return "ICMSamplePlugin";
	}

	@Override
	public String getName(Locale locale) {
		return "ICM Sample Plugin";
	}

	@Override
	public String getVersion() {
		return "1.0";
	}

	@Override
	public String getScript() {
		return "ICMSamplePlugin.js";
	}

	@Override
	public String getCSSFileName() {
		return "ICMSamplePlugin.css";
	}

	@Override
	public String getDojoModule() {
		return "icmsample";
	}

	@Override
	public PluginAction[] getActions() {
		return new PluginAction[] { new ICMSampleAction() };
	}
}

次に、Plugin クラスの getScript メソッドおよび getCSSFileName メソッドで指定した、 src/com/ibm/icm/sample/plugin/WebContent フォルダ以下の ICMSamplePlugin.js および ICMSamplePlugin.css を実装します。

JavaScript の ICMSamplePlugin.js は、このサンプルでは特に実装しなければならない処理がないため空のファイルになっています。もしページロード時に必要な処理がある場合はここに実装を追加してください。

スタイルシートの ICMSamplePlugin.css の実装は、以下のリスト 2 のようです。ここでは、後に実装するカスタム・ウィジェットのスタイルシートである icmsample/resources/ICMSampleWidget.css をインポートしてロードするようにしています。

リスト 2. ICMSamplePlugin.css
@import url("icmsample/resources/ICMSampleWidget.css");

カスタム・アクションの実装

次に、カスタム・アクションのクラスを実装します。カスタム・アクションの実装クラスは、先ほどの Plugin クラスの getActions メソッドの返り値に含めていた ICMSampleAciton クラスです。ICMSamplePlugin サブ・プロジェクトの com.ibm.icm.sample.plugin.actions パッケージにあり、実装は以下のリスト 3 のようです。

基本的には ICN プラグインの PluginAction クラスの一般的な実装方法をベースとしていますが、ICM のカスタム・アクション開発の場合は以下の 2 つを必ず実装する必要があります。

  • getActionModuleClass メソッドで、カスタム・アクションのクライアントサイド JavaScript での処理を実装した Dojo モジュールを指定する必要があります。この Dojo モジュールは ICM が提供する JavaScript API に含まれる icm/action/Action という Dojo モジュールを継承している必要があります。ICM が提供する JavaScript API の詳細については参考文献の Knowledge Center ページ「IBM Case Manager JavaScript API リファレンス」を参照してください。ここでは後に実装する icmsample/action/ICMSampleAction モジュールを指定します。実際の JavaScript ファイルは src/com/ibm/icm/sample/plugin/WebContent フォルダ以下の icmsample/action/ICMSampleAction.js です。
  • getAdditionalConfiguration メソッドで、このカスタム・アクションのプロパティなどの情報を JSONObject として返す必要があります。ここでは alert に表示するメッセージを設定するための message というプロパティを定義しています。JSONObject に含めるパラメータの一覧は、参考文献の Technote 「Technote: Defining registry files for custom actions, properties, page widgets, and events in IBM Case Manager V5.2」 にありますので、詳しくはそちらを参照してください。
リスト 3. ICMSampleAction クラスの実装
package com.ibm.icm.sample.plugin.actions;

import java.io.IOException;
import java.util.Locale;

import com.ibm.ecm.extension.PluginAction;
import com.ibm.json.java.JSONObject;

public class ICMSampleAction extends PluginAction {

	@Override
	public String getId() {
		return "icmsample.SampleAction";
	}

	@Override
	public String getName(Locale locale) {
		return "ICM Sample Action";
	}

	@Override
	public String getIcon() {
		return "";
	}

	@Override
	public String getPrivilege() {
		return "";
	}

	@Override
	public String getServerTypes() {
		return "p8,cm";
	}

	@Override
	public String getActionFunction() {
		return "";
	}

	@Override
	public boolean isMultiDoc() {
		return false;
	}

	@Override
	public boolean isGlobal() {
		return false;
	}

	@Override
	public String getActionModelClass() {
		return "icmsample/action/ICMSampleAction";
	}

	@Override
	public JSONObject getAdditionalConfiguration(Locale locale) {
		String jsonString = "{" +
			"\"ICM_ACTION_COMPATIBLE\": true," +
			"\"context\": null," +
			"\"name\": \"ICM Sample Action\"," +
			"\"description\": \"Show an alert message.\"," +
			"\"properties\": [" +
				"{" +
					"\"id\": \"label\"," +
					"\"title\": \"Label\"," +
					"\"defaultValue\": \"Show message\"," +
					"\"type\": \"string\"," +
					"\"isLocalized\":false" +
				"}," +
				"{" +
					"\"id\": \"message\"," +
					"\"title\": \"Message\"," +
					"\"defaultValue\": \"Hello, World!\"," +
					"\"type\": \"string\"," +
					"\"isLocalized\":false" +
				"}" +
			"]" +
		"}";
		try {
			return JSONObject.parse(jsonString);
		} catch (IOException e) {
			e.printStackTrace();
		}
		return null;
	}
}

次に、getActionModuleClass メソッドで指定した Dojo モジュールである icmsample/action/ICMSampleAction を実装します。実装は以下のリスト 4 のようです。先にも紹介したように、ICM の JavaScript API として公開されている icm/action/Action という Dojo モジュールを継承しており、execute 関数を実装してアクションの message プロパティに指定された値を alert で表示するようにしています。

リスト 4. カスタム・アクションを実装した Dojo モジュールである icmsample/action/ICMSampleAction の実装
define([
	"dojo/_base/declare",
	"icm/action/Action"
], function(declare, Action) {

	return declare("icmsample.action.ICMSampleAction", [Action], {
		execute: function(){
			alert(this.propertiesValue.message || "No message.");
		}
	});
});

以上でカスタム・アクションの実装は完了です。

カスタム・ウィジェットの定義ファイル

次にカスタム・ウィジェットの定義をします。前節のカスタム・アクションの場合は、PluginAction クラスの中で Dojo モジュール名の指定やパラメータの定義を行いました。カスタム・ウィジェットの場合は Java クラスの中ではなく、ICMRegistry サブ・フォルダの中の JSON ファイルで定義を行います。

まず以下のリスト 5 のように、ICMRegistry サブ・フォルダの中の Catalog.json ファイルで、このウィジェット・パッケージに含まれるすべてのカスタム・ウィジェットについての情報を JSON 形式で定義します。このサンプルでは、ICMSampleWidget というカスタム・ウィジェット 1 つだけが定義されています。各カスタム・ウィジェットの情報には、ウィジェットの名前やカテゴリ、Page Designer 上で表示されるアイコン (後述の図 24 参照) のパスなどを定義します。アイコンのパスは ICMRegistry フォルダからの相対パスになっています。この JSON で定義するカスタム・ウィジェット情報のパラメータの詳細については、参考文献の Technote 「Technote: Defining registry files for custom actions, properties, page widgets, and events in IBM Case Manager V5.2」を参照してください。

リスト 5. Catalog.json
{
	"Name":"IBM Case Manager sample widget package",
	"Description":"IBM Case Manager sample widget package",
	"Locale":"",
	"Version":"1.0",
	"Categories":[
		{
			"id":"ICMSampleWidgets",
			"title":"ICM Sample Widgets"
		}
	],
	"Widgets":[
		{
			"id": "ICMSampleWidget",
			"title": "ICM Sample Widget",
			"category": "ICMSampleWidgets",
			"description": "ICM sample widget to show hello message.",
			"definition": "ICMSampleWidget.json",
			"preview": "",
			"icon": "images/sample_icon.png",
			"runtimeClassName": "icmsample/pgwidget/ICMSampleWidget",
			"help": "",
			"previewThumbnail": ""
		}
	]
}

次に、Catalog.json で定義したそれぞれのカスタム・ウィジェットについて、definition パラメータで指定した JSON ファイルで詳細なウィジェット情報を定義します。ここでは、ICMSampleWidget というカスタム・ウィジェットの詳細情報を、以下のリスト 6 のように ICMRegistry サブ・フォルダの ICMSampleWidget.json ファイルで定義しています。先ほどの Catalog.json ファイルで定義した情報と一部重複していますが、こちらにはカスタム・ウィジェットのプロパティなどが追加で定義されています。ここではウィジェットに表示するためのメッセージ文字列を設定するための message というプロパティを定義しています。

この JSON ファイルで定義するパラメータの一覧も、先ほどと同じく参考文献の Technote 「Technote: Defining registry files for custom actions, properties, page widgets, and events in IBM Case Manager V5.2」にありますので、詳しくはそちらを参照してください。

リスト 6. ICMSampleWidget.json
{
	"id": "ICMSampleWidget",
	"title": "ICM Sample Widget",
	"category": "ICMSampleWidgets",
	"description": "ICM sample widget to show hello message.",
	"definition": "ICMSampleWidget.json",
	"preview": "",
	"icon": "images/sample_icon.png",
	"runtimeClassName": "icmsample/pgwidget/ICMSampleWidget",
	"help": "",
	"previewThumbnail": "",
	"properties":[
		{
			"propertyType":"property",
			"type":"string",
			"id":"message",
			"title": "Message",
			"defaultValue":"Hello, World!",
			"disabled": false,
			"required": true,
			"visibility": true
		}
	],
	"events":[]
}

カスタム・ウィジェットの実装

次に、カスタム・ウィジェットを実装します。カスタム・ウィジェットの実装は、前節の ICMSampleWidget カスタム・ウィジェットの定義ファイルの中で runtimeClassName に指定していた Dojo モジュールである icmsample/pdwidget/ICMSampleWidget です。実際のファイルは src/com/ibm/icm/sample/plugin/WebContent フォルダ以下の icmsample/pdwidget/ICMSampleWidget.js で、実装は以下のリスト 7 のようです。

カスタム・ウィジェットの UI は通常、ICM の JavaScript API で提供されている icm/base/BasePageWidget を継承して実装します。ECM コミュニティ・ブログ「IBM Case Manager V5.2.0 Custom Page Widgets and Actions Development」にあるサンプルに付属のドキュメントが参考になります。ここでは、カスタム・ウィジェットの message プロパティで指定した値を画面に表示するだけのシンプルな実装になっています。ウィジェットで使用しているテンプレートの HTML はリスト 8 にある icmsample/pdwidget/templates/ICMSampleWidget.html です。

リスト 7. カスタム・ウィジェットを実装した Dojo モジュールである icmsample/pgwidget/ICMSampleWidget の実装
define([
	"dojo/_base/declare",
	"icm/base/_BaseWidget",
	"icm/base/BasePageWidget",
	"dojo/text!./templates/ICMSampleWidget.html"
], function(declare, _BaseWidget, BasePageWidget, template){

	return declare("icmsample.pgwidget.ICMSampleWidget", [_BaseWidget, BasePageWidget], {
		templateString: template,

		postCreate: function(){
			this.inherited(arguments);
			this._showMessage();
		},

		_showMessage: function(){
			this._messageNode.innerHTML = this.widgetProperties.message;
		}
	});
});
リスト 8. icmsample/pgwidget/templates/ICMSampleWidget.html の実装
<div class="icmsampleMessage" data-dojo-attach-point="_messageNode"></div>

また、カスタム・ウィジェットのスタイルは、以下のリスト 9 にある icmsample/resources/ICMSampleWidget.css で定義しています。このスタイルシートは、先のリスト 2 に挙げたプラグインのスタイルシートからインポートされています。

リスト 9. icmsample/resources/ICMSampleWidget.css
.icmsampleMessage {
	font-weight: bold;
	padding: 15px 5px;
}

以上でカスタム・ウィジェットの実装は完了です。

ウィジェット・パッケージのビルド

実装が完了したら、プロジェクトをビルドしてウィジェット・パッケージを作成します。ビルドには Ant を使用します。図 13 のように、ICMSample プロジェクトと ICMSamplePlugin サブ・プロジェクトにそれぞれ build.xml ファイルを作成し、まず ICMSamplePlugin サブ・プロジェクトをビルドして ICN プラグインの JAR ファイルを作成し、その JAR ファイルを ICMRegistry サブ・フォルダとともに ZIP ファイルにまとめて ICMSample.zip ファイルを作成するような Ant スクリプトを実装します。この記事の末尾にあるサンプルの ZIP ファイルに含まれている build.xml をコピーして使用することもできます。その際、プロパティの値は環境に合わせて適宜編集してください。

図 13. build.xml ファイルの作成 (Web プロジェクトなしの場合)

build.xml ファイルの準備ができたら、以下の手順で Ant を実行します。

  1. RAD のパッケージ・エクスプローラー上で、ICMSample プロジェクトの build.xml を右クリックし、「実行」 > 「Ant ビルド」を選択します。
  2. Ant タスクが実行され、図 13 のように ICMSample プロジェクトの直下に ICMSample.zip というウィジェット・パッケージのファイルが作成されたことを確認します。 (表示されていない場合はパッケージ・エクスプローラーを更新してみてください)

以上でウィジェット・パッケージのビルドは完了です。

カスタム・ウィジェットの作成 ② : Web プロジェクトありの場合

今度は、図 4 の [タイプ ③] で紹介した Web プロジェクトありの構成で、先ほどと同じカスタム・ウィジェットを作成してみます。ここまで紹介してきた Web プロジェクトなしの構成の場合との違いを中心に紹介します。なお、完成版はこの記事の末尾にあるダウンロードの章の ICMSampleProjects.zip ファイルの中に含まれている ICMSample2 プロジェクトを参考にしてください。

プロジェクトの作成

先の Web プロジェクトなしの場合と同様の手順で、まず ICMSample2 という名前の Java プロジェクトを作成し、サブ・プロジェクトとして ICMSample2Plugin という名前の Java プロジェクトを作成します。さらに、サブ・プロジェクトとして ICMSample2Widgets という動的 Web プロジェクトを以下の手順で作成します。

  1. RAD のメニューから「ファイル」 > 「新規」 > 「プロジェクト」を選択します。
  2. 「動的 Web プロジェクト」を選択して「次へ」をクリックします。 (図 14)
  3. プロジェクト名に「ICMSample2Widgets」と入力します。さらに ICMSample2 プロジェクトのサブ・プロジェクトとなるようにするために、「デフォルト・ロケーションの使用」のチェックを外して、ロケーションに以下のパスを指定します。「EAR にプロジェクトを追加」のチェックを外して、「終了」をクリックします。 (図 15)

    ロケーション : <ルート・プロジェクトである ICMSample2 プロジェクトのロケーション>\ICMSample2Widgets

  4. ICMSample2Widgets プロジェクトが ICMSample2 プロジェクトのサブ・プロジェクトとして作成されたことを確認します。 (図 16)
図 14. 動的 Web プロジェクトを選択
図 15. ICMSample2 プロジェクトのサブ・プロジェクトになるようにロケーションを指定して ICMSample2Widgets プロジェクトを作成
図 16. ICMSample2Widgets プロジェクトが ICMSample2 プロジェクトのサブ・プロジェクトとして作成されたことを確認

フォルダとファイルの作成

プロジェクトの作成が完了したら、カスタム・ウィジェットおよびカスタム・アクションの実装に必要なフォルダおよびファイルを作成します。下図 17 は、Web プロジェクトなしの場合とありの場合とのファイル構成を比較した図です。基本的に作成するファイルは同じなのですが、Web モジュール部分の実装を Web プロジェクト内で行うようにします。具体的には、Web プロジェクトなしの際に ICN プラグインプロジェクトの中で作成していた icmsample パッケージ以下の Dojo モジュールが、Web プロジェクトありの際には Web プロジェクトにそのままの構成で移動していることがわかります。なお、パッケージ名、ファイル名やクラス名が重複しないように、icmsample だった部分は icmsample2 に変更してあります。

図 17. カスタム・ウィジェットおよびカスタム・アクション実装用のファイルとフォルダの作成 (Web プロジェクトなしとありの場合の比較)
表 4. プロジェクト内の各ファイルの詳細 (Web プロジェクトありの場合)
ファイル名内容
ICMRegistry フォルダ
Catalog.jsonパッケージに含まれるすべてのカスタム・ウィジェットの情報をカタログとしてまとめた JSON ファイル
ICMSampleWidget.jsonICMSampleWidget カスタム・ウィジェットの詳細情報をまとめた JSON ファイル
images/sample_icon.pngPage Designer 上で表示されるカスタム・ウィジェットのアイコン (後述の図 24 参照)
ICMSample2Plugin/src/com/ibm/icm/sample/plugin フォルダ
ICMSample2Plugin.javaICN プラグインの Plugin クラス
actions/ICMSample2Action.javaICMSampleAction カスタム・アクションの実装クラス。ICN プラグインの Action クラスをベースに ICM アクション用の拡張部分を追加して実装。
ICMSample2Plugin/src/com/ibm/icm/sample/plugin/WebContent フォルダ
ICMSample2Plugin.cssICN プラグインのスタイルシート
ICMSample2Plugin.jsICN プラグインの JavaScript ファイル
ICMSample2Widgets/WebContent/icmsample2 フォルダ
action/ICMSampleAction.jsICMSampleAction カスタム・アクションの JavaScript の実装
pdwidget/templates/ICMSampleWidget.htmlカスタム・ウィジェットのテンプレート HTML
pdwidget/ICMSampleWidget.jsICMSampleWidget カスタム・ウィジェットの JavaScript の実装
resources/ICMSampleWidget.cssICMSampleWidget カスタム・ウィジェットのスタイルシート

プラグインの実装

つづいて ICN プラグインの Plugin クラスを実装します。この Web プロジェクトありの場合のサンプルの Plugin クラスは、 ICMSample2Plugin サブ・プロジェクトの com.ibm.icm.sample.plugin パッケージの ICMSample2Plugin クラスで、実装はリスト 10 にあります。

先の Web プロジェクトなしの場合と大きく違うのは、getDojoModule メソッドの実装がなくなった点です。前節でファイルを作成した際に紹介したとおり、Dojo モジュールが ICN プラグインプロジェクトから Web プロジェクトに移動したので、ICN プラグインとして提供する Dojo モジュールがなくなり、getDojoModule メソッドの実装が不要になったためです。もし Dojo モジュールを ICN プラグインの中に一部残す場合には getDojoModule メソッドの部分は削除せずに残しておく必要がありますが、その場合、ICN プラグインの Dojo モジュールと Web プロジェクトの Dojo モジュールのパッケージ名は重複しないように注意してください。

その他の部分は基本的に Web プロジェクトなしの場合とほぼ同じで、プラグインの ID やクラス名などが重複しないように変更してあるだけです

リスト 10. ICMSamplePlugin クラスの実装
package com.ibm.icm.sample.plugin;

import java.util.Locale;

import com.ibm.ecm.extension.Plugin;
import com.ibm.ecm.extension.PluginAction;
import com.ibm.icm.sample.plugin.actions.ICMSample2Action;

public class ICMSample2Plugin extends Plugin {

	@Override
	public String getId() {
		return "ICMSample2Plugin";
	}

	@Override
	public String getName(Locale locale) {
		return "ICM Sample2 Plugin";
	}

	@Override
	public String getVersion() {
		return "1.0";
	}

	@Override
	public String getScript() {
		return "ICMSample2Plugin.js";
	}

	@Override
	public String getCSSFileName() {
		return "ICMSample2Plugin.css";
	}

	@Override
	public PluginAction[] getActions() {
		return new PluginAction[] { new ICMSample2Action() };
	}
}

次に、Plugin クラスの getScript メソッドおよび getCSSFileName メソッドで指定した、ICMSample2Plugin プロジェクトの src/com/ibm/icm/sample/plugin/WebContent フォルダ以下の ICMSample2Plugin.js および ICMSample2Plugin.css を実装します。

JavaScript の ICMSample2Plugin.js の実装はリスト 11 のようです。先の Web プロジェクトなしの構成の場合は何も実装のない空ファイルになっていましたが、Web プロジェクトありの構成の場合は Web プロジェクトの中で実装している Dojo モジュールのパッケージのパスを登録するコードを実装する必要があります。ここでは require 関数を使って、Web プロジェクトの /ICMSample2Widgets/icmsample2 という URL を icmsample2 という Dojo パッケージのパスとして登録しています。

リスト 11. ICMSample2Plugin.js
require({
	paths: {
		"icmsample2": "/ICMSample2Widgets/icmsample2"
	}
});

スタイルシートの ICMSample2Plugin.css の実装は、以下のリスト 12 のようです。先の Web プロジェクトなしの構成の場合と同様、カスタム・ウィジェットのスタイルシートをインポートしてロードするようにしていますが、URL が Web プロジェクトのコンテキストルートである /ICMSample2Widgets を含んだ URL になっていることに注意してください。

リスト 12. ICMSamplePlugin.css
@import url("/ICMSample2Widgets/icmsample2/resources/ICMSampleWidget.css");

カスタム・アクションの実装

カスタム・アクションの実装については、ICMSampleAction.js の場所が ICN プラグインプロジェクトから Web プロジェクトに移動になった点以外は特に大きな変更はありませんので、詳細は省略します。細かい変更としては、ID やネームスペースが重複しないように icmsample から icmsample2 に変更になっています。

カスタム・ウィジェットの定義

カスタム・ウィジェットの定義についても Web プロジェクトなしの場合と大きな変更はありません。ICMRegistry サブ・フォルダ内の JSON ファイルでカスタム・ウィジェットに関する情報を定義しています。詳細は省略します。

カスタム・ウィジェットの実装

カスタム・ウィジェットの実装についても、ICMSampleWidget.js の場所が ICN プラグインプロジェクトから Web プロジェクトに移動になり、ID やネームスペースを変更した点以外は特に変更はありません。詳細は省略します。

ウィジェット・パッケージのビルド

実装が完了したら、プロジェクトをビルドしてウィジェット・パッケージを作成します。図 18 のように、ICMSample2 プロジェクトと ICMSample2Plugin サブ・プロジェクトに加えて、ICMSample2Widgets サブ・プロジェクトにも build.xml ファイルを作成します。この build.xml により EAR モジュールをビルドできるようにするため、WebContent/META-INF/application.xml も作成します。この記事の末尾にあるサンプルの ZIP ファイルに含まれている build.xml および application.xml をコピーして使用することもできます。その際、プロパティの値は環境に合わせて適宜編集してください。

図 18. build.xml ファイルおよび application.xml ファイルの作成 (Web プロジェクトありの場合)

build.xml ファイルの準備ができたら Ant を実行し、図 18 のように ICMSample2 プロジェクトの直下に ICMSample2.zip というウィジェット・パッケージのファイルが作成されたことを確認します。 (表示されていない場合はパッケージ・エクスプローラーを更新してみてください)

以上でウィジェット・パッケージのビルドは完了です。

ウィジェット・パッケージのデプロイ

カスタム・ウィジェットの開発が完了してウィジェット・パッケージがビルドできたら、ウィジェット・パッケージをデプロイして実際に動かしてみます。Web モジュールが含まれているかいないかによってウィジェット・パッケージのデプロイの手順も変わります。ここではそれぞれのデプロイ手順を紹介します。

Web モジュールなしの場合

カスタム・ウィジェットのパッケージに Web モジュールが含まれていない場合は、ICM 管理者クライアントの Web ページからパッケージをデプロイすることができます。

  1. ブラウザから ICM 管理者クライアントにアクセスして、管理者ユーザーでログインします。

    http://<ICM_server>:<port>/navigator/?desktop=icmadmin

  2. ドメインのオブジェクト・ストアの一覧から、ウィジェット・パッケージをデプロイしたい設計オブジェクト・ストア (Design Object Store) を選択して開きます。 (図 19)
  3. 選択した設計オブジェクト・ストアの Widget Packages 一覧画面を開き、Register Custom Widgets ボタンをクリックします。 (図 20)
  4. ウィジェット・パッケージの ZIP ファイル (ここでは ICMSample.zip) を選択して Next ボタンをクリックします。 (図 21)
  5. 表示されたウィジェット・パッケージの情報を確認して Finish ボタンをクリックすると、ウィジェット・パッケージがデプロイされます。 (図 22)
  6. Widget Packages 一覧画面に戻り、デプロイしたウィジェット・パッケージがリストに表示されていることを確認します。
  7. デプロイが完了したら、アプリケーション・サーバーを再起動します。
図 19. DESGIN 設計オブジェクト・ストアの選択
図 20. Widget Packages 一覧画面で Register Custom Widgets ボタンをクリック
図 21. 作成したウィジェット・パッケージを指定して Next ボタンをクリック
図 22. ウィジェット・パッケージの情報を確認してデプロイ

Web モジュールありの場合

カスタム・ウィジェットのパッケージに Web モジュールが含まれている場合は、Web モジュールのデプロイ処理が必要となるため、ICM 管理者クライアントの Web ページからはパッケージをデプロイできません。代わりに、Case Manager をインストールしたサーバーにインストールされているデスクトップ・アプリケーションである「Case Manager 構成ツール (Case Manager Configuration Tool)」を使用します。デプロイの手順は以下です。

  1. Case Manager 構成ツールがインストールされているマシンに、ウィジェット・パッケージの ZIP ファイルをコピーしておきます。
  2. Case Manager 構成ツールを起動し、インストールに使用した構成プロファイルを開きます。 (もしプロファイルがない場合は新規に作成し、サーバー情報などを設定してください)
  3. 開いた構成プロファイルの中の「Deploy and Register Widget Package」タスクをダブルクリックして開きます。「Widgets package file path」に 1 でコピーしておいたウィジェット・パッケージの ZIP ファイル (ここでは ICMSample2.zip) を指定し、デプロイするサーバーの情報を「Application server node」「Application server name」で選択したら、「Save」ボタンを押して保存します。 (図 23)
  4. 「Run Task」ボタンを押してタスクを実行します。コンソールに「Finished running Deploy and Register Widgets Package」というメッセージが表示されれば完了です。
図 23. ウィジェット・パッケージの情報を確認してデプロイ

カスタム・ウィジェットの動作確認

ウィジェット・パッケージのデプロイが完了したら、以下の手順で Page Designer でカスタム・ウィジェットとカスタム・アクションをページに配置し、実際にデプロイして動作確認を行います。

  1. ブラウザから Case Manager Builder を開きます。

    http://<ICM_server>:<port>/CaseBuilder/

  2. 動作確認に使用するソリューションを選択して「編集」リンクをクリックします。
  3. 「ページ」タブから動作確認に使用するページを選択し、リンクをクリックして Page Designer を起動します。
  4. Page Designer を起動すると、ウィジェットのパレットに「ICM Sample Widgets」というカテゴリが表示され、「ICM Sample Widget」というカスタム・ウィジェットが使用できるようになっています。ここでは「ICM Sample Widget」をページにドラッグ&ドロップして配置します。 (図 24)
  5. 配置した ICM Sample Widget ウィジェットの右上部分にある歯車アイコンをクリックしてプロパティ設定ダイアログを開き、Message プロパティの値を適宜編集して「OK」ボタンをクリックします。 (図 25)
  6. Toolbar ウィジェットの右上部分にある歯車アイコンをクリックしてプロパティ設定ダイアログを開き、「ボタンの追加」アイコンをクリックしてアクションを追加します。アクションのリストに「ICM Sample Action」が表示されるようになっているので、これを選択して、Label および Message プロパティを適宜編集して「OK」ボタンをクリックします。 (図 26)
  7. ページを保存し、ソリューションをコミットしてデプロイします。
  8. デプロイしたソリューションをブラウザで開き、先に示した図 5、図 6 のようにカスタム・ウィジェットとカスタム・アクションが動作することを確認します。
図 24. カスタム・ウィジェットをドラッグ&ドロップして配置
図 25. カスタム・ウィジェットのプロパティを編集
図 26. カスタム・アクションの追加とプロパティの設定

ウィジェット・パッケージのアンインストール

最後に、デプロイしたウィジェット・パッケージのアンインストール手順について紹介します。ウィジェット・パッケージのデプロイは 1 つの画面だけで処理を完了させることができましたが、アンインストールは複数のステップを実行する必要があります。

ウィジェット・パッケージの削除

まず、ウィジェット・パッケージを削除します。ウィジェット・パッケージの削除は、Web モジュールなしのパッケージのデプロイ時に使用した ICM 管理者クライアントから行うことができます。削除に関しては、Web モジュールのあり、なしにかかわらずこの ICM 管理者クライアントを使用します。

  1. ブラウザから ICM 管理者クライアントにアクセスして、管理者ユーザーでログインします。

    http://<ICM_server>:<port>/navigator/?desktop=icmadmin

  2. ドメインのオブジェクト・ストアの一覧から、ウィジェット・パッケージをデプロイしてある設計オブジェクト・ストア (Design Object Store) を選択して開きます。
  3. 選択した設計オブジェクト・ストアの Widget Packages 一覧画面を開き、削除するウィジェット・パッケージを選択してから Actions > Unregister Custom Widgets を選択します。 (図 27)
  4. ウィザードに従ってウィジェット・パッケージを削除します。
図 27. ウィジェット・パッケージの削除

ICN プラグインの削除

次に、ウィジェット・パッケージに含まれていた ICN プラグインを削除します。ICN プラグインの削除は、ICM 管理者クライアントの管理者ビューから行います。

  1. ブラウザから ICM 管理者クライアントにアクセスして、管理者ユーザーでログインします。

    http://<ICM_server>:<port>/navigator/?desktop=icmadmin

  2. 左側のフィーチャーリストから管理者ビュー (歯車のアイコン) を選択して開きます。
  3. 「プラグイン」を選択して一覧を表示し、ウィジェット・パッケージに含まれていた ICN プラグインを選択して「削除」ボタンをクリックします。 (図 28)
  4. 確認ダイアログが表示されたら「削除」ボタンをクリックして削除を実行します。
  5. 削除が完了したら、アプリケーション・サーバーを再起動します。
図 28. ICN プラグインの削除

Web モジュールの削除

Web モジュールありの構成にした場合は、さらに Web モジュール (EAR) を削除する必要があります。EAR の削除は WebSphere Application Server (WAS) の管理コンソールから行います。

  1. ブラウザから WAS の管理コンソールにアクセスして、管理者ユーザーでログインします。
  2. Applications > Application Types > WebSphere enterprise applications を選択してアプリケーション一覧画面を表示します。
  3. 一覧からウィジェット・パッケージに含まれていた EAR モジュール (ここでは ICMSample2Widgets) を選択して、Uninstall ボタンをクリックします。 (図 28)
  4. ウィザードにしたがってアプリケーションを削除します。
図 29. WAS 管理コンソールから EAR の削除

以上で、ウィジェット・パッケージ内のすべてのモジュールの削除が完了です。

まとめ

この記事では ICM のカスタム・ウィジェットを開発するにあたって、プロジェクト構成の選定から、実際にプロジェクトを作成してデプロイ、動作確認、さらにアンインストールするまでの一連の手順を紹介しました。紹介したステップを元にしてさまざまなカスタム・ウィジェットおよびカスタム・アクションを作成していただくことで、幅広いニーズに応じたケース管理ソリューションを開発いただけます。この記事がその際の参考になればと思います。


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


関連トピック


コメント

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

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Information Management, Web development
ArticleID=983110
ArticleTitle=IBM Case Manager のカスタム・ウィジェット開発手順
publish-date=09182014