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:

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:

  1. 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 Microsoft.Clm.Provision.dll.

  2. 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.

  3. 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.

  4. 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).

  5. Register your notification handler by editing the CLM Notifications section 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 subscribing for

    • class: Fully qualified type name implementing the INotificationSink interface

    • initializationData: Configuration string data specific to your handler. This string will be passed to your handler's Initialize method.

An example of the configuration is shown below. This example illustrates the configuration of notification handlers for the events ApproveRequest and MarkRequestAsFailed.

C#  Copy Code 
<!-- 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:

C#  Copy Code 
<ClmNotifications> 
…
<add event="ApproveRequest" class="Contoso.Clm. NotificationHandlers.OnApproveRequestSendEmail,Contoso.Clm.NotificationHandlers" initializationData="admin@contoso.com"/> 
<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:

C#  Copy Code 
<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.

See Also