The Server Notifications Connector is an interface to the IBM® Tivoli® Directory
Integrator (Tivoli Directory
Integrator) notification system. It listens for and reports, as
well as issues, Server API notifications. The Connector provides the
ability to monitor various processes taking place in the Tivoli Directory
Integrator Server,
such as AssemblyLine stop and start process events, as well as issue
custom server notifications.
The Server Notifications Connector supports the Iterator and AddOnly
modes.
Iterator Mode
Depending on how it is configured the Server Notifications Connector
in Iterator mode is capable of listening to and reporting either local
or remote Server API notifications, but not both during the same Connector
session.
The "Local" connection type should be used when the Connector is
run in the same JVM as the Tivoli Directory
Integrator Server which sends notifications.
The "Remote" connection type should be used when the Connector
connects to a remote Tivoli Directory
Integrator Server run in a different JVM.
AddOnly Mode
The Connector in AddOnly mode sends Server API custom (that is,
user-defined) notifications through either the local or the remote
Server API session, but not both during the same Connector session.
The "Local" connection type should be used when the Connector is
run in the same JVM as the Tivoli Directory
Integrator Server which sends notifications.
The "Remote" connection type should be used when the Connector
connects to a remote Tivoli Directory
Integrator Server run in a different JVM.
The data needed for creating the notification objects is retrieved
from the conn Entry passed to the Connector by the AssemblyLine.
The Connector looks for fixed-name Attributes in this Entry, retrieves
their values, builds the notification object using these values and
emits this notification object through the Server API. For more information
about the fixed-name Attributes please see the "Schema" section.
Since each Server API notification also causes a corresponding
JMX notification to be emitted, the Server Notifications Connector
in AddOnly mode also indirectly sends JMX notifications. For more
information about the details of custom notifications please see section Schema.
The Server Notifications Connector provides the option to use Secure
Sockets Layer (SSL) when the connection type is set to remote.
If the remote Tivoli Directory
Integrator server accepts SSL connections only,
the Server Notifications Connector automatically establishes an SSL
connection provided that a trust store on the local Tivoli Directory
Integrator Server
is configured properly. When SSL is used, the Connector uses a Server
API SSL session, which runs RMI over SSL.
Trust store
A trust store on the local Tivoli Directory
Integrator Server is needed because
when the remote Tivoli Directory
Integrator Server fires a notification a new
SSL connection to the local Tivoli Directory
Integrator Server is created and
in order for this new SSL connection session to be established the
local Tivoli Directory
Integrator Server must trust (through its trust store)
the remote Tivoli Directory
Integrator Server SSL certificate. A trust store
is configured by setting the appropriate values for the javax.net.ssl.trustStore, javax.net.ssl.trustStorePassword and javax.net.ssl.trustStoreType properties
in the global.properties or solution.properties files.
The Server Notifications Connector is capable of authenticating
by using a client SSL certificate. This is only possible when the
remote Tivoli Directory
Integrator Server API is configured to use SSL and to
require clients to possess SSL client certificates. A trust store
must be configured properly on the local Tivoli Directory
Integrator server.
Username and Password Authentication
The Server Notifications Connector is capable of using the Server
API username and password authentication mechanism. The desired username
and password can be set as a Connector parameter, in which case the
Connector will use the Server API username and password authentication
mechanism. If SSL is used and a username and password have been supplied
as Connector parameters, then the Connector will use the supplied
username and password and not an SSL client certificate to authenticate
to the remote Tivoli Directory
Integrator Server.
The Server Notifications Connector uses the following parameters:
Connection Type
Determines whether the Server Notifications Connector will listen
for and emit local or remote Server API notifications. The available
values for this parameter are remote and local. local means
that the Connector will only listen for and notifications in the local
Java Virtual Machine. remote means that the Connector will
connect to a remote Tivoli Directory
Integrator Server system and register for
and emit notifications in the Java Virtual Machine of that remote
system.
RMI URL
Specifies the Remote Method Invocation (RMI) URL used to connect
to the remote Tivoli Directory
Integrator Server system. This parameter is only
taken into account if the connectionType parameter is set
to remote. An example value for this parameter is:
rmi://127.0.0.1:1099/SessionFactory
Username
Specifies the user name the Connector uses to authenticate to
the Tivoli Directory
Integrator server. This parameter is only taken into account
if the Connection Type parameter is set to remote.
Password
Specifies the password the Connector uses to authenticate to
the Tivoli Directory
Integrator server. This parameter is only taken into account
if the Connection Type parameter is set to remote.
Filter Config Instance ID
Specifies a Config Instance ID, which the Connector
will use to filter event notifications. If this parameter is specified,
the Connector will only report notifications that have this Config
Instance ID. This parameter is only taken into account if the Connector
mode is Iterator.
Filter Notification ID
Specifies a Notification ID, which the Connector will use to
filter event notifications. If this parameter is specified the Connector
will only report notifications which have the specified notification
ID. This parameter is only taken into account if the Connector mode
is Iterator.
Timeout (seconds)
Specifies the maximum number of seconds to wait for a notification.
After this timeout expires, the Connector will terminate. If this
parameter value is set to "0", then the Connector will wait forever.
This parameter is only taken into account if the Connector mode is
Iterator.
Receive All Server API Events
Specifies if "di.*" notifications will be received by
the Connector. This parameter is only taken into account if the Connector
mode is Iterator.
Receive All Config Instance Events
Specifies if "di.ci.*" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive Config Instance Start Events
Specifies if "di.ci.start" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive Config Instance Stop Events
Specifies if "di.ci.stop" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive Configuration Updated Events
Specifies if "di.ci.file.updated" notifications will
be received by the Connector. This parameter is only taken into account
if the Connector mode is Iterator.
Receive All AssemblyLine Events
Specifies if "di.al.*" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive AssemblyLine Start Events
Specifies if "di.al.start" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive AssemblyLine Stop Events
Specifies if "di.al.stop" notifications will be received
by the Connector. This parameter is only taken into account if the
Connector mode is Iterator.
Receive Server Shutdown Event
Specifies if "di.server.stop" notifications will be
received by the Connector. This parameter is only taken into account
if the Connector mode is Iterator.
Use Custom Notification
Specifies whether the Connector will receive any additional
or custom notifications. If it is checked the additional/custom notifications
can be specified in the Custom Notification types Connector
parameter. This parameter is only taken into account if the Connector
mode is Iterator.
Custom Notification types
Specifies the notification types of additional or custom Server
API notifications which the Server Notifications Connector will listen
to and report. Each notification type must be typed on a separate
line. This parameter takes effect only if the Use Custom Notification parameter
is true, and is only taken into account if the Connector mode is Iterator.
Debug
Turns on debug messages. This parameter is globally defined
for all Tivoli Directory
Integrator components.
The Server Notifications Connector in Iterator mode sets the following
Attributes in the Input Attribute Map:
event.rawNotification
The notification event object (com.ibm.di.api.DIEvent). It contains
the complete information about the Server API event generated in the
core of the Tivoli Directory
Integrator Server.
event.type
The type of the notification event (java.lang.String). This
Attribute specifies what has happened. An example value of this Attribute
would be "di.al.start".
event.id
The notification ID (java.lang. String). This Attribute specifies
the source of the event, that is, which Tivoli Directory
Integrator component has fired this
event. An example value of this Attribute would be "AssemblyLines/tcp".
event.userData
The notification user data. (java.lang.Object). Optional user-defined
information whose purpose is to convey more information related to
the event, for example why the event happened, where the event happened,
etc. This Attribute is only available if such user-data was actually
passed on generating the event.
For AssemblyLine events this Attribute
contains the AssemblyLine unique code, which can be used to unambiguously
identify the AssemblyLine instance which has generated this event
(for example "1709375019").
If the userData object is of type
com.ibm.di.entry.Entry, then its Attributes are also mapped in the
generated output Entry, so they can be directly accessed in the Assembly
Line (for example, conn.getAttribute("event.userData.hostname") )
without a need of additional scripting in order to make them available.
event.configInstanceId
The config instance ID (java.lang.String). The ID of the loaded
and running config instance which has fired this event. An example
value of this Attribute would be "C__dev_assembly_TCPServer.xml".
event.dateCreated
The date object stores the time and date when this notification
was created. (java.util.Date).
AddOnly mode
The Server Notifications Connector in AddOnly mode expects to receive
the following Attributes from the Output Attribute Map:
event.type
The type of the notification event (java.lang.String). This
Attribute specifies what event the custom notifications signals. Since
this is a user-defined event this can be any String. An example value
of this Attribute would be "myAL.DBRecord.Committed". This Attribute's
presence in the conn Entry is required. If this Attribute is missing
from the conn Entry, then the Connector throws an Exception.
The
value supplied by the user for this Attribute will be prefixed with
the "user." prefix by the Connector when building the notification
object. For example if the type passed by the user is "process.X.completed"
the type of the event broadcasted will be "user.process.X.completed".
event.id
The notification ID (java.lang. String). This Attribute specifies
the source of the event, that is, which Tivoli Directory
Integrator component has fired this
event. Since this is a user-defined event this can be any string,
for example "myAssemblyLine_5". This Attribute's presence in the conn
Entry is required. If this Attribute is missing from the conn Entry,
then the Connector throws an Exception.
event.userData
The notification user data. (java.lang.Object). Optional user-defined
information whose purpose is to convey more information related to
the event, for example why the event happened, where the event happened,
etc. The presence of this Attribute in the conn Entry is
optional.
Directory Integrator, Version 7.1.1