14 Rules

Overview

 

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

 

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

 

User Role(s) That Can Perform this Action: Data Managers

 

Workflow: This an optional feature but can improve efficiency.

 

Example Use Cases:

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

 

Description: 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 Runtime 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. 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. 

 

These 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”.

 

See table below for syntax.

 

 

 

 

 

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, Participate must be actived.

 

See table below for syntax.

 

 

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 remove.

 

 

 

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.

 

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

 

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 ActionTypes.

RunOn = For all actions except EventAction, the parameter that defines when the ActionType will execute.  The current phases include InitialDataEntry, DoubleDataEntry, AdministrativeEditing, and Batch.

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.

RunOnSchedule = The 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.

Target = The 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.

ValueExpression = A calculation or other expression that defines what will be populated in the DestinationProperty (for an InsertAction) or EventDestination (for an EventAction).

 

Expressions

 

The Equality and Relational Operators

eq      

Equal to

Variables used with this operator could be of any type

ne

Not Equal to

Variables used with this operator could be of any type            

ct

Contains

Variables used with this operator could be of any type

gt

Greater Than

Variables used with this operator should be of a number type

gte

Greater Than or Equal to          

Variables used with this operator should be of a number type

lt

Less Than

Variables used with this operator should be of a number type

lte

Less Than or Equal to

Variables used with this operator should be of a number type

 Example: SE.ENROLLMENT.STARTDATE eq “completed”

 

The Conditional Operators

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: CURRENT_DATE -1 and SE.SCREENING.STATUS ne “completed”

 

The Arithmetic Operators

+    

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 

Rules supports the following operators to be used with dates

The Equality and Relational Operators

eq      

Equal to

ITEM_OID eq 2008-12-12

ne

Not Equal to

ITEM_OID ne 2008-12-12          

gt

Greater Than

ITEM_OID gt 2008-12-12

gte

Greater Than or Equal to

ITEM_OID gte 2008-12-12

lt

Less Than

ITEM_OID lt 2008-12-12

lte

Less Than or Equal to

ITEM_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 Rule Parameters

Parameter

Description

To

Message

Subject

${participant.firstname}

Participant first name

 

x

 

${participant.loginurl}

Participant URL with automatic login

 

x

 

${participant.url}

Participant URL without automatic login (requires an access code)

 

x

 

${study.name}

The name of the Study as defined in OpenClinica.

 

x

x

${participant.accessCode}

The single-use code the Participant must use to access OpenClinica Participate.

 

x

 

${event.name}

The name of the Event as specified in the Build Study task in OpenClinica.

 

x

x

${participant}

The Participant contact information as provided when the Participant was connected to the Study. This may have been a mobile phone number (for SMS notification), email address, or both. OpenClinica automatically sends the notification to any and all means that were provided for the Participant.

x

 

 

${participant.id}

Participant ID

 

        x

        x

${site.id}

Site ID

 

        x

        x

${site.name}

Site Name

 

        x

        x

${study.id}

Study ID

 

        x

  x

 

/n

Use at end of line for line break

 

        x

 

 

 

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".)


Approved for publication by ktamm. Signed on 2020-09-30 2:17PM

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