When Things Go Wrong

What RuleBox does when a rule throws, and the mistakes it catches early.

When Things Go Wrong

Rules call real code, and real code fails. Here is what you can expect.

A rule that throws

Say a rule calls a credit bureau, and the bureau is down:

class extends="rulebox.models.RuleBook"{

	function defineRules(){
		addRule(
			newRule( "lookupBureau" )
				.then( ( facts, result ) => {
					throw( type="App.BureauDown", message="Credit bureau is down" )
				} )
		)
	}

}

When you run it, two things happen:

1. The rule is marked FAILED in the audit trail.
2. The error is thrown again to you, unchanged.

var book = getInstance( "BureauRules" )

try {
	book.run()
} catch( any e ) {
	e.type                              // "App.BureauDown"
	book.getRuleStatus( "lookupBureau" )  // "FAILED"
}

RuleBox never hides an error. You choose what to do with it. Because the FAILED mark is written first, you can always see which rule broke.

A name that was never registered

Lesson 6 had a then that points at the action decide. If you load the file and forget to register it:

getInstance( "RuleBook@rulebox" )
	.loadRules( new rulebox.models.JSONRuleSource( expandPath( "/config/rules/loan.json" ) ) )

you get an error straight away, when the rules load:

RuleBox.UnregisteredActionException: No action registered under the name 'decide'.

You find out on startup, not the first time a customer hits that rule. A predicate that is missing gives RuleBox.UnregisteredPredicateException.

Missing or bad facts

If a rulebook enforces its facts (lesson 3), a run with a missing required fact, a value of the wrong type, or a value outside a fact's allowed list fails before any rule runs:

RuleBox.InvalidFactsException: RuleBook [loan] was given invalid facts: Missing required fact [creditScore].

The message lists every problem at once, and its extendedInfo holds them as JSON ({ fact, problem, message }), handy for showing them on a form. The messages name the fact but never repeat its value, since facts can be personal data. To check facts without running anything, call validateFacts( facts ): it returns the same problems as an array.

A rule that was never added to a book

A Rule only works inside a RuleBook. Running one that is on its own gives a clear error instead of a confusing one:

getInstance( "Rule@rulebox" ).run()
// RuleBox.RuleNotAttachedException

Always create rules with newRule() inside defineRules(), or with the Builder.

Try it

Make lookupBureau throw, run the book inside a try, and print getRuleStatusMap() in the catch. Notice that rules after the failing one are still REGISTERED: the chain stopped where the error happened.

Next: see all of this in a browser.