Developing APIs‎ > ‎Extensibility‎ > ‎

Logic Event Rule Types

Events are server-side JavaScript-code business logic, providing access to external/reusable functions by way of Nashorn, an open-source implementation of JavaScript. They are a key architectural element, providing:

  • Re-use. Table events are re-used over all resources built on that table. When Live API Creator receives resource updates, they are de-aliased onto the underlying base table objects.
  • Encapsulation. Live API Creator automatically invokes event logic as updated requests are processed.

You can:

  • Perform additional processing using events. For example, you can use an event to insert (Audit) changes for the current entity, call an external resource, send email, update a calendar system, post a message on a queue, call a push notification engine, or process additional custom logic. Events can begin with the incoming request, the final response, and early and post-commit processing on a transaction.
  • Perform additional logic by combining events with resources (user defined endpoints to external systems). For example, you can return the lat/long coordinates to be used in a Google map for product delivery by using an event that passes a customer's address to a resource which in turn calls Google Geocode.

For more information:

  • About resource/object mapping, including de-aliasing column names, and encapsulations, see Logic Execution.
  • About Nashorn, see Nashorn.

Specify Event Firing

You can specify when the event is fired. Events interact with other logic and fire at predetermined times during logic execution, depending on the event type:

  • Normal. Fires after row-logic is completed. The row data reflects derivation results. You can change the row, but you must ensure that required logic is executed using logicContext.save().
  • Early. Fires before your logic executes. The row data is not subjected to formulas and other derivations. You can change the row, and the changes are subjected to validations, other chained logic, and saved.
  • Commit. Fires after row-logic is completed for all the rows in the transaction. The rows reflect logic processing. You cannot change the rows.

For more information:

Rules vs. Events

Rules reduce the amount of code you must write. Using rules requires that you transition to "think spreadsheet". Use rules before you build your events. Events are a complement to the other declarative forms of rules. They address issues not addressed by rules and have unlimited flexibility.

"Think Spreadsheet" Rules Example

The following is a common example. Assume you need a sum (or count) of child rows for a parent, for example, a sum of unpaid order amounts. Events are a familiar concept, so experienced programmers may envision the following code, perhaps as part of the Add Order use case, to adjust sums and counts:
Define Order event MaintainCount as
if (logicContext.initialVerb == 'INSERT' && row.isPaid == false) { // row is the order
customer = row.customer; // parent accessor
customer.balance += row.amountTotal;
logicContext.update(customer);
}
Consider the other use cases:
  1. Delete Order: Decrement the count - if the order isPaid.
  2. Change Order.isPaid: Watch for such a change, and if you detect it, adjust the sum by amountTotal.
  3. Change Order.amountTotal: Watch for such a change, and if you detect it, adjust the sum by the difference.
  4. Reassign Order: Often overlooked, reduce the old customers' balance, increment the new one, only if the order isPaid.
If the qualification condition or summed field (amountTotal) is itself derived, perhaps from still another table, the code can get complicated. Define a sum or count and all of the boilerplate code to address the use cases above are handled without error. Sums and counts operate just like spreadsheets:

 SpreadsheetReactive Logic
UserDefines cell formula:
Cell A =
    Sum(ColumnB)
Defines database column:
Customer.balance =
      sum(orders.amountTotal where paid = false)
API CreatorWatches for changes:
  • ColumnB changes
  • ColumnB new rows
  • ColumnB deleted rows
Watches for changes:
  • amountTotal changes
  • paid changes
  • Foreign Key changes (Orders.CustomerName)
  • Inserted Orders
  • Deleted Orders
 Reacts to changes:
  • Adjust CellA
Reacts to changes:
  • Adjust Customer.balance (SQL and transaction management)

Use Events

You specify your logic in server-side JavaScript. Your logic is passed key information required for its operation. The logic engine invokes the following variables on every update, providing key contextual information:

  • row. The row object reflects client changes from JSON, and all logic processing. It has attributes for every column, so you can refer to a order's row.amount_total. It also provides role accessors, so you can refer to an orders' row.customer.balance, or obtain a collection of row.lineitems (a collection of lineitem rows). Rows also provide persistence to read/alter data.
For more information about the row object, see Row Objects.
  • oldRow. The oldRow objects reflects the row before the transaction started. This object is from the database read. It has the prior values of the object being updated, so you can detect changes.
  • logicContext. The logicContext object provides many services, such as verb (insert, update or delete), services to read and write data (including logic enforcement), create new objects, event logging, etc.

For more information about the logicContext object, see The logicContext Object.

  • logic.sys. System methods, including InsertIntoFrom, allocateFromTo, and findWhere.

For more information about the system methods (rule/logic types), see Rule Types.

Like all JavaScript rules, events have access to the standard variables including row, oldRow, and logicContext.

For more information:

Logic Event Examples

A typical example is an auditing event. The use of the current/old bean in making your logic conditional:

if (row.amount_total != oldRow.amount_total)
  SysLogic.insertChildFrom("purchaseorder_audit", logicContext);

Event Context

Live API Creator passes contextual variables to your events, such as row, oldRow, and logicContext. Live API Creator pre-supplies methods, identified with SysLogicYou can also invoke JavaScript methods, including systems supplied ones.

Database validation depends on your validation logic, so the system must ensure this is executed after any changes you make. This applies to events. API Creator can execute update logic multiple times, but associated events fire only once per transaction.

For more information:

  • About the logicContext object, including how to update an object using the touch method, see The logicContext Object.
  • About system methods, see Rule Types.
  • About a list of the methods, including JavaScript context variables, see Quick Reference.