Docs‎ > ‎

Reference

This is the Espresso Logic Reference.   The material here presumes a basic familiarity with Espresso:
  • these videos provide a quick demo, illustrating the basic product use and objectives
  • basic product usage is illustrated by the Key Learnings that start automatically when you first use Espresso
This page provides various quick-reference indices to frequently accessed topics.  

You can access detailed API information here.

Resource End Points

RESTful Resource End Points are determined from the objects shown below.  Note that all of the Resource End Points except Custom are automatically provided by the system.

 Type  Obtained from  Programming Notes
 Base Table  Schema   Espresso reads Schema to build the Object Model with Accessors for attributes and related objects, and Logic Events for Insert, Update and Delete operations

 Live Logic: you can define transactional business logic as described below
 Custom Resources  Espresso Designer  Used to provide "document model" GET response JSON (e.g, Customers with a set of Orders and a set of Addresses)

 Updates are governed by Live Logic (see Resource / Object Mapping)
 View Table
 Schema  Used for complex SQL
 
 Updates are not subjected to Live Logic
 Stored Procedure  Schema  Per security, you can access Stored Procedures using REST.
 Logic Administration Objects  Built in  APIs to obtain the list of tables, resources and to authenticate a user



JavaScript Extension Points

Espresso provides the following Extensibility services.  These are largely derived from the Java Script Object Model, created by Espresso when you connect to your database.

 Type  Description  Applies to
 Formula and Validation Logic  Logic is specified in JavaScript for access to if/else conditional flow, functions such as Date arithmetic, and so on.  Formulas and Validations, based on the Object Model
 Logic Event Rule Type  Invoke JavaScript action (often an extensible service); can execute during or after row PUT/POST/DELETE processing, or on commit (after all rows are processed).  For example, you might want to send mail or start workflows on certain updates.  Tables, based on the Object Model
 Resource Row Event  Invoked as each row is returned, e.g., add attributes or filter the row  Resources, based on the Object Model
 JavaScript Resource Type  Materialize data using JavaScript, e.g., by invoking REST services to build a request that integrates data from other systems  Resources
 HTTP Handler  Define new RESTful endpoint Resources with potentially no relationship to the data model  RESTful server
 Request Event  Invoked for masked request, e.g., to log requests or recompute responses  RESTful Server


JavaScript Context

Your JavaScript has access to Libraries, both pre-supplied and your own extensions.

The following are set when JavaScript logic is invoked.  See syntax notes here.

 Variable  Description  Applies to
 logicContext  Services for creating, reading, updating and deleting rows.
  Provides information about key logic state, including verb, nest level

Important - please see the api documentation
 logic (all rule types listed in the Live Logic section, below)
 log  for printing to the log, accessed via helpers, e.g.,

log.debug("message to log; row: " + row);
log.finer("more verbose - but < finest");
log.error("more serious message");
logicContext.logDebug("msg with object"); // recommended
 all
 out  for printing to sys out, e.g.

out.println("message to log")
 all
 req  The request object provides access to the HTTP request, including ApiKey, resource name, arguments, etc.  Access the latter as req.getUserProperties().get("argName"); for arguments supplied as arg.argName=true  all
 row  The object being inserted/updated/deleted/retrieved

 This provides access to attributes and related parent objects
 logic
 oldRow  Prior values of the object being updated. This is only defined for updates.

 Provides access to attributes and related parent objects
 logic
 containingRow  Provides access to containing row instance  resources
 tableRow Provides access to the database record after security applied, changes ignored. Resource Row Event
 parentRow Provides access to the containing row instance in a resource event. Resource Row Event
 resource Provides access to the resource object.  Resource Row Event
 SysUtility JavaScript object used to retrieve a resource, or invoke another REST service. all
 json In Request Event (Request) this is a Java String of the inbound content.  Use String(json) to create a real JavaScript object.
 In Request Event (Response), this is a Java Object accessible to JavaScript of the outbound JSON.
In a future release, these will be true JavaScript objects, but until then some care is needed.
 



Services

The engine has several services that can be used for additional interaction.

 The LogicContext object
 This object is available in all JavaScript rules, and gives you access to a lot of information, and behavior.
 System Methods  These can be used in actions, validations and formulas as required
 Data formatting  Reference for the formatting of numbers and dates
 Admin Data Metadata services



Data Access

You can access data via simple Persistence APIs using LogicContext, or via REST.

 Persistence
 Services to read, insert, update and delete rows
 Rows Rows sent/received in Object Persistence.  In addition to persistence, provide access to attributes and related objects
 RESTful Access Services for RESTful access to other servers, including important contrast between Object / RESTful access


Live Logic

This summarizes the Reactive Logic and Java Script Events you can use to express your transactional Business Logic for PUT, POST and DELETE operations:  
  • Events are familiar, based on 

    Think Spreadsheet

    Caution: learn to think spreadsheet, to save meaningful amounts of time by using Reactive Logic (Sums, Counts, Formulas) rather than events.
    the automatically created Object Model via the row object

  • Reactive is like a spreadsheet: you declare expressions for column derivations and table validations... the system watches for changes to referenced data, and adjusts the referencing data.   The Tutorial explains how to use them.

 Rule/Logic Type        Description  Example

 Formula
 
Derive attribute value using other attributes in that table, or parent table (changes are propagated).   for conditional assignment, use JavaScript if/else, or the ternary operator (? :).  Derive Lineitem.amount as 

 return row.part_price * row.quantity_ordered


Derive 
product_billofmaterials.value as

return row.kit_number_required * row.product.price


Derive order.DueDate as

if (row.due_date === null) {
   return new Date(moment(row.placed_date).add('months', 1)
else
   return row.due_date; // no change

 Parent Copy
 
Derive child attribute value from parent attribute value (unlike formula references, parent changes are not propagated)

 Derive Lineitem.Price as 

 ParentCopy(product.price)

 Sum
 
Derive parent attribute value by summing designated child attribute, with optional Child Qualification Condition  Derive Customer.balance as

Sum(ordersList.amount_un_paid where is_ready = true)
Sum(children where anAttribute != null)

 Count

Derive parent attribute value by counting designated child rows, with optional Child Qualification Condition   Derive Customer.big_order_count as 
 
Count(ordersList where amount_total > 100)
 Min/Max  Derive parent value as the min/max of designated child rows, with optional Child Qualification Condtion   Derive Customer.maxOrder as 

max(ordersList where is_ready = true)


 Validation

Multi-attribute expression of class/parent attributes that must be met for a transaction to succeed (else exception is thrown); can execute as transaction rows are processed, or at commit time after all rows are processed.

 Validate Customer.CheckCredit as

row.balance < row.credit_limit


 Commit Validation Multi-attribute expression of class/parent attributes that must be met for a transaction to succeed (else exception is thrown); executes at commit time so your validation code sees the results of all rule executions for all rows (e.g., sums, counts) Validate Purchaseorder.NotEmpty on commit as 

return row.item_count > 0

More information here.

 Managed Parent
 Automatically insert a parent object if it does not already exist.
 Create parent for GroupBy, e.g., empsales to track total sales for employee each month

 InsertInto  Copy one or more source rows to a target class.  Useful for auditing, deep copy   if (row.baseSalary != oldRow.baseSalary)
SysLogic.insertChildFrom(
"employee_audits", logicContext)

 Allocation   Allocates a provider amount to recipients, creating allocation objects (a provider / recipient junction) for each such allocation  
SysLogic.allocateFromTo(
 logicContext,
 SysLogic.findWhere(row.paymentCustomer.ordersList,
    "row.amount_un_paid > 0", "placed_date a"), 
 "payment_order_allocations", 
 "amount_un_disbursed");


 Event
 
Invoke JavaScript action (often an extensible service); can execute during or after row processing, or on commit (after all rows are processed)

 see example above
 Early EventInvoke JavaScript action during row processing, before rule execution (formulas, events, validations) often used to compute foreign keys
 Commit Event Invoke JavaScript action after all rows are processed and all rules have firedoften used to send mail, start business processes, send updates to other systems, etc.
findWhere  Returns a filtered, sorted collection (used in events)  
SysLogic.findWhere(
    row.paymentCustomer.ordersList,
    "row.amount_un_paid > 0",
    "placed_date a")
 Syntax  Formulas, events and validations must follow this syntax.
 
     

Key Notes:

Logic is unordered
The Business Logic Engine invokes your rules automatically during transaction processing, ordered by their dependencies

Old Values
Formulas, Validations and Actions can reference not only row.attribute values, but use oldRow.attribute values, enabling you to specify state transition logic (eg, logic based on data changes)

Null values
Support is provided to simplify null value checking as described here

logicContext
Provides access to runtime services and state, such as logicNestLeveluseCaseName, services to create, read, update and delete rows, etc. Full reference here.

Logic Design Patterns 
Most requirements can be met using these patterns which leverage Forward Chaining; see the Tutorial and SysLogic.

Extensibility
Rules can invoke JavaScript, enabling you to meet requirements not solved by Core Rules.  Judicious design can result in reusable logic, as illustrated by the pre-supplied BusinessLogic services for allocation and copy. 


Data Integration

Data Integration is a key element of business logic.  This page describes several of the key services, and some examples.


Troubleshooting


 Debugging  Debugging logic
 General  General trouble shooting