Text Tag Extraction enables integrators to automatically extract signatures and fields by placing Text Tags in a document. OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Anatomy of a Text Tag

This section describes:

Text Tag Syntax

The following line illustrates the syntax of a Text Tag:

  • {{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}

Field names are alphanumeric. They cannot contain special characters other than the underscore (_).

Note from this line that:

  • The beginning and end of a Text Tag have double curly brackets. Curly brackets should not appear anywhere else in a Text Tag.
  • The third character — the X — is placeholder for an optional character. That character can be either a question mark (?) or an asterisk (*). An asterisk indicates that an Input Field is required. A question mark indicates that an Input Field is optional. The question mark is the default value — i.e., if neither character is present, an Input Field will be optional. Example: {{*esl:signer1:textfield}}
  • fieldName is the name of the field that will be created by the Text Tag (a Signature, an Autofield, or an Input Field) — see Text Tag Types. If specified, this parameter will follow the “esl” prefix. Field names are alphanumeric. They cannot contain special characters other than the underscore (_). If you plan to retrieve the value entered during the Signing Ceremony, enter a unique name per field. Example: {{esl_SignerAutograph:signer1:Signature}}
  • roleName is the name of the role associated with the intended signer. To find the role name you need to use, see Role Names in Text Tags.
  • fieldType is one of the field types described in Text Tag Types.
  • parameter1 and parameter2 are parameters described in Text Tag Parameters.
  • A Text Tag cannot appear on multiple lines.

    If a list of parameters is present, it must be a comma-separated list.

The following line illustrates the shortest valid syntax for a Text Tag:

  • {{esl:roleName:fieldType}}

Role Names in Text Tags

If you create a package using the OneSpan Sign Application (i.e., a browser), the role name of the sender is always Owner.

If you create a "recipient" signer or a "group" signer using the OneSpan Sign Application, the role name of the signer is Signer#, where # starts at 1 and increases by one for each signer. The lowest available # is used for a new signer. Thus if you delete the signer with role Signer1 and then add a new signer, the new signer's role name will be Signer1.

If you create a "placeholder" signer, and name it client, then client will be its role name. Moreover, that will remain its role name when that placeholder is later replaced with a specific recipient or group.

If you create a signer using the SDK, and assign a Custom ID to that signer, that ID will be the signer's role name. If you do not assign a Custom ID to the signer, one is generated for the signer using the same rules as described above for the OneSpan Sign Application.

Text Tag Types

There are three main types of Text Tags:

Signatures

A particular Signature Text Tag can be any of the following field types:

  • Signature — This Signature Block is Click-to-Sign. The signer's name will be stamped on the clicked block.
  • Initials — This Signature Block is Click-to-Initial. The signer's initials will be stamped on the clicked block.
  • Capture — The signer clicks this Signature Block, and draws their signature using a mouse or another input device. The signer can also choose to sign on a mobile device such as a smartphone if the sender has mobile capture enabled on their account. The drawing is then stamped on the Signature Block.
  • Mobile_Capture — To e-sign this Signature Block, the signer will receive a link via email that redirects them to open the document on their mobile phone. They are then required to draw their signature using their finger or a stylus. The drawing of the signature is then stamped on the block.
Autofields

A particular Autofield Text Tag can be any of the following field types:

  • SignerName — At the time of signing, the system automatically populates this field with the full name of the signer.
  • Signature — If the signer is required to sign multiple signature fields, this field allows you to bind different text tags for each required signature.
  • SignerTitle — If the signer's title is available, the system automatically populates this field with that title at the time of signing. Otherwise, the field is left blank.
  • SignerCompany — If the name of the signer's company is available, the system automatically populates this field with that name at the time of signing. Otherwise, the field is left blank.
  • SigningDate — At the time of signing, the system automatically populates this field with the current date.
Input Fields

A particular Input Field Text Tag can be any of the following field types:

  • TextField — This box accepts any text entered by the signer prior to signing.
  • TextArea — This is similar to the TextField type, in that it provides an area where free-form text can be entered by signers. However, unlike Text Fields, it provides automatic wraparound. Each Text Area can accept up to 4000 characters.
  • List — This drop-down menu provides the ability to select one of many options.
  • Radio — Radio buttons also provide the ability to select one of many options.
  • Checkbox — Prior to signing, the signer can either select or clear this simple check box.
  • Label — The package sender can add a Label Field to embed text in a document. This is a read-only field with a value that will be simply stamped on the PDF. During the Signing Ceremony, the Label Field is displayed as non-editable text.

Text Tag Parameters

When you build a Text Tag, the system uses the parameters in the following table. Offset and Size are used for all three Text Tag types. The table's other parameters are used only for Input Field types. All parameters in the following table are optional.

If quotes are required in any parameter in the following table, you must use straight quotes. You cannot use curly quotes.

Parameter Description Examples
Offset

Offset (in points) to be applied in positioning the field relative to the top left corner of the Text Tag

If unspecified, the field will be inserted at the exact position of the Text Tag. Values can be positive or negative.

{{esl:signer3:initials:offset(20,40)}}

{{esl:signer3:initials:offset(-20,-40)}}

Size Size of the field (in points). If unspecified, the system's default values will be used. Valid values must be positive. {{esl:signer1:capture:size(200,50)}}
Group

The radio group to which the field will belong

If unspecified, the system will use its default radio group.

{{esl:signer1:Radio:Group("MyGroup"),Value("X")}}
Options The list of values available for a List field {{esl_colour:signer1:list:options("Red", "Blue", "Green")}}
Value

The field's default value

For Radio and Checkbox field types: (1) if no value is specified, the option will by default be deselected/unchecked; (2) to have the option selected/checked by default, the value “X” must be specified; (3) if any other value or the empty string is specified, the option will by default be deselected/unchecked.

{{esl:signer1:label:value("This is a test label")}}

{{esl_paymentMethod:signer1:textfield:value("Please enter your preferred payment method")}}

{{esl:signer1:checkbox:value("X")}}

Maxlen The maximum permitted value for the field {{esl_paymentMethod:signer1:textfield:Maxlen(200)}}

You can't add Custom Fields or Notary Fields via Text Tags.

Video Tutorial

How to Automatically Extract Signature Fields Using Text Tags in OneSpan Sign

Other Extraction Methods

You may also be interested in our other extraction types:

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names from the feature overview.

Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be signer1. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

PDF used in this guide can be found here.

The Code

The sample code below shows you how to setup your document package (transaction in the new UI) for Text Tag extraction. In the withSigner call, you will see that the custom ID coincides with the one in the image of the PDF form shown earlier in the guide. The .withDocument also has a call to enableExtraction.

Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

DocumentPackage pkg = PackageBuilder.newPackageNamed("Text Tag Example Package")
     .withStatus(PackageStatus.SENT)
     .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                .withFirstName("John")
                .withLastName("Smith")
                .withCustomId("signer1"))
     .withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
                .fromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
                .withExtractionType(ExtractionType.TEXT_TAGS_ONLY)
                .enableExtraction())
     .build();

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

 

capture

Get the Code | See this feature in action in our Interactive Demo

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names from the feature overview.

Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be signer1. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

PDF used in this guide can be found here.

The Code

The sample code below shows you how to setup your document package (transaction in the new UI) for Text Tag extraction. In the WithSigner call, you will see that the custom ID coincides with the one in the image of the PDF form shown earlier in the guide. The .WithDocument also has a call to enableExtraction.

Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Text Tag Example Package")
    .WithStatus(DocumentPackageStatus.SENT)
    .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
            .WithFirstName("John")
            .WithLastName("Smith")
            .WithCustomId("signer1"))
    .WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
            .FromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
            .WithExtractionType(ExtractionType.TEXT_TAGS_ONLY)
            .EnableExtraction())
    .Build();

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names from the feature overview.

Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be signer1. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

PDF used in this guide can be found here.

The Code

Typically, you will probably build your JSON string dynamically versus having a giant static string, like this. This is to give a good representation of the structure of the JSON you will need to create your package (transaction in the new UI) properly.

The JSON below is formatted for readability. In each roles object, you will see that the custom ID coincides with the one in the image of the text tags shown earlier in the guide. The documents object also has extract to true.

Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

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="sample-contract.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "documents": [
    {
      "id": "sample-contract",
      "name": "Test Document",
      "extract": true,
      "extractionTypes":[
         "TEXT_TAGS"
      ]
    }
  ],
  "status": "DRAFT",
  "type": "PACKAGE",
  "roles": [
    {
      "id": "signer1",
      "type": "SIGNER",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John",
          "lastName": "Smith",
          "id": "signer1"
        }
      ],
      "name": "signer1"
    }
  ],
  "name": "Text Tags Example Package"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo

Request Payload

PropertyTypeEditableRequiredDefaultSample Value(s)
statusstringYesNoDRAFTDRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
typestringYesNoPACKAGEPACKAGE / TEMPLATE / LAYOUT
namestringYesYesn/aText Tags Example Package
documents
idstringYesNon/asample-contract
namestringYesNon/aTest Document
extractbooleanYesNofalsetrue / false
extractionTypesstring arrayYesNo[]["TEXT_TAGS","ACROFIELDS"]
roles
idstringYesNon/asigner1
namestringYesNon/asigner1
typestringYesNoSIGNERSIGNER / SENDER
signers
emailstringYesYesn/a[email protected]
firstNamestringYesYesn/aJohn
lastNamestringYesYesn/aSmith
idstringYesNon/asigner1
The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names from the feature overview.

Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be signer1. This will be the Role Name used in the code section below to let OneSpan Sign know what fields to associate with each signer.

PDF used in this guide can be found here.

The Code

The sample code below shows you how to setup your document package (transaction in the new UI) for Text Tag extraction. When building Role object, you will see that the Role Name coincides with the one in the image of the PDF form shown earlier in the guide. Then don’t forget to enable the document level extract, and set esl_doc_extract_type to 1, which is text tags extraction.

Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the Role Name and the associated text tags from the PDF.

    	ESignLiveSDK sdk = new ESignLiveSDK();
         
        //Create package
        ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
        pkg.name = 'Test Text Tags - ' + Datetime.now().format();
        pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;
        
        //Create Roles
        String roleId1 = 'signer1';
        ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();
        role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', '[email protected]', 'CEO', 'ABC Bank');
        role1.id = roleId1;
        role1.name = roleId1;
        pkg.roles = new List<ESignLiveAPIObjects.Role>{role1};    //add role
        
        //Prepare Documents Blob
        String document1Name = 'Sample_Text_Tag';
        StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_text_tag' LIMIT 1];
        Map<String,Blob> documentBlobMap = new Map<String,Blob>();
        documentBlobMap.put(document1Name, sr.Body);
         
        //Create Document Metadata
        ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
        document1.name = document1Name;
        document1.id = document1Name;
        document1.extract = true;
        ESignLiveAPIObjects.Data data_x = new ESignLiveAPIObjects.Data();
        data_x.esl_doc_extract_type = '1';
        document1.data = data_x;
        pkg.documents = new List<ESignLiveAPIObjects.Document>{document1};    //add document
        
    	//Send package One Step
        String packageId = sdk.createPackage(pkg,documentBlobMap);
        System.debug('PackageId: ' + packageId);

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo