Creating APIs‎ > ‎Logic‎ > ‎Rule Types‎ > ‎

Validation Rule Type

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. Validations are expressions assigned to a table 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 using JavaScript notation. When you alter the validation's table, either directly by the client or through logic chaining, Live API Creator uses reactive programming and verifies that the result values still meet the validation.

For more information about reactive programming, see reactive programming.

Example: Validation that Rejects an Order when Balance Exceeds Credit Limit

You can create a validation that rejects an order when the balance of unpaid orders exceed the maximum credit limit. You can create additional derivation rules before determining the state of the unpaid balance. If your create a validation reject if (row.totalUnpaidOrders > row.creditLimit) 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: Validation that References 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. Such derivations are always subjected to validation checks at each level. The transaction might fail due to the following validation:

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. Validations 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 the validation can be rechecked.

Best Practice: Create validations that reference derivation results. For an example, see the "Commit Validations" section.

For more information:

Create Validation Rules

  1. In API Creator, select Manage, Rules, and click Create New Rule.
  2. Select the Validation rule type, the table to which it applies, and click Create Rule.
  3. Define the parameters of the rule:

    Validation name

    The name of the validation rule. 

    Tip: Leave this field blank for the system default.

    Table

    The name of the parent table representing the count result.

    Code

    See context help.

    Error message

    See context help.

    Problem attributes

    See context help.

    Active

    Select to activate the rule (The definition must be complete).

    Commit-time only

    See context help.

    Comments

    Add comments regarding this validation rule.

  4. Click Activate and Close to return to the list of rules.

The validation rule is created.

Attribute References: row, oldRow

Validations are defined for a table and can reference any column of that table by way of the row variable. Validations can also reference old values by way of oldRow, for example:

return 100 * (row.total - oldRow.total) / row.total;

Reference Parent Data

Validations 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 can 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 sub-resources that optimize database and network traffic.

For more information:

Create Conditional Validations

You can create validations that are conditional. Per use of JavaScript, you can use if/else statements:

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

Live API Creator reduces null-pointer exceptions by handling references to null attributes in expressions in the following way:

  • parent. If a child references a missing optional parent role name, the value is returned as null. Employee logic can refer to onLoanDepartment, which returns null if the foreign key is null.
  • parent.attribute. Is null if no parent. If the parent exists, it is treated as described below for attribute references.
  • attribute. To simplify null checking, null numeric attributes are returned as 0 and null string attributes are returned as the empty string.

Access Database Services and Other Utility Functions

Most validations 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

The error message is the text in the exception returned to the client if the validation 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, numeric and date values can be formatted using a format string specified after a vertical bar.

For example, 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.

For more information about these conventions, see Format Data in Rules.

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).

Commit Validations

You can define a validation so that it is checked 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 validations, see the No Empty Orders Example.