Validation procedures

Validation procedures can be used to validate input such as HTTP requests. Its normal usage is during authentication or registration, where form parameters need special validation. A phone number needs a certain format, or additional fields during registration needs validation.

A validation procedure has the following structure:

Listing 292 Structure of Validation procedures
1
2
3
4
5
6
7
function result(validationContext) {
  var errors = {};

    // validate the object

    return errors;
}

Important

The main function of a validation procedure must be called result.

Function

The result function takes one argument, which is the object to be validated.

result(validationContext)

The main function of a transformation procedure

Arguments:
  • validationContext – The context object for validation procedures
Returns:

a map of errors if validation fails, or an empty map on successful validation.

Return Value

The returned value should be a JavaScript object representing the validation errors that were found. If the object is valid, an empty object should be returned. Otherwise, the object should contain entries of the form:

{ "fieldName" : "message.key" }

These message keys are then used in the the templates shown to the end user to present a localized error message.

Examples

A good example is during registration when a Form is validated and the username field is expected to contain a String with at least 2 characters. If that data fails to validate we want to show a localized message to the user. For this we return a message key that we define validation.username_too_short.

Listing 293 Username length validation procedure
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
function result(validationContext) {
  var errors = {};
  var username = validationContext.request.getFormParameter("userName");

  if ((typeof username == "string") && username.length < 2) {
      errors.username = "validation.username_too_short";
  }

  return errors;
}

Another common scenario is to add additional parameters to the form that the user should enter. A good example is a check box for accepting license terms. A validation procedure can be added to validate that the checkbox is checked before accepting the request.

Listing 294 Validate terms of service
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
function result(validationContext) {
  var errors = {};

  var acceptTerms = validationContext.request.getFormParameter("agreeToTerms");

  if (acceptTerms !== 'on')
  {
      errors.terms = "error.validation.terms";
  }

  return errors;
}

API

The following validation-procedure types are supported:

Examples of validation procedures can be found in the $INSTALL_DIR/examples/configs/validation-procedures directory.

Request validation-procedure API

Request validation-procedures may be configured to validate requests received by Authenticators.

This type of validation-procedure must have a result function which receives a context of the same type as the authenticator’s RequestModel object.

Context

validationContext

The input argument to the result function of a validation procedure. It contains the following attributes

validationContext.request

Returns the httpRequest for the current transaction

Returns:httpRequest for the current transaction
validationContext.response

Returns the httpResponse for the current transaction

Returns:httpResponse for the current transaction
validationContext.originalQueryParameters

Returns the query parameters given in the initial request

Returns:originalQueryParameters of the initial request
validationContext.sessionManager

Returns the Session Manager

Returns:sessionManager of the current session