OneSpan Sign How To: Using Text Tags

In the upcoming release of OneSpan Sign (11.5), we've added a new Text Tag Extraction feature that 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. Version 11.5 is scheduled to be released on August 7th for the sandbox environment and August 17th for production environment. In this blog, I will walk you through an example of how to use Text Tags.

The Code

Let's get straight into it. The Text Tag extraction feature is very straightforward to use. In short, all you need to do is add the "text tags" on your document where you want your signatures and fields to be using OneSpan Sign's nomenclature. Once you upload your document to OneSpan Sign, the text tags will disappear and be replaced with the corresponding signatures and fields. For example, the following is the shortest valid syntax for a text tag:

{{esl:role:fieldType}}

Where role the is the roleId of your recipient and fieldType is the signature or field type that you want to put. Below is a screenshot of the document I used in my example. It illustrates a few valid example text tags that you can use.

The Text Tags extraction feature is available through our REST API and SDKs. For a complete description of the new Text Tag feature, refer to our documentation. Once your document is finalized, you need to enable this feature during transaction creation. Below are examples using our Java SDK, .NET SDK, and REST API respectively.

Java SDK

EslClient eslClient = new EslClient( API_KEY, API_URL );

DocumentPackage pkg = PackageBuilder.newPackageNamed("Text Tags Example")
		.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
				.withFirstName("John")
				.withLastName("Smith")
				.withCustomId("signer1"))
		.withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
				.fromFile("C:/Users/hhaidary/Desktop/sample_contract_text_tags.docx")
				.enableExtraction()
				.withExtractionType(ExtractionType.TEXT_TAGS))
		.build();

PackageId packageId = eslClient.createAndSendPackage(pkg);

System.out.println(packageId);

.NET SDK

EslClient eslClient = new EslClient(API_KEY, API_URL);

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

PackageId packageId = eslClient.CreatePackageOneStep(pkg);

Debug.WriteLine(packageId);

REST API

POST https://sandbox.esignlive.com/api/packages HTTP/1.1
Content-Type: multipart/form-data; esl-api-version=11.9; boundary=lKkOm3QpMGT9LnKz
Authorization: Basic YOUR_API_KEY
Host: sandbox.esignlive.com
Content-Length: 13736
Expect: 100-continue
Connection: Keep-Alive

--lKkOm3QpMGT9LnKz

Content-Disposition: form-data; name="payload"; filename="payload"

{
  "autocomplete": true,
  "documents": [
    {
      "extract": true,
      "extractionTypes": [
        "TEXT_TAGS"
      ],
      "index": 0,
      "name": "Sample Contract"
    }
  ],
  "name": "Text Tags Example",
  "roles": [
    {
      "id": "signer1",
      "index": 0,
      "name": "signer1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John",
          "id": "signer1",
          "lastName": "Smith"
        }
      ]
    }
  ],
  "status": "SENT",
  "type": "PACKAGE",
  "visibility": "ACCOUNT"
}

--lKkOm3QpMGT9LnKz

Content-Disposition: form-data; name="file"; filename="C:/Users/hhaidary/Desktop/sample_contract_text_tags.docx"

[doc binaries]

--lKkOm3QpMGT9LnKz--

Running Your Code

Once you run your code, you will see that the text tags have disappeared and have been replaced with their corresponding signature and fields.

You can download the sample JSON and document above from the Developer Community Code Share.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: developer.esignlive.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary

Technical Evangelist

LinkedIn | Twitter 

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today