6.4 Creating Rules

Simple single-field validation checks can be created within the CRF Template or by writing a Rule. More complex edit checks that compare values across fields, across forms, or across Events can only be addressed by writing a Rule. Rules are written in XML and then uploaded into OpenClinica. You can also use OpenClinica's Rule Designer, an XML code generator, to create your Rules.

Before writing a Rule, you should have an idea of what you want that Rule to do. For example, if date of drug administration is less than the date of informed consent, you'd like the Rule to create a Discrepancy Note.

We'll use this example to step through the process of writing a Rule.

To create a Rule using XML:

  1. As a user with a Data Manager or Study Director role, Go to Tasks > Build Study and look up the OIDs for the Study Events, Forms, Item Groups, and Items that will be used in the Rule.

    In our example Study, the following OIDs apply:

  2. Go to Tasks > Build Study, and on the Create Rules row of the Tasks table, click .

    The Import Rule Data screen displays.

  3. Click the All Actions Without Comments link and open the file in an XML editor.

    Free XML editors (such as Notepad++ for Windows or TextWrangler for Mac) are available on the internet. Be sure to open the file in an XML editor; if you edit the file in a browser, the Rule will not upload properly.

    The Rule Template, which contains all possible Rule Actions, displays:

  4. To save the template, click File>Save As and provide a file location and name for the Rule.
  5. Once the Template is saved, there are 5 steps to writing the Rule:
    • Delete the actions you don't want the Rule to perform.
    • Identify the Target.
    • Determine if you want the Rule to run on a specified schedule once per day (currently recommended for Notification Action Rules only; for other Rule Actions, carefully consider the impact of scheduling multiple rules to run on a schedule - and managing that schedule. For example, if you set all your Rules to run at 17:00 hours, performance may be impacted. However, if you have a particularly large form with many Rules associated with it, it may be better to schedule those rules to run on a schedule to increase performance during data entry.)
    • Define the Rule (RuleDef)
    • Reference the Rule (RuleRef)

    Delete the Actions You Don't Want the Rule to Perform
    In the Rule Assignment portion of the template, delete the lines for the actions that you don't want. For information see Rule Action Types.

    For our Discrepancy Note example, the resulting template would be as follows:

Identify the Target

Place the cursor between the opening and closing tags of the Target and provide the OID for the Target of the Rule. For a Discrepancy Note action, the Target is the Item that will be flagged with a Discrepancy Note if a specified condition is met.

In our example of checking Drug Administration Date against Informed Consent Date, the Target is the Drug Administration Date because it is the second item value entered. The system would not know of an issue with these two items until that value is entered. Since these dates occur on different Events, the Target must begin with the Study Event OID and finish with the Item OID as follows:

Determine if You Want the Rule to Run on a Specified Schedule
Rules will run automatically during data entry when the user clicks Save. If you want your Rule to run at a specified time each day, you can specify that time in the RunOnSchedule tag.

With the setting highlighted above, the Rule will run at 17:00 hours (5:00pm) every day. The time must be entered in 24-hour format (00:00 to 23:59), though OpenClinica will only run the Rule based on the hour values provided. For example, if you specify 17:30, the Rule will run at 17:00.

If the time is left blank, the Rule will run at 20:00. If you remove the parameter completely, the Rule will run based on its run parameters only and will not run on a schedule.

RunOnSchedule is particularly useful for running a Rule based on OpenClinica Participate data since edit checks are limited for Patient Reported Outcome data during data entry. OpenClinica uses the Participant local date-time for RunOnSchedule execution when the Participant local date-time is available. Otherwise, the server date-time is used.

Define the Rule (RuleDef)

In the RuleDef portion of the Template, define the Rule Expression. This is the condition that will trigger the Rule to fire. Mathematic operators and logical operators can be used in the Rule Expression. For more information, see Expression Element.

The Rule Expression is always relative to the Target. Once the full Target is defined, you only need to provide the Item-level reference for the Target, but when referencing any Item outside of that Form and/or Event, the full path for the Item must be provided.

For our example, the Expression is:

I_ADMIN_DT lt SE_REGISTRATION.F_CONSENT.IG_INFORMEDCONSENT.I_CONSENT_DT

Once the Expression is written, the rest of the RuleDef is a matter of entering text to help identify and describe the Rule, as follows:

Description: A clear, concise explanation of what the Rule is doing. This is presented to users who view Rules using Task>Monitor and Manage Data>Rules, and is only displayed if the user clicks Show More.

Name: A very brief explanation of what the Rule is doing. This is presented to users who view Rules using Task>Monitor and Manage Data>Rules.

OID: The user-defined unique identifier for the Rule. This must be entered in all capital letters and can only contain letters, numbers, and underscore. It must be unique within the Study and can be no more than 40 characters.

For our example, the resulting Rule would be as follows:

 

Reference the Rule (RuleRef)

In the RuleRef portion of the Template, reference the Expression you wrote in the RuleDef and execute the Rule.

Copy the OID of the Rule that you created in the RuleDef portion of the Template into the RuleRef OID.

In our example it would appear as follows: <RuleRef OID="I_ADMIN_DT_R1">

Identify when the Rule should run as follows:

A Rule Expression can either evaluate to true or false. It is best practice to write your Rules to trigger when the expression evaluates to true. There will be times when you will need to write Rules to evaluate to false, but that should be the exception.

For our example, if the Expression is true, a discrepancy note should be created. As such, ensure the first line of the DiscrepancyNoteAction tag is as follows: IfExpressionEvaluates="true" Note that "true" must be in lower case.

The <Run> tag allows you to specify when you want the Rule to be executed. For each option specify true or false (must be in lower case).

For a DiscrepancyNoteAction, you must specify the message that the data entry person will see if the Rule is triggered. Type that message between the opening and closing <Message> tags.

For our example, the RuleRef (and the completed Rule) would be as follows:

 

Functional approval by Laura Keita (lkeita), Director of Training and Compliance. Signed on 2017-08-10 4:42PM

Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2017-08-10 5:07PM

Not valid unless obtained from the OpenClinica document management system on the day of use.