About Client Plug-Ins

A client plug-in is a third-party component added to ActivID CMS to support functionality on the client side (browser). A client plug-in is a JavaScript function that is called by an HTML page generated by ActivID CMS. This function takes as parameters a set of user attributes. The result is also a set of attributes.

The plug-in function, in turn, invokes other third-party components. Client plug-ins are called immediately after the page is loaded. To develop a generic client plug-in, you must implement all methods of a generic client plug-in interface.

Plug-ins are configured to be called at different logical steps of the ActivID CMS device issuance and user management workflows. You can define multiple client and server plug-ins for each logical step.

Client plug-ins are called on the client side when the screen or operation generated for that logical step is loaded. Server plug-ins are called on the server side when the screen or operation for that logical step is submitted back to the ActivID CMS. For example, if there is a client plug-in and a server plug-in for the logical step USER_INFO (the logical step activated when selecting a user in the device issuance workflow) then the following sequence occurs.

1. When the page showing user information is loaded from the ActivID CMS by the browser, it incorporates custom JavaScript methods defined by the plug-in. These JavaScript methods are invoked by the browser.

2. The JavaScript methods can download custom components and execute them.

3. For example, the custom component performs a biometric check or a biometric enrollment and returns the result as either output attributes or as an exception to ActivID CMS.

4. ActivID CMS updates the value of the attributes returned by the client plug-in.

To develop a generic client plug-in, implement all the methods of the generic client plug-in interface.

Defining a Client Plug-In

To define a client plug-in, perform the following steps.

1. Create a file that contains the JavaScript and HTML code to be integrated into the HTML page generated by the ActivID CMS Portal. The JavaScript code contains the function to call, and the HTML code contains the tags for third-party components.

2. Add entries to the generic_plugin.properties file that describe for which hook (USER_INFO, DEVICE_PRODUCE, etc.) and with which parameters the plug-in is to be called by the ActivID CMS.

   The generic_plugin.properties file is located on the server in the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\ directory and contains detailed information on the hooks available for each ActivID CMS function (device issuance, device replacement, device unlock, etc.)..

   For each plug-in:

   • Specify the name of the control to be called to invoke the plug-in. plug_in_name.control is the plug-in name used by ActivID CMS to identify the name of JavaScript function to call.

     For example, if the control parameter is ClientPluginSample1, then the function defined in the HTML is ClientPluginSample1_invokeAsync.

     Plug-ins are invoked with a callback function in the order in which their plug_in_name.control entries appear in the properties file. ActivID CMS waits for all the plugins to return data via their callback and only proceeds when all the callbacks are called with a successful value; otherwise, the hook is aborted and the corresponding ActivID CMS function is terminated.

   • Define the name of each attribute to be passed to the plug-in, in the form: plug_in_name.input. This lists the attribute names that are to be passed to the client plug-in by the ActivID CMS invokeAsync function. For example:

     Copy

     GenericPluginSample1.input = cn:str, givenName:str
     Supported types: str only for string, bin for binary

     Important: If you have configured ActivID CMS to work with more than one type of directory, you may need to specify the directory type by adding a suffix with the directory short name (for example, <plugin name>.input.msft-ad). For details about the directory short names, see Configuring the Generic Plugin.

   • Specify the attributes to be returned by the plug-in to the callback function, in the form: plug_in_name.output. This lists the attribute names that have values produced by the plug-in. ActivID CMS transports the resulting values to the server and sets the corresponding attributes.

     Important: If you have configured ActivID CMS to work with more than one type of directory, you may need to specify the directory type by adding a suffix with the directory short name (for example, <plugin name>.output.msft-ad). For details about the directory short names, see Configuring the Generic Plugin.

   • Specify the name of the HTML page that defines the JavaScript invokeAsync function: plug_in_name.page is the name of the HTML file.

   • Add the plug-in name to the client plug-in list for the logical step that corresponds to the screen where the plug-in is needed.

     For example, to declare the ClientPluginSample1 client plug-in (in the first screen of the device issuance process), the entry in the generic_plugin.properties file would look something like the following example:

     Copy

     USER_INFO.plugin.client = ClientPluginSample1

   Note: It is recommended that you do not use JSP files to define the JavaScript invokeAsync function as plug-ins. This file type is pre-compiled, and it is not easy to insert them dynamically into the ActivID CMS framework.

3. Store HTML pages and third-party packages in the following directory: %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\data

Sample Configuration Files

This section provides a sample configuration of a generic_plugin.properties file that is used as either a client or a server plug-in.

# Declare the list of enrollment plug-ins
EnrollmentPlugins = GenericPluginSample1
 
# Configure the sample enrollment and client plug-ins to be called during the
#USER_INFO logical step
USER_INFO.plugin.server = GenericPluginSample1
USER_INFO.plugin.client = ClientPluginSample1
 
# Define the sample enrollment plug-in
GenericPluginSample1.class = 
com.activcard.aims.plugin.generic.GenericPluginSample1
GenericPluginSample1.conf_file = GenericPluginSample1.properties
GenericPluginSample1.input = cn:str, givenName:str
GenericPluginSample1.output = att1:str
GenericPluginSample1.link = sn:str
 
#Define the sample client plug-in
ClientPluginSample1.control = ClientPluginSample1
ClientPluginSample1.page = ClientPluginSample1.htm
ClientPluginSample1.input = cn:str, givenName:str
ClientPluginSample1.output = biometric:bin
ClientPluginSample1.link = sn:str

The following section provides a sample HTML file (for example, ClientPluginSample1) that can be used as a client plug-in.

<script language="JavaScript">
function ClientPluginSample1_invoke(inputStringArray) {
alert ("ClientPluginSample1.Invoke() nb params="+inputStringArray.length);
for (i = 0; i < inputStringArray.length; i++) {
        alert ("ClientPluginSample1.Invoke() inputparam["+i+"]="+inputStringArray[i]);
}
var rv = "test";
alert ("ClientPluginSample1.Invoke() returns " + rv);
return rv;
}

function ClientPluginSample1_invokeAsync(inputStringArray, cb) {
try {
         var rv = ClientPluginSample1_invoke(inputStringArray);
        cb(rv, null); // or simply cb(rv)
    } catch (e) {
        cb(null, e); // raise an error
    }
}
</script>