Developing, Installing, and Deploying Event Notification Plug-Ins

This section describes how to develop an event notification plug-in to process events that are generated by the ActivID CMS. For example, you can create a plug-in that notifies an external system whenever a device is issued to a user.

The following diagram illustrates how ActivID CMS communicates with an external system using an event notification plug-in:

Event Notification Plug-In Overview

The sections below describe how to develop, compile, and deploy event notification plug-ins, what methods are called at start-up, and the event notification workflow.

Developing an Event Notification Plug-In

Event notification plug-ins are implemented using Java. To develop an event notification plug-in, you can take either of the following actions:

  • Implement all of the methods from the com.activcard.aims.event. AIMSEventListener interface. The AIMSEventListener interface provides the methods that allow ActivID CMS to initialize and send events to the event notification plug-in.

or

  • If your plug-in needs to react to certain events (but not every type), create a subclass of com.activcard.aims.event.AIMSEventAdapter. The abstract class AIMSEventAdapter facilitates the process of creating plug-ins that react to some types of events, but not to all types of events (for example, plug-ins that only react to request and device events).

For example, if you create a subclass AIMSEventAdapter, you will not have to provide any implementations for the methods that are not relevant to your integration.

Compiling an Event Notification Plug-In

To be able to compile the plug-in, the following external .jar files must be added to the project:

  • aims-spi.jar

  • ac-interfaces.jar

  • slf4j-api-2.0.12.jar

These .jar files are located in the cms_dir\aims.war\WEB-INF\lib directory where cms_dir represents the installation directory of ActivID CMS.

Important: The cms_portal directory, used in previous versions of ActivID CMS, no longer exists. With the migration to WildFly in ActivID CMS 6.0, that directory is now called aims.war.
Note: ActivID CMS includes the log4j bridge (log4j-over-slf4j-2.0.12.jar) on the server side, which means that users can use either slf4j or log4j in their code. However, the appender packages must be added to the logback.xml file to enable logging for the plugin package.

Deploying an Event Notification Plug-In

To deploy an event notification plug-in, complete the following steps:

  1. Package the plug-in into a .jar file.

  2. Copy this .jar file into the %PROGRAMDATA%\HID Global\Credential Management System\custom.war\WEB-INF\lib directory on the ActivID CMS server. Declare each plug-in in the eventnotificationplugin.properties file (as shown in the following example eventnotificationplugins.properties file):

    Example 1: eventnotificationplugins.properties File

    Copy 
    plugins = MyFirstPlugin,MySecondPlugin
    MyFirstPlugin.class=com.activcard.aims.PlugIn1
    MySecondPlugin.class=com.activcard.aims.PlugIn2

    This example contains two plug-ins; one named MyFirstPlugin and the other MySecondPlugin, both of which are declared. The classes containing the implementation of these two plug-ins are:

    • com.activcard.aims.PlugIn1

    • com.activcard.aims.PlugIn2

  3. If any Java extensions are required, they need to be added to the Java Runtime Environment (JRE), which is used by ActivID CMS and runs the plug-ins. The JRE is located in the directory parent_of_cms_dir\_jvm\lib where parent_of_cms_dir is the parent directory of the ActivID CMS installation directory (the directory in which the ActivID CMS directory is located).

The plug-in must be installed on the system that acts as the host for the ActivID CMS server. The external system that is called when the event occurs can be hosted on a separate system. If the external system is hosted on a separate system, it is the responsibility of the Event Notification plug-in to transfer the events to that remote system.

Calling Methods at Start-Up

ActivID CMS reads the eventnotificationplugins.properties file at start-up. This properties file resides on the system that is hosting ActivID CMS in the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files. ActivID CMS instantiates each of the notification plug-ins declared in the properties file.

When ActivID CMS starts up, it calls the following Event Notification Plug-in SPI A Service Provider Interface (SPI) consists of a set of constant definitions and method declarations without implementations and intended to be called or used in a pre-determined generic manner with a set of outputs that meet pre-determined abstract rules and expectations. methods for each plug-in:

  1. The init() method initializes the plug-in (this method does not take any arguments).

  2. The onSetParams() method provides the plug-in with the name of the folder that contains the ActivID CMS configuration files.

The onSetParams() method accepts a hashtable object that contains a single key, ConfigFolder, and a string whose value is %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\.

At this point, the plug-ins have been initialized and are waiting for events to occur. When an event does occur it is broadcast to all the plug-ins, and depending on the plug-in implementation an event can either be ignored or processed.

Understanding Event Notification Workflow

Once an event notification plug-in has been installed, whenever an event occurs the following happens:

  1. ActivID CMS performs an operation (for example, device issuance).

  2. Once the operation has completed, ActivID CMS calls each event notification plug-in and passes it an AIMSEvent object. Each AIMSEvent object has a set of public accessors for each of the member attributes. These public accessors enable the event notification plug-in to retrieve all of the relevant information about the event and forward it on to the corresponding external system.

  3. The external code processes the event.

  4. When the plug-in is loaded by ActivID CMS on a Windows system, the working directory is set to be:

%PROGRAMDATA%\HID Global\Credential Management System\custom.war\WEB-INF\lib

where cms_dir represents the directory into which ActivID CMS was installed.

Methods Called When an Event Occurs

When an event occurs, there are different types of methods used for handling each of the event classes. Each event class is described in more detail in the following sections:

Each of the methods are called in response to an event occurrence that takes the AIMSEvent object as its only parameter.

A sample plug-in, NotificationPluginSample.java, is included with the ActivID CMS release in the \CMS\SDK\SPI\Notification directory. The sample plug-in logs all the received events into a file.

Deploying the Sample Java Plug-In

A sample plug-in (NotificationPluginSample.java) is included with the ActivID CMS release in the \CMS\SDK\Notification directory. This sample plug-in logs all of the received events into a file.

To deploy the sample plug-in, complete the following steps:

  1. Compile the NotificationPluginSample class with Java to generate a .jar or .class file. For details and more information, see Compiling an Event Notification Plug-In.

  2. Copy the generated binary file to the aims-main/web-inf/lib directory on the ActivID CMS server.

  3. In the eventnotificationplugins.properties file, specify the name and class of the plug-in.

For more information, see Deploying an Event Notification Plug-In.