Validate Async

Validation Async allows you to validate the value of a field on change by calling an endpoint.

This allows for more complex validation than is possible using local validation rules.

When the value of a schema with a Validate Async configuration changes, first any local validation is run. If this local validation passes, a request is sent to the URL defined at [url], where the request body is a JSON object containing the value of the field under a property matching the value of [param].

On success, the server should respond with a 2xx status code and either an empty body, in which case no feedback is given to the user, or a JSON body with a message property, which will be shown to the user. On failure, the server should respond with a 422 status code and a JSON body with a message property which will be shown to the user.

Note that "failed" validation does not prevent the client from submitting the step in the case of async validation.

Also, in the case where the validation-async network call fails or returns an unexpected response, the client ignores the problem and allows the user to submit.

For these reasons, any validation which is critical should also be performed by the server on submission.

import com.wise.dynamicflow.feature.ValidateAsync
import com.wise.dynamicflow.feature.builders.build
import com.wise.dynamicflow.misc.HttpMethod
import com.wise.dynamicflow.step.Step
import com.wise.dynamicflow.step.builders.build

val validationAsync = Step.build {
    id = "validationAsync"
    title = ""
    schemas {
        obj {
            id = "#schema"
            title = "Enter recipient account details"
            properties {
                string("iban") {
                    title = "IBAN"
                    validationAsync = ValidateAsync(param = "iban", method = HttpMethod.POST, url = "/validate")
                }
            }
        }
    }
    layout {
        form { schemaId = "#schema" }
    }
}

Given a schema defined as:

string {
    title = "IBAN"
    validationAsync = ValidateAsync(
        param = "iban",
        method = HttpMethod.POST,
        url = "/validate-iban"
    )
}

When the user enters a value, e.g. "NL30ABNA7619995846", a POST request would be made to the /validate-iban endpoint with the following body:

{
  "iban": "NL30ABNA7619995846"
}

On success, the server responds with a 200 status code and the response body should either be empty, in which case no feedback will be given to the user, or a JSON body with the following structure:

{
  "message": "Valid IBAN"
}

In which case the message will be displayed to the user to let them know the value they have entered is valid.

On failure, the server should respond with a 422 status code and a json body giving a message to display to the user:

{
  "message": "This IBAN is invalid. Please check it again."
}