To handle event notifications in Forefront Identity Manager Certificate Management (FIM CM), you will need to create a notification handler class which implements the INotificationSink interface. It must also contain an Initialize method and a Notify method. FIM CM uses the Initialize method to instantiate objects of your notification handler class. The instance is created once, when the FIM CM server starts, and lives for the duration of the server instance. The Notify method of this class is called for each trigger of each relevant event, and once for each relevant instantiated object. It is possible for different notification handlers to subscribe to the same event, and it is also possible that one notification handler to subscribe to many events. Therefore, in the first case, one event could trigger the Notify methods of two different notification handler objects of different classes, and in the latter case, two different event types could each trigger the Notify method of two different objects of the same handler class.
In sum, here are some relevant issues regarding the lifetime of a notification handler:
- A new instance of the handler class is
instantiated for each event configuration. Each instance is created
once and lives as long as the FIM CM server process is running.
- The Notify method of a notification
handler object is called for each trigger of the event type to
which that object is subscribed.
- Configuring the same handler for different
event types will result in multiple instances of the notification
handler being instantiated, once for each event type when the FIM
CM Server starts.
Developing the Notification Handler Class
Developing a notification handler is a simple process. Most of your development time will be spent creating the notification functionality that your handler will be performing.
To develop a FIM CM notification handler, follow these steps:
- In your Visual Studio.NET project, right-click Solution
Explorer and select Add Reference…. Add a reference to the
Microsoft.Clm.Shared.dll. If you intend to include Provision API functionality in your notification handler, you should also add a reference to
- Decide which events you are interested in receiving
notifications for. These are the events that your notification
handler will subscribe to. There are many different event types,
all of which are described in NotificationType.
- Implement your notification handler by creating a class that
implements the INotificationSink
interface. Make sure that the functions in this class are
re-entrant and thread-safe.
- Place your notification handler assembly in the FIM CM server's
c:\program files\Microsoft Certificate Lifecycle Manager
2007\web\bin and c:\program files\Microsoft Certificate
Lifecycle Manager 2007\bin folders, or register the class in
the server's Global Assembly Cache (GAC).
- Register your notification handler by editing the
CLM Notificationssection in the FIM CM web.config configuration file. You must create a new entry for each notification handler subscription. Each new entry consists of the following attributes:
- event: Name of the event the handler is
- class: Fully qualified type name implementing
- initializationData: Configuration string data
specific to your handler. This string will be passed to your
handler's Initialize method.
- event: Name of the event the handler is subscribing for
An example of the configuration is shown below. This example illustrates the configuration of notification handlers for the events ApproveRequest and MarkRequestAsFailed.
<!-- CLM NOTIFICATIONS SECTION +++++++++++++++++++++++++++--> <ClmNotifications> <add event="ApproveRequest" class="MyImplementation. NotificationHandlers.OnApproveRequest,MyImplementation.NotificationHandlers" initializationData="my data"/> <add event="MarkRequestAsFailed" class=" MyImplementation. NotificationHandlers.OnMarkRequestAsFailed, MyImplementation. NotificationHandlers" initializationData="my data"/> </ClmNotifications>
Note that each entry in the configuration file is
restricted to handling one event type. You can write as many
different notification handlers for each event type as you want,
and each class must be configured in the
<ClmNotifications> area of FIM CM’s web.config
file. You can also use your single notification handler for
multiple events by configuring it in multiple event sections of the
<ClmNotifications> section of the configuration
file. Each event configuration will result in a separate instance
of your notification handler being created. For example, for events
of the type ApproveRequest, you might decide to implement
one class that logs the events to disk in a log file, and a
separate class that sends an email to the administrator whenever
such events trigger. In that case, you would have two classes that
subscribe to ApproveRequest events, and they would be
registered in the FIM CM web.config file as follows:
<ClmNotifications> … <add event="ApproveRequest" class="Contoso.Clm. NotificationHandlers.OnApproveRequestSendEmail,Contoso.Clm.NotificationHandlers" initializationData="firstname.lastname@example.org"/> <add event="ApproveRequest" class="Contoso.Clm.NotificationHandlers.OnApproveRequestLogEvent,Contos.Clm.NotificationHandlers" initializationData="C:\ClmLogs\ApproveRequest.xml"/> … </ClmNotifications>
Or you may have a more generic notification handler class that performs different functions based on which event type occurs:
<ClmNotifications> … <add event="ApproveRequest" class="Contoso.Clm. NotificationHandlers.RequestLogger,Contoso.Clm.NotificationHandlers" initializationData="C:\ClmLogs\ApproveRequest.xml"/> <add event="CancelRequest" class="Contoso.Clm.NotificationHandlers.RequestLogger,Contos.Clm.NotificationHandlers" initializationData="C:\ClmLogs\CancelRequest.xml"/> … </ClmNotifications>
In the above example, one instance of the RequestLogger
class is instantiated with the string
C:\ClmLogs\ApproveRequest.xml, and will trigger
whenever an event of type ApproveRequest fires. Another
instance is instantiated with the string
C:\ClmLogs\CancelRequest.xml and will trigger whenever
an event of type CancelRequest fires.
This second example illustrates why it is important that notification handlers be re-entrant and thread-safe, since multiple notification handler objects of the same class can be instantiated at any given time.
Any change to web.config will recycle the FIM CM Server web process, so FIM CM will restart automatically after you have changed the web.config file.