Quick Start for Custom Rules

Create a new rule

1 Prerequisites

Before you can get started using rules, you must first have a study version in the Testing container that includes the following elements:

Forms
Visits (that contain forms)
Subjects
Sites associated with the study version placed in the Testing container

2 Access the Rule Editor

On the Home page, click the Testing Mode button for the study you want to work on.
Along the top, make sure Subjects is selected.
If you have access to multiple sites for the study, select a site from the Site drop-down in the upper-right.
In the table, locate and click the visit card that you want to edit.
On the left side of the visit window, click the form for which you want to create the rule.
Select the question that should contain a rule. On the right, expand the Rules pane, and click Add Rules.

3 Add a rule

In the Rule editor complete the following fields and click Next:

Rule Name: Enter a name for your rule. Each name must be unique within a study.
Description: Enter a short description of your rule. This field isn't mandatory but can help you distinguish between each rule and its purpose in a study. This is helpful when you want to reuse a rule.
Do not block users: Turn this toggle on if you want to allow site users to edit and save forms without being blocked while the rule is running.

Define variables for your rule:

Click the plus sign (+) next to Variable to add a variable.
In the first field, enter a name for the variable.
Select a visit, a form, and an item from each drop-down.
Tip: The rule is executed against every visit in the study that contains the form. If you leave -All Visits- in the visits field, the variable data will be retrieved from the form in current visit where rule is being run. If you select a specific visit, the variable data will be retrieved from the form in the specified visit for every visit where the rule is executed.
Repeat steps a, b and c for every new variable you wish to create.

In the Expression field, enter the JavaScript expression that will be evaluated to a value.
Refer to the Rules Developer Guide to get an overview of the rules you can program.
From the Action drop-down, choose the type of the response you want the rule to generate:

Select Create Query to automatically generate a query each time the value returned by the rule expression is False. Additionally, enter a query message for users to see.
Select Create Assigned Query to assign the query to a specific study roles. Click the textbox to select one or more study roles and then enter a query message on the right.
Note:The Roles drop-down list contains only the study roles that have been created in the study. The template study roles are not included.
Read step by step instructions to Create a rule for an automated query.
Select Calculate Value if you want the system to automatically calculate a value and populate a read-only item with the result. You must also select the Target Type (Text or Number) and the Format for the calculated value.
Read step by step instructions to Create a rule for calculated value.
Select Send Notification to send email notification to specific users. Enter a subject line, the email addresses separated by semicolon and the message to send.
Read step by step instructions to Create a rule to send an email notification.

Click Save.
Note:If the rule expression contains syntax errors the Rule Editor marks it for you to correct. Before it can be promoted to UAT and Approved, a rule must contain a valid expression and at least one action.

4 Debug a rule

While creating a rule in the Rule Editor, add log statements where needed.
Tip: To edit an existing rule, click on the menu icon then select Edit.
For more information on how to use the log helper function properly see logMsg() helper function.
Click Debug, this will automatically save changes to the JavaScript expression.
Review the log window that appears on the right.
Make any necessary changes to the JavaScript expression until it works as expected.
Click Save.
Read step by step instructions and details to debug a rule.

Rule Examples

Compare two values

For this example, a vital sign form is used to collect the vital sign information from a subject. A rule will be used to calculate the subject's blood pressure by comparing the diastolic and systolic readings and generate a query if the diastolic reading is greater than systolic pressure.

Evaluate if diastolic blood pressure is greater that systolic blood pressure using their variable names and return False to raise a query. Then select Create Query as the action and enter your query message:


                    if(bpdia > bpsys)
    return false;

return true;

Calculate BMI

For this example, a vital sign form is used to collect the vital sign information from a subject. A rule will be used to display the BMI as a read-only value by reading the weight and height from the form.

Calculate BMI by adding the variables from the form, and return the BMI formula as a read-only item, then select Calculate Value as the action to display the calculated value on the form:


                    if((weight === 0) || (height === 0)){
    return 0;
} else {
    return weight / (height * height);
}

Date of informed consent must be within a date range

For this example, a screening form is used to collect the date of informed consent. This rule will be used to calculate if the date is within a range and create a query notification if the date is outside the defined parameters.

Evaluate if the date of informed consent is within parameters using the "isDateInRange()" helper function. Return False to raise a query, then select Create Query as the action and enter your query message:


                    var dateFrom = new Date("March 1, 2020");
var dateEnd = new Date("March 30, 2020");

return isDateInRange(dateInformedConsent, dateFrom, 
dateEnd, "both");

Note: See other Rule Examples available in the Rules Developer Guide.

Testing and Publishing

1 Test and approve a rule

You need to test and approve a rule before publishing it to Production.

On the Home page, click the Testing Mode button for the study you want to work in. Along the top, make sure Subjects is selected.
If you have access to multiple sites for the study, select a site from the Site drop-down in the upper-right.
In the table, locate and click the visit card that you want to edit.
On the left side of the visit window, click the form for which you want to test and approve a rule.
Enter a value for the question containing the rule.
Click Save.
Repeat steps 6 and 7 to test all possible scenarios. If the rule generates the expected result for all scenarios:
1. On the Rules pane, next to the rule's name, click the rule status icon to show the status slider.
2. Move the slider from UAT to Approved.
  Note: Click the menu icon (Menu icon) and select View to see a rule's details in read-only mode.

2 Publish one or multiple rules

There are two ways in which you can publish a rule: you can either publish one rule at a time or publish multiple rules at once.

On the Home page, click the Testing Mode button for the study you want to work on.
Along the top, make sure Subjects is selected.
If you have access to multiple sites for the study, select a site from the Site drop-down in the upper-right.
In the table, locate and click the visit card that you want to edit.
On the left side of the visit window, click the form that includes the rule or rules that you want to publish.
At the top of the Rules pane, click the All Rules in the Form toggle.
On the Rules pane, click the View all Rules in the Form toggle button.
Click Publish All Approved Rules.
Note: You can publish rules in Production by following steps 6 and 7 only if the study is already in the Approved container. If not, you need to move the study from Testing to Approved to publish all rules in Production.

3 Modify and republish a published rule

You can modify a published rule and re-publish it as needed. If you modify a published rule in Testing mode, changes won't appear in Production mode until you update that rule's status to Published.

On the Home page, click the Testing Mode button for the study you want to work on.
Along the top, make sure Subjects is selected.
If you have access to multiple sites for the study, select a site from the Site drop-down in the upper-right.
In the table, locate and click the visit card that you want to edit.
On the left side of the visit window, click the form for which you want to modify a published a rule.
At the top of the Rules pane, click the All Rules in the Form toggle.
Select the question that contains that rule.
On the right, expand the Rules pane, click the menu icon.
Select Edit.
On the Rule editor, make your changes. Click Save.
Note: The rule's status is updated to Draft. The rule currently published in Production isn't impacted by this change. If you want to start over, you can always delete a rule with a Draft status.