Build a Complex Web Form with RuleBox and TestBox

Learn to manage your web form's question flow with RuleBox in this session. Simplify complex conditional statements by structuring logic in a readable and testable Given-When-Then format. Discussion covers prototyping tips, writing test cases, integrating external data, and managing multiple form versions with a single set of rules. Ideal for ColdFusion web developers exploring TestBox and/or RuleBox, with a demo featuring ColdBox and cborm, though not required.

1. INTO THE BOX 2024
THE NEW ERA OF
MODERN DEVELOPMENT

2. BLUE ROOM
PRESENTED BY
ANNETTE LISKEY
BUILD A COMPLEX WEB FORM
WITH RULEBOX AND TESTBOX

3. ANNETTE LISKEY
SPEAKER EN ITB 2024
Web Developer at University of Virginia

A.S., Computer Science
B.A., English
M.Ed., Educational Technology
Current

• Full stack
• Business analysis
• Project management
• ColdFusion + ColdBox
Previous

• ColdFusion MX
• IT/Tech Support
• PHP, WordPress
• Educator

4. INTO THE BOX 2024
AGENDA
•Introduction
•Concept: Rules Engine
•Proof of Concept
•Real (Fake) Example
•Tips for Success
•References & Questions

5. INTO THE BOX 2024
LEARNING OBJECTIVES
•Define a rules engine
•Write rules for RuleBox
•Write tests to verify the rules (TestBox)
•Use RuleBox to handle conditional logic in a web form
•Accommodate multiple versions of a form with minimal code changes

6. INTO THE BOX 2024
PROJECT ORIGIN STORY

•A massive PDF
•Up to ~80 possible questions
•Sometimes just 1 question
•Annual requirement for all human subject research
•Like doing taxes, but not as much fun

7. INTO THE BOX 2024
“Can we make this
into a web form?”

— Everyone Who Used The PDF Form

8. Conditional Logic

•Always required questions
•Sometimes required questions
•Follow-up items, sometimes optional
Plus

•External data sources
•Changing questions & conditions
•Multiple versions, simultaneously

INTO THE BOX 2024
FORM REQUIREMENTS

9. INTO THE BOX 2024
“Maybe I can use RuleBox.”

— Me

10. INTO THE BOX 2024
RuleBox &
TestBox

Thanks, Ortus!

11. Concept: Rules Engine
INTO THE BOX 2024

12. What is a rules engine?
Imperative
Programming
Rules Engine Machine Learning
See: https://www.capitalone.com/tech/machine-learning/rules-vs-machine-learning/
INTO THE BOX 2024

13. INTO THE BOX 2024
•Not a Business Rules Management System with a UI to create rules (Drools)
•Not a UI for web forms with conditional logic (Qualtrics)
•Not a decision table, control table, truth table, etc.
•Decision table could be useful documentation
•Not low code or no code
What is not a rules engine?

14. •Extract the business logic
•More readable
•Long-term sustainability
•Best if logic is known

INTO THE BOX 2024
Why use a rules engine?

15. •Many facts in, one result out
•Simple object result

•Based on RuleBook
•Written as “Given-When-Then”
•Plays nice with TestBox


INTO THE BOX 2024
Features of RuleBox

16. Proof of Concept
INTO THE BOX 2024

17. Simple example
Primary Color Wheel
Source: https://www.britannica.com/science/primary-color#/media/1/476096/269450
INTO THE BOX 2024
PROOF OF CONCEPT

18. •GIVEN
Two colors
•WHEN
One color is red
Other color is blue
•THEN
Result is violet
INTO THE BOX 2024
PROOF OF CONCEPT

19. •GIVEN
Two colors (facts)
•WHEN
One color is red
Other color is blue
•THEN
The result is violet
INTO THE BOX 2024
PROOF OF CONCEPT

20. •GIVEN
Struct of ”facts”
•WHEN
Closure that
evaluates to true
•THEN
Return
a simple value
INTO THE BOX 2024
PROOF OF CONCEPT

21. •GIVEN
Struct of ”facts”
•WHEN
Closure that
evaluates to true
•EXCEPT
Unless
something else is true
•THEN
Return a simple value
INTO THE BOX 2024
PROOF OF CONCEPT

22. •Add multiple rules in one function
function defineRules(){
….
}
•Rules are skipped if the when() evaluates to false
•If when() is true, actions in then() occur and affect the result
•If when() is true and stop() is present, no more rules are checked


INTO THE BOX 2024
RuleBox execution

24. Beyond two colors
Rules for Secondary and Intermediate Colors
Option 1: More Specific Rules
•Add rules with facts.color3
•Order matters!
More specific = higher placement
•Strategic use of .stop()



Option 2: Separate Rules File
•Different situation, different rules
•Call the rules that fit the case
INTO THE BOX 2024

25. Call the Rules
INTO THE BOX 2024

26. Rules File in
Models
INTO THE BOX 2024

27. WireBox injection
Inside the component, outside the functions



INTO THE BOX 2024

28. Build the facts, call the rules
Give a struct, get a component



INTO THE BOX 2024

29. Results, the value
writedump( theResults.getResult() )



INTO THE BOX 2024

30. Results, the component
writedump( theResults )
INTO THE BOX 2024

31. Troubleshoot the rules
writedump( theResults.getRuleStatusMap() )
•NONE: Rule not checked
•SKIPPED: when() was false
•EXECUTED: when() was true,
then() actions executed
•STOPPED: when() was true,
then() actions executed,
no more rules checked
INTO THE BOX 2024

32. Test the Rules
INTO THE BOX 2024

33. Define your test cases
•Does the result exist?
•Is it the expected format?
•Is it the expected value?
•Test at least one wrong answer
red + blue not equal orange
INTO THE BOX 2024

34. Test case matrix
INTO THE BOX 2024

35. Test Code in
Tests Folder
INTO THE BOX 2024

36. Code: 1 unit test, 1 expectation
INTO THE BOX 2024

37. Results: 1 unit test, 1 expectation
INTO THE BOX 2024

38. Code: More unit tests

39. Results: More unit tests
INTO THE BOX 2024

40. Code: Multiple expectations
INTO THE BOX 2024

41. Results: Multiple expectations
INTO THE BOX 2024

42. Real (Fake) Example
INTO THE BOX 2024

44. •Not my project, just a good example of PDF to web
•Some questions are always shown
•Some questions skipped based on prior answers
•PDF and Web Form Prototypes from USDA:
https://www.fns.usda.gov/cn/revised-prototype-application-free-reduced-pric
e-school-meals




INTO THE BOX 2024
Application for free lunch (USDA)

45. •Create a form_template
•Create all possible questions
•A form entity for each lunch application
•Each form has answers
•Each form has question_shown




INTO THE BOX 2024
General object map

47. •Create new form entity for each submission
•Each form related to a form_template
•A question_shown record for every potential question
•Set showQuestion property for each question_shown (some always shown)
•As answers are saved, re-evaluate the showQuestion properties
•Use RuleBox to do the evaluation




INTO THE BOX 2024
General workflow

48. •The results will be whether a dependent question is required
•The facts are the answers needed to make that determination
•Example:
Case number is required if any assistance program is true

The question to check is caseNumber
The fact needed is the answer to isAssistance

The result is true (caseNumber is required) if isAssistance is true



INTO THE BOX 2024
RuleBox evaluates conditional questions

49. Rules: Case number question
INTO THE BOX 2024

50. Code: Call the rules
INTO THE BOX 2024

51. •Abstract code so one function works for all questions
•Only evaluate showQuestion for the conditional questions
Skip questions that are always shown
Skip questions that are constant (external data)
•Only evaluate when the saved answer matters
Skip answers that are not conditional factors
•Put all and only the relevant data in the facts struct




INTO THE BOX 2024
Refined workflow

52. Analyze the
Conditional Questions
INTO THE BOX 2024

53. •Identify the questions that are conditional

“Show this question? It depends”
•Include all the necessary conditions in the facts struct

“Show this question? It depends on x, y, and z.”


INTO THE BOX 2024
Goal

54. •Look for conditional questions
A question that is only shown depending on answers to other questions
•Look for conditional factors
The answers/other data that influences the conditional question
•Create a related questions object

INTO THE BOX 2024
Option 1: Identify dependent relationships
Conditional Question Conditional Factors
Case Number Assistance Program
Income Frequency Any Income of That Type

55. •Create question groups object
All functionally related questions – independent and dependent
Include any data from external sources (they’re just questions)


INTO THE BOX 2024
Option 2: Identify question groups
Question Group 1 Question Group 2
is_SNAP has_work_income
is_TANF frequency_work_income
is_FDPIR
case_number

56. •Combination of related questions and question groups
•Potential conditional question groups
•Analyze the form content to determine the right option

INTO THE BOX 2024
Other Options

57. Algorithm, part 1
Save answer, build facts
•Only after saving an answer that affects a condition question
•Gather all the questions in that answer’s question group in an array
•For each question in question group array
Get the current answer to that question
Append it to facts struct as a struct (struct of structs)
INTO THE BOX 2024
Key Value
Question Slug Answer Value
isAssistance true

60. Algorithm, part 2
Save answer, build facts
•For each question in the questionGroup array (again)
•If it’s a conditional question
•Append to the facts struct
question_to_check : [this_question_slug]
•Call the rules with the current facts struct
•Results tell you if the current question (“question_to_check”) is required
•Update showQuestion property in current question’s question_shown entity
INTO THE BOX 2024

62. Rules are Specific,
Calling Rules is Abstract
INTO THE BOX 2024

63. Extra credit: determine eligibility
RuleBox can do math!
INTO THE BOX 2024

64. Tips for Success
INTO THE BOX 2024

65. •Essential if moving from PDF
•Communicate mental models
•Solidify question format
•Identify opportunities for improvement

INTO THE BOX 2024
Prototype!

66. Option 1: Same as the PDF
Prototype of assistance question
INTO THE BOX 2024

67. Option 2: Better than the PDF
Prototype of assistance question
INTO THE BOX 2024

68. Prototype to M.V.P.
Minimum Viable Product
•Goal is to build a shared mental model
•As low-fidelity as possible
•UX tools support branching, but do you need it?
•Even a PowerPoint will do
•Make the conditionals obvious

INTO THE BOX 2024

69. Make the conditions obvious
K.I.S.S.
INTO THE BOX 2024

70. Use Question Slugs
INTO THE BOX 2024

71. Question slugs (for brain slugs)
Human-friendly alternate ids
•Short phrase to identify a question
•Property on question object but not the primary key
•Makes the rules and tests more readable
•Reduces cognitive load for developers
•Useful for versioning

INTO THE BOX 2024

72. Use Form Templates
INTO THE BOX 2024

73. Form templates for versioning
•New form version = new form template
•New template = new question entities
•Minor question change? Same question slug
•Same slugs = same rules, same tests
•Examples:
One form is a subset of another form’s questions
Minor change to wording of a question (“minors” vs “minors and neonates”)
INTO THE BOX 2024

74. Helpful links
•RuleBox: https://github.com/coldbox-modules/rulebox
•TestBox: https://github.com/Ortus-Solutions/TestBox
•Rules Engine vs. Machine Learning:
https://www.capitalone.com/tech/machine-learning/rules-vs-machine-learnin
g/
•USDA Lunch Application Prototype:
https://www.fns.usda.gov/cn/revised-prototype-application-free-reduced-pric
e-school-meals
•Demo Code: https://github.com/brufftech/rulebox-demo
INTO THE BOX 2024

75. This is the end
Annette Liskey
INTO THE BOX 2024

76. INTO THE
BOX 2024
THANK YOU TO
OUR
SPONSORS
INTO THE BOX 2024