enforce database integrity on RESTful update requests - derivations
(conditions that must be met for successful transaction commits).
Rules are specified with a combination of Events
and Reactive Logic.
is passed to your code, in particular the row
The bulk of your business rules are enforced with Reactive Logic, which operates as follows:
- On RESTful updates, (Post, Put, Delete), the system:
- Watches for changes to referenced data,
- Reacts to adjust referencing data,
- which may Chain to other rules per this video.
- Chaining includes references in other tables - SQL and transaction bracketing are automated
Reactive Logic has key differences to conventional procedural code:
| Key Difference|| What it means || Why it matters|
| Automatic Invocation|| The API Server (not your code) calls the logic, e.g., changing a LineItem Quantity adjusts the Amount, without the need to explicitly invoke such logic|| eliminates errors where certain paths might fail to invoke required logic|
| Automatic Chaining|| Changes trigger other changes, e.g., changing a Line Item Quantity adjusts the Amount, and that chains to adjust the Order total.|| simplifies maintenance, since ordering is dictated by dependencies - recomputed on each change|
| Automated SQL|| Watch/React includes multi-table logic (in the example above, you do not need to issue the SQL to retrieve the order)|| SQL is a chore to code, and to optimize (pruning, caching)|
The net result is that the logic shown here is fully executable.
Update logic is complementary to other forms of business logic such as process (workflow) logic, application integration, and decision logic.
You can jump directly to the Reference, which provides links to each rule type, as well as tutorials and training. After reading this page, you may also wish to explore the architecture. This page provides a basic background on business logic - its key elements, its key characteristics.
Use the API Creator
(illustrated above) in your Browser to specify logic (sum example shown here
). Changes are affected instantly, without the need for code generation or deployment.
Events are a pattern likely to be familiar to most programmers. Reactive Logic makes things remarkably simpler, but there are a different programming model (see the table above).
The way to approach the problem is quite familiar. The approach is methodology neutral, but it's easiest to describe it in concrete terms. Agile is popular, so we select it:
You begin by identifying your epics. A system might have several epics, for example, sales entry, and HR management.
Within an epic, you identify multiple user stories, such as Place Order, Fill Order and Change Order.
Within Place Order, you identify the behaviors, aka requirements, aka exit criteria. For example, Place Order might include Verify No Empty Orders and Check Credit. A Behavior should be testable.
Enter the Behavior as a Topic
API Creator supports the ability to define Topics, and link them to one or more rules. So, for each behavior (such as Check Credit), enter it as a Topic.
Define the Logic that solves the Behavior
Finally, you define one or more rules that solve the identified behavior, Check Credit.
In many cases, such as the example below, this will entail capturing a Validation rule, and then defining the multiple derivations that provide the data for the Validation.
A First Look at Logic
The sample problem
(Customers, Orders and Parts) illustrates the use and operation of business logic. Logic is expressed as a set of spreadsheet-like expressions that define what your data means.
Consider the User Story Place Order, with the behavior Customer's balance may not exceed their credit limit. The following logic, which looks rather like a requirements document, is fully executable:
Validations are expressions that must be satisfied to commit transactions (else an exception is thrown and the entire transaction is rolled back). Far beyond simple single-attribute validations, the requirement is multi-attribute validations, such as this Customer Validation:
balance < credit_limit
Applied to individual column attributes. Validations are the most familiar form of business logic, but derivations and events are the most valuable, per dependency / re-use automation noted below. Derivations here include multi-table derivation rules such as in this rule which defines the balance as the sum of the unpaid order totals:
Customer.balance = sum(purchaseorder.amount_total where paid = false)
Derivations are conceptually similar to spreadsheet cell formulas. Note that:
- Derivations are multi-table, as in the example above
- Derivations can chain, both to validations, and other derivations:
Purchaseorder.amount_total = sum(lineitem.amount)
Lineitem.amount = qty_ordered * product_price
Lineitem.product_price = copy(product.price)
- Chaining, ordering and dependencies are automatically handled (further described below)
- Derivations can include if/else logic, state transition logic, and reference related data
- Derivations are highly optimized to eliminate / optimize SQLs. For example, changing an orders's date does not retrieve the customer, and paying an order adjusts the customer with a 1-row update -- not an aggregate query
You typically use both Reactive Logic and Events to meet requirements. They are integrated by virtue of a common underlying Object Model, created directly from your schema. You access this via Row Objects
You declare the logic in the Browser as shown at the top of this page. Dialogs
make it simple to define, and the system produces this documentation automatically.
So logic is not only executable, it is transparent documentation that enables Business Users and IT to partner and find missing / incorrect elements.
Logic Re-use over Behaviors
Significant value is realized in the next User Story / Behavior, e.g., Change Order Item - Reassign Product. You will often find such related User Stories require no new logic. That is because Reactive Logic is defined on the tables and columns - not a specific service. Automatic Invocation ensures it is re-used over all relevant User Stories / Behaviors.
That is a significant statement. In the case of our
customer.balance rule, this means that this one statement obligates the system respond to all of the following:
- Order inserted - balance increased
- Order deleted - balance decreased (if not paid)
- Order paid - balance decreased
- Order unpaid - balance decreased
- Order amountTotal changed - balance adjusted
- Order reassigned to different customer - balance increased for new customer, decreased for old
Our 5 rules fully dictates the following User Stories - the complete order entry system:
- Place Order – the balance is increased, and checked against the credit limit
- Change customer credit limit – but not fall below the current balance
- Delete Order – the balance is reduced for unpaid orders
- Pay Order – the balance is reduced
- UnPay Order – the balance is increased
- Reassign Order to a new customer – new customer balance increased, old balance decreased (for unpaid Orders).
- Reassign a Line Item to a different Product (see above)
- Add a Line Item – adjust order and customer, with credit limit check
- Delete a Line Item – adjust order and (for unpaid orders) customer
- Change Line Item Price – adjust order and customer, with credit limit check
- Change Line Item Quantity – adjust order and customer, with credit limit check.
- Combinations of these, such as altering the quantity and product.
Let's further explore the implications of this declarative
approach to logic using Reactive Logic.
Example: Change Item Quantity
This example will enable us to explore business logic. When a Line Item
qtyOrdered is updated, the resultant logic (shown here) recomputes the
Customer.balance, and checks the credit.
This is fully automated - no code is required. The system processing is essentially a highly optimized version of forward chaining:
- Watch: Detect what has changed
- React: Determine the attributes dependent on what has changed - including across tables - and adjust these, in an order that reflects their dependencies
- Chain for further dependencies
shows how the "First Look" logic above - designed
to address Place Order / Check Credit - also
solves Change (Put) qtyOrdered:
- The amount derivation references
qtyOrdered, so it is recomputed
amount, so (per chaining), it is recomputed (SQL automated)
balance references the
amountTotal, so it is recomputed
- The validation references the
balance, so it is re-evaluated (failure results in rollback and exception)
Logic chaining execution order reflects dependencies between the rules. So, when you iterate and alter the logic, a new execution order is computed. This eliminates one of the main hassles of maintenance - time-consuming study of existing code to determine where to introduce new code.
Important Note: derived attributes are physically stored in the database. Important performance optimizations
presume the stored data is correct, so, when you introduce new columns (e.g., the customer balance), you must bring the database into compliance with the rule. This discussion
illustrates how to do this, using SQL.
After the rules execute, you can use the Log
to understand what rules fired, and what SQL was issued.
In addition to this page, please see:
- Reactive Logic - explore the background of Reactive Logic, and how it operates
- Tutorial - see how Reactive Logic can be used to address remarkably complex transactions
- Logic Patterns - key patterns in leveraging Reactive Logic