Abstract

Adapters subscribing to Notification Lists are virtually identical in structure to those that subscribe to other events. This article targets ASL programmers who are familiar with Advanced ASL concepts such as drivers and subscriptions and who wish to implement processing driven by Notifications filtered by Notification Lists configured in the Global Manager Administration Console. Such adapters may run externally under sm_adapter or sm_server or may run internally on SAM.

Subscribing to Notification Lists

As with other event adapters, a subscription object of the proper type provides the means to characterize and obtain events of interest. In this case, create a uniquely named GA_NLSubscription object and initialize the NLName property with the name of the target Notification List in SAM. Register this subscription with the subscriber front end that will supply the formatted event records to the ASL script. The remainder of the front-end and driver objects are constructed and configured normally. The subscriber front end may be optionally configured to produce periodic TIMER_ALARM messages.

NotifListNameInSam = "MyNotifications";
 
nls = self->create( "GA_NLSubscription", NotifListNameInSam."-NLS" );
nls->NLName = NotifListNameInSam;
 
fe = self->create("GA_SubscriberFE", NotifListNameInSam."-FE" );
fe->SubscribesTo += nls;
fe->timerAlarmInterval = 60;  

Once the driver is started, the ASL script will receive messages in the standard event format: individual data fields separated with field separators (FS) with the first field set as an integer event timestamp. The standard CONNECT, DISCONNECT, and TIMER_ALARM messages are unchanged.

The GA_NLSubscription object will provide four new message types: NL_NOTIFY, NL_CHANGE, NL_CLEAR, and NL_DELETE reflecting operations on all ICS_Notifications that match the criteria of the target Notification List. Each of these messages has a familiar-looking format:

<timestamp>|<msgType>|<ClassDisplayName>|<InstanceDisplayName>|<EventDisplayName>|<Props>|  

Although this appears to mimic the format of other event records, there is an important twist: fields 3,4, and 5 are not the distinguishing Class::Instance::Event of the Notification, but rather the corresponding DisplayName properties. Except for display purposes, these values are of little programming value. Access to the ICS_Notification is provided instead by field 6, the name of a local ASL_NLData object that holds copies of properties of the originating ICS_Notification. This local object is temporary and has an effective lifetime only of the processing of the event record by the START rule. Except for a display-only situations, the ASL script will ignore fields 3,4,5 of the event message and instead use the 'props' value from field 6 to locate the associated ASL_NLData object.

The ASL_NLData class provides these four methods:

These methods can be used to obtain information from the local ASL_NLData 'snapshot' of the Notification. However, to actually modify the original ICS_Notification, an object reference must be created using the Notification Name retrieved from the ASL_NLData object. The following snippet illustrates the high points of an adapter rule to process an NL_NOTIFY message.

//+ NL_NOTIFY
//
//     1067896794|NL_NOTIFY|Router|ChicagoHub|Down|zkb7kh3t30zf9v3v1dz|
//
NL_NOTIFY {
              timestamp: integer fs
                 action: "NL_NOTIFY" fs
       classDisplayName: word fs        // DisplayNames *not* true C:I:E
    instanceDisplayName: word fs
       eventDisplayName: word fs
               propName: word fs        // name of ASL_NLData holding notif vals
                         eol
} do {
 
    // ASL_NLData object is local...
    propObj = self->object( "ASL_NLData", propName );
 
    // do something interesting like cut a Trouble Ticket using information
    // read from the propsObj (quick and local...)
    className =    propObj->get( "ClassName" );
    instanceName = propObj->get( "InstanceName" );
    eventName =    propObj->get( "EventName" ); 
    ....
 
    // use ICS_Notification for write operations (slow and remote...)
    notifName = propObj->get( "Name" );
    notifObj = object( "ICS_Notification", notifName );
    notifObj->UserDefined1 = "Ticketed: ".time();
    
    // tell SAM and clients like us that the notif has changed
    notifObj->changed();
}  

About the Author

Alan Fortier is a Consultant Engineer in the Custom Sales Engineering group and was previously Senior Principal Engineer on SAM Adapter and ATMFR products.

Discuss

Click here to discuss this article