Business Rules

Rules matrices

A matrix is a decision table. Inputs are the columns you match on, outputs are the columns you get back, and each row is one rule. Write one row per business requirement, not one row per combination: the matching does the rest.

Inputs

Setting	Purpose
Dimension	The input’s name. When a matrix is called, a parameter with this name (spaces removed) supplies the value.
Value type	How cells are compared (see below).
Weight	How much a match on this input counts. A blank weight counts as zero.
XPath	Where to find the value in a record’s data when the matrix evaluates a record.

Value type	A cell matches when the input…
String	equals the cell, with % as a wildcard (North% matches North East)
List	is one of the cell’s comma-separated values
Int, Money, Float, Date	equals the cell
Int, Money, Float, Date low – high	falls in the range (a Money range with no high value is open-ended)
Boolean	equals the cell (true/false or 1/0)

Any cell can be set to does not match, which reverses it: State does not match CA, NY.

How the winning row is chosen

1. A blank cell matches anything.
2. A row is eligible only if every filled cell matches. A row that needs a value the caller didn’t supply isn’t eligible.
3. Among eligible rows, the highest total weight of matched inputs wins. Ties go to the row with more matched cells.

Example: pricing an inspection, with weights Client 10, State 5, Order amount 1.

Row	State	Client	Order amount	Cost	Price
1				50	100
2	CA			60	120
3		Acme		50	90
4			500,000 and up	50	110
5	TX		0 – 100,000	45	100

• Acme, CA, 250,000: rows 1, 2, and 3 are eligible. Row 3 (weight 10) beats row 2 (weight 5), so the price is 90.
• Another client, TX, 80,000: row 5 matches State and Order amount (weight 6) and beats row 1, so cost is 45 and price is 100.
• No order amount supplied: rows 4 and 5 aren’t eligible.

Outputs

Each output has a name, a type (String, Money, Float, Integer, Boolean, or Object), and a default value. An Object output points to a record, such as a workflow template, a person, or a team, so other building blocks can act on it. When a matrix sets fields on a record or assigns worklist items, output text can include {Field} placeholders, which are filled from the record being evaluated.

Chaining. If an output’s name contains Matrix and its value is the name of another matrix, QBO looks up that matrix with the same inputs and adds its outputs to the result. Chains are limited to 16 levels by default.

Build and test

• In Matrix View, use Add Input Column, Add Output Column, Add Single Row, and Copy Row. Type test values into the input boxes and search to see which rows win.
• What-if Analysis tests a lookup from a set of inputs.
• Copy duplicates a matrix, so you can test changes before switching over.
• Create a Score creates a score template with the same name, with an item for each output (see Scoring).
• To load many rows at once, drag a spreadsheet onto Matrix View. Its column names must match the input and output names.

Where matrices plug in

Use	Outputs it reads
Worklist assignment	Team, Person, Priority, SmartWorklist (see Worklists)
Worklist audit sampling	Percent, Minimum, Maximum, Template
Form field rules	Behavior, from the matrix named Rules (below)
Set fields on any record	Outputs named exactly like the record’s fields

Form field rules

Forms that use the standard validator can read field-level rules from a matrix named Rules. QBO creates it the first time it’s needed, with inputs Template and RuleSet and outputs Rule and Behavior. Add a row with Template set to the form’s name, Rule set to the field name, and a Behavior such as:

• {'required': true} makes the field required.
• {'hidden': true} hides the field.
• {'validateClass': 'qbo-date'} adds validators.

Leave RuleSet blank, because the system sets it. This lets you change built-in forms per environment without editing them.

Validation rules

A validation rule runs whenever a chosen operation (such as Save, Insert, or Update) runs on a chosen kind of record (its class name, such as Process). Set the Validator Plugin to RuleValidator and attach an XSLT Validator. QBO passes it the record’s data plus the parameters of the call, and reads the result:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
    <RuleValidation>
      <xsl:if test="//DateClosed != '' and (count(//ClosedReason)=0 or //ClosedReason='')">
        <Exception>A closed case needs a close reason.</Exception>
      </xsl:if>
      <xsl:if test="count(//DateDue)=0 or //DateDue=''">
        <Warning>This case has no due date.</Warning>
      </xsl:if>
    </RuleValidation>
  </xsl:template>
</xsl:stylesheet>

• <Exception> stops the operation and returns the message as an error.
• <Warning> lets the operation continue and shows the message as an alert.
• Only active rules run.

Because the check runs on the server, it covers forms, imports, workflow steps, and API calls alike. Add scripts to forms if you want faster feedback for users, but don’t rely on them to enforce a rule.

Caution

Rules are cached for 24 hours by default. After you edit a rule, use Purge Cache on its summary page so the change takes effect.

Linked records

A link connects a primary record to a linked record. A typical use is linking document templates to the contacts, organizations, states, or process and workflow templates they apply to. The Linked Objects page lets you link or unlink templates in bulk. The standard list of a record’s children (the list by object query) also returns records linked to it. Links can be grouped into named sets (the link type), and a whole set can be copied to a new name or deleted at once.