Visual Rules Engine - User Guide

Questionnaire Rules Engine - User Guide

Table of Contents

1. Introduction
2. Getting Started
3. Understanding Rules
4. Creating Rules
5. Conditions
6. Actions
7. Testing Rules
8. Best Practices
9. Troubleshooting

---

Introduction

The Questionnaire Rules Engine allows you to create dynamic, intelligent questionnaires with conditional logic, automatic scoring, and smart behavior. Rules enable you to:

• Show/Hide Questions based on previous answers
• Calculate Scores automatically
• Assign Grades based on responses
• Set Answers programmatically
• Make Questions Required conditionally
• Enable/Disable Questions dynamically

What Can Rules Do?

Rules transform static questionnaires into interactive experiences:

• Display questions only when relevant
• Calculate compliance scores automatically
• Guide users through complex decision trees
• Provide instant feedback with grades
• Reduce user effort by auto-populating answers

---

Getting Started

Accessing the Rules Builder

1. Navigate to any questionnaire in the Questionnaire Builder
2. Click the "Rules" button at the top of the page (next to "Builder")
3. The Rules interface will open, showing any existing rules

Rules Interface Overview

The Rules interface has three main areas:

Header Actions:

• Validate - Check all rules for errors
• Test Rules - Simulate rule execution with sample data
• JSON Editor - Switch to advanced JSON editing mode
• Create New Rule - Add a new rule
• Save Rules - Save all changes to the questionnaire

Visual Editor:

• Lists all rules as expandable cards
• Shows rule summary (conditions and actions)
• Displays validation errors in red
• Allows inline editing of each rule

Help Section:

• Quick reference for rule capabilities
• Links to documentation and examples

---

Understanding Rules

Rule Structure

Every rule has three main components:

IF [Conditions] THEN [Actions]

Example:

IF Question "Risk Level" equals "High"
THEN Show Question "Mitigation Plan"
     Add 10 to Score
     Set Grade to "Needs Review"

Rule Execution Order

Rules execute in the order they appear in the list (top to bottom). You can reorder rules by dragging the handle icon (☰) on each rule card.

Active vs Inactive Rules

• Active Rules (green toggle): Execute when conditions are met
• Inactive Rules (gray toggle): Ignored during execution

Use inactive status to temporarily disable rules without deleting them.

---

Creating Rules

Step 1: Create a New Rule

1. Click "Create New Rule" button
2. A new rule card appears at the bottom of the list
3. Click the card to expand and edit

Step 2: Name Your Rule

1. Enter a descriptive name in the Rule Name field
   • Good: "Show mitigation plan for high risk"
   • Bad: "Rule 1"
2. Optionally add a Description explaining the rule's purpose

Step 3: Set Conditional Logic

Choose how multiple conditions are evaluated:

• AND - ALL conditions must be true
• OR - ANY condition can be true

Example:

Condition 1: Risk Level = "High"
Condition 2: Impact = "Critical"

AND logic: Both must be true
OR logic: Either can be true

Step 4: Add Conditions

Conditions determine WHEN the rule executes.

1. Click "Add Condition" button
2. Select Condition Type:
   • Question - Based on a question's answer
   • Score - Based on current score value
3. Configure the condition (see Conditions section)

Step 5: Add Actions

Actions determine WHAT happens when conditions are met.

1. Click "Add Action" button
2. Select Action Type from the dropdown
3. Configure the action (see Actions section)

Step 6: Save the Rule

1. Click "Save Rules" button in the header
2. If validation errors exist, they'll be shown
3. Fix any errors and save again

---

Conditions

Conditions define when a rule should execute. Each condition compares a value using an operator.

Question Conditions

Test the answer to a specific question.

Configuration:

1. Type: Question
2. Question: Select from dropdown (grouped by section)
3. Operator: Choose comparison type
4. Value: Enter the value to compare

Available Operators (by question type):

Text Questions:

• equals - Exact match
• not equals - Not an exact match
• contains - Contains text
• not contains - Doesn't contain text
• is empty - No answer provided
• is not empty - Has an answer

Number Questions:

• equals - Equal to
• not equals - Not equal to
• less than - Less than
• greater than - Greater than
• less than or equal - ≤
• greater than or equal - ≥

Multiple Choice:

• equals - Selected option equals
• not equals - Selected option doesn't equal
• in - Selected option is in list
• not in - Selected option not in list

Date Questions:

• equals - Same date
• not equals - Different date
• before - Earlier than
• after - Later than

Checkbox (Yes/No):

• equals - Checked or unchecked
• not equals - Opposite state

Examples:

Question: "Risk Level" equals "High"
Question: "Budget" greater than "100000"
Question: "Description" contains "critical"
Question: "Start Date" after "2024-01-01"
Question: "Approved" equals "true"

Score Conditions

Test the current questionnaire score.

Configuration:

1. Type: Score
2. Operator: Choose comparison
3. Value: Enter score to compare

Examples:

Score greater than 75
Score equals 100
Score less than or equal 50

Multiple Conditions

When you have multiple conditions:

• AND Logic: ALL conditions must be true for the rule to execute
• OR Logic: ANY condition being true will execute the rule

Example with AND:

IF Risk Level = "High"
AND Impact = "Critical"
THEN Show "Escalation Procedure"

(Both must be true)

Example with OR:

IF Status = "Failed"
OR Score < 60
THEN Set Grade to "Needs Improvement"

(Either can be true)

---

Actions

Actions define what happens when rule conditions are met.

Show Questions

Makes questions visible on the questionnaire.

Configuration:

1. Action Type: Show Questions
2. Target Questions: Select questions to show (multi-select)

Use Case:

IF Risk Level = "High"
THEN Show Questions: "Mitigation Plan", "Risk Owner", "Review Date"

Hide Questions

Makes questions invisible (and skips validation).

Configuration:

1. Action Type: Hide Questions
2. Target Questions: Select questions to hide (multi-select)

Use Case:

IF Compliance Required = "No"
THEN Hide Questions: "Compliance Framework", "Audit Date"

Enable Questions

Makes questions editable.

Configuration:

1. Action Type: Enable Questions
2. Target Questions: Select questions to enable (multi-select)

Use Case:

IF User Role = "Administrator"
THEN Enable Questions: "Override Reason", "Admin Notes"

Disable Questions

Makes questions read-only.

Configuration:

1. Action Type: Disable Questions
2. Target Questions: Select questions to disable (multi-select)

Use Case:

IF Status = "Approved"
THEN Disable Questions: "Risk Rating", "Assessment Score"

Set Answer

Automatically populate a question's answer.

Configuration:

1. Action Type: Set Answer
2. Target Question: Select ONE question
3. Answer Value: Enter the value to set

Use Case:

IF Risk Level = "Critical"
THEN Set Answer: "Priority" = "Immediate"

Notes:

• Value must match question type (number for number questions, etc.)
• For multiple choice, use exact option text
• For checkboxes, use "true" or "false"

Clear Answer

Remove the answer from questions.

Configuration:

1. Action Type: Clear Answer
2. Target Questions: Select questions to clear (multi-select)

Use Case:

IF Start Over = "Yes"
THEN Clear Answer: "Risk Level", "Impact", "Mitigation Plan"

Set Score

Set the questionnaire score to a specific value.

Configuration:

1. Action Type: Set Score
2. Score Value: Enter numeric value

Use Case:

IF All Controls Passed = "Yes"
THEN Set Score: 100

Add to Score

Increase the score by a specific amount.

Configuration:

1. Action Type: Add to Score
2. Score Value: Enter numeric value to add

Use Case:

IF Security Controls = "Implemented"
THEN Add to Score: 25

Note: Use negative numbers to subtract from score.

Calculate Total Score

Calculate score based on all responses (uses built-in scoring logic).

Configuration:

1. Action Type: Calculate Total Score

Use Case:

IF All Questions Answered = "Yes"
THEN Calculate Total Score

Set Grade

Assign a grade or rating to the questionnaire.

Configuration:

1. Action Type: Set Grade
2. Grade Value: Enter grade text (e.g., "Pass", "Fail", "A", "Critical")

Use Case:

IF Score >= 90
THEN Set Grade: "Excellent"

IF Score >= 70
THEN Set Grade: "Good"

IF Score < 70
THEN Set Grade: "Needs Improvement"

Repeat Questions

Dynamically repeat a set of questions based on a count.

Configuration:

1. Action Type: Repeat Questions
2. Count Source: Question containing the count
3. Questions to Repeat: Select questions (multi-select)

Use Case:

IF Number of Systems > 0
THEN Repeat Questions: "System Name", "System Owner", "Risk Level"
     (repeats based on Number of Systems value)

Set Display Options

Configure what's displayed on the questionnaire.

Configuration:

1. Action Type: Set Display Options
2. Options: Check desired options
   • Display Score
   • Display Grade
   • Display Rules

Use Case:

IF Assessment Complete = "Yes"
THEN Set Display Options: Display Score, Display Grade

---

Testing Rules

The Test Mode allows you to simulate rule execution before deploying to production.

Opening Test Mode

1. Click "Test Rules" button in the header
2. A modal opens showing all questions
3. Status shows number of active rules

Running Tests

Step 1: Enter Sample Answers

• Fill in answers for questions
• Use realistic test data
• All question types supported:
  • Text fields
  • Number inputs
  • Date pickers
  • Checkboxes
  • Dropdowns

Step 2: Execute Rules

• Click "Run Test" button
• Rules execute in order
• Results display immediately

Step 3: Review Results

Execution Summary:

• Rules Executed: "3/5" (3 out of 5 rules ran)
• Visible Questions: Count of shown questions
• Hidden Questions: Count of hidden questions
• Final Score: Calculated score
• Final Grade: Assigned grade

Execution Log:

• Each rule shows EXECUTED or SKIPPED status
• Click a rule to expand details
• See which conditions matched (✓/✗)
• See which actions fired
• Human-readable messages explain results

Question State Viewer:

• Left column: Visible questions
• Right column: Hidden questions
• Shows impact of rules on questionnaire

Test Actions

• Clear All: Remove all test answers and results
• Reset: Clear results but keep answers
• Run Test: Execute rules again with current answers
• Close: Exit test mode

Example Test Scenario

Testing a Risk Assessment:

1. Enter Test Data:

   • Risk Level: "High"
   • Impact: "Critical"
   • Budget: "500000"

2. Run Test

3. Review Results:

   • Rule "Show Mitigation for High Risk" - ✓ EXECUTED
     • Condition: Risk Level equals "High" ✓
     • Action: Showed 3 questions ✓
   • Rule "Add Score for Budget" - ✓ EXECUTED
     • Condition: Budget > 100000 ✓
     • Action: Added 25 to score ✓
   • Final Score: 25
   • Visible Questions: 15
   • Hidden Questions: 3

4. Verify Behavior:

   • Mitigation questions are visible ✓
   • Score increased correctly ✓
   • Rules executed as expected ✓

---

Best Practices

Rule Organization

1. Use Descriptive Names

✅ Good: "Show compliance questions for regulated industries"
❌ Bad: "Rule 1"

2. Add Descriptions

✅ Good: "This rule displays additional compliance questions when
         the organization is in a regulated industry (Finance,
         Healthcare, Government)"
❌ Bad: (no description)

3. Order Rules Logically

• Put foundational rules first (e.g., scoring rules)
• Put conditional visibility rules after
• Group related rules together

4. Keep Rules Simple

• One rule = one logical purpose
• Break complex logic into multiple rules
• Avoid circular dependencies

Condition Design

1. Use Appropriate Operators

✅ For exact matches: "equals"
✅ For partial text: "contains"
✅ For ranges: "greater than" + "less than" (two conditions)

2. Handle Edge Cases

✅ Test for empty answers: "is not empty"
✅ Test for unexpected values
✅ Provide defaults with lower-priority rules

3. Combine Conditions Wisely

✅ AND: When all criteria must be met
✅ OR: When any criteria is sufficient

Action Patterns

1. Progressive Disclosure

Show simple questions first
Hide advanced questions
Show advanced questions only when needed

2. Validation Support

Enable questions when prerequisites are met
Disable questions when not applicable
Clear answers when context changes

3. Score Management

Use "Set Score" to initialize
Use "Add to Score" to increment
Calculate total score at the end

4. Grade Assignment

Create tiered rules from highest to lowest:
  IF Score >= 90 THEN Grade = "Excellent"
  IF Score >= 70 THEN Grade = "Good"
  IF Score >= 50 THEN Grade = "Satisfactory"
  ELSE default grade applies

Testing Strategy

1. Test Individual Rules

• Enable one rule at a time
• Verify expected behavior
• Check edge cases

2. Test Rule Combinations

• Enable all rules
• Test various answer combinations
• Verify rules don't conflict

3. Test with Real Data

• Use actual questionnaire scenarios
• Test all question types
• Verify scoring accuracy

4. Test Edge Cases

• Empty answers
• Boundary values (0, max)
• Unexpected combinations

---

Troubleshooting

Common Issues

Rules Not Executing

Problem: Rules don't run when expected

Solutions:

1. ✅ Check rule is Active (toggle is green)
2. ✅ Verify conditions match actual answers
3. ✅ Use Test Mode to debug
4. ✅ Check conditional logic (AND vs OR)
5. ✅ Verify question QUIDs are correct

Validation Errors

Problem: Cannot save rules due to errors

Common Errors:

"Condition X: Question must be selected"

• Select a question from the dropdown

"Condition X: Value is required"

• Enter a comparison value

"Action X: At least one target question required"

• Select target questions for the action

"Action X: Answer value is required"

• Enter a value for Set Answer actions

"Circular dependency detected"

• Rule depends on a question it modifies
• Restructure rules to avoid loops

Unexpected Behavior

Problem: Rules behave differently than expected

Debugging Steps:

1. Use Test Mode:

   • Enter test answers
   • Review execution log
   • Check which conditions matched
   • Verify actions executed correctly

2. Check Rule Order:

   • Rules execute top to bottom
   • Later rules can override earlier ones
   • Reorder if needed

3. Verify Operators:

   • "equals" is case-sensitive
   • "contains" is case-insensitive
   • Check number comparisons

4. Check Question Types:

   • Checkbox: Use "true"/"false"
   • Numbers: Use numeric values
   • Dates: Use YYYY-MM-DD format
   • Multiple choice: Use exact option text

Performance Issues

Problem: Questionnaire is slow with many rules

Solutions:

1. ✅ Minimize number of rules (combine when possible)
2. ✅ Avoid checking the same condition multiple times
3. ✅ Use specific conditions (avoid wildcards)
4. ✅ Disable unused rules
5. ✅ Deactivate test/debug rules

Getting Help

Validation Errors:

• Click "Validate" button to see all errors
• Red border on rule cards indicates errors
• Hover over error icons for details

Execution Issues:

• Use Test Mode to simulate execution
• Review execution log for details
• Check condition evaluation results
• Verify action execution messages

Complex Scenarios:

• Export rules via JSON Editor
• Share with team for review
• Document complex logic in descriptions
• Create example test cases

---

Advanced Topics

JSON Editor Mode

For advanced users, you can edit rules in raw JSON format:

1. Click "JSON Editor" button
2. Edit JSON directly
3. Click "Apply Changes" to return to visual mode

Use Cases:

• Bulk editing multiple rules
• Copying rules between questionnaires
• Advanced debugging
• Version control

Warning: Invalid JSON will prevent returning to visual mode.

Backward Compatibility

The visual rules builder is 100% compatible with existing questionnaires:

• Existing rules are preserved
• Legacy format stored in database
• Automatic conversion on load/save
• No migration required

Rule Templates (Coming Soon)

Pre-built rule templates for common scenarios:

• Risk-based disclosure
• Score-based grading
• Progressive questionnaires
• Compliance workflows

---

Quick Reference

Common Rule Patterns

Show Question if Another is Answered:

IF Question X is not empty
THEN Show Question Y

Hide Questions for Certain Answers:

IF Question "Applicable" equals "No"
THEN Hide Questions: "Details 1", "Details 2", "Details 3"

Score Based on Answer:

IF Question "Status" equals "Complete"
THEN Add to Score: 20

Grade Assignment by Score:

IF Score >= 90 THEN Set Grade: "Pass"
IF Score < 90 THEN Set Grade: "Fail"

Auto-populate Answer:

IF Question "Type" equals "Critical"
THEN Set Answer: "Priority" = "High"

Conditional Required:

IF Question "Regulated" equals "Yes"
THEN Show Question "Compliance Framework"
     Enable Question "Compliance Framework"

Keyboard Shortcuts

• Enter: Save current field
• Escape: Cancel edit
• Tab: Move to next field

Button Reference

Button	Function
Validate	Check all rules for errors
Test Rules	Open test mode simulation
JSON Editor	Toggle advanced editing mode
Create New Rule	Add new rule at bottom
Save Rules	Save all changes
Expand/Collapse	Toggle rule details
Delete	Remove rule (with confirmation)
Duplicate	Create copy of rule

---

Support

For additional help:

• View Documentation: [Link to detailed docs]
• See Examples: [Link to example questionnaires]
• Contact Support: [Support contact info]

---

Last Updated: 2024-10-04
Version: 1.0