Restricting Field Values

To download the full code sample see our Code Share site. The PDF used in this topic can be found here.

When creating a form, you may require that a user fill-in some mandatory fields. Or you may also want to ensure that valid entries are entered by your user. By validating form data while the user is filling it out, the user can know immediately if they've made any mistakes or if they’ve left a required field empty. This saves you the time of having to deal with improper or empty form input. With OneSpan Sign, you can achieve this by creating field validators. A field validator enables you to require and restrict the range of acceptable values for an unbounded field.

When building a field validator, you must first select the field's desired data type (for example, numeric, alphabetic). Then you can add other parameters (such as maximum length).

A field may only have one validator.

The sample code below shows you how to add field validation to a field that is bound to a signature.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

.withSignature(SignatureBuilder.captureFor("signer@example.com")
    .withName("client_signature")
    .withId(new SignatureId("client"))
    .withPositionExtracted()
    .withField(FieldBuilder.signatureDate()
        .withId(new FieldId("signature_date"))
        .withName("client_date")
        .withPositionExtracted())
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_first"))
        .withName("first_name")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid first name.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_last"))
        .withName("last_name")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid last name.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_address"))
        .withName("address")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.basic().required().withErrorMessage("Please enter a valid address.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_city"))
        .withName("city")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid city.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_state"))
        .withName("state")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().maxLength(2).minLength(2).withErrorMessage("Please enter a valid state.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_zip"))
        .withName("zip")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.numeric().required().maxLength(5).minLength(5).withErrorMessage("Please enter a valid zip.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_country"))
        .withName("country")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid country.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_phone"))
        .withName("phone_number")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.regex("^[2-9]\\d{2}-\\d{3}-\\d{4}$").required().withErrorMessage("Please enter a valid phone number (XXX-XXX-XXXX)")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_email"))
        .withName("email")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.email().required().withErrorMessage("Please enter a valid email.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_company"))
        .withName("company")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid company.")))
    .withField(FieldBuilder.textField()
        .withId(new FieldId("client_policy"))
        .withName("policy_number")
        .withPositionExtracted()
        .withValidation(FieldValidatorBuilder.numeric().required().withErrorMessage("Please enter a valid policy number.")))
)

In this example, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the withName() method and use the withPositionExtracted() method to ensure that the exact position and size are retained in OneSpan Sign

Position extraction in can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to pass a field validator type to the FieldValidatorBuilder. You can either use the pre-defined validators that come with the API/SDKs, or you can create your own customized validator using regular expressions.

The required() method makes a field mandatory and the withErrorMessage() method customizes the error message that will appear if your user enters invalid format data or if the required field is left empty. You can also restrict the length of an input using the maxLength() and minLength() methods.

Results

Once the transaction is sent, any required fields will be marked for the signer to complete. The signer will not be able to continue until these fields are completed.

To download the full code sample see our Code Share site. The PDF used in this topic can be found here.

When creating a form, you may require that a user fill-in some mandatory fields. Or you may also want to ensure that valid entries are entered by your user. By validating form data while the user is filling it out, the user can know immediately if they've made any mistakes or if they’ve left a required field empty. This saves you the time of having to deal with improper or empty form input. With OneSpan Sign, you can achieve this by creating field validators. A field validator enables you to require and restrict the range of acceptable values for an unbounded field.

When building a field validator, you must first select the field's desired data type (for example, numeric, alphabetic). Then you can add other parameters (such as maximum length).

A field may only have one validator.

The Code

The sample code below shows you how to add field validation to a field that is bound to a signature.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

.WithSignature(SignatureBuilder.CaptureFor("john.smith@gmail.com")
    .WithName("client_signature")
    .WithPositionExtracted()
    .WithField(FieldBuilder.SignatureDate()
        .WithName("client_date")
        .WithPositionExtracted())
    .WithField(FieldBuilder.TextField()
        .WithName("first_name")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid first name.")))
    .WithField(FieldBuilder.TextField()
        .WithName("last_name")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid last name.")))
    .WithField(FieldBuilder.TextField()
        .WithName("address")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Basic().Required().WithErrorMessage("Please enter a valid address.")))
    .WithField(FieldBuilder.TextField()
        .WithName("city")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid city.")))
    .WithField(FieldBuilder.TextField()
        .WithName("state")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().MaxLength(2).MinLength(2).WithErrorMessage("Please enter a valid state.")))
    .WithField(FieldBuilder.TextField()
        .WithName("zip")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Numeric().Required().MaxLength(5).MinLength(5).WithErrorMessage("Please enter a valid zip.")))
    .WithField(FieldBuilder.TextField()
        .WithName("country")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid country.")))
    .WithField(FieldBuilder.TextField()
        .WithName("phone_number")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Regex("^[2-9]\\d{2}-\\d{3}-\\d{4}$").Required().WithErrorMessage("Please enter a valid phone number (XXX-XXX-XXXX)")))
    .WithField(FieldBuilder.TextField()
        .WithName("email")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Email().Required().WithErrorMessage("Please enter a valid email.")))
    .WithField(FieldBuilder.TextField()
        .WithName("company")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid company.")))
    .WithField(FieldBuilder.TextField()
        .WithName("policy_number")
        .WithPositionExtracted()
        .WithValidation(FieldValidatorBuilder.Numeric().Required().WithErrorMessage("Please enter a valid policy number.")))
)

In this example, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the withName() method and use the withPositionExtracted() method to ensure that the exact position and size are retained in OneSpan Sign

Position extraction in can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to pass a field validator type to the FieldValidatorBuilder. You can either use the pre-defined validators that come with the API/SDKs, or you can create your own customized validator using regular expressions.

The required() method makes a field mandatory and the withErrorMessage() method customizes the error message that will appear if your user enters invalid format data or if the required field is left empty. You can also restrict the length of an input using the maxLength() and minLength() methods.

Results

Once the transaction is sent, any required fields will be marked for the signer to complete. The signer will not be able to continue until these fields are completed.

To download the full code sample see our Code Share site. The PDF used in this topic can be found here.

When creating a form, you may require that a user fill-in some mandatory fields. Or you may also want to ensure that valid entries are entered by your user. By validating form data while the user is filling it out, the user can know immediately if they've made any mistakes or if they’ve left a required field empty. This saves you the time of having to deal with improper or empty form input. With OneSpan Sign, you can achieve this by creating field validators. A field validator enables you to require and restrict the range of acceptable values for an unbounded field.

When building a field validator, you must first select the field's desired data type (for example, numeric, alphabetic). Then you can add other parameters (such as maximum length).

A field may only have one validator.

The sample code below shows you how to add field validation to a field that is bound to a signature.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

HTTP Request

POST /api/packages

HTTP Headers

Accept: application/json   
Content-Type: multipart/form-data   
Authorization: Basic api_key 

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj....
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"

{
  "autocomplete": true,
  "documents": [
    {
      "approvals": [
        {
          "role": "manager",
          "fields": [
            {
              "subtype": "LABEL",
              "binding": "{approval.signed}",
              "extract": true,
              "type": "INPUT",
              "name": "manager_date"
            },
            {
              "subtype": "CAPTURE",
              "extract": true,
              "type": "SIGNATURE",
              "name": "manager_signature"
            }
          ],
          "name": ""
        },
        {
          "role": "client",
          "fields": [
            {
              "subtype": "LABEL",
              "binding": "{approval.signed}",
              "extract": true,
              "type": "INPUT",
              "name": "client_date"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid first name.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "first_name"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid last name.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "last_name"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid address.",
                "pattern": ""
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "address"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid city.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "city"
            },
            {
              "validation": {
                "maxLength": 2,
                "required": true,
                "minLength": 2,
                "errorMessage": "Please enter a valid state.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "state"
            },
            {
              "validation": {
                "maxLength": 5,
                "required": true,
                "minLength": 5,
                "errorMessage": "Please enter a valid zip.",
                "pattern": "^[-+]?[0-9]*\\.?[0-9]*$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "zip"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid country.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "country"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid phone number (XXX-XXX-XXXX)",
                "pattern": "^[2-9]\\d{2}-\\d{3}-\\d{4}$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "phone_number"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid email.",
                "pattern": "^([a-z0-9_\\.-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "email"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid company.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "company"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid policy number.",
                "pattern": "^[-+]?[0-9]*\\.?[0-9]*$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "policy_number"
            },
            {
              "subtype": "CAPTURE",
              "extract": true,
              "type": "SIGNATURE",
              "name": "client_signature"
            }
          ],
          "name": ""
        }
      ],
      "extract": true,
      "name": "Contract"
    }
  ],
  "status": "SENT",
  "type": "PACKAGE",
  "roles": [
    {
      "id": "client",
      "type": "SIGNER",
      "signers": [
        {
          "lastName": "Smith",
          "email": "client@gmail.com",
          "firstName": "John",
          "id": "client"
        }
      ],
      "name": "client"
    },
    {
      "id": "manager",
      "type": "SENDER",
      "signers": [
        {
          "lastName": "Haidary",
          "email": "manager@gmail.com",
          "firstName": "Haris",
          "id": "manager"
        }
      ],
      "name": "manager"
    }
  ]
}

For a complete description of each field, see the Request Payload table below.

To download the full code sample see our Code Share site. The PDF used in this topic can be found here.

When creating a form, you may require that a user fill-in some mandatory fields. Or you may also want to ensure that valid entries are entered by your user. By validating form data while the user is filling it out, the user can know immediately if they've made any mistakes or if they’ve left a required field empty. This saves you the time of having to deal with improper or empty form input. With OneSpan Sign, you can achieve this by creating field validators. A field validator enables you to require and restrict the range of acceptable values for an unbounded field.

When building a field validator, you must first select the field's desired data type (for example, numeric, alphabetic). Then you can add other parameters (such as maximum length).

A field may only have one validator.

The sample code below shows you how to add field validation to a field that is bound to a signature.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

// Approval for client
ESignLiveAPIObjects.Approval approvalForClient = new ESignLiveAPIObjects.Approval();
approvalForClient.role = roleId2;
approvalForClient.id = 'approvalForClient';

// Signature field for client
ESignLiveAPIObjects.Field fieldClient1 = new ESignLiveAPIObjects.Field();
fieldClient1.extract = true;
fieldClient1.name = 'client_signature';
// Match PDF field property name
fieldClient1.type = 'SIGNATURE';
fieldClient1.subtype = 'CAPTURE';

// Date field for client
ESignLiveAPIObjects.Field fieldClient2 = new ESignLiveAPIObjects.Field();
fieldClient2.extract = true;
fieldClient2.name = 'client_date';
// Match PDF field property name
fieldClient2.type = 'INPUT';
fieldClient2.subtype = 'LABEL';
fieldClient2.binding = '{approval.signed}';

// Text field: first_name
ESignLiveAPIObjects.Field fieldClient3 = new ESignLiveAPIObjects.Field();
fieldClient3.extract = true;
fieldClient3.name = 'first_name';
// Match PDF field property name
fieldClient3.type = 'INPUT';
fieldClient3.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_first_name = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_first_name.required = true;
FieldValidation_first_name.errorMessage = 'Please enter a valid first name.';
FieldValidation_first_name.pattern = '^[\\sa-zA-Z]+$';
fieldClient3.validation = FieldValidation_first_name;

// Text field: last_name
ESignLiveAPIObjects.Field fieldClient4 = new ESignLiveAPIObjects.Field();
fieldClient4.extract = true;
fieldClient4.name = 'last_name';
// Match PDF field property name
fieldClient4.type = 'INPUT';
fieldClient4.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_last_name = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_last_name.required = true;
FieldValidation_last_name.errorMessage = 'Please enter a valid last name.';
FieldValidation_last_name.pattern = '^[\\sa-zA-Z]+$';
fieldClient4.validation = FieldValidation_last_name;

// Text field: address
ESignLiveAPIObjects.Field fieldClient5 = new ESignLiveAPIObjects.Field();
fieldClient5.extract = true;
fieldClient5.name = 'address';
// Match PDF field property name
fieldClient5.type = 'INPUT';
fieldClient5.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_address = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_address.required = true;
FieldValidation_address.errorMessage = 'Please enter a valid address.';
FieldValidation_address.pattern = '';
fieldClient5.validation = FieldValidation_address;

// Text field: city
ESignLiveAPIObjects.Field fieldClient6 = new ESignLiveAPIObjects.Field();
fieldClient6.extract = true;
fieldClient6.name = 'city';
// Match PDF field property name
fieldClient6.type = 'INPUT';
fieldClient6.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_city = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_city.required = true;
FieldValidation_city.errorMessage = 'Please enter a valid city.';
FieldValidation_city.pattern = '^[\\sa-zA-Z]+$';
fieldClient6.validation = FieldValidation_city;

// Text field: state
ESignLiveAPIObjects.Field fieldClient7 = new ESignLiveAPIObjects.Field();
fieldClient7.extract = true;
fieldClient7.name = 'state';
// Match PDF field property name
fieldClient7.type = 'INPUT';
fieldClient7.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_state = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_state.required = true;
FieldValidation_state.errorMessage = 'Please enter a valid state.';
FieldValidation_state.pattern = '^[\\sa-zA-Z]+$';
FieldValidation_state.maxLength = 2;
FieldValidation_state.minLength = 2;
fieldClient7.validation = FieldValidation_state;

// Text field: zip
ESignLiveAPIObjects.Field fieldClient8 = new ESignLiveAPIObjects.Field();
fieldClient8.extract = true;
fieldClient8.name = 'zip';
// Match PDF field property name
fieldClient8.type = 'INPUT';
fieldClient8.subtype = 'TEXTFIELD';
// Set validator
ESignLiveAPIObjects.FieldValidation FieldValidation_zip = new ESignLiveAPIObjects.FieldValidation();
FieldValidation_zip.required = true;
FieldValidation_zip.errorMessage = 'Please enter a valid zip.';
FieldValidation_zip.pattern = '^[-+]?[0-9]*\\.?[0-9]*$';
fieldClient8.validation = FieldValidation_zip;

In this example, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the name attribute of a field and enable the document as well as field level extract to ensure that the exact position and size are retained in OneSpan Sign.

Position extraction in can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to pass a field validator type to the FieldValidatorBuilder. You can either use the pre-defined validators that come with the API/SDKs, or you can create your own customized validator using regular expressions.

The required() method makes a field mandatory and the withErrorMessage() method customizes the error message that will appear if your user enters invalid format data or if the required field is left empty. You can also restrict the length of an input using the maxLength() and minLength() methods.

Results

Once the transaction is sent, any required fields will be marked for the signer to complete. The signer will not be able to continue until these fields are completed.