a rule to show a group

In this short page we will discuss a very common situation. Consider the following CRF in which medication is recorded. First of all the so-called indicator question is asked Was any medication used in the previous 12 months?

fig. 1: CRF for medication history

To minimize dataentry-errors we would like to hide the repeating-items group and only show it, after the first question has been answered with Yes. This is done by creating a Rule-file with a ShowAction.
Let's take this step by step and the first thing to do is create and upload the CRF. Click here for the CRF plus the XML-file.
As you can see in the tab Groups we defined the Group_Display_Status as HIDE in column F.

fig. 2: the group is not shown by default

When we open this CRF for dataentry, only the indicator question is shown.

composing the rule-file

What we need to do next is create a Rule file that will show the Group Medication when the answer to the indicator question is Yes. And to do this we need the OIDs of all the objects concerned. Take a look at this page for instructions on how to get them. For reference it is nice to have these OIDs in the header of our Rule file, so after some searching this should look like this:

fig. 3: the OIDs

In this documentation part of the Rule-file, we see the OID for the Event and the CRF. Then we have two OIDs for ItemGroups: one for the ItemGroup to which the indicator-question belongs and one for the ItemGroup we want to show.

Now we are ready to write our expression and that will be I_TDSSH_MEDUSED eq 1, because Yes was coded as 1. As you can see, the Expression is part of the so-called RuleDef, short for RuleDefinition. We give our RuleDef an OID, so we can later refer to it. You can use anything for this RuleDef-OID, but it must be unique for your Study. You might be tempted to call this rule Rule1 or something like that, but be careful with such OIDs: it's easy to forget you already had a Rule23 three weeks ago, so instead of creating a new Rule, you are overwriting an existing one. An easy trick to avoid this is using something unique, like the ItemOID of the target of your RuleAssignment. Now because all OIDs in OpenClinica have a prefix that indicates the type of object, we start our RuleOID with R_, followed by the ItemOID. And to avoid further confusion when we need more than one Rule associated with the same Target, we add a counter to the RuleOID. This sums up to R_I_TDSSH_MEDUSED_1 in our example. Finish this part with a short name in the list of Rules and a long description to explain the why and how of this ShowAction.

fig. 4: the RuleDef with the expression

some action please

So now we have the expression right: if the answer to "was any medication used in the previous 12 months" is "Yes", then we want a ShowAction. First of all we have the target, in this case R_I_TDSSH_MEDUSED_1: whenever this Item is changed, the associated expressions will be evaluated. Another way of saying this "this target refers to the following RuleDefs", or in XML <RuleRef OID="R_I_TDSSH_MEDUSED_1">
And what should be the result of the evaluation of the expression of the RuleDef? We want a ShowAction, but only if the expression evaluates to true:
<ShowAction IfExpressionEvaluates="true">
Of course we must say what we want to show, or: what the DestinationProperty of our ShowAction is.
(Excuse us: DestinationProperty? Where did that come from? Wouldn't Target be more appropriate? Maybe, but that term is already in use.)
In our case the DestinationProperty of the ShowAction is the ItemGroup with OID IG_TDSSH_MEDICATION and our RuleAssignmentnow looks like this:

fig. 5: the RuleAssignment

and it looks like ...?

The result is quite good: you start with:

fig. 6: what is your answer?

And then when you've clicked Save you get:

fig. 7: the result of the ShowAction

three more things

You may have noticed that we did not discuss one line, the one with the Run-tag. What this line does it that it defines at which occasions the Action must be performed.
And you will probably wonder if we can use a corresponding HideAction, like we did on this page. Unfortunately the answer is: not yet. You can only Show hidden Groups, but you can not Hide shown Groups.
And you may think "mmm, we defined the GROUP_REPEAT_NUMBER as 5, but I only see 1 row" and yes, you are right: this is a bug.

Other how-to-pages can be found here.

this page was last reviewed August 2014