Validation Rule Type

Validation Rule Type
lac32
Behind the actual data entry of an order or shopping cart is some sort of validation logic. The business requirements determine the level of open and unpaid orders a customer may have at any moment in time. Validation rules are expressions assigned to an entity that must be true for a transaction to commit. They can reference other columns in the row as 
row.attribute
 as well as parent columns. Specify validation rule using JavaScript notation. When you alter the validation rule's entity, either directly by the client or through logic chaining, API Creator verifies that the result values still meet the validation rule using reactive logic.
In this article:
2
Create Validation Rules
  1. In API Creator, with your API open, in the Manage section, click 
    Rules
    .
    A list of rules display on the By entity tab.
  2. Click 
    Create New Rule
    .
  3. Select the 
    Validation
     rule type, the table to which it applies, and then click 
    Create Rule
    .
  4. Define the parameters of the rule:
    Validation name
    The name of the validation rule.
    Leave this field blank for the system default.
    Entity
    The name of the parent entity representing the count result.
    Code
    See the context help. You can access and insert JavaScript code examples into the code editor.
    For more information about the code examples that are available for validation rules, see Code Examples.
    Error message
    The text in the exception returned to the client if the validation rule evaluates to false. The error message can be up to 2,000 characters long, and you can embed data values, signified by brackets ({}). The data values consist of the name of a column or of a parent column. In addition, you can format numeric and date values using a format string specified after a vertical bar.
    For examples, see the "Error Message Examples" section. 
    Problem attributes
    The error attributes are included in the exception returned to the client if the validation evaluates to false. Your client can use these to aid in the user interface for error handling (for example, position the cursor and highlight).
    Active
    Select to activate the rule.
    The API definition must be complete before you can activate the rule.
    Commit-time only
    You can define a validation so that API Creator checks it only at the end of the transaction, when API Creator has executed the logic for all rows in the transaction.
    For more information about commit validation rules, see the No Empty Orders Example.
    Comments
    Comments about this validation rule.
  5. Click 
    Activate and Close
     to return to the list of rules.
The validation rule is created.
Validation Rule Syntax
You can use the following JavaScript code examples or explore the examples that are available in API Creator.
For more information about the JavaScript code examples that you can access and insert into the code editor in API Creator, see Code Examples.
Define Validation Rules that Reference Attributes
You define validation rules for a entity and they can reference any column of that entity by way of the 
row
 variable. Validation rules can also reference old values by way of 
oldRow
, for example:
return 100 * (row.total - oldRow.total) / row.total;
Define Validation Rules that Reference Parent Data
Validation rules can also reference parent attributes (one side of a one-to-many relationship). To reference parent data, use the dot-notation reference to the parent role/attribute. The database commands required to access parent data are automated. This reduces coding, and helps ensure good performance by automatic caching. For example, you might ensure orders are not altered for customers on hold:
return ! (logicContext.verb == "INSERT" && row.customer.isOnHold == false);
API Creator cascades changes in these parent columns to each related child row. You ca reference parent data without cascade using a parent copy.
Parent references are provided for transactional update logic, not for retrieval. You do not need to define new child columns derived from parent columns for retrieval.
Best Practice:
Create parent subresources that optimize database and network traffic.
For more information:
Define Conditional Validation Rules
You can create validation rules that are conditional. Per use of JavaScript, you can use if/else statements, such as:
 
if (row.total > 100) {
  return 5;
} else {
  return 3;
}
You can also use ternary expressions, such as:
return row.total > 100 ? 5 : 3;
Null Handling
API Creator reduces null-pointer exceptions by handling references to null attributes in expressions in the following ways:
  • parent
    . If a child references a missing optional parent role name, API Creator returns the value as null.
    Employee
    logic can refer to
    onLoanDepartment
    , which API Creator returns null if the foreign key is null.
  • parent.attribute
    . API Creator returns the value as null if the parent does not exist. If the parent exists, API Creator treats the parent as an 
    attribute
    reference.
  • attribute
    . To simplify null checking, API Creator returns null numeric attributes as 0 and returns null string attributes as the empty string.
Access Database Services and Other Utility Functions
Most validation rules are simple expressions, perhaps with conditional logic. You can also employ server-side JavaScript. You can access database services and other utility functions your logic may require using additional context, including the
logicContext
object.
For more information:
Error Message Examples
The following error message:
Customer {name}'s balance: {balance|#,##0.00} exceeded their credit limit: {customer_credit.credit_limit | #,##0.00} which is effective as of {customer_credit.effective_date | MM/dd/yy HH:mm}.
results in the following message being sent back to the client if the validation is violated:
Customer BigCorp's balance: 23,456.78 exceeded their credit limit: 20,000.00 which is effective as of 06/11/13 09:56.
The formatting strings use the standard formatting conventions.
Validation Rule Examples
Example: Define Validation Rules that Reject an Order when Balance Exceeds Credit Limit
You can create a validation rule that rejects an order when the balance of unpaid orders exceed the maximum credit limit. You can create additional validation rules before determining the state of the unpaid balance. If your create a 
reject if 
(row.totalUnpaidOrders > row.creditLimit)
 validation rule on the customer entity, you must derive 
totalUnpaidOrders
 as the 
sum
(OrderTotal where paid= false)
. This includes the qualification 
paid=false
. This paid flag is on the invoice (order) and when the state change occurs. This increases or decreases 
totalUnpaidOrders
 on the Customer entity.
Example: Define Validation Rules that Reference Attributes in Current Row, Previous Values, and Parent Columns
Altering a line Item can adjust the purchase orders 
amount_total
, which adjusts the customer's balance. These validation rules are always subjected to validation checks at each level. The transaction might fail due to the following validation rule:
Validation Customer.CheckCredit as
return row.balance < row.credit_limit
with Message(Balance {balance} exceeds credit}
Failed transactions are rolled back and a suitable message is returned to the client. Validation rules can reference all attributes of the current row, their previous values, and parent columns. Changes to parent columns referenced in child logic cascade to all children, so API Creator can recheck the validation.
Best Practice:
 Create validation rules that reference derivation results. Create a commit validation rule.