CA Live API Creator 4.1

5.4 5.3 5.2 5.1 5.0 4.1 4.0 3.2 3.1.1 3.1
English

Quick Reference

Quick Reference
calac41
Basic API Creator usage is illustrated by the learnings that start automatically when you first use API Creator. This article provides quick-reference indices to frequently accessed topics.
You can access detailed internal javadoc by downloading the .
 
Prerequisite:
 Before using this quick reference, ensure that you have a basic familiarity with 
CA Live API Creator
.
In this article:
 
 
Resource Endpoints
 
CA Live API Creator
 determines the RESTful endpoints, or resources, from the objects shown in the following table. 
CA Live API Creator
 provides the endpoints, except the endpoints that you explicitly define using API Creator:
Type
Obtained from
Programming Notes
Base Table
Schema
 
CA Live API Creator
 reads the schema to build the JavaScript object model, with accessors for attributes and related objects, and logic events for INSERT, UPDATE, and DELETE operations. API Creator creates your JavaScript object model automatically from the schema. This provides access to attributes and related parent objects.
 
Reactive logic:
 You can define transactional business logic.
For more information:
  • About row objects and about base tables, see Row Objects.
  • About the JavaScript object model, see Row Objects.
Resources that you explicitly define using API Creator
API Creator/resources
Used to provide document-model GET response JSON (for example, Customers with a set of Orders and a set of Addresses).
Table-based resources typically automate SQL handling, but you can use custom SQL and integrate non-SQL data by specifying resource types. Reactive logic and resource/object mapping govern updates.
For more information:
View Table
Schema
Used for complex SQL. Updates are not subjected to reactive logic.
Stored procedure
Schema
Per security, you can access stored procedures using REST.
Custom endpoint
API Creator (from the resources that you explicitly define using API Creator 
Create RESTful endpoints with potentially no relationship to the data model. Indicate that requests to your custom endpoint require authentication and can return JSON and other formats, such as HTML.
For more information about how to create a custom endpoint, see Manage Custom Endpoints.
Logic administration objects
Built in
APIs to obtain the list of tables and resources and to authenticate a user.
For more information, see System REST Endpoints.
JavaScript Extension Points
 
CA Live API Creator
 includes the following extensibility services. 
CA Live API Creator
 derives many of these services from the underlying JavaScript object model. The extensibility services can invoke loadable logic libraries.
For more information:
  • About extensibility, see Extensibility.
  • About the logic libraries, including how to add user libraries and start using its facilities in your rules, see Logic Libraries.
 The following table lists the JavaScript extension points that are included:
JavaScript Event
Description
Applies to
Formula rules and validation rules
Access if/else conditional flow, functions such as date arithmetic, by specifying logic in JavaScript.
Formula and validation rules, based on the JavaScript object model.
For more information:
Event rules
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 JavaScript object model.
For more information, see Event Rule Types.
Resource row events
Invoked as each row is returned. For example, add attributes or filter the row.
Resources, based on the JavaScript object model.
For more information, see Resource Row Events.
JavaScript resources
Not explicitly bound to tables, such as other web services. Can call outside REST service and connect to multiple servers of any type.
Resources
For more information, see Define JavaScript Resource Types.
Custom endpoints
RESTful endpoints that do not need to map to a specific data model.
API Server
For more information, see Manage Custom Endpoints.
Request events
Invoked for all requests. For example, to log requests or alter the request or response.
API Server
For more information about the event handlers you can use to complement your rules, see Event Handlers.
Custom authentication provider
Manages API users access to your API using corporate security services.
API Server
For more information about custom authentication providers, see Authentication Providers.
JavaScript Context Variables
Your JavaScript has access to the libraries that 
CA Live API Creator
 includes and to your own extensions. The following context variables are set when 
CA Live API Creator
 invokes JavaScript logic:
 For more information about the libraries, see Logic Libraries.
Variable
Description
Applies to
log
For printing to the log, accessed by way of helpers, for example:
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, for example:
out.println("message to log")
All
req
The 
request
object provides access to the HTTP request, including API key, resource name, arguments, etc. Access the latter as 
req.getUserProperties().get("argName");
for arguments supplied as 
arg.argName=true
.
For more information about the request object, see The req Object.
All
row
The 
row
 object that you are inserting/updating/deleting/retrieving.
For more information about the row object, see Row Objects.
Logic
oldRow
Reflects the row before the transaction started. Provides access to attributes and related parent objects.
CA Live API Creator
 defines this variable only for updates.
Logic
containingRow
Provides access to data from the containing row instance.
Resources
tableRow
Provides access to the database record after security applied, changes ignored.
Resource row events
For more information about resource row events, see Resource Row Events.
parentRow
Provides access to the containing row instance in a resource event.
Resource row events
resource
Provides access to the resource object. 
Resource row events
json
In a request event (request), this is the raw Java string of the inbound content that the client sends. Create a real JavaScript object using 
String(json)
. In a request event (response), this is a Java object accessible to JavaScript of the outbound JSON.
For more information about the 
json
variable and how 
CA Live API Creator
 invokes request events (request and response), see Event Handlers.
 
Services
You can use the following API Server services for additional interaction:
API Server Services
Description
The 
logicContext
object
Use in your JavaScript rules. Provides access to runtime services, to runtime state, and to services to create, read, update, and delete rows. Provides information about logic state, including verb and nest level.
This service applies to logic (the rule types listed in the "Reactive Logic" section of this article).
For more information about this object, see The logicContext Object.
The 
SysLogic
object
Access to logic services. Includes methods that you can use in validation rules, formula rules, and event rules.
For more information about this object's methods, see The SysLogic Object.
Admin data
Retrieve information about an API using the system REST endpoints that 
CA Live API Creator
 provides. 
CA Live API Creator
 provides these endpoints as metadata services.
For more information about these endpoints, see System REST Endpoints.
The 
SysUtility
object
Provides access to services, such as retrieving a resource or invoking another REST service.
For more information about the 
SysUtility
 object, see The SysUtility Object.
@metadata
action tags
Additional attributes provide services for complex transaction processing.
For more information about complex transaction processing, see Complex Transaction Processing.
Data Access
 Access data by way of simple persistence APIs using the 
LogicContext
 object or by way of REST:
  •  
    Persistence.
    Services to read, insert, update, and delete rows.
  •  
    Rows.
     
    CA Live API Creator
     transforms resource rows to table rows for business-logic processing and persistence.
    For more information about rows, see Customize your API.
  •  
    RESTful access.
     Services for RESTful access to other servers.
    For more information about RESTful access, including the difference between accessing data using the LogicContext object and REST, see The logicContext Object.
For more information about persistence, see The logicContext Object.
Reactive Logic
You can express your transactional business logic for PUT, POST, and DELETE operations using reactive logic and JavaScript events. Reactive logic is like a spreadsheet. You declare expressions for column derivations and table validations. 
CA Live API Creator
 watches for changes to referenced data and reacts to adjust the referencing data, which can chain. Events are familiar, based on the automatically-created JavaScript object model by way of the row object.
Debug using the log and link your logic to user story behaviors/acceptance criteria using topics.
The following table lists the rule types:
Rule Type
Description
Example
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
Derive child attribute value from parent attribute value.
Changes to the parent attribute are not propagated to the child attribute.
Derive 
Lineitem.Price
 as:
ParentCopy(product.price)
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)
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)
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)
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
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 (for example, sums, counts).
Validate 
Purchaseorder.NotEmpty
 on commit as:
return row.item_count > 0
For more information about commit validation, rule/logic type, see the Reactive Logic Tutorial.
Automatically insert a parent object if it does not already exist.
Create parent for 
GroupBy
, for example, 
empsales
to track total sales for employee each month.
Invoke JavaScript action (often an extensible service); can execute during or after row processing, or on commit (after all rows are processed).
SysLogic.allocateFromTo(
logicContext,
SysLogic.findWhere(row.paymentCustomer.ordersList,
"row.amount_un_paid > 0", "placed_date a"), 
"payment_order_allocations", 
"amount_un_disbursed");
Early Event
Invoke JavaScript action during row processing, before rule execution (formulas, events, and 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 email, start business processes, and to send updates to other systems.
 
Notes:
 
  •  
    Rules syntax.
     Formula rules, event rules, and validation rules must follow this syntax.
  •  
    Logic is unordered
     
    .
     The business logic engine invokes your rules automatically during transaction processing, ordered by their dependencies. API Server invokes the logic and calls the rules automatically when referenced data changes.
    For more information about rules, see Learning Rules.
  •  
    Old values.
     Formulas, validations, and actions can reference not only 
    row.attribute
     values, but use 
    oldRow.attribute
     values. You can specify state transition logic (for example, logic based on data changes) using formulas, validations, and actions.
  •  
    Null values.
     You can check for null values.
    For more information:
    • About null values and marking a formula as Just In Time (JIT), see Formula Rule Type.
    • About JIT, see the following Just In Time note.
  •  
    Just In Time.
     You can specify derivation rules (formula, sum, count, and min/max) as JIT. If the value in the database is null, the rule fires on first retrieve and is stored in the database. This is useful, for instance, to recompute values without incurring the cost up front.
    Specifying derivation rules as JIT can affect performance whenever new values are computed on the fly.
    For more information about JIT, including how to specify to have 
    CA Live API Creator
     recompute your rules when/as it detects null vales, see Synchronize Data with Logic.
  •  
    Logic design patterns
     
    .
     Use these patterns to meet most requirements, which leverage forward chaining.
    For more information:
  •  
    Performance
     
    .
     Adjustments are one-row "delta" updates, which require that stored values match the rule definitions. Ensure that your existing data is consistent with the rules, such as with SQL commands.
    For more information:
System Methods
The 
SysLogic
 object includes the following methods. You can use these methods in event rules, validation rules, and actions.
For more information about the 
SysLogic
 object, see The SysLogic Object.
Method Name
Description
Example
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)
 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");
Returns a filtered, sorted collection (used in events).
SysLogic.findWhere(
  row.paymentCustomer.ordersList,
  "row.amount_un_paid > 0",
  "placed_date a")
Data Integration
For a description of the key services, see Business to Business Example.
 
Service
Summary
Example
Resources that you explicitly define using API Creator
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.
Create or update existing data lookup parent data to set foreign keys by programming requests.
For more information:
Business logic
Applied uniformly over all requests
Unlike web applications where business logic might be unavailable in a button (controller code), logic is applied 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.
For more information about how to invoke APIs from other systems using the REST utilities service, including the 
SysUtility
object, see Integrate Systems and Data.
Troubleshooting
For general troubleshooting, see Troubleshooting.
For information about how to debug logic, see Debug.