qbo.BusinessRule: Enforcing Custom Rules

Background

The qbo.Application.BusinessRule class enables configuration of business rules that are enforced server-side in the application tier. Examples include:
  • When closing a Foreclosure, ensure the Foreclosure Status is set to 'Complete', 'Cancelled', or 'Opened in Error'.
  • When re-projecting a due date for a task (Import Form), ensure the projected date is not more than 200 days in the future.
  • Don't order a credit report if there is an existing credit report less than 1 month old.
When a user does something in the UI that violates a business rule, they will receive an error message exactly as if they had done something that violates a data constraint. For example, if the user enters data on an Edit form and clicks save, any business rule violations will result an an alert (red background) informing them of the rule violation.

If a third party system invokes QBO 3 code that encounters a business rule violation, they will receive an error message (Http 500 error) detailing the rule violation.

IValidator Interface

The IValidator interface is a hook that allows installing rule validation plugins, such as Schematron, XSDs, or the QBO 3-specific RuleValidator class.  The RuleValidator class behaves as follows:
  • Accepts incoming parameters as XML, 
  • Transforms the XML against XSLT, and
  • Reads the resulting XML file, looking for Exception or Warning nodes
An example RuleValidator XSLT is:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"
>
    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="/">
<RuleValidation>
<xsl:if test="//DateClosed != '' and not (//Status = 'Done' or //Status = 'Finito')">
<Exception>You must set the Status to 'Done' or 'Finito' before closing a process!</Exception>
</xsl:if>
</RuleValidation>
    </xsl:template>
</xsl:stylesheet>

Note that the RuleValidator class may leverage Xslt extension objects, including accessing database information via the data plugin, and security information via the security plugin.

Business Rule Module

To enable power users to configure rules, the Business Rule module allow "rules" to be created by adding rows to the BusinessRule table. Business Rules are defined to work against a Class/Operation pair, such as:
  • Foreclosure/Save
  • ImportForm/Save
  • Loan/CreditReport
Wiring of a BusinessRule includes:
  • Calling AbstractObject.Invoke* methods will 
  • Call AbstractObject.ValidateRules(), will
  • Call BusinessRule.Validate(source, operation, parameters), which search for BusinessRule rows matching ClassName/Operation, and for each rule returned, will
  • Call BusinessRule.Validate(source, parameters), which will invoke an underlying ValidatorPlugin, and will
  • Call the IValidator.Validate() interface, raising exceptions and warnings as they are parsed
When Business Rules are Inappropriate

Be careful about using the BusinessRule module to handle rules that can be enforced using core QBO 3 functionality, particularly the security module. Business Rules are enforced via a plugin instantiated via reflection, and typically includes notable extra processing of each transaction. Because lots of rules can slow a system down, it is preferable to enforce logic via native C# code when possible.

For example, the Freddie Mac ADR system allows law firms to transmit new Foreclosure data and update existing Loan data, but they may not insert new Loans.  While one can write a BusinessRule to raise an error if an attorney transmits Loan information for a loan that does not yet exist, it is more efficient to simply deny their user account the LoanInsert permissions.
Comments