Debug a rule

Rule designers can debug rules by using logMsg() statements to obtain information regarding the rule logic and make sure it works as desired.

The Debug functionality is only available in Testing mode. You must have a study version in the Testing container that includes the required elements. You access the Rules interface from a specific study version and site as described in Access the rules interface.

Note:

Before you can debug a rule, test data must have been entered for the rule. The Debug button runs the rule against data entered for the subject for which the rule was accessed, this includes relevant data entered in other visits.

1. Navigate to your desired study in Testing mode and select a site.
2. In the table, locate and click the visit card that you want to edit.
3. On the left side of the visit window, click the form containing the rule you want to work with.
4. Select a question and expand the Rules pane on the right to view the rules it contains.

   Tip:

   When you click on any question you can activate View all Rules in this form option to get a list of all the rules added to any question in that form
5. Open the Rule Editor:
   • To edit an existing rule: For the given rule click on the menu icon () then select Edit.
   • To create a new rule: See Create rules using the rule editor.
6. Add log statements where needed.
   For more information on how to use the log helper function properly see logMsg().

   Tip:

   A predictive text feature is available as you type, with descriptions of this and all other rule helper functions. This allows you to select an existing function from the list and add it to your expression, including parameters as placeholders for you to complete.

   Predictive text also suggests variable names and some standard JavaScript syntax.

7. Click Debug.
   Clicking Debug automatically saves changes to the JavaScript expression. All rule saving requirements must be fulfilled.

   Note:

   Any compilation error or missing requirement will not allow the debug process to complete.

The log window appears on the right in the Rule editor.

Rule runs against data of the selected subject and outputs the calls made to the logMsg() helper function within the rule and for all instances. This means that, if the rule belongs to a form in multiple visits or a question in repeating sections, the rule is analyzed for all impacted visits and repeating sections. The output from each rule instance is listed in the log window.

If any exception is encountered, the stack trace details and error messages are displayed in the log window.

Review the log messages and make any necessary changes to the rule expression. Add additional log statements as required and repeat this process until the rule's path of execution is as expected. Then Save your changes and exit the rule editor.

Tip:

Since the logMsg() helper function only runs in debug mode, there is no need to remove the calls before publishing the rule.

After saving, you must test rule performance to be as expected. To make your rule available in Production, you must test, approve, and publish your rule.

For examples, and more information on developing custom rules, see:

• Rule statuses and lifecycle
• Prepare your rule for testing and approval
• Test and approve a rule
• Publish a single rule
• Publish multiple rules at the form level
• Publish multiple rules at the study level
• Rules helper function reference
• Rules examples