Logic

Logic
lac31
In the context of 
CA Live API Creator
, business logic refers to the PUT/POST/DELETE-transactional business logic that API Creator applies when committing a transaction. The rules (your logic) are composed of multi-table derivation, constraint, and event rules. The rules govern update processing, using expressions instead of code.
In this article:
2
Specify Business Logic
You specify your business logic in the following ways:
  •  
    Fill out a form.
     You use forms for parent copies, sum, count, min, max.
  •  
    Provide server-side JavaScript.
     For formulas and validations, you provide an expression, or more generally a function.
You specify business rules with a combination of JavaScript (logic) events and reactive logic. You associate the server-side JavaScript events with tables. 
CA Live API Creator
 passes contextual information to your code, in particular the 
row
 object. You can extend 
CA Live API Creator
 using logic libraries. Reactive logic enforces the bulk of your business rules.
The following image shows this process:
 
You specify business logic as a series of constraint declarations. Declarations are expressions that the runtime system ensures to be true for a transaction to succeed. The logic that you declare in API Creator is bound to your database tables and enforced on all updates against those tables. API Creator automatically reuses the logic across the verbs (insert, update, delete) and the resources that you create over the table.
Logic ensures the integrity of your data when update requests are made. For example, business rules for the following constraints:
  •  
    Derivations. 
    Rules to derive or return a column value (for example, Sum, Count, Formula, Min/Max, and Parent Copy). Reactive programming expressions define the value of a column in a table. They range from simple formulas (product_price * qty_ordered) to multi-table (sum example). API Server watches for changes in referenced data; if detected, it recomputes the derivation in an optimal manner. Watching for changes can become complex, because derivations can chain.
For more information about reactive programming, see Reactive Programming on the Wikipedia website.
  •  
    Validations. 
    Rules to ensure the integrity of the transaction. They are expressions that must be true for a transaction to commit (else an exception is raised). Validations are multi-field and can operate on derivation results (as in this credit_limit example). Each rule is defined on a business entity (Table) and perhaps an attribute (Column). The rule is triggered when a state change occurs (for example, PUT/POST/DELETE operations) on the entity or attribute.
Design Approach
Using Agile as an example:
  1.  
    Identify an epic.
     A system might have several epics, for example, sales entry, and HR management.
  2.  
    Identify a feature,
     such as Place Order.
  3.  
    Identify a user story. 
    Within a Feature, identify multiple user stories, such as Check Credit, Explode Bill of Materials. Your User Stories should be testable.
  4.  
    Identify the behavior.
     Alternative to User Story in some methodologies.
  5.  
    Enter the user story/behavior as a topic.
     Define topics and associate rules to the topics. For each behavior (such as Check Credit), categorize the rules into a topic. 
  6.  
    Define the logic that solves the behavior.
     Define one or more rules that solve the identified behavior, for example, the Check Credit topic.
Often, such as the following example, specifying business logic entails capturing a validation rule and then defining the multiple derivations that provide the data for the validation.
For more information about managing topics, including entering behaviors as topics, categorizing and filtering rules into topics, and entering user stories/behavior as topics, see Manage Topics.
A First Look at Logic
The 
Demo
 API sample illustrates the use and operation of business logic. Logic is expressed as a set of rules that defines what your data means. Like a spreadsheet, API Creator invokes rules in response to changes in the data from PUT, POST, and DELETE requests on base tables.
For more information about the Demo API sample, see Demo API Sample.
Your logic specifications are defined for base tables and are automatically applied to all resources defined over that table. Logic execution is a sophisticated process. It automates complex multi-table dependencies with automatic reuse across use cases, while maintaining enterprise-class performance through SQL reduction/elimination. Logic plans reflect the latest deployed logic, so that compliance and performance are maintained while providing business agility.
Consider the Place Order user story, with the behavior customer's balance cannot exceed their credit limit. The following logic, which looks rather like a requirements document, is 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
API Creator applies derivation logic 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)
Alter, or derive, the value of a specific attribute using derivation rule types. Much like a spreadsheet cell, these derivations become part of a chain of events. The events are called during the processing of a data transaction. These derivations are applied to a specific attribute on a table.
This exercise uses the classic Customer/Order/Invoice to describe each of the derivation rules and how they are applied to an invoice. The following image shows an example invoice:
  
The typical invoice contains company information, customer billing information, customer shipping information, order header (invoice specific), and line item details. Using this template as a guide, the invoice line item has an item#, quantity, details, unit price ($), and Total price ($).
The 
TotalPrice
 is derived using a formula
 
(
row.unitprice
*
row.quantity
). You do not enter the unit price by hand. It is assigned to the Parts inventory system. The next rule to add is a parent copy of
unitprice
from the parts table when you enter the part item number. The parent copy makes a replication of the value at the time of entry (non-maintained) so future price changes do not impact existing orders. Not shown is the
lineitem
discount calculations for this customer using a formula
 
which applies quantity discounts based on customer loyalty. You can also populate the details on the line item using the Parent Copy from part.
The 
SubTotal
 invoice uses a sum on the invoice (order header) itself and 
CA Live API Creator
 uses the s
um(lineitem.TotalPrice)
derivation.
 
The invoice discount
 
is the
s
um(lineitem.discount)
.
 
The Tax/VAT is another formula:
row.subtotal * row.taxrate
. Finally, 
CA Live API Creator
 calculates the grand total using the following formula:
((row.subtotal -row.discount) - (row.tax + row.shipping))
State change means that inserting a new line item, deleting a line item, changing a quantity, or even an item number triggers 
CA Live API Creator
 to recalculate these rules.
Derivations are conceptually similar to spreadsheet cell formulas:
  • Derivations are multi-table, as in the previous example.
  • 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
       
  • API Creator handles chaining, ordering, and dependencies automatically.
  • 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
API Creator creates JavaScript objects, or rows, for each base table. The rows provide accessors for attributes and related data, and automated persistence. API Creator supplies old/new versions of rows to your events and logic, with automatic resource/object mapping. Resource/object mapping means your rules apply to update requests for both custom and default resources.
Early events, row events, regular events, request, and response events are JavaScript entry points to perform user-defined actions. For example, auditing, copying (an order clone), sending mail, and messages. These entry points are complementary to other forms of business logic such as process (workflow) logic, application integration, and decision logic.
You typically use both reactive logic and JavaScript events to meet requirements. API Creator integrates the rules and events by virtue of a common underlying object model that it creates from your schema.
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 do not require new logic. Reactive logic is defined on the tables and columns, and not on a specific service. Automatic invocation ensures it is reused over all relevant User Stories/Behaviors. In the case of the 
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
API Creator's five rules fully dictate the following user stories, which are 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.
There are implications of this declarative approach to logic using reactive logic. The following image shows the logic reuse over behaviors:
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. 
CA Live API Creator
 watch/react-processing is an optimized version of forward chaining. It:
  1.  
    Watches.
     
    CA Live API Creator
     watches for changes in referenced data.
  2.  
    Reacts.
     Determines the attributes dependent on what has changed, including across tables, and adjusts these, in an order that reflects their dependencies.
  3.  
    Chains.
     If detected, 
    CA Live API Creator
     optimally recomputes the derivation. This can become complex, because derivations can chain.
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.
 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 when you save and activate. The rules are maintained in the repository. Manage the rules by way of a RESTful API or by exporting the API.
For more information about exporting APIs, see Import and Export API Definitions.