FIM CM Notification API Architecture
The Forefront Identity Manager Certificate Management (FIM CM) Notification API provides an interface with which a developer may register subscribers for notification events. The API also contains components that collect notification events, generate notifications, and distribute notifications.
Synchronous and One-way Processing Model
FIM CM notifications are one-way events delivered from the FIM CM server to the notification system. They are forwarded to each registered subscribing notification handler. Notification handlers do not communicate back to the FIM CM server.
The notification architecture uses a synchronous model of notifying the notification handlers. FIM CM processing for the given operation is suspended while the notification handler is executing. Multiple notification handlers configured for the same event will be executed in succession.
It should also be mentioned that notification handlers execute in the context of the FIM CM process thread. If they perform activities that last a long time this will impact the response time of the FIM CM client. In most cases, if the data from a notification object does not require immediate action, it is best to simply log the data to a file, or send it in an e-mail, so that it can be processed later.
Warning
For these reasons, it is crucial that your notification handler code be both thread-safe and re-entrant.
Multiple Notification Handlers for the Same Events
To send notifications, the FIM CM Notification system must have information about subscribers and the events that the subscribers are interested in receiving. Multiple notification subscribers may subscribe for the same event. In this case, notifications are delivered in the same order as the notification handlers are registered.
On the other hand, the same notification subscriber can register for multiple FIM CM event notifications. In this situation, FIM CM creates a new instance of the handler class for each subscription.
Subscription management is performed by registering the notification handler in the FIM CM’s web.config configuration file. To register a notification handler, modify the ClmNotifications section in the web.config file as follows:
<ClmNotifications>
<add event="event name that FIM CM publishes"
class="fully qualified DLL name of notification handler located in the web\bin and bin folders"
initializationData="data to be passed to the Initialize() call of this notification handler"/>
</ClmNotifications>
Each notification handler should implement the INotificationSink interface. All events require the notification subscribers to implement the INotificationSink interface.
Notification Class
You can access request details in a notification handler by using the Notification class, which contains details that describe the information pertinent to the event being triggered. Every time a notification handler is invoked to handle an event, an object of this kind is created by FIM CM and provided to the notification handler in the Notify method. The information includes the following: time when the event started, time when the operation triggering the event was started and completed, status information for the event, type of the notification, the request for this event, and a GUID of the user who performed the operation that triggered this event.
Notification Events
Notification event types are described in NotificationType. Depending on the type of event you are working with, Notification handlers may fire under different circumstances. For instance, some event types trigger only for software certificate profiles (such as DownloadPfx), some events trigger only for smart card operations (such as SmartcardPinRolloverExecute, SmartcardPrint, and SmartcardAssignCard), and some event types trigger for both (such as CreateRequest, CancelRequest, and ApproveRequest). One should also keep in mind that the same notification event may trigger in multiple situations. For example, a CreateProfile notification will fire during the execution of numerous different request types (such as EnrollProfile, RecoverProfile, and DuplicateProfile).
Relationship with other FIM CM Components
FIM CM notification handlers can leverage the programming model of the FIM CM Provision API to obtain additional information for the notification data received. For example, the notification handler receives a request Guid corresponding to the request associated with the current operation. The notification handler can then call GetRequest to load the request object for that request.
Notification handlers receive a Request object as part of the notification. You can use the information in this Request object to obtain further information, like the details of the Profile Template associated with the request or the smart card associated with the request.
See Also
Concepts
FIM CM Notification API Fundamentals