Rational Software Whitepaper
IBM Rational ClearQuest
AuditTrail & eSignature Packages
User Guide
Ryan Sappenfield, Product Manager
rjsappen@us.ibm.com
Revision 1.0
29-Nov-04
Table of Contents
OVERVIEW ...................................................................................................1
AUDITTRAIL PACKAGE ..............................................................................2
Administration ........................................................................................................... 2
Audit trail capture ...................................................................................................... 2
Information in the audit trail ...................................................................................... 2
Audit Trail Display. .................................................................................................... 2
Customization ........................................................................................................... 2
ESIGNATURE PACKAGE ............................................................................4
Administration (eSig_Config records) ....................................................................... 4
Signature Enforcement and Validation ..................................................................... 5
Information recorded for each signature................................................................... 5
Verification that the signature is still valid ................................................................. 6
Ability to display current and historical signature information ................................. 6
Customization ........................................................................................................... 6
IMPLEMENTING CUSTOMIZATIONS .........................................................7
AuditTrail customizations .......................................................................................... 7
1.
Exclusion of specific fields from AuditTrail capture. ...................................... 7
2.
Audit Trail format............................................................................................ 7
3.
Prevent the capture of AuditTrail data for a record........................................ 8
eSignature customizations ........................................................................................ 9
1.
eSignature log format .................................................................................... 9
2.
Control access to eSig_Config records ......................................................... 9
Overview
Companies that develop drugs or medical devices must satisfy a variety of record-keeping requirements imposed by
the Food and Drug Administration (FDA) through its various regulations. When such companies use ClearQuest as
part of their development process, they might be required to use ClearQuest in a way that satisfies these FDA
regulations. Specifically, they might be required to satisfy the 21 CFR Part 11 regulations, which say how audit
trails and electronic signatures must be applied to electronic record-keeping systems used during the development of
drugs and medical devices.
With the ClearQuest v2003 SR4 release, ClearQuest can now be used in a way that will allow customers to satisfy
these requirements.

Password security. ClearQuest passwords must provide a reasonable level of security against various
kinds of security threats. This functionality will be implemented through ClearQuest support for LDAP
authentication.
NOTE: ClearQuest LDAP support will be generally available for SR5. Please contact your IBM Rational
sales team for more information.

Audit trails. When ClearQuest data is changed, ClearQuest must be able to record who changed what
when. This functionality can be implemented with the new AuditTrail package provided with SR4.

Electronic signatures. When a user enters or changes administrator-defined ClearQuest data, the user
must prove his or her identity for each change or each group of related changes. This functionality can be
implemented with the new eSignature package provided with SR4.
Page 1 of 13
AuditTrail Package
Administration
A ClearQuest administrator will be able to specify that certain records should automatically get an audit trail when
created or updated. If the administrator specifies that a given record type will have an audit trail, all changes to
records of that type will automatically get an audit trail from then on. The administrator will be able to turn off the
audit trails for any record type that has them.
Audit trail capture
To ensure reasonable response times, the AuditTrail package will not store all audit trail information for a record as
one of the record’s fields. Instead, only the most recent change to the record will be stored and displayed with the
record; a separate table will provide access to the complete audit trail history.
The AuditTrail package will create a new database table that contains the audit trail for all records that are enabled
for audit trails. The table will store sufficient information to link each record to each change made to that record, and
will record the version of the database schema that was used to describe the record.
Information in the audit trail
The audit trail describes a sequence of events that have happened to the record being audited. For each such event,
ClearQuest will record the following information:

Who changed it: ClearQuest will record the user name (such as “jdoe”) and the full name (such as “John
Doe”) of the user who made the change. The full name is taken from the fullname field in the ClearQuest
user table.

When it was changed: ClearQuest will record the date and time of the change. This timestamp includes
its own time zone so that there is no ambiguity about what the timestamp means. The time zone can be
GTM, the client’s time zone, or the database server’s time zone, but it must be specified.

The action and state: The action that changed the record and the final state of the record will be recorded
for this event.
o

Deleted records: Information is never deleted from the audit trail. If an audited record is deleted,
an entry is made in the audit trail with an Action of DELETE and State of DELETED.
What fields were changed: For each data field in the record that was changed with this event, the audit
trail will record the name of the field, its old value, and its new value.
o
Deltas for multi-line text fields: If the full old and new values of multi-line text fields were
recorded in the audit trail, they would consume excessive disk space and be hard for humans to
read. Consequently, the audit trail will show only those lines that changed between the old and the
new values. Line numbers will indicate which lines are affected. (A consequence of this feature
is that an append-only field, such as the Notes field where text is appended at the top but old text is
never changed, will display only the new appended text in the audit trail.)
Audit Trail Display.
Applying the AuditTrail package to a record type will give that record’s form a new tab that displays the audit trail
for the record. This tab contains no editable fields.
Customization
The AuditTrail package provides a customization mechanism by which its functionality can be modified via userdefined extensions, similar to the various Hooks provided by ClearQuest itself. Extensions allowed by the package
include:

Exclusion of specific fields from AuditTrail capture. Some fields in a record do not pertain to the
"predicate data" covered by 21 CFR 11 regulations. At the customer's option, a set of fields can be
Page 2 of 13
specified for each entity type (or even each entity) that will not be subject to AuditTrail capture. Note that
if a change to a record affects only those fields that a customer has marked for exclusion, the package will
still record the relevant user name, time of the change, and the state information for the record.

Audit trail format. The AuditTrail is currently captured in a textual format. Each change to an originating
record prepends its AuditTrail data to the existing AuditTrail information. The customer may supply an
extension to format the data that is recorded for each change.

Prevent the capture of AuditTrail data. There is currently no way to disable a ClearQuest package for a
record type once it has been applied to that record type. We will allow the customer to provide an extension
to disable AuditTrail capture for specific record types. (This could also be used at a finer-grained level, e.g.
to disable AuditTrail capture for specific states, but that is not the intent of this extension and should be
discouraged.)
Page 3 of 13
eSignature Package
The Electronic Signature package will provide the following functions:
Administration (eSig_Config records)
Once the eSignature package has been applied to a schema, enabling eSignatures for a specific record type requires
two additional actions by the administrator: applying the package to that record type (via the Package Wizard or the
packageutil enablerecordtype command) and creating at least one eSig_Config record describing
when the target record type needs to be signed.
The eSig_Config record provides the administrator with a field that selects the target record type, and two
options to indicate when records of that type are to be signed: State selection and Action selection. If the chosen
record type is stateful, then both State selection and Action selection options are available; if the record type is
stateless, only Action selection is available. The State and Action selections are both cleared when the record type is
changed.
Note that eSig_Config records always indicate when a record is to be signed; they cannot suppress signature
collection. Hence multiple eSig_Config records can be created for the same target record type without causing
ambiguity: Signatures are to be collected if any record exists that matches a specific state and/or action condition.
Similarly, if the administrator selects both Action-based and State-based criteria on an eSig_Config record, the
criteria in the record are logically or'd together. Hence a target record will require a signature if an eSig_Config
record exists that matches either the current state condition or the current action condition.
Figure 1 (below) shows a sample eSig_Config record form.
Figure 1: eSig_Config record
Page 4 of 13
Target record type selection
This field allows the user to select one entity type. The choice list includes all entity types found in the schema
(whether stateful or stateless), except for certain types that are internal to ClearQuest: History, Attachments,
ratl_replicas, Groups, Users, AuditTrailLog, eSigLog.
Sign by State
The two fields here allow the user to select from one or more of the states available to the chosen entity type (if
any), as well as how the selected state(s) are used to determine whether a signature is required. The choices for
Sign When are:

Entering State: Records of the target type are signed if the action will cause the record to enter
the specified state.

Leaving State: Records of the target type are signed if the action will cause the record to leave the
specified state.

Modify In State: Records of the target type are signed if the record is in the specified state
immediately before, during, or immediately after the action 1.
Sign by Action
This field displays all Actions for the target record type except for Base actions, Record Script Aliases, and Import.
The administrator may select one or more of these options. Since this will be the only criterion requiring signatures
for stateless record types, the administrator must select at least one Action if the target record is stateless.
Signature Enforcement and Validation
When the eSignature package is applied to a record type, that record type's forms will include an additional tab
containing fields related to eSignature, including User Name, Password, Signature Log, and an "Is Current" flag.
If a signature is required, the user name and password will be marked as required fields; otherwise, they are readonly. If a signature is required, the user name and password are checked to ensure that they match the username and
password with which the user logged in to ClearQuest. If they match, then the change is accepted and the signature
is logged. If they are not valid, the user gets an error message and no change is made to the database.
Information recorded for each signature
By default, the eSignature package will record for each signature:

o The user name of the user signing the record
o The user’s printed name
o The user’s group membership
o The action being taken
o The final state of the record
o Timestamp for the action
Ability to record meaning of signature: The eSig log will automatically record customer-defined
information about the signature. Exactly how the meaning is captured is up to the customer organization
and the policies or procedures it institutes to satisfy the FDA regulations. A customer-modifiable global
script will be used to specify and format the contents of the eSig log.
Page 5 of 13
Verification that the signature is still valid
A signature is valid for a record only if the record has not changed since the signature has been applied. The
eSignature tab will provide a field (labeled "Signature is Current") that indicates this condition. This field is always
read-only; it displays "True" if the last change to the record included a signature, and "False" otherwise.
Ability to display current and historical signature information
The eSignature tab includes a field, "eSignature Log", that displays the full signature history for a record. Note that
this includes only changes that have been signed; the AuditTrail package can be used to provide a more detailed
change history.
Customization
The eSignature package provides a customization mechanism by which its functionality can be modified via userdefined extensions, similar to the various Hooks provided by ClearQuest itself. Extensions allowed by the package
include:

eSignature log format: The eSignature log is captured in a textual format. Each signature is prepended to
the existing eSignature data (if any) for that record. The customer may supply an extension to format the
signature when it is recorded for each change.

Control access to eSig_Config records. The administrator may provide an extension that will ensure that
only authorized users may create, modify, or even view eSig_Config records. (Ideally, this probably
should be done by changing the ownership of the eSig_Config record type.)
Page 6 of 13
Implementing Customizations
The customer can add certain extensions to the AuditTrail and eSignature packages to customize their behavior. To
do so, they add one or more Perl functions to the Global Hooks section of their schema. (Adding the extensions to
Global Hooks makes them available to any hook in the packages. However, these extensions are not invoked as
Named Hooks, but as normal Perl functions.)
Each extension has a specified name, arguments, and return value, as described in the subsections below.
In the examples that follow, the text in Courier is required as part of the customer extension. Text in courier
italic illustrates code that might be written by the customer to implement the extension.
AuditTrail customizations
IMPORTANT: To use these examples, create a new Global PERL script, for example: at_Cust_Hooks. Then
cut and paste the subroutines in blue highlights below to the global script you just created. The AuditTrail
package hooks will look to call these routines by name, so case and spelling are very important!
1. Exclusion of specific fields from AuditTrail capture.
Some fields in a record may not be pertinent to the "predicate data" covered by 21 CFR 11 regulations. At the
customer's option, a set of fields can be specified for each entity type (or even each entity) that will not be subject to
AuditTrail capture. Note that if a change to a record affects only those fields that a customer has marked for
exclusion, the package will still record the relevant user name, time of the change, and the state information for the
record.
Example
sub atCust_ExcludeField {
my ($session, $entity, $fieldName) = @_;
return ($fieldName eq "Description");
}
Arguments:
$session: The current session object
$entity: The entity object for which an audit trail is being written.
$fieldName: The name of the field that may be excluded from the AuditTrail.
Return Value: 0 to keep the field in the AuditTrail; non-0 to exclude it.
2. Audit Trail format
Audit trail format. The AuditTrail is currently captured in a textual format. Each change to an originating record
prepends its AuditTrail data to the existing AuditTrail information. The customer may supply an extension to format
the data that is recorded for each change.
Example
Page 7 of 13
sub atCust_CreateLogEntry {
my($session, $entity, $timestamp, $action,
$state, $login, $fullname, $groups) = @_;
# Note: This example doesn't record which fields actually changed.
return "AuditTrail: " . $timestamp . $action . $state .
$login . $fullname . $groups . "\n**********\n";
}
Arguments:
$session: The current session object
$entity: The entity object for which an audit trail is being written.
$timestamp: A string-formatted timestamp value. (We pass this as a convenience; the extension may create its own
timestamp field, or even omit it entirely.)
$action: The name of the current action that is being executed.
$state: The current state of the record. If the current action has modified the state, this field reflects the new state.
$login: The name of the user, as represented by ClearQuest. (Note that if LDAP is in use, this may be a different
name from the one which the user used to log in to ClearQuest.)
$fullname: The full name of the user, if known to ClearQuest.
$groups: A list of the ClearQuest group names to which the user belongs. (This represents only the groups that are
managed by the ClearQuest User Admin tools. If LDAP is in use, the directory may hold other group names
independent of those managed by ClearQuest.)
Return Value: A string representing the full audit trail entry to be written to the log, including any delimiters or
space between entries.
3. Prevent the capture of AuditTrail data for a record
Prevent the capture of AuditTrail data. There is currently no way to disable a ClearQuest package for a record
type once it has been applied to that record type. We will allow the customer to provide an extension to disable
AuditTrail capture for specific record types.
Example
sub atCust_SuppressAuditTrailRecord {
my($session, $entity) = @_;
# return 0; # return 0 to enable AuditTrail (default)
return 1; # return 1 to disable AuditTrail
}
Arguments:
$session: The current session object
$entity: The entity object for which an audit trail is to be written
Return Value: 0 to cause an AuditTrail record to be captured; non-0 to suppress it.
Page 8 of 13
eSignature customizations
IMPORTANT: To use these examples, create a new Global PERL script, for example: eSig_Cust_Hooks. Then
cut and paste the subroutines in blue highlights below to the global script you just created. The eSignature
package hooks will look to call these routines by name, so case and spelling are very important!
1. eSignature log format
The eSignature log is captured in a textual format. Each signature is prepended to the existing eSignature data (if
any) for that record. The customer may supply an extension to format the signature when it is recorded for each
change.
Example
sub eSigCust_MakeLogEntry {
my ($timestamp, $action, $state, $login, $fullname, $groups) = @_;
return "Signed: $timestamp $action $state " .
"$login $fullname $groups \n";
}
Arguments:
$timestamp: A string-formatted timestamp value. (We pass this as a convenience; the extension may create its own
timestamp field, or even omit it entirely.)
$action: The name of the current action that is being executed.
$state: The current state of the record. If the current action has modified the state, this field reflects the new state.
$login: The name of the user, as represented by ClearQuest. (Note that if LDAP is in use, this may be a different
name from the one which the user used to log in to ClearQuest.)
$fullname: The full name of the user, if known to ClearQuest.
$groups: A list of the ClearQuest group names to which the user belongs. (This represents only the groups that are
managed by the ClearQuest User Admin tools. If LDAP is in use, the directory may hold other group names
independent of those managed by ClearQuest.)
Return Value: A string representing the full eSignature entry to be written to the eSignature log, including any
delimiters or space between entries.
2. Control access to eSig_Config records
Although ClearQuest provides the ability to limit access to the creation, modification, or deletion of records to
authorized users, there are conflicts between this facility and the package mechanism. As a result, if the
administrator uses the usual ClearQuest access control methods to specify which users may work with eSig_Config
records, future upgrades to the eSignature package will become more difficult to apply.
This extension provides an alternate means to limit access to eSig_Config records. The administrator may supply
this extension to ensure that only authorized users may create, modify, or even view eSig_Config records.
Page 9 of 13
This extension is invoked during the ACCESS_CONTROL hook for the eSig_Config record; the last three
arguments ($actionname, $actiontype, $username) come directly from the invocation of that hook.
Example
sub esigCust_ConfigAccessCtrl {
my ($session, $actionname, $actiontype, $username) = @_;
return 1 if $username eq "admin";
return 0;
}
Arguments:
$session: The current session object
$actionname: The name of the action which the user is attempting to perform.
$actiontype: The type of this action. This will be one of the following:





CQPerlExt::SUBMIT
CQPerlExt::MODIFY
CQPerlExt::CHANGECQPerlExt::STATE
CQPerlExt::DUPLICATE
CQPerlExt::UNDUPLICATE
$username: The name of the logged-in user. (If using LDAP, note that this will be the name known to ClearQuest,
not the LDAP user name.)
Return Value: 0 to prohibit the user from acting on an eSig_Config record; non-0 to grant access to the user.
Page 10 of 13
Rational Software
IBM Software Group
Rational Software
20 Maguire Road
Lexington, MA 02421
Tel: (781) 676-2400
Web: www.ibm.com/rational
Rational and the Rational logo, among others, are trademarks or registered trademarks of Rational Software Corporation in the
United States and/or other countries. References to other companies and their products use trademarks owned by the respective
companies and are for reference purposes only.
 Copyright 2004 by IBM Corporation.
Subject to change without notice. All rights reserved.
Page 11 of 13