Docs‎ > ‎API Creator‎ > ‎

Specify your Business Rules

Business logic consists of multi-table computations, validations, and actions such as auditing, cloning, and sending mail. This is complementary to other forms of business logic such as process (workflow) logic, application integration, and decision logic.

To view a video that explains reactive logic, see Videos.

Business rules enforces database integrity on RESTful update requests, for example, business rules for derivations and validations (conditions that must be met for successful transaction commits). You specify business rules with a combination of logic 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 by way of loadable JavaScript librariesReactive logic enforces the bulk of your business rules.

For more information:

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.

The way to approach the problem is quite familiar. The approach is methodology-neutral, but it is easiest to describe it in concrete terms. Agile is popular, so we select it:
  • Identify an Epic. A system might have several epics, for example, sales entry, and HR management.

  • Identify a Feature, such as Place Order
  • Identify a User Story. Within a Feature, identify multiple user stories, such as Check Credit, Explode Bill of Materials.  All User Stories should be testable
  • Identify the Behavior. Alternative to User Story in some methodologies.
  • Enter the User Story / Behavior as a topic. Define topics and associate rules to the topics. You associate a rule to a topic on the Manage, Rules page. For each behavior (such as Check Credit), enter it as a topic. 
For more information about categorizing rules into topics and filtering rules by topics, see Topics.
  • Define the logic that solves the behavior. Define one or more rules that solve the identified behavior, for example, the Check Credit topic.
In many cases, such as the following example, 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 Business Logic Demo 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 the most familiar form of business logic and are expressions that must be satisfied to commit transactions. Without the validations, an exception is thrown and the transaction is rolled back. Validations can be simple single-attribute or multi-attribute. For example, the following Customer Validation has a multi-attribute requirement:

balance < credit_limit

For more information about validations, see Validations.

  • Derivation Logic

Derivation logic is applied to individual column attributes. Derivations and events are more valuable than validations, per dependency/re-use automation. Derivations include multi-table derivation rules. For example, the following rule 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:

  • Derivations are multi-table, as in the previous example.
  • Derivations can chainboth 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 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 one-row update, not an aggregate query.

    For more information:

    • Event Logic
    Uses JavaScript to address requirements such as auditing, copying (for example, 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 through 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. Dialogs make it simple to define, and the system produces this documentation automatically. 

    Logic is transparent documentation. As a business user and IT, you can partner and find missing/incorrect elements using the logic.

    For more information:

    Logic Re-use over Behaviors

    Significant value is realized in the next User Story/Behavior, for example Change Order Item - Reassign Product. Related User Stories typically require no new logic 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. 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 five rules fully dictate 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.
    There are implications of this declarative approach to logic using reactive logic.

    Example: Change Item Quantity

    Use this example to explore business logic. When you update the Line Item qtyOrdered, the resultant logic recomputes the Order.amountTotal and Customer.balance, and checks the credit. Live API Creator watch/react processing is a highly-optimized version of forward chaining. It:
    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.
    For more information:
    • About change management, including when Live API Creator invokes and executes logic, see Change Management.
    • About how the "A First Look at Logic" works, designed to address Place Order/Check Credit, also solves Change (PUT) qtyOrdered, see the Rules Animation Doc video.
    The Rules Animation Doc video illustrates the following:
    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. Iterating and altering the logic computes a new execution order. This eliminates the time-consuming study of existing code to determine where to introduce new code, which is the main hassle of maintenance.

    Derived attributes are stored in the database. Performance optimizations presume the stored data is correct.

    Important! When you introduce new columns (for example, the customer balance), bring the database into compliance with the rule.

    For more information:

    Manage Rules

    Reactive Logic is active as soon as you save and activate. The rules are maintained in the Repository. Manage the rules by way of a RESTful API or by Project Export. 

    Test your Logic

    Test your logic using the REST Lab and Data Explorer. After the rules execute, you can view logging information to understand what rules fired and what SQL was issued.

    For more information:

    More Information

    For more information about:
    • The background of reactive logic, and how it operates , see Reactive Logic.
    • How to use reactive logic to address complex transactions, see the Tutorial.
    • Key patterns in leveraging reactive logic, see Logic Patterns.
    Subpages (22): View All