There are two main types of rules that Data Managers can create:

• EventAction rules automatically schedule events
• NotificationAction rules automatically send notifications by email or SMS

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 in the table below. You cannot be written based on an event being Removed or Archived.

Despite the use of the new data model, with Statuses and Independent 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 Study Runner.
2. Select Rules.
   1. The Rules option does not display when logged in at the Site level. Change to Study level to see the Rules option.

Step 2: 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 BBEdit for Mac.

Note: The Rules Template file contains instructions that are bracketed by “<!– ” and “–>“. These instructions can be left in in the file, as they will not affect the functionality of the rule. However, they can also be removed in order to make the file easier to read.

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 the lines starting from <NotificationAction > to </NotificationAction> tags. 
• If you are making a NotificationAction rule, delete the lines starting from <EventAction> to </EventAction> tags. 

Step 6: Define the Target.

The target is the trigger condition – any time a value changes, the rule evaluates the target. The two supported trigger conditions are as follows.

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

First, remove the text “Context=”OC_RULES_V1“.

Between the > and <, enter the trigger condition, including the actual Event OID for the event whose status or start date updates should trigger the rule:

• [SE_EVENTOID].STATUS if you want the rule to trigger when the [SE_EVENTOID] status changes
• [SE_EVENTOID].STARTDATE if you want the rule to trigger when the [SE_EVENTOID] start date changes.

(Optional): If you want the rule to run at a certain time, use the RunOnSchedule tag. Specify the time in 24-hour format UTC and remove the “<!– ” and “–>” text.

Step 7: Define an OID for the rule.

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

Step 8: Enter the expression.

Expressions are the conditions that cause the rule to run. There are two types of actions: Event Action and Notification Action.

1. Event Action
   1. IfExpressionEvaluates: Define as “true” or “false”, meaning that if the rule action will only occur when the expression you define matches (“true”) or does not match (“false”).
   2. OID: Replace “Target_Event_OID” with the Study Event OID for the event that will be scheduled by this rule.
   3. RunOnStatus: If you want the rule to run only when the target event is at specific status, specify all of the statuses as true or false. For a repeating event, specify the ordinal in square brackets. For ex. SE_DAILYDIARY[1].
      1. For example, if it is a scheduling rule, you would likely only want the rule to run when the event has a status of “not_scheduled”.
   4. EventDestination: STARTDATE. Legacy rules can only schedule events, and not advance them through the workflow.
   5. ValueExpression: Remove Context=”OC_RULES_V1″ and enter the expression whose result should be entered into the EventDestination property of the event. For example, in the example below (SE_ENROLLMENT.STARTDATE +7. ), the EventDestination property that will be set to the start date of the Enrollment event plus 7 days.         
   6. Note: See syntax below, in the tables
2. NotificationAction:  
   1. IfExpressionEvaluates: Define as “true” or “false”, meaning that if the notification will be sent only when the expression you define matches (“true”) or does not match (“false”).
   2. To: Specify the recipient(s) by replacing user1@openclinica.com with:
      1. A comma separated list of email recipients, if the notification always needs to be sent to the same individuals / group of individuals.
      2. ${participant}, if the notification needs to be sent to the email address and phone number that have been entered into OpenClinica for the Participant. Can only be used if OpenclinicaParticipate is active.
   3. Subject: Enter the subject line for the notification. 
   4. Message: Define the message that will be sent to recipients. 
   5. Note: For details of the parameters that can be used within the Subject and Message tags, see the table Notification Action Parameters table below.

Step 9: Enter the information about the rule itself.

1. RuleDef: Enter the same Rule OID as you entered in the RuleRef tag above, and add a name for the rule as well.
2. Description: Describe the rule in simple terms so that it is easy to understand what the rule is doing.
3. Expression: Enter the condition that will trigger the rule to run.                              
4. Note: See syntax below, in the tables.

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

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

Step 12: Click Choose file, and select a file to upload. Then click the Continue button. If any errors are identified within the rule XML, address them and upload the file again.

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.

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

4. Specify test values for variables in your rule expression.
5. Click the Validate & Test button again.
6. 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

Icon	Action	Description
	View	View the rule information, such as Target OID, Study Event Definition, CRF Name, etc.
	Remove	Remove the rule
	Download	Download the rule
	Test	Test to ensure that the rule works

 

Rule Components

Rule Component	Description
RuleDef	The rule definition, which includes the rule OID, name, description, and expression. This defines the rule, which is then assigned (referenced) in the RuleRef.
RuleRef	The 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 actions and ActionTypes.
RunOnStatus	For 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.
Target	The target is the event that when changed, causes the rule to be evaluated. The legacy rule can be triggered on EVENT.STARTDATE or EVENT.STATUS.
RunOnSchedule	This 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 hour in the UTC time zone and may trigger then if the expression is true. Notes: When minutes are documented in the scheduled time, they are ignored. For example, if a rule is defined to run at 17:30 UTC, it will be queued up for processing with all rules defined to run between 17:00 UTC and 17:59 UTC. The system will start processing rules on the hour (00), but it may take longer to process all rules depending on factors such as complexity of rule logic and number of rules and participants in the study. Each target must use the same RunOnSchedule configuration. If multiple rules using the same target are uploaded with different RunOnSchedule configurations, the system will take on the RunOnSchedule property of the latest upload for all rules using this target. Two targets are possible per event: EVENT.STARTDATE and EVENT.STATUS. Examples: SE_EVENT1.STATUS with <RunOnSchedule Time=”06:00″> and SE_EVENT1.STATUS with <RunOnSchedule Time=”15:00″> Χ SE_EVENT1.STATUS with <RunOnSchedule Time=”06:00″> and SE_EVENT1.STATUS with RunOnSchedule not included Χ SE_EVENT1.STATUS with <RunOnSchedule Time=”06:00″> and SE_EVENT1.STARTDATE with <RunOnSchedule Time=”15:00″> √
EventAction	Defines: Whether the rule will evaluate based on the expression matching (“true”) or not matching (“false”). The Event OID of the target event that will be scheduled by the rule.
EventDestination	Must be set to STARTDATE.
ValueExpression	A calculation or other expression that defines what will be populated in the EventDestination.
Expression	The expression that will trigger the rule to run.

 

Expressions

Expression	Definition	Variable Type
eq	Equal to	Any
ne	Not Equal to	Any
ct	Contains	Any
gt	Greater Than	Number
gte	Greater Than or Equal to	Number
lt	Less Than	Number
lte	Less Than or Equal to	Number

Example:

SE_ENROLLMENT.STATUS eq “completed”

Conditional Operators

Operator	Function	Description
and	And	Variables used with this operator should be of a boolean type
or	Or	Variables used with this operator should be of a boolean type

Example:

SE_SCREENING.STARTDATE lte _CURRENT_DATE and SE_SCREENING.STATUS ne “completed”

Arithmetic Operators

Operator	Function	Description
+	Addition	Variables used with this operator should be of a number type
–	Subtraction	Variables used with this operator should be of a number type
*	Multiplication	Variables used with this operator should be of a number type
/	Division	Variables used with this operator should be of a number type

Example:

SE_ENROLLMENT.STARTDATE + 7

Dates within Rules: Equality and Relational Operators

Expression	Definition	Full Expression
eq	Equal to	SE_EVENTOID eq 2025-01-15
ne	Not Equal to	SE_EVENTOID ne 2025-01-15
gt	Greater Than	SE_EVENTOID gt 2025-01-15
gte	Greater Than or Equal to	SE_EVENTOID gte 2025-01-15
lt	Less Than	SE_EVENTOID lt 2025-01-15
lte	Less Than or Equal to	SE_EVENTOID lte 2025-01-15

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

Rule Examples

Schedule Day 7 Questions event for 7 days after the Baseline Questions event is marked as complete.

Notify participant that the Baseline Questions event is available when the current date is equal to or past the event start date. The notification will be sent every day at 09:00 UTC until the event is marked as complete, skipped or stopped.

Notify participant that Day 7 Questions event is available when the current date is before or equal to STARTDATE and the event has been scheduled.

When the Baseline visit has been completed, schedule both Visit1 and Visit 2, as well as notify a user that Baseline has been completed.