OpenClinica User Manual/Writing rules

Recent improvements in rule assignment

As of version 3.1.x, OpenClinica allows rules with relative paths that can be assigned to every instance of a given CRF. Previous versions (3.0.x and earlier) required rules to be assigned to each Event and CRF, so a greater number of assignments had to be created and tested.

Writing Rules

• In rules, the operators ‘ne’,’eq’ etc. and the logical operators ‘and’ and ‘or’ are case sensitive (so writing rules containing ‘AND’ or ‘EQ’ results in errors).

• There are bugs in Openclinica when using brackets in rule expressions - the error "OCRERR_0006 : Syntax Error, Missing right parenthesis." occurs when a "variable name is immediately adjacent to the right-hand bracket", see https://issuetracker.openclinica.com/view.php?id=4195#bugnotes

• Note that you don’t need to specify a specific version of a CRF in a rule, you can miss off ‘_V1’ from the target CRF end, references to F_LIRAGLUTIDE_V1 can be changed to F_LIRAGLUTIDE.

• Numeric comparisons between field may only be performed where both fields are numeric - e.g. a string field that frequently contains a number can't be compared with a numeric field. e.g. Trying to use the lte operator with a string and numeric field results in the error: 'OCRERR_0001 : Logic Error, ITEM_NAME and null cannot be used with the LESS_THAN_EQUAL operator.'

• For rules on repeating group items, ensure in the target you specify either the integer row number or the keyword '[ALL]', as per the creating rules documentation, e.g. F_BCFALLSDIARY.IG_BCFAL_FALLSDIARY[ALL].I_BCFAL_QSFALLS

Testing Rules

Rules are more complex to test than ranges as there are frequently more than one per CRF section, and they may need to be tested one at a time, and in several ways.

When testing rules, discrepancy notes are only created if the rule triggers, and then Save is pressed with the rule still triggered (the data not corrected).

The time taken to test can be reduced if care is taken when writing test documents to:

1. Avoid triggering rules the second time
2. Ensure that a rule on a different field is triggered when save is pressed the second time

If you follow these guidelines, every time that Save is pressed, a new rule is triggered and tested.

How to do this:

1. Set up the a rule on one field in a section to fail, then press save
2. Alter the data to ensure the rule on the first field doesn't trigger again, and alter data so that a rule on a second field triggers
3. Press save again - the first rule wasn't triggered, so no discrepancies will be created, and a second rule is triggered, so the section doesn't change.

Reusing Rules and Tests

If we use standardised CRFs (Standards), we can also re-use standardised rules and tests for them.

Errors during testing

There are a number of errors that may be seen during testing rules.

Incorrect group

This error appears in the stdout_*.log when a rule has been triggered (the browser shows the OpenClinica Generic Error page), but the target is incorrect, and contains the wrong group:

java.lang.NullPointerException
	at org.akaza.openclinica.logic.rulerunner.RuleRunner.prepareEmailContents(RuleRunner.java:120)

e.g. Set as: SE_BC1VISIT.F_BC1VISIT.IG_BC1VI_UNGROUPED.I_BC1VI_TIABLCON Rather than: SE_BC1VISIT.F_BC1VISIT.IG_BC1VI_INCLUSIONCRITERIA.I_BC1VI_TIABLCON