Docs‎ > ‎CA Live API Creator‎ > ‎

Rules

Business rules enforce database integrity on RESTful update requests - derivations and validations (conditions that must be met for successful transaction commits).  

Rules are specified with a combination of Events and Reactive Logic.

Events are server-side JavaScript that you associate with tables.  Contextual information is passed to your code, in particular the row object.  Extensibility is provided via loadable JavaScript libraries.

The bulk of your business rules are enforced with Reactive Logic, which operates as follows:
  1. You bind spreadsheet-like expressions (or, more generally, JavaScript functions) to database tables and columns

  2. 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.

  3. 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.



Design Approach

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:

Identify an Epic

You begin by identifying your epics. A system might have several epics, for example, sales entry, and HR management. 

Identify a User Story 

Within an epic, you identify multiple user stories, such as Place Order, Fill Order and Change Order.

Identify a Behavior

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:

  • Validation Logic

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

  • Derivation Logic
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:
  1. Derivations are multi-table, as in the example above

  2. 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)


  3. Chaining, ordering and dependencies are automatically handled (further described below)

  4. Derivations can include if/else logic, state transition logic, and reference related data

  5. 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

  • Event Logic - Uses JavaScript to address requirements such as auditing, copying (e.g., an order clone), or invoking a web service or a business rules engine.
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.

Resource/Object Mapping means your rules apply to update requests for both Custom and Default resources.

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:
  1. Place Order – the balance is increased, and checked against the credit limit
  2. Change customer credit limit – but not fall below the current balance
  3. Delete Order – the balance is reduced for unpaid orders
  4. Pay Order – the balance is reduced
  5. UnPay Order – the balance is increased
  6. Reassign Order to a new customer – new customer balance increased, old balance decreased (for unpaid Orders).
  7. Reassign a Line Item to a different Product (see above)
  8. Add a Line Item – adjust order and customer, with credit limit check
  9. Delete a Line Item – adjust order and (for unpaid orders) customer
  10. Change Line Item Price – adjust order and customer, with credit limit check
  11. Change Line Item Quantity – adjust order and customer, with credit limit check.
  12. 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 Order.amountTotal and 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:
  1. Watch: Detect what has changed

  2. React: Determine the attributes dependent on what has changed - including across tables -  and adjust these, in an order that reflects their dependencies

  3. Chain for further dependencies
This video shows how the "First Look" logic above - designed to address Place Order / Check Credit - also solves Change (Put) qtyOrdered:
  1. The amount derivation references qtyOrdered, so it is recomputed
  2. The amountTotal references amount, so (per chaining), it is recomputed (SQL automated)
  3. The balance references the amountTotal, so it is recomputed
  4. The validation references the balance, so it is re-evaluated (failure results in rollback and exception)

Iterations

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.


Testing

You can use the RESTLab and the Data Explorer to test your logic.

After the rules execute, you can use the Log to understand what rules fired, and what SQL was issued.


Resources

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