Docs‎ > ‎

Reference

This is the CA Live API Creator Reference.   The material here presumes a basic familiarity with the product:
  • 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 API Creator
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   API Creator 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  API Creator/Resources  Used to provide "document model" GET response JSON (e.g, Customers with a set of Orders and a set of Addresses)

 Resources typically automate SQL, but you can specify Resource Types for custom SQL, and to integrate non-SQL data.

 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

Live API Creator provides the following Extensibility services.  Many of these are derived from the underlying Java Script Object Model, created by Live API Creator when you connect to your database.

Note these services can invoke Loadable Logic Libraries: re-usable solutions for patterns.

 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
 Custom Endpoints  Define new RESTful endpoint Resources with potentially no relationship to the data model  API Server
Request Events  Invoked for all requests, e.g., to log requests or alter the request or response  API 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 row object being inserted/updated/deleted/retrieved (your object model is created automatically from the schema).

 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   
 SysUtility  Useful functions for manipulating resources
 @Metadata  Additional attributes provide services for Complex Transaction Handling

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 Logic is like a spreadsheet: you declare expressions for column derivations and table validations... the system watches for changes to referenced data, and reacts to adjust the referencing data - which can chain.   The Tutorial explains how to use them, illustrating these patterns.

  • Use the Log for debugging - it depicts:
    • Rule Execution - logs every rule that fires, including complete row state, with indenting to show multi-object chaining
    • SQL - use this to verify that SQL is expected

  • Use Topics to link your Logic to User Story Behaviors / Acceptance Criteria.

 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 Condition   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 Event Invoke JavaScript action during row processing, before rule execution (formulas, events, validations)  often used to compute primary keys
 Commit Event  Invoke JavaScript action after all rows are processed and all rules have fired often 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


Logic is automatically invoked
You do not call the rules - the system does that automatically when referenced data changes.

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. 

Performance
Adjustments are 1 row "delta" updates, which require that stored values match the rule definitions.  You will need to ensure that your existing data is consistent with the rules, such as with SQL commands like this.


Data Integration

This page describes several of the key services.  See the B2B Example.

 Service Summary Example
 Custom Resources Alias and Projection provide mapping and transformation logic API definition agreement with Partner, or internal system, does not conform to SQL schema
 Multi-Table Resources Support Business Transactions with more than one row type Order with a list of items
 @metadata tag Additional attributes provide services for Complex Transaction Handling Program requests to create or update existing data.

 Program requests to lookup parent data to set foreign keys.
 Business Logic Applied uniformly over all requests Unlike Web Apps where business logic might be unavailable in a button (controller code), logic is applied the uniformly, regardless of whether the request is an interactive program, or another computer
 REST utilities APIs to issue REST calls, including creating resource instances Create a resource instance that corresponds to a Partner API agreement, and post it.


Troubleshooting


 Debugging  Debugging logic
 General  General trouble shooting