Standard Rules

A Draft in a Standard Library Project may have associated Standard Rules. These rules define:

  • What should and should not appear in a Study Draft (e.g. is a Form allowed or denied in this Study)

  • What may be allowed to appear in a Study Draft (to control what Standards Managers have to review)

  • The settings of object attributes and Custom Properties

These rules are associated with Project Custom Properties and are activated based on the values of those Custom Properties.

Some examples:

  1. A Standard Library defines a Vitals Form which has a question for the subject "Height". In a neonatal study it may be more appropriate to measure the "Length" of the subject. A Standard Rule may be defined that when the Project Custom Property "Is Neonatal Study?" is set to "Yes" then the Question text for the Vitals HEIGHT question should be "Length".

  2. A Standard Library defines a Pregnancy Test Form which is commonly used but it should never appear in studies with Male-only subjects enrolled. A Standard Rule may be defined that states when the Project Custom Property "Male Only Study?" is set to "Yes" then the Pregnancy Test Form should not appear in the study.

  3. A Standard Library defines a Pharmacokinetics (PK) Form and this should always be used in Phase I studies. A Standard Rule may be defined that states that when the Project Custom Property "Study Phase" is equal to "Phase I" then the PK Form must exist in the study.

  4. A study build will use a Standard Library but the standards manager does not want to review Custom Functions which are created specific for this study. A Standard Rule may be defined that states that a Custom Function with any name (or a name matching a specific pattern) may exist. Custom Functions created in the study which match this rule are then listed as "allowed changes" from the library and do not require approval. Note that it is also possible to switch off standards compliance reporting for object types at the URL level see Configuring Standards Compliance configuration at URL level.

Standard Rules in Standards Compliance

When comparing a Study Draft to a Library Draft, Standards Compliance is calculated for the Study Draft. For example this calculation can tell you if the design of a Form deviates from the Standard Library. However, in many cases we expect some deviation from the Library based on some attributes of the Project or Study. Examples of Project attributes which might affect library usage are:

  • The Phase of the Study

  • The Therapeutic Area of the study

  • Whether the study has integrations such as IxRS or Rave Safety Gateway

  • The age range of the subjects

  • The countries or regions where the study will be carried out

  • Whether a study is a new or a roll-over study

These Project Attributes can be created as Custom Properties for the TrialGrid URL and then become available for all Projects in the TrialGrid URL.

Standard Rules can be used to vary the expected presence/absence of a Form, Field or other object from the Study Draft and the expected values of object attributes (such as question text) based on the Project Custom Property settings.

When a Draft is linked to a Library which has Standard Rules defined then the Rules in that library are evaluated against the Custom Property settings of the Project the Study Draft belongs to. i.e. If you create a Project and set its Custom Property for "Therapeutic Area" to "CNS" and then create a Draft in that Project and link it to a Library for standards comparison then the Rules in that library will be evaluated to determine which ones should be active where "Therapeutic Area" is equal to "CNS". This will affect Standards Compliance calculations.

Logical Expressions

A Standard Rule has a logical expression. When that expression evaluates to True then the Rule is activated. Logical expressions will normally include references to Project Custom Properties. To refer to a Project Custom Property we use the format p("<property name>")

Examples of expressions:

Expression

Explanation

An empty expression always evaluates to False. This means the Rule will not be activated.

 
True

Always evaluates to True. This means the Rule will always be activated.

 
False

Always evaluates to False This means the Rule will never be activated.

 
p("Therapeutic Area") == "Oncology"

Evaluates True when the Project Custom Property named "Therapeutic Area" is set to the value "Oncology"

 
p("Therapeutic Area") != "Oncology"

Evaluates True when the Project Custom Property named "Therapeutic Area" is NOT set to the value "Oncology"

 
p("Therapeutic Area") in ["Oncology","CNS","Derm"]

Evaluates True when the Project Custom Property named "Therapeutic Area" is any one of the values "Oncology","CNS" or "Derm"

 
p("Early Phase Study") == "True"

Evaluates True when the Project Custom Property "Early Phase Study" equal to "True"

 
not p("Early Phase Study") == "True"

Evaluates True when the Project Custom Property "Early Phase Study" does not equal "True" (i.e. is equal to "False" or is empty/not set)

 
   p("Early Phase Study") == "True"
or p("Therapeutic area") == "CNS

Evaluates to True when the Project Custom Property "Early Phase Study" is equal to "True" or the Project Custom Property "Therapeutic Area" is equal to "CNS"

 
    p("Early Phase Study") == "True"
and p("Therapeutic area") == "CNS"

Evaluates to True when both the Project Custom Property "Early Phase Study" is equal to "True" AND the Project Custom Property "Therapeutic Area" is equal to "CNS"

 
not (
      p("Early Phase Study") == "True"
   or p("Therapeutic area") == "CNS"
)

Evaluates to True when the Project Custom Property "Early Phase Study" is not set to "True" or the Project Custom Property "Therapeutic Area" is not equal to "CNS"

 
to_integer(p("Max Subject Age")) < 18

Evaluates to True when the value of the Project Custom Property "Max Subject Age" converted to an integer number is less than 18.

 
to_integer(p("Min Subject Age")) >= 21

Evaluates to True when the value of the Project Custom Property "Min Subject Age" converted to an integer number is greater than or equal to 21.

Note

The keywords: True, False, or, and, not, p, to_integer, to_float and in are all case-sensitive.

Standard Rule Types

TrialGrid defines four types of Standard Rules:

  1. Must Exist : These Rules state that an object must exist in the Study when the condition is met.

  2. Must Not Exist : These Rules state that an object must not exist in the Study when the condition is met.

  3. May Exist : These Rules state than an object may exist in the Study when the condition is met.

  4. Must Have Attribute : The Rules state that an Object attribute or Custom Property must match a certain value when the condition is met.

Must Exist Rules

When you want to ensure that a study design contains a particular object (e.g. a Form or Custom Function) a MUST EXIST rule can be defined in the library which ensures that this object exists in any study linked to the library. This is useful when you have standard forms which are used in all studies or when studies with IxRS integrations require a specific set of Forms, Fields, Custom Functions and Edit Checks. The librarian can create a set of rules in the Library which state that when the Project is an IxRS study then these objects MUST exist in a study built from or linked to this library.

Must Not Exist Rules

The opposite of Must Exist rules. Sometimes Forms or other study design objects exist in the library but there are situations where they should not be used. For example, IxRS related Forms, Custom Functions etc may not be desired in studies which do not have IxRS integration. If they are included in the study build they may match the library but they are not valid in the context of that study. In this case a set of MUST NOT EXIST rules can be created by the librarian to ensure that these objects are not used in a study built from or linked to this library.

May Exist Rules

When a study draft is linked to a library draft, compliance between the study draft and the library is calculated. If an object in the study draft is not found in the library draft then this is a deviation and it must be explained by the study builder. However, it is common to have study-specific objects such as Edit Checks, Forms and Custom Functions and some organizations may not wish to have standards managers review every object not found in the library. A set of May Exist rules can be created by the librarian to allow objects not found in the library to be automatically approved for the purposes of compliance checking. Wildcard identifiers (see below) are especially useful for May Exist rules because they allow rules to be written that match objects with any name or with a name that matches a certain pattern (e.g. object name starts, contains or ends with some set of characters).

May Exist rules are also useful for copying optional objects from a Library when creating a Draft from a library using Rules. Objects identified by May Exist rules will be copied from the library to the new Draft but they can then be deleted from the created Draft without triggering any standards compliance issues.

Must Have Attribute Rules

Although a library may contain a standard Form (or other object) some variation of the attributes of that object are expected in some circumstances. For example, some question labels may vary based on whether the study is observational vs having an active medication or for different patient populations. If MUST/MAY/MUST NOT rules determine whether an object should exist, Value Must Match rules determine what it should look like.

Standard Object Identifiers

In order to identify the study objects that Rules act upon, the Rule Identifier for the object type must be used:

Object Type

Identifier Pattern

Example

Form

FORM_OID

DM

Field

FORM_OID.FIELD_OID

DM.DOB

Folder

FOLDER_OID

SCREEN

Matrix

MATRIX_OID

BASE

MatrixFolderForm

MATRIX_OID.FOLDER_OID.FORM_OID

BASE.SCREEN.DM

Data Dictionary

DATA_DICTIONARY_NAME

SEVERITY

Data Dictionary Entry*

DATA_DICTIONARY_NAME.CODED_VALUE

SEVERITY.S

Unit Dictionary

UNIT_DICTIONARY_NAME

HEIGHT

Unit Dictionary Entry*

UNIT_DICTIONARY_NAME.CODED_UNIT

HEIGHT.CM

Custom Function

CUSTOM_FUNCTION_NAME

*AlwaysTrue

Derivation

DERIVATION_NAME

CALC_AGE

Edit Check

EDIT_CHECK_NAME

CHK AE_001

Edit Check Action*

EDIT_CHECK_NAME.ACTION_NAME (CQL)

EDIT_CHECK_NAME.CustomFunction CFNAME (CQL)

EDIT_CHECK_NAME.AddForm FORMOID (CQL)

CHK AE_001.OpenQuery (SCREEN.DM.DOB)

CHK AE_001.CustomFunction *AlwaysTrue (:DOB)

CHK AE_001.AddForm FORM001 (*.DM.DOB)

Important

[*] Some objects in Medidata Rave are allowed to contain period (.) characters. This can confuse identifiers. For example a Data Dictionary Entry coded value of "UNIT.1" in a Data Dictionary called "WEIGHTS.UNIT" might have a rule identifier like "WEIGHTS.UNIT.UNIT.1" The system cannot know if this is referring to a Data Dictionary called "WEIGHTS.UNIT.UNIT" with a Coded Value of "1" or some other combination. In this situation periods should be identified with the \ character. It would be "WEIGHTS\.UNIT.UNIT\.1".

Note

Check Actions have two forms of identifier. For:

  • CustomFunction

  • AddForm

  • MergeMatrix

  • AddMatrix

  • OldMergeMatrix

Actions a name/OID (of a Custom Function, Form or Matrix) follows the action identifier. For all other action types (e.g. OpenQuery) the Action name only appears. In all cases the CQL value should match the CQL defined for the CheckAction in the TrialGrid Edit Check editor.

Important

When two objects exist with the same identifier only the first will be imported. For example, if a Data Dictionary had two Coded values of "F" "(F/Female and F/Female (Reported)" for example then only one of these (the first in ordinal order) would be imported.

Wildcard Object Identifiers

An Object Identifier can be set as a Wildcard identifier. In this case the Object Identifier is treated as a regular expression which may match many object names, rather than a single name.

A good introduction and tutorial for learning more about regular expressions is here: https://regexone.com/ and you can test the regular expressions used by TrialGrid with the https://regex101.com/ or https://pythex.org/ websites.

Wildcard object identifier examples:

Pattern

Meaning

.*

Match any character (.) repeated zero or more times (*) so applies to all names.

DEMOG

Match the sequence of letters "DEMOG" anywhere in the object name.

This pattern would match "ABC_DEMOG_1" and "DEMOG2" as well as "DEMOG"

^DEMOG\d$

Match identifiers that start (^) with DEMOG followed by a single digit (\d) and the end of the identifier ($).

This pattern would match "DEMOG1" but not "DEMOG123"

^DEMOG\d*$

Match identifiers that start (^) with DEMOG followed by any number of digits (\d*) and then the end of the identifier ($).

This pattern would match "DEMOG1" or "DEMOG123"

^DEMOG(RAPHY)?$

Match identifiers that start (^) with DEMOG followed by RAPHY repeated zero or 1 (?) times. The braces () around RAPHY group these characters together so they can be operated on by the ?

This pattern would match "DEMOG" or "DEMOGRAPHY"

^DEMOG(1|2)$

Match identifiers that start (^) with DEMOG followed either (|) by number 1 or 2. and then the end of the identifier ($).

^DM\..*DAT$

Match identifiers that start (^) with DM followed by a period (\.). The period normally means "any character" but we want to match an actual period so the \ "escapes" this period. Then we want any number of characters (.*) ending with DAT and then the end of the identifier ($).

This pattern would match "DM.BDAT", "DM.BIRTHDAT" or "DM.VISITDAT" but not "DM.BDATE" since it does not end "DAT"

Wildcard Identifiers are useful when you want to use an object naming convention like "ends with 'DAT'" or "contains 'HIV'" to identify a set of objects and apply a rule to them without having to create a rule for every possible identifier.

Important

Wildcard checks against object identifiers are Case Insensitive. So "demog" will match "DEMOG".

Must Have Attribute rules and Wildcard Values

Must Have Attribute rules are useful when you want to ensure that an object attribute is set to some value. One of our examples was:

A Standard Library defines a Vitals Form which has a question for the subject "Height". In a neonatal study it may
be more appropriate to measure the "Length" of the subject. A Standard Rule may be defined that when the Project
Custom Property "Is Neonatal Study?" is set to "Yes" then the Question text for the Vitals HEIGHT question should
be "Length".

This rule checks that an attribute of a Field with OID "HEIGHT in the form with OID "VITALS" is always set to "Length". If the conditions of this Rule are met then standards compliance calculations will flag the VITALS Form as non-compliant if its HEIGHT question pretext is not set to "Length".

However, sometimes you may not wish to be so strict. It may be enough that the question text contains the word "Length" and we don't care if the text is "Length:", "Measured Length" or "Enter Length of Subject". Wildcards can be used in this situation also. Using the same patterns as described above for Wildcard Object Identifiers we can enter a pattern of "Length" (meaning match any string containing the characters "Length") and check the "wildcard" checkbox for the attribute.

Important

Wildcard checks against attribute values are Case Sensitive. So Length will not match "length".

Rule Priorities

Each standard Rule has a priority associated with it. The lower the number, the higher the priority of the Rule. A Rule with priority 1 will be applied in preference to a rule with priority 99.

For example, imagine two rules:

RULE A : When p("Uses IxRS") == "True" Form "IXRS" MUST EXIST in the Study (Priority 2)

RULE B : When p("Study Phase") == "I" Form "IXRS" MUST NOT EXIST in the Study (Priority 1)

In the case where the Project custom property "Uses IxRS" is set to "True" and the Project custom property "Study Phase" is set to "I" then these rules are in conflict, Rule A says that IXRS form must exist and rule B says it must not. In this case RULE B wins because it has a priority of 1 which makes it more important than RULE A. If both rules had the same priority then the MUST EXIST (Rule A) rule would win because the system chooses the MUST EXIST rule when MIST EXIST and MUST NOT EXIST rules have the same importance.

Generating a Draft from Library Rules

The Standard Rules in a Library define what objects should and should not exist in a Study Draft and what their attribute values should be given a set of Project-level settings defined as Custom Properties.

From the Draft List page for a Project the "New Draft From Library" button allows a Draft to be generated from a Library and its Standard Rules based on the settings of the current Projects custom properties.

For example, if a URL has a set of Custom Properties set for the Project attributes:

  • Therapeutic Area (CNS, HIV etc)

  • Study Phase (Phase I / Phase II / Phase III etc)

  • IxRS Integration (Yes/No)

Then the user setting up the Project will select the appropriate values for this Project.

A Library Draft containing standard objects (Forms, Custom Functions, Data Dictionaries etc) may have a set of Standard Rules which match the Project settings. e.g. A Standard Rule which says when a Project Study Phase is Phase I then the PK Form MUST EXIST in this Project.

When creating a Draft from a Library TrialGrid looks at the settings of Custom Properties on the Project the new Draft is being created in. These settings activate (or de-activate) Rules in the Library selected. For example, if the Project Study Phase is "Phase I" then the Rule described above would be activated and the PK Form would be copied into the new Draft because "PK Form MUST EXIST when Study Phase is Phase I".

How Standard Rules are resolved on Draft Creation

When creating a Draft from a Library TrialGrid identifies all the Standard Rules which are activated by the current Project settings. This is a collection of Standard Rules which state that an object must or must not exist or that some attribute of the object should be changed (e.g. to activate or inactivate it, to change question or query text etc)

For each object targeted by a Must Exist rule TrialGrid determines if the set of rule activations should allow this object to be created in the Draft. The highest priority rule between the Must Exist and Must Not Exist rules wins.

For example. There might be a set of Standard Rules in the Library Draft to copy from:

RULE A : When True Form "DM" MUST EXIST in the Study (Priority 99)

RULE B : When p("Therapeutic Area") == "HIV" Form "DM" MUST NOT EXIST in the Study (Priority 1)

RULE C : When p("Therapeutic Area") == "HIV" Form "DM_HIV" MUST EXIST in the Study (Priority 1)

If the Project has Therapeutic Area set to "HIV" then TrialGrid will not create the DM Form but will create the DM_HIV Form.

Explanation:

RULE A states that the DM Form MUST EXIST for all Studies but RULE B is also activated because the Project has Therapeutic Area = "HIV".

Rule B states that the Form DM MUST NOT exist so RULE A and RULE B are in conflict.

Since RULE B has a Priority of 1 (high priority) and RULE A has a Priority of 99 (lower priority) RULE B wins and the DM Form is not created.

RULE C ensures that the Form DM_HIV is created in the study.

Note

If two (or more) Must Exist / Must Not Exist Rules conflict and have the same priority then the Must Exist Rule will be selected.

Once an Object is selected to be copied from the Library Draft TrialGrid looks for Must Have Attribute Standard Rules which may modify the attributes of that Object. For example, the Help Text of the Form might be changed depending on the Phase of the study.

Note

Wildcard Must Have Attribute rules are ignored when creating a Draft from a Library in this way because these rules are used to check values, not to set them. For example, if the Wildcard rule says the Attribute must match a pattern of 3 letters followed by a number, the system can't know what actual value to enter.

Child-objects are also copied so when a Form is copied then each of the Fields within the Form is also copied unless there is a Must Not Exist rule specifically targeting that Field. As each Field is copied, rules for each Field are also examined.

Related objects are also copied and change rules applied to them. If a Field is copied then any associated Data Dictionaries or Unit Dictionaries are also copied.

Must Exist rules on Child Objects

Generally Must Exist Rules should be provided for top-level objects such as Forms, Matrices, Data Dictionaries etc. Importing an object also ensures that its child objects are also imported (unless they have specific Must Not Exist rules).

However, it is possible to state Must Exist rules for Child Objects such as the Fields in a Form. If a Must Exist Rule appears for a child object then this in turn will cause the import of the parent object. In this way the import system traverses from child to parent and then back down again through the children of that parent. For example, if FieldA in a Form1 has a Must Exist Rule then Form1 will be imported along with all the other Field children of Form1 (unless there is a Rule that explicitly states that a particular Field MUST NOT exist).

Important

If there is a Must Exist Rule on a Child Object and a Must Not Exist Rule on the Parent Object then the import of the Child Object is cancelled. However, any related objects to the Child Object may still be imported. For example, FieldA has a Must Exist Rule. Its parent FORM1 has a Must Not Exist Rule. FieldA will not be imported. However, if FieldA has a related DataDictionary then that Data Dictionary will be imported.

Steps in the Import Process

When creating a Draft from a Library via Standard rules the system follows this process:

  1. Identify all the rules in the Library Draft that evaluate True for the current Project settings.

  2. Expand all the Wildcard Object identifier rules into individual rules by finding all objects in the Library draft which match the rules. For example a Rule "Forms with OID ^VITALS(1|2|3)$ MUST NOT EXIST" will search the library for all forms which match this pattern. If forms VITALS1, VITALS2, VITALS3 and VITALS4 exist then this will match for VITALS1, VITALS2 and VITALS3 and the wildcard rule will be turned into 3 fixed rules:

    • "Forms with OID VITALS1 MUST NOT EXIST"

    • "Forms with OID VITALS2 MUST NOT EXIST"

    • "Forms with OID VITALS3 MUST NOT EXIST"

    In this way a single wildcard rule can be expanded into several fixed rules before processing.

  3. Process the active Must Exist rules in the following order, omitting elements with Must Not Exist rules and applying changes to attributes defined by Must Have Attribute rules

    1. Data Dictionaries

    2. Data Dictionary Entries

    3. Unit Dictionaries

    4. Unit Dictionary Entries

    5. Folders

    6. Custom Functions

    7. Forms

    8. Fields

    9. Matrices

    10. Derivations

    11. Derivation Steps

    12. Checks

    13. Check Steps

    14. Check Actions

    15. Matrix Folder/Forms

    16. Custom Properties of Objects

At the end of this step of the process the new draft will be populated with Forms, Fields, Folders and other objects but to avoid the need to create Must Exist rules for every object the system then tries to find objects in the library which are related to what has already been populated but which have not themselves been copied over.

It performs two further steps:

  1. Examine all Matrices in the Library Draft. Any which contain a Folder/Form combination which are already in the new Draft are copied over along with those combinations. For example, if FORM1 and FOLDER1 have been copied to the new Draft via Must Exist rules but Matrix MATRIX1 has not been copied over. MATRIX1 contains two folder/form combinations FORM1/FOLDER2 and FORM1/FOLDER1. In this case FORM1 and FOLDER1 exist in the new Draft and so MATRIX1 will be copied over with the FORM1/FOLDER1 combination. The MATRIX1 copy in the Draft will not include the FORM1/FOLDER2 combination because FOLDER2 was not found in the new Draft.

  2. Examine all Edit Checks in the Library Draft. If the Edit Check steps and actions ALL reference Folders/Forms/Fields which exist in the new Draft then the Edit Check will be copied over to the new Draft. Note that this does not include Edit Checks with AddForm, AddMatrix and MergeMatrix actions where the target of the action does not already exist in the new Draft because including these would require copying in the related Form or Matrix which would require further analysis for their related Edit Checks etc.

  3. Examine all Derivations in the Library Draft. If the Derivation target and steps ALL reference Folders/Forms/Fields which exist in the new Draft then the Derivation will be copied over to the new Draft.

These steps exist to reduce the number of Must Exist rules that would otherwise have to be written to ensure every Matrix, Edit Check and Derivation is copied over.

At the end of this process, all selected objects are copied to the new Draft.