Rational Software Whitepaper

IBM Rational ClearQuest

AuditTrail & eSignaturePackages

User Guide


Ryan Sappenfield, Product Manager

Revision 1.0

29-Nov-04

Table of Contents


Overview

AuditTrail Package

Administration

Audit trail capture

Information in the audit trail

Audit Trail Display.

Customization

eSignature Package

Administration (eSig_Config records)

Signature Enforcement and Validation

Information recorded for each signature

Verification that the signature is still valid

Ability to display current and historical signature information

Customization

Implementing Customizations

AuditTrail customizations

1.Exclusion of specific fields from AuditTrail capture.

2.Audit Trail format

3.Prevent the capture of AuditTrail data for a record

eSignature customizations

1.eSignature log format

2.Control access to eSig_Config records

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.

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.
  • 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.
  • 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 user-defined 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 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 itsAuditTrail 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.)

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_Configrecord, the criteria in the record are logically or'd together. Hence a target record will require a signature if an eSig_Configrecord 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

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 read-only. 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:

  • The user name of the user signing the record
  • The user’s printed name
  • The user’s group membership
  • The action being taken
  • The final state of the record
  • 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.

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 user-defined 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 existingeSignature 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.)

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 theextensions 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 itsAuditTrail data to the existing AuditTrail information. The customer may supply an extension to format the data that is recorded for each change.

Example

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.

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!