Restricting Field Values

 .withSignature(SignatureBuilder.captureFor("[email protected]")   .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."))) 

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("[email protected]")   .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": "[email protected]",   "firstName": "John",   "id": "client"   }   ],   "name": "client"   },   {   "id": "manager",   "type": "SENDER",   "signers": [   {   "lastName": "Haidary",   "email": "[email protected] ",   "firstName": "Haris",   "id": "manager"   }   ],   "name": "manager"   }   ],   "name": "Sample Contract"   }   ------WebKitFormBoundary1bNO60n7FqP5WO4t-- 

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]*$';   FieldValidation_zip.maxLength = 5;   FieldValidation_zip.minLength = 5;   fieldClient8.validation = FieldValidation_zip;   //text field: phone_number   ESignLiveAPIObjects.Field fieldClient9 = new ESignLiveAPIObjects.Field();   fieldClient9.extract = true;   fieldClient9.name = 'phone_number';   //match pdf field property name   fieldClient9.type = 'INPUT';   fieldClient9.subtype = 'TEXTFIELD';   //set validator   ESignLiveAPIObjects.FieldValidation FieldValidation_phone_number = new ESignLiveAPIObjects.FieldValidation();   FieldValidation_phone_number.required = true;   FieldValidation_phone_number.errorMessage = 'Please enter a valid phone number (XXX-XXX-XXXX)';   FieldValidation_phone_number.pattern = '^[2-9]\\d{2}-\\d{3}-\\d{4}$';   fieldClient9.validation = FieldValidation_phone_number;   //text field: email   ESignLiveAPIObjects.Field fieldClient10 = new ESignLiveAPIObjects.Field();   fieldClient10.extract = true;   fieldClient10.name = 'email';   //match pdf field property name   fieldClient10.type = 'INPUT';   fieldClient10.subtype = 'TEXTFIELD';   //set validator   ESignLiveAPIObjects.FieldValidation FieldValidation_email = new ESignLiveAPIObjects.FieldValidation();   FieldValidation_email.required = true;   FieldValidation_email.errorMessage = 'Please enter a valid email.';   FieldValidation_email.pattern = '^([a-z0-9_\\.-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$';   fieldClient10.validation = FieldValidation_email;   //text field: company   ESignLiveAPIObjects.Field fieldClient11 = new ESignLiveAPIObjects.Field();   fieldClient11.extract = true;   fieldClient11.name = 'company';   //match pdf field property name   fieldClient11.type = 'INPUT';   fieldClient11.subtype = 'TEXTFIELD';   //set validator   ESignLiveAPIObjects.FieldValidation FieldValidation_company = new ESignLiveAPIObjects.FieldValidation();   FieldValidation_company.required = true;   FieldValidation_company.errorMessage = 'Please enter a valid company.';   FieldValidation_company.pattern = '^[\\sa-zA-Z]+$';   fieldClient11.validation = FieldValidation_company;   //text field: policy_number   ESignLiveAPIObjects.Field fieldClient12 = new ESignLiveAPIObjects.Field();   fieldClient12.extract = true;   fieldClient12.name = 'policy_number';   //match pdf field property name   fieldClient12.type = 'INPUT';   fieldClient12.subtype = 'TEXTFIELD';   //set validator   ESignLiveAPIObjects.FieldValidation FieldValidation_policy_number = new ESignLiveAPIObjects.FieldValidation();   FieldValidation_policy_number.required = true;   FieldValidation_policy_number.errorMessage = 'Please enter a valid policy number.';   FieldValidation_policy_number.pattern = '^[-+]?[0-9]*\\.?[0-9]*$';   fieldClient12.validation = FieldValidation_policy_number;   //text field: country   ESignLiveAPIObjects.Field fieldClient13 = new ESignLiveAPIObjects.Field();   fieldClient13.extract = true;   fieldClient13.name = 'country';   //match pdf field property name   fieldClient13.type = 'INPUT';   fieldClient13.subtype = 'TEXTFIELD';   //set validator   ESignLiveAPIObjects.FieldValidation FieldValidation_country = new ESignLiveAPIObjects.FieldValidation();   FieldValidation_country.required = true;   FieldValidation_country.errorMessage = 'Please enter a valid country.';   FieldValidation_country.pattern = '^[\\sa-zA-Z]+$';   fieldClient13.validation = FieldValidation_country;   approvalForClient.fields = new List<ESignLiveAPIObjects.Field>{fieldClient1,fieldClient2,fieldClient3,fieldClient4,fieldClient5,fieldClient6,fieldClient7,fieldClient8,fieldClient9,fieldClient10,fieldClient11,fieldClient12,fieldClient13}; 

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.