CA Live API Creator 3.1.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
lac31
 
Prerequisite: 
You have a basic familiarity with 
CA Live API Creator
.
Basic API Creator usage is illustrated by the learnings that start automatically when you first use API Creator. This article provides various quick-reference indices to frequently accessed topics. You can access detailed internal javadoc by downloading the .
In this article:
 
 
Resource Endpoints
RESTful resource endpoints are determined from the objects shown in the following table. 
CA Live API Creator
 provides all of the resource endpoints, except custom.
 
 
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.
Reactive logic: You can define transactional business logic.
For more information:
Custom resources
API Creator/resources
Used to provide "document model" GET response JSON (for example, Customers with a set of Orders and a set of Addresses). Resources typically automate SQL, 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:
  • About defining custom resources (custom REST resource endpoints) and resource types, see Customize your API.
  • About resource/object mapping, see Architecture.
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/Custom resources 
Use custom endpoints to 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, see 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
The following extensibility services are included. Many of these services are derived from the underlying JavaScript object model. The extensibility services can invoke loadable logic libraries.
For more information about the extensibility services, see Extensibility.
The following table lists the JavaScript extension points that are included:
 
 
JavaScript Event Type
 
 
Description
 
 
Applies to
 
Formula and validation logic
Access if/else conditional flow, functions such as Date arithmetic, by specifying logic in JavaScript.
Formulas and validations, based on the JavaScript object model.
For more information:
Logic event rule types
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 about logic event rule types, see Logic 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:
JavaScript resource types
Materialize data using JavaScript, for example, by invoking REST services to build a request that integrates data from other systems.
Resources
For more information about JavaScript resource types, see Define JavaScript Resource Types.
Custom endpoints
Define new RESTful endpoint Resources with potentially no relationship to the data model.
API Server
For more information about custom endpoints, see 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
Connect to corporate security.
API Server
For more information about custom authentication providers, see Create Custom Authentication Providers using JavaScript.
 
 
JavaScript Context Variables
Your JavaScript has access to the pre-supplied libraries and to your own extensions. The following context variables are set when 
CA Live API Creator
 invokes JavaScript logic:
For more information:
 
 
 Variable
 
 
Description
 
 
 Applies to
 
logicContext
Services for creating, reading, updating, and deleting rows. Provides information about logic state, including verb and nest level.
For more information, see The logicContext Object.
Logic (the rule types listed in the "Reactive Logic" section)
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 Request Object.
All
row
The 
row
 object you are inserting/updating/deleting/retrieving.
API Creator creates your JavaSCript object model automatically from the schema. This provides access to attributes and related parent objects.
For more information about the 
row
 object, see Row 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 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
SysUtility
object
This object includes useful functions for manipulating resources.
For more information about the 
SysUtility
object, see The SysUtility Object.
All
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 engine services for additional interaction:
 
 
Engine Service
 
 
Description
 
The 
LogicContext
object
This object is available in all JavaScript rules, and gives you access to a lot of information, and behavior.
For more information about the LogicContext object, see The logicContext Object.
The 
SysLogic
object
SysLogic
methods are pre-supplied methods identified by a leading 
SysLogic
. You can use system methods in actions, validations, and formulas.
For more information about the 
SysLogic
methods, see Rule Types. 
Admin data
Metadata services.
For more information about the admin data engine service, see System REST Endpoints.
The 
SysUtility
object
You can use this JavaScript object to retrieve a resource or invoke 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.
 
 
API
 
 
Description
 
Persistence
Services to read, insert, update, and delete rows.
For more information about persistence, see The logicContext Object.
Rows
Rows sent/received in object persistence. In addition to persistence, provide access to attributes and related objects.
For more information about rows API, 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.
 
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. 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.
For more information:
The following table lists the rule/logic types:
 
 
 Rule/Logic 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.
 
Note: 
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.
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");
Invoke JavaScript action (often an extensible service); can execute during or after row processing, or on commit (after all rows are processed).
See the previous example.
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, send updates to other systems, etc.
Returns a filtered, sorted collection (used in events).
SysLogic.findWhere(
  row.paymentCustomer.ordersList,
  "row.amount_un_paid > 0",
  "placed_date a")
Notes:
  •  
    Rules syntax.
     Formulas, events, and validations must follow this syntax.
For more information about the syntax, see Rules 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.
  • The 
    logicContext
    object
    .
     Provides access to runtime services and state, such as 
    logicNestLevel
    , 
    setUseCaseName
    , and services to create, read, update, and delete rows.
For more information about the 
logicContext
object, see The LogicContext Object.
  •  
    Logic design patterns
     
    .
     Use these patterns to meet most requirements, which leverage forward chaining.
    For more information:
  •  
    Extensibility
     
    . 
    You can meet requirements not solved by core rules by defining rules that can invoke JavaScript. Judicious design can result in reusable logic, as illustrated by the pre-supplied BusinessLogic services for allocation and copy. You can add JavaScript as 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.
  •  
    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 like this.
For more information:
Data Integration
For a description of the key services, see Integrate Systems and Data. For an example, see the Business to Business 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.
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 information about how to debug logic, see Debug.