How to customize a schema to respond to logon and logoff events.

Answer

IBM Rational ClearQuest (CQ) version 8.0.1.1 introduces the ability for a schema to define a logon and logoff hook. These hooks are fired whenever a client logs onto, or logs off from, a user database. These hooks are available for use in CQ databases using Feature Level 8 (FL8).

A logon hook can be used in addition to (or instead of) the client version check to limit logons to specific groups or users. It can also be used to track user logon activity for auditing purposes.

Considerations:

There are several characteristics of these hooks that need to be carefully considered prior to using them:

1. Adding a logon hook will increase the time required for logon. When the logon hook exists, the "users" record for the current user must be loaded, and the hook code loaded into the VBscript or Perl engine so the hook can be fired. This additional overhead can make a noticeable difference in the logon time, even if the hook itself does nothing. Any additional work done by the hook itself, such as updating a record to track user logon activity, will only further increase that time. If the primary purpose of a logon hook is to control what client versions can access the CQ database, it is best to use the FL8 capability ALLOWED_CLIENT_VERSIONS master or schema property; see technote How to specify what client versions can access a ClearQuest database for more details.
   
2. There is no guarantee that a logoff hook will be called, since the session may be forcibly terminated or crash. Logoff hooks will typically be called when a controlled timeout event occurs however, but this cannot be guaranteed.
   
3. One CQ Web session may actually use multiple user sessions to handle background tasks. A web session may also be migrated to a new cqrpc process where a new logon will happen. Each of these sessions is separate from the others and the logon and logoff hooks will fire for each of them.
   
4. The logon hook runs on the server before a full client session has been created. Therefore, session variables that identify the session type (such as _CQ_WEB_SESSION or _CQ_OSLC_SESSION) will not yet be set when the logon hook runs. Any session variables set in the logon hook will persist and will be available to the full session.

Configuration:

To create a logon or logoff hook, the "packageutil createuserhook" command is used. This command creates an empty hook of a specified type as a Record Script on the "users" record type. The script for the hook will match the script languages in use by the schema. When the Windows scripting language is VBscript, the command will create a VBscript and a Perl hook, since the script language for Unix is always Perl.

If the hook already exists in the schema, a warning will be issued and the existing hook will not be modified. Once the hook is created, it can be edited or deleted like any other hook using the CQ Designer.

Note: Prior to running the specific packageutil createuserhook sub-command to implement either the logon or logoff hook capability, ensure any copy of the CQ Designer has been closed. The command will modify the already checked-out schema revision (which prevents saving the copy that was open in the CQ Designer). If the schema is not already checked-out, the schema will be checked-out, and the specified hook will be added. By default, the schema will then be checked-in. To provide an opportunity to further modify the schema, and the new hook, it is generally better to have the packageutil createuserhook sub-command use the "-nocheckin" argument, to prevent the check-in event from occurring.

For example, to create both logon and logoff hooks in the DefectTracking schema in the schema repository for the dbset named "Alpha", use the following commands, which include the best-practice of "-nocheckin":


packageutil createuserhook -dbset Alpha admin "" DefectTracking logon -nocheckin
packageutil createuserhook -dbset Alpha admin "" DefectTracking logoff -nocheckin


Note: the use of the packageutil command is solely supported for the above described purpose, or where otherwise elaborated in published documentation.

Once the hooks are created, proceed to use the CQ Designer to edit them. As with any other schema change, a user database must be upgraded with the new schema revision to utilize the hooks. As with any planned schema changes, best practices recommend using the Test Work function or check-in the schema and manually upgrade a database to test the new hooks (preferably in a test environment).