23 通知イベントの開発
この章では、通知イベントを開発する方法について説明します。内容は次のとおりです。
23.1 通知の概念
イベントとは、Oracle Identity Managerで発生する操作で、ユーザー作成、リクエスト開始またはユーザーが作成した任意のカスタム・イベントなどが含まれます。
イベントは、ビジネス操作の一部として、またはエラー生成を介して生成されます。イベント定義は、イベントを記述するメタデータです。イベントのメタデータを定義するには、機能コンポーネントでサポートされるすべてのイベント・タイプを識別することが重要です。たとえば、スケジューラ・コンポーネントの一部として、スケジュール済ジョブ実行の失敗とスケジューラの停止に対してメタデータを定義できます。ジョブの失敗またはスケジューラの停止のたびにイベントが発生し、イベントに関連付けられている通知が送信されます。
通知テンプレートは、特定のイベントと関連付けられています。テンプレートは、通知の書式の定義に使用します。Oracle Identity Managerでは、事前定義済またはデフォルトの通知テンプレートが提供されます。また、新しい通知テンプレートを作成することもできます。
一部のイベントでは、デフォルトでOracle Identity Managerから通知が送信されます。たとえば、UIまたはリコンシリエーションを介してユーザー名およびパスワードなしでユーザーを作成した場合、ユーザーおよびユーザーのマネージャにログイン資格証明が通知されます。
次の各項で説明するように、通知APIおよびリゾルバ・クラスを使用して、新しい通知イベントを定義できます。カスタム通知の要件の例を次に示します。
-
ユーザーをロールに割り当てます。ユーザーおよびロールの所有者は通知されます。
-
リコンシリエーションの一部として財務的に重要な新しいアプリケーション・インスタンスをユーザーに割り当てます。アプリケーション・インスタンスの所有者およびコンプライアンス責任者は、統制外試行の可能性がある場合に通知されます。
23.2 カスタム通知の開発
カスタム通知を開発するには、通知ロジックを構築し、プラグイン・パックを作成し、起動ロジックを構築し、通知サービスを構成します。
この項では、カスタム通知の開発方法について説明します。次の項目が含まれます。
23.2.1 通知ロジックの構築
通知ロジックを構築するには、イベント・メタデータXMLを定義し、リゾルバ・クラスを作成します。
この項では、通知ロジックを構築する方法について説明します。次の項目が含まれます。
23.2.1.1 イベント・メタデータの定義
各イベントに対して、通知エンジンで定義される特定のスキーマを持つXMLファイルを作成する必要があります。そのスキーマ(.xsdファイル)に準拠して、イベントの概要を定義するXMLファイルが作成されます。イベントが定義されると、そのイベントの通知テンプレートを定義できます。
イベント・ファイルは通知エンジンで定義されるスキーマ、NotificationEvent.xsdに準拠している必要があります。イベント・ファイルにはイベントに関する基本情報が含まれます。
ノート:
NotificationEvent.xsdファイルは、MDSのiam\iam-product\features\notification\metadataディレクトリにあります。
次にイベントXMLファイルのサンプルを示します。
<?xml version="1.0" encoding="UTF-8"?> <Events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../metadata/NotificationEvent.xsd"> <EventType name="User Created"> <StaticData> <Attribute DataType="X2-Entity" EntityName="User" Name="Granted User"/> <Attribute DataType="X2-Entity" EntityName="User" Name="Grantee User"/> <Attribute DataType="91-Entity" EntityName="User Group" Name="User Grp"/> </StaticData> <Resolver class="oracle.iam.notification.DemoResolver"> <Param DataType="91-Entity" EntityName="Resource" Name="ResourceInfo"/> </Resolver> </EventType> </Events>
このイベントXMLファイルには、次の要素があります。
-
EventType name: イベントに通知テンプレートを作成する際に利用できるイベントの名前。
-
StaticData: 静的パラメータのリスト。ユーザーは、このパラメータ・セットに、データ依存ではないパラメータを追加できます。つまり、この要素では、通知テンプレートが構成されるときに表示される静的データを定義します。たとえば、ユーザー・エンティティはデータ依存ではなく、解決されたときに、すべてのイベント・インスタンスおよび通知テンプレートに対して同じ属性セットを持ちます。
-
Param DataType: 動的パラメータのリスト。ユーザーは、このパラメータ・セットに、データ依存のパラメータを追加できます。たとえば、Resourceエンティティはデータ依存です。このフィールドに対応する参照がUIに表示されます。ユーザーがこのリソース・オブジェクトを選択すると、そのコールは、ツリー(ユーザーはここからテンプレートで使用する属性を選択します)に表示されるフィールドを取得するために提供されているリゾルバ・クラスに向かいます。
ノート:
使用可能なデータとは、テンプレートにトークンとして組み込むことのできる属性のリストです。これらのトークンは、実行時にリゾルバ・クラスによって渡される値と置き換えられます。トークンの例については、Oracle Identity Governanceの管理の通知テンプレートの作成のステップ7を参照してください。
Oracle Identity Governanceの管理の通知テンプレートの作成に記載されているように、通知テンプレートを作成する際に使用可能なデータがドロップダウン・リストに表示されます。
選択されたデータは単一の属性であり、ユーザーが属性名をコピーして通知テンプレートに貼り付ける際に役立ちます。選択されたデータの属性名は、「使用可能なデータ」リストで選択されたものと同じです。
検索でサポートされる動的エンティティは、ユーザー、リソースおよび組織です。これらのエンティティ名をParam DataType要素で指定する必要があります。
ノート:
<Param DataType>要素は、必須要素ではありません。ただし、使用する際は、エンティティ名にUser、ResourceまたはOrganizationを指定する必要があります。
-
Resolver class: リゾルバ・クラスは、通知ごとに定義する必要があります。これは、通知作成画面で使用できるパラメータと、それらのパラメータを通知の送信時に置き換える方法を定義します。つまり、リゾルバ・クラスは、実行時にデータを動的に解決し、UIに属性を表示します。リゾルバ・クラスの実装の詳細は、リゾルバ・クラスの作成を参照してください。
通知サービスによって、プラグインのMETA-INFディレクトリから、カスタム・イベントXMLファイルが読み取られます。
イベントXMLの推奨の使用方法は、プラグインのMETA-INFディレクトリに配置することです。カスタム通知イベント・プラグインの構造は、次のとおりです。
-
lib/ディレクトリ
-
Notification_Resolver.jar
-
-
META-INFディレクトリ
-
Notification_Event.xml
-
-
plugin.xml
プラグインJARの作成およびプラグイン登録ユーティリティを使用したデプロイの詳細は、プラグインの開発を参照してください。
23.2.1.2 リゾルバ・クラスの作成
すべてのクラスが、NotificationEventResolverインタフェースを実装する必要があります。
この項では、NotificationEventResolverインタフェースのメソッドについて説明し、カスタム・リゾルバ・クラスを作成する例を示します。次の項目が含まれます。
ノート:
カスタム通知イベント・リゾルバ・クラスをコンパイルするには、ORACLE_HOME/server/apps/oim.ear/APP-INF/lib/OIMServer.jarファイルがCLASSPATHに含まれている必要があります。
23.2.1.2.1 getAvailableDataメソッド
APIは次のとおりです。
public List<NotificationAttribute> getAvailableData(String eventType, Map<String, Object> params);
このAPIは、使用可能なデータ変数のリストを戻します。この変数は、テンプレートの作成時や変更時にUI上で使用でき、ユーザーはこの変数を選択して、この変数をテンプレート上のメッセージの一部にすることができます。
eventTypeパラメータは、テンプレートが読み取られるイベント名を指定します。
paramsパラメータは、使用可能なデータがフェッチされるエンティティ名および対応する値を持つマップです。次に例を示します。
map.put("Resource", "laptop");
これは、リゾルバ・クラスで指定したコードに従って、laptopリソースまたはその他のデータに関連付けられたフィールドをフェッチする際に役立ちます。
サンプル・コード:
/** * this is a dummy implementation and uses hardcoded values * Implementors need to iterate the XML as found through the event type * params : will have all the specific values that your resolver needs * for instance resource name = "laptop" that you may want here to be resolved through your custon implementation */ List<NotificationAttribute> list = new ArrayList<NotificationAttribute>(); NotificationAttribute subatr = new NotificationAttribute(); subatr.setName("Dynamic1"); subatr.setType("91-Entity"); subatr.setEntityName("Resource"); subatr.setRequired(false); subatr.setSearchable(true); subatr.setSubtree(lookup91EntityMetaData("resource"), params.get(0)); list.add(subatr);
メイン・ツリーにはエンティティ情報が含まれ、サブツリーにはUIで使用可能なすべてのノードが含まれます。サブツリー内の各ノードからの名前フィールドは、UI上で選択できます。
23.2.1.2.2 getReplacedDataメソッド
APIは次のとおりです。
HashMap<String, String> getReplacedData(String eventType, Map<String, Object> params);
このAPIは、通知を送信するときに、実行時にテンプレートで提示された変数の解決された値を戻します。
eventTypeパラメータは、テンプレートが読み取られるイベント名を指定します。
paramsパラメータは、テンプレート内の残りの変数を解決するためにリゾルバで必要とされるベース値(usr_key、obj_keyなど)を持つマップです。
サンプル・コード:
HashMap<String, Object> resolvedData = new HashMap<String, Object>(); resolvedData.put("shortDate", new Date()); resolvedData.put("longDate", new Date()); String firstName = getUserFirstname(params.get("usr_key")); resolvedData.put("fname", firstName); resolvedData.put("lname", "lastname"); resolvedData.put("count", "1 million"); return resolvedData;
23.2.1.2.3 例: カスタム・リゾルバ・クラスの作成
プロキシとして、追加されたユーザーに電子メール通知を送信するOracle Identity Managerの例を考えてみます。通知電子メールの日付書式を変更する必要がある場合は、プロキシの追加時に、通知用の新しいリゾルバ・クラス・ファイル(AddProxyResolverModifiedなど)を作成します。AddProxyResolverModifiedリゾルバ・クラスのコードは次のとおりです。
package oracle.iam.selfservice.notification; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Date; import java.util.logging.Level; import java.text.ParseException; import java.text.SimpleDateFormat; import static oracle.iam.identity.utils.Constants.PROXY_START_DATE; import static oracle.iam.identity.utils.Constants.PROXY_END_DATE; import static oracle.iam.identity.utils.Constants.PROXY_ORIGINAL_USR_NAME; import static oracle.iam.identity.utils.Constants.PROXY_ORIG_USER_LOGIN; import static oracle.iam.identity.utils.Constants.FIRSTNAME; import static oracle.iam.identity.utils.Constants.LASTNAME; import oracle.iam.notification.impl.NotificationEventResolver; import oracle.iam.notification.vo.NotificationAttribute; public class AddProxyResolverModified implements NotificationEventResolver { public List<NotificationAttribute> getAvailableData(String eventType, Map<String, Object> params) throws Exception { return null; } public HashMap<String, Object> getReplacedData(String eventType, Map<String, Object> params)throws Exception { SimpleDateFormat sdfSource = new SimpleDateFormat("MMMMMMMM DD,yyyy HH:mm:ss a z"); SimpleDateFormat sdfDestination = new SimpleDateFormat("EEE, d MMM yyyy HH:mm:ss Z"); Date sdate = null; Date edate = null; HashMap<String, Object> resolvedData = new HashMap<String, Object>(); resolvedData.put("firstName",params.get(FIRSTNAME)); resolvedData.put("lastName",params.get(LASTNAME)); resolvedData.put("originalusername",params.get(PROXY_ORIG_USER_LOGIN)); String proxy_startDate = (String )params.get(PROXY_START_DATE); System.out.println("proxy_startDate : " + proxy_startDate); String proxy_endDate = (String) params.get(PROXY_END_DATE); System.out.println("proxy_endDate : " + proxy_endDate); sdate = sdfSource.parse(proxy_startDate); edate = sdfSource.parse(proxy_endDate); proxy_startDate = sdfDestination.format(sdate); System.out.println("proxy_startDate : " + proxy_startDate); proxy_endDate = sdfDestination.format(edate); System.out.println("proxy_endDate : " + proxy_endDate); resolvedData.put("proxystartdate", proxy_startDate); resolvedData.put("proxyenddate", proxy_endDate); return resolvedData; } }
23.2.1.3 plugin.xmlファイルの作成
plugin.xmlファイルは、プラグイン・フレームワークによって使用される標準のXMLファイルです。なんらかの機能によってプラグインが使用される場合、これによってプラグイン・ポイントが公開されます。このXMLには、プラグイン・ポイントの情報が保持されます。
通知イベントおよびリゾルバ・プラグイン用に公開されるプラグイン・ポイントは、次のとおりです。
oracle.iam.notification.impl.NotificationEventResolver
通知イベントおよびリゾルバ用のplugin.xmlのサンプルは、次のとおりです。
<?xml version="1.0" encoding="UTF-8" ?> <oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <plugins pluginpoint="oracle.iam.notification.impl.NotificationEventResolver"> <plugin pluginclass="ext.domain.notification.resolver.SendChallengeQuestionsResolver" version="1.0" name="Challenge Question Resolver" /> </plugins> </oimplugins>
23.2.2 リゾルバ・クラスを含むプラグイン・パックの作成
リゾルバ・クラスの作成後、プラグインJARファイルにパッケージ化し、プラグイン登録ユーティリティを使用してJARファイルをデプロイします。
プラグインJARの作成およびプラグイン登録ユーティリティを使用したデプロイの詳細は、プラグインの開発を参照してください。
23.2.3 起動ロジックの構築
イベント・メタデータXMLを定義し、リゾルバ・クラスを作成することで、通知ロジックを構築した後、Oracle Identity Managerの特定の操作で通知ロジックをコールできます。これは、イベント・ハンドラを使用することで実行できます。
通知の起動ロジックは、カスタム・イベント・ハンドラとして構築されます。カスタム・イベント・ハンドラは、関連する操作の適切なステージに構成されます。カスタム・イベントは、プラグイン登録ユーティリティを使用してデプロイされます。イベント・ハンドラの開発の詳細は、イベント・ハンドラの開発を参照してください。
23.2.4 通知サービスの構成
通知のインフラストラクチャレベルの構成は、Oracle Identity ManagerまたはBPELワークフローで行うことができます。
通知のインフラストラクチャレベルの構成の作成には、次のオプションがあります。
-
Oracle Identity Managerにおける通知構成: Oracle Identity Managerにおいて、通知構成は通知プロバイダを介して処理されます。UMSが、デフォルトの通知プロバイダです。通知プロバイダの詳細は、Oracle Identity Governanceの管理の通知プロバイダの管理を参照してください。
-
BPELワークフローにおける通知構成: SOAによって通知サービスが公開され、それをBPELワークフローにおいて通知用にコールします。SOA電子メール通知の詳細は、Oracle Identity Governanceの管理のSOA電子メール通知の構成を参照してください。
ノート:
Dynamic Monitoring Service (DMS)を使用してパフォーマンス・メトリックを表示できます。次のDMSメトリックが通知のパフォーマンスの監視のために存在します。
-
OIM_Notification
: 通知プロバイダで要した時間に関する詳細を提供します。 -
oracle.iam.notification.api.NotificationService
: 通知の数や通知にかかる時間などの詳細を提供します。