Definition: A rule is a logical expression used to automate a task.

Examples:

  • A rule might be used to automatically schedule an event when the Enrollment event has a status of completed.
  • A rule might be used to notify participants about forms that are due when using OpenClinica Participate.

Data Managers can create rules to automatically schedule events (EventAction) or automatically send notifications by email or SMS (NotficationAction).

You can download the Rules Template and edit it to create a rule to perform either an EventAction or a NotificationAction.

Note: You can only write rules based on the statuses of Not Scheduled, Scheduled, Data Entry Started, Completed, Skipped, Stopped, Signed, and Locked. You cannot be written based on an event being Removed or Archived.

Despite the use of the new data model, with Statuses and Indepent Status Attributes, rules that use the old data model will still work correctly. 

Quick Start Guide

To Create a Rule:

Step 1: Access the Manage Rules screen.

  1. Click Tasks in the header bar of Runtime.
  2. Select Rules.

Step 2: To Download the Rules Template.

Click the Download Rules Template link at the top of the table.

Step 3: Open the Rules Template in an XML editor, such as Notepad ++ for Windows or TextWrangler for Mac.

Step 4: Find and record OIDs to reference Events and Forms.

  1. Click Tasks in the header bar of Study Runner, and select View Study.
  2. Click the Download the Study Metadata link at top of the screen and record OIDs, or scroll down on the screen and record OIDs from there.

See Locate Object Identifiers in a Study for more information on finding OIDs.

Step 5: In the Rules Template, delete any actions you do not want the rule to perform.

  • If you are making an EventAction rule, delete everything between the EventAction tags.
  • If you are making a NotificationAction rule, delete everything between the NotificationAction tags.

Step 6: Define the Target.

Any time a value changes, the rule evaluates the target. For example, you can use:

  • Event Status: SE_EVENTOID.STATUS
  • Event Start Date: SE_EVENTOID.STARTDATE

Step 7: Define an OID for the rule.

It must be entered in all capital letters. You can include numbers and underscores. It must be unique within the study and can only be 40 characters long.

(Optional): If you want the rule to run at a certain time, specify the time in 24-hour format.

Step 8: Enter the expression.

Expressions are the conditions that cause the rule to run.

Event Action: If you want the rule to run when the event reaches a certain status, specify all of the statuses as true or false.

NotificationAction: Specify the recipient(s), subject of the notification, and message next to the corresponding tags. You can include multiple email addresses separated by commas. To use this rule, Openclinica Participate must be actived.

Note: See syntax below, in the tables.

Step 9: Make sure all tags are closed, and save the file as an XML file.

Step 10: Click the Add Rules link at the top of the Manage Rules screen.

Step 11: Click Choose file, and select a file to upload. Then click the Continue button.

To View a Rule:

Click the View button next to the rule you want to view.

To Remove a Rule:

Click the Remove button next to the rule you want to remove.

To Download a Rule:

Click the Download button next to the rule you want to download.

To Test a Rule:

  1. Click the Test button next to the rule you want to test.

  1. Check that the Target, Rule Expression, and Actions are displayed correctly on the screen.
  2. Click the Validate & Test button.

  1. Specify test values for variables in your rule expression.
  2. Click the Validate & Test button again.
  3. Review the results of the test. On the left-hand sidebar under Alerts & Messages, you will see a statement about whether the test was valid or invalid. Scroll down to Verify results for more details.

Actions

IconActionDescription
ViewView the rule information, such as Target OID, Study Event Definition, CRF Name, etc.
RemoveRemove the rule
DownloadDownload the rule
TestTest to ensure that the rule works

Rule Components

Rule ComponentsDescription
RuleDefThe rule definition, which includes the rule OID, name, description, and expression. This defines the rule, which is then assigned (referenced) in the RuleRef.
RuleRefThe rule definition/expression being used by the assignment is referred to in the RuleRef. This is an OID for the particular RuleDef. Each RuleRef may have multiple ActionTypes.
RunOnFor all actions except EventAction, the parameter that defines when the ActionType will execute. The current phases include InitialDataEntry, DoubleDataEntry, AdministrativeEditing, and Batch.
RunOnStatusFor EventAction, the parameter that defines when the EventAction will execute. The current status values include not_scheduled, scheduled, data_entry_started, completed, skipped, and stopped.
RunOnScheduleThe Rule Def expression will be evaluated and triggered the first time it becomes true based on a change of event status or other component of the expression. The rule will also be evaluated daily at the set time and may trigger then if the expression is true.
TargetThe target is the item where an action will be fired. This is a single item in a CRF. When this item is encountered in the CRF and the user selects the Save button, the system will execute the actions associated with a rule.
ValueExpressionA calculation or other expression that defines what will be populated in the DestinationProperty (for an InsertAction) or EventDestination (for an EventAction).

Expressions

ExpressionDefinitionVariable Type
eqEqual toAny
neNot Equal toAny
ctContainsAny
gtGreater ThanNumber
gteGreater Than or Equal toNumber
ltLess ThanNumber
lteLess Than or Equal toNumber

Example:

SE.ENROLLMENT.STARTDATE eq completed

Conditional Operators

OperatorFunctionDescription
andAndVariables used with this operator should be of a boolean type
orOrVariables used with this operator should be of a boolean type

Example:

CURRENT_DATE -1 and SE.SCREENING.STATUS ne completed

Arithmetic Operators

OperatorFunctionDescription
+AdditionVariables used with this operator should be of a number type
-SubtractionVariables used with this operator should be of a number type
*MultiplicationVariables used with this operator should be of a number type
/DivisionVariables used with this operator should be of a number type

Example:

SE.ENROLLMENT.STARTDATE + 7

Dates within Rules: Equality and Relational Operators

ExpressionDefinitionFull Expression
eqEqual toITEM_OID eq 2008-12-12
neNot Equal toITEM_OID ne 2008-12-12
gtGreater ThanITEM_OID gt 2008-12-12
gteGreater Than or Equal toITEM_OID gte 2008-12-12
ltLess ThanITEM_OID lt 2008-12-12
lteLess Than or Equal toITEM_OID lte 2008-12-12

The format of the date included in an expression should be yyyy-MM-dd.

Example:

January 01, 2020 should be written as: 2020-01-01

You can also use _CURRENT_DATE to compare values against the current server date.

For example, with a NotificationAction, to notify Participants of a Form that must be completed on the next day, you could use an expression such as:

<Expression>SE_OID.STARTDATE eq (_CURRENT_DATE +1) and SE_OID.STATUS ne “complete”</Expression>

This would send a notification one day in advance of the expected form completion date as long as the form was not already completed by the Participant.

Notification Action Parameters

ParameterDescriptionToMessageSubject
${participant.firstname}The Participant First NameX
${participant.loginurl}The Participant URL with Automatical LoginX
${participant.url}The Participant URL without Automatic LoginX
${study.name}The Name of the Study, as Defined in OpenClinicaXX
${participant.accesscode}The Single-Use Code the Participant Must Use to Access OpenClinica ParticipateX
${event.name}The Name of the Event, as Specified in OpenClinicaXX
${participant}The Participant Contact Information, as Provided When the Participant was Connected to the Study. (This Could be a Mobile Number for SMS Notification, an Email Address, or Both); OpenClinica Automatically Sends the NotificationX
${participant.id}Participant IDXX
${site.id}Site IDXX
${site.name}Site NameXX
${study.id}Study IDXX
/nUse at the End of a Line for a LinebreakX

For example, the following rule will send a notification to any Participant who has an Event scheduled for the following day:

Notice that the Rule Expression uses _CURRENT_DATE and compares it to SE_INITIALTREATMENT.STARTDATE to determine that the Event is scheduled for the next day. (In other words, if TODAY is equal to the day BEFORE the visit and the status is not yet completed, send a notification.

If you want to send a reminder one day AFTER the visit, you would use _CURRENT_DATE eq SE_INITIALTREATMENT_STARTDATE +1, meaning that the rule will trigger if _CURRENT_DATE is one day AFTER the visit was scheduled and the status is not yet completed.)