Standard Libraries

TrialGrid manages Standard Libraries in a hierarchy of linked Drafts:

A Standards Library is simply a Draft inside a Project which has the "Is Standards Library" checkbox set. Every Draft can have one Standard Library set making a chain of standard libraries back to a root or top-level library.

Checking Compliance

The Standard Draft tree is a mechanism for determining compliance to the standard. For each object in a Draft ( a Form, Edit Check etc) TrialGrid follows the tree "up" back to the root looking for an object to compare to. Usually the system will look for an object with the same identifier (Name/OID) as the object in the Draft but you are able to customize this per-object so that you can have an object named "VT2" in a Draft and have it compare to an object called "VT" in the library.

In the following example, Draft 1 uses the AE form but its direct parent CNS Standards does not contain the AE form. The AE form is originally defined in the Core Standards:

For every object in the Draft TrialGrid can determine if it is:

Not found in the standard tree
Found in the standard tree and is an exact match to the standard definition
Found in the standard tree but is different to the standard definition (see how differences are calculated
Found in the standard tree, is different to the standard definition but has allowed changes.
Found in the standard tree, is different to the standards definition but adhere to Standard Rules.

If the object is not found, is different from the standard definition in a way that is not allowed or which does not meet the standard rules then these deviations should be explained.

Objects that come from other Libraries

Note that TrialGrid does not enforce copying objects from the Standard library. It is often convenient for the Study Builder to copy definitions for Forms or Edit Checks from a previous study or from a different Standard Library.

By default, all objects are compared against the Draft Default Library (the Library set at the Draft level for all objects to be compared against). But on a per-object basis this can be overridden so that objects can be copied from different libraries and still compared correctly.

In this example we can see the AE form is being compared to the Core Library version of this Form and the TA1 form is being compared against the version of the TA1 form in the TA Library.

TrialGrid provides assurance that whatever the source, the object matches the selected Standard library. This approach provides the Study Builder with freedom to design in the most efficient way for them while also tracking standards compliance with no extra effort.

Comparing Differences

If an object has been changed from the standard definition then it is helpful to understand what the changes are so that these can be explained and approved for the study.

TrialGrid provides a side-by-side color-coded comparison of objects in text form so that the differences can be quickly identified. Deletions are highlighted in red and additions in green.

The sidebar shows child objects (such as Fields in a Form) and whether they are matched between the compared objects. If Ordinals have changed then we would see Fields listed in a different order with lines drawn to match them up:

It is also possible for the view to show "Allowed Changes". Some objects such as Forms and Fields can have rules set in the Standard Library version of the Form which allows some properties to be changed. This allows, for example, the Field Question text or Control Type to be changed without triggering a standards compliance warning. These changes are still shown in the compare view but they are shown as an "allowed change".

Where an object or attribute setting meets or fails Standard Rules this is also shown in the comparison. For example, this might show that the "Is Log" setting for a Field on a Form is different to the library version of the Field but that it meets the standard rules.

Explaining and Approving Differences

When an object is not found in the Standard Library or is different from the standard definition, the Study Builder must explain the differences via a pop-up in the object listing. Once explained these difference can be Approved by a user with Manage Approval permission from their Project Role.

A user with Manage Approval permission may also Deny a change signalling to the requester that the change made is not acceptable. All Approval/Denial actions have an associated comment so that the requester can be given instruction on how to make the change acceptable.

Conditional Approvals

A user with Manage Approval permission may also Conditionally Approve a difference. A Conditional Approval can be useful for new study objects not found in the standard library (e.g. a study specific form). The Conditional Approval can signal the study builder to continue developing this object and act as a reminder to the standards manager to re-evaluate the object at a later time when work has completed.

Important

A Conditional Approval deviation allows the deviation value to change without resetting the state of that deviation to Unexplained. For example, a user can change help text to "Test A" and if that deviation is Conditionally Approved the user can change the help text to "Test B" and the state stays as Conditional Approval. In effect, any value can be entered until the item is re-reviewed and the state changed (e.g. to Approved but also to Denied/Request Approval or Conditionally Approved again).

Overall Object State

Because each individual deviation from the standard requires explanation and each explanation can be one of:

Unexplained

Approval Requested

Conditionally Approved

Approved

Denied

Then an object can have a mixture of deviations in different states. The overall state of the object is determined:

If the object has no deviations to explain then it appears in the Approved state.

Otherwise, if the object has at least one Denial then the object appears in the Denied state.

Otherwise, if the object has at least one Unexplained deviation then the object appears in the Unexplained state.

Otherwise, if the object has at least one Conditional Approval then the object appears in the Conditionally Approved state.

Otherwise, if the object has at least one Approval then the object appears in the Approved state.

An audit trail is kept of the explanations and approvals for deviations from the standards.

Reporting on Compliance

A summary of compliance metrics is available on the Standard Compliance page. This page shows the overall counts of objects found in the Standard Library Drafts vs how many were not found because they were new or were changed.

A PDF report of the summary can be generated from the same page.

How Differences between objects are Calculated (Fingerprints)

In calculating compliance of an object to its library counterpart the TrialGrid system has to perform a comparison between two objects. Some types of objects have many attributes themselves and/or children with many attributes. For example, if you look at the Fields tab of an ALS spreadsheet you will see many columns representing the attributes of Fields in a Form.

To determine if two objects are the same or different TrialGrid has to compare every attribute of each of them. This is time-consuming so TrialGrid uses a shortcut. It pre-calculates a "fingerprint" for Draft objects (Forms, Edit Checks etc) every time the object is saved.

The fingerprint is calculated by concatenating all the attribute values of an object (and of its children) into a single long text value and then taking a cryptographic hash of the resulting value.

Example:

Object 1:
+===================+==========================+
| Attribute Name    | Value                    |
+===================+==========================+
| Is Active         | True                     |
| Log Direction     | Portrait                 |
| View Restrictions | Investigator,Coordinator |
+-------------------+--------------------------+
FingerPrint("True,Portrait,Investigator,Coordinator") = 0e86611408ce880597cc260dff382fc4

Object 2:
+===================+==========================+
| Attribute Name    | Value                    |
+===================+==========================+
| Is Active         | True                     |
| Log Direction     | Landscape                |
| View Restrictions | Investigator,Coordinator |
+-------------------+--------------------------+
Fingerprint("True,Landscape,Investigator,Coordinator") = 5b33236163847902033770743cd3424e

The hash values allow TrialGrid to tell if two objects are exactly the same without comparing every attribute - it can simply compare the fingerprints. If they are the same then its an exact match, if they are not the same then the compare machinery needs to look more closely at the objects to determine if there are reportable differences.

Some attributes are not included in fingerprints. These are:

Attribute	Objects Affected	Explanation
Ordinal	Forms, Fields, Folders Data Dictionary Entries, Unit Dictionary Entries	It is not useful to include Ordinal in a comparison between Forms and other objects. If a new Form is added to a Draft then the Ordinals of all Forms "below" that Form are changed and the Ordinal of a Form in a library is unlikely to be the same as the Ordinal of the same Form in a draft so most Forms would be "different" by this metric. Some objects have child-objects (Fields in Forms, Entries in Data Dictionaries etc). These have their own fingerprints calculated and are added into the parent fingerprint. Note that because Ordinal is not part of the fingerprint of each child the order in which these are added is based on their identifier value (FieldOID for Fields, CodedValue for Dictionary Entries, CodedUnit for Unit Dictionary Entries).
OID	Forms, Folders	Forms are (normally) matched by OID so when we want to compare a Form with OID "FORMA" against a Form with OID "FORMB" we want to know if their contents is identical so we don't include that identifier in the fingerprint.
Name	Checks, Derivations, Custom Functions, Data Dictionaries, Unit Dictionaries	Objects which have a name rather than an OID are identified by their names so we do not include the name of the object in the fingerprint (see OID above)
Labels	All objects	The labels associated with an object are not included in its fingerprint.

Note

Custom Property values are included in the fingerprints of objects which have them.

Note

Fingerprints are a detail of the TrialGrid compliance and comparison system but we document them because they can be included in Document Templates for informational purposes.