Validation Rule Type

Validation Rule Type
lac52
Validation rules are expressions that are assigned to an entity that must evaluate to 
true
 for a transaction to commit. The validation rule must return a boolean value. Validation rules can reference other columns in the row as 
row.attribute
 as well as reference parent columns. 
Layer7 Live API Creator
 checks validation rules as rows are processed, during server update request processing. When you alter the validation rule's entity, either directly by the client or through logic chaining, 
Layer7 Live API Creator
 verifies that the result values still meet the validation rule using reactive logic.
Layer7 Live API Creator
 checks commit validation rules only at the 
end
 of the transaction, just prior to commit, when it has executed the logic for all the rows in the transaction.For more information about an example of a commit validation rules, where it checks the Orders' item count, see No Empty Order Example.
In this article:
 
 
2
 
 
Null Handling
 
Layer7 Live 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, 
    Layer7 Live API Creator
     returns the value as null.
  • parent.attribute
    . If a parent does not exist, 
    Layer7 Live API Creator
     returns the 
    parent.attribute
     value as null. If the parent exists, 
    Layer7 Live API Creator
     returns null numeric attributes as 0 and returns null string attributes as the empty string.
  • attribute
    Layer7 Live API Creator
     returns null numeric attributes as 0 and returns null string attributes as the empty string.
Create a Validation Rule
  1. In API Creator, in the Create section, click 
    Rules
    .
    If your API does not have existing rules, the Welcome to Rules page appears. If your API has existing rules, they are listed on the By entity tab by default.
  2. Click 
    Create a Rule
    .
  3. Select 
    Validation
     or 
    Commit Validation
     as the rule type, the entity to which it applies, and then click 
    Create Rule
    .
  4. Define the parameters of the rule:
    Title
    The title for the validation rule. The title for rules does not affect logic processing. To apply a default value, leave this field blank.
    Required:
     No
    Entity
     
    The name of the parent entity representing the count result.
    Topics
     
    The topic that you want to associate to this rule.
    For more information about topics, see Manage Topics.
    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 JavaScript 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 must be complete.
    Commit-time only
     
    You can define a validation so that 
    Layer7 Live API Creator
     checks it only at the end of the transaction, when 
    Layer7 Live API Creator
     has executed the logic for all rows in the transaction.
    Name
     
    The name of the validation rule. Leave this field blank for the system default.
    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 from the code editor in API Creator.
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);
 
Layer7 Live API Creator
 cascades changes in these parent columns to each related child row. You can reference parent data without cascade using a parent copy.
Parent references are provided for transaction update logic, not for retrieval. You do not need to define 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;
Error Message Examples
The following error results in 
Layer7 Live API Creator
 sending a message back to the client if the validation is violated:
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}.
Example error message:
 
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 you 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}
Layer7 Live API Creator
 rolls back failed transactions and returns a suitable message 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 
Layer7 Live API Creator
 can recheck the validation.
Best Practice:
 Create a commit validation rule that references derivation results.
Access Database Services and Other Utility Functions
Most validation rules are simple expressions, perhaps with conditional logic. You can also provide access to database services and other utility functions your logic might require using context variables, including the 
logicContext
 object, by employing JavaScript.
For more information about the list of JavaScript context variables, see Extensibility.