OneSpan Sign How To: Using Text Anchors
Lately, there has been a number of questions, in the forums, concerning the text anchor extraction feature with the SDKs and API, so I thought it would be a great opportunity to create a How To blog. In short, text anchors allow you to position a field or signature based on the text in your document. This document can be of any type as opposed to document extraction, which requires a PDF form. In this blog, I will show you how to use text anchor extraction with the OneSpan Sign Java SDK, .NET SDK, and the REST API.
Text Anchor Parameters
Before diving into the code, let me give you a brief description of each parameter you can pass when building your text anchor. It is important to note that when using text anchor, the search is performed in a case sensitive fashion. Also, if some parameters are not specified, they will default to the values below.
| Parameter | Description | Required | Default Value |
|---|---|---|---|
| Anchor Text | The exact string that will be searched in your document. | Yes | Not applicable |
| Anchor Point | The corner of the specified character to use as the base for calculating the position. Available values: TOPLEFT, TOPRIGHT, BOTTOMLEFT, and BOTTOMRIGHT. | Yes | Not applicable |
| Index | The occurrence of the string. For example, a value of 1 will skip the first occurrence and use the second instance to calculate position. | No | 0 |
| Character Index | The index of the character within the anchor text that will be used to calculate the position. | No | 0 |
| Left Offset | The offset applied to the final x-coordinate. | No | 0 |
| Top Offset | The offset applied to the final y-coordinate. | No | 0 |
| Height | The height of the field or signature. | No | 50 |
| Width | The width of the field or signature. | No | 200 |
The Code
As I mentioned above, I will show you how to use text anchor with the Java SDK, .NET SDK, and the REST API. Go ahead and skip to the section which applies to your technology. I will cover the same information in each segment. Full example code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.
Java SDK
Let’s begin with the Java SDK. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. The sample code below shows you how to edit the document block for text anchor. If you need a comparison to the basic document object creation or if this is your first time creating a package with the Java SDK, see this blog.
.withDocument(newDocumentWithName("Sample Contract")
.fromFile("PATH_TO_YOUR_FILE")
.enableExtraction()
.withSignature(signatureFor("[email protected]")
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("Signature of the Client")
.atPosition(TextAnchorPosition.TOPLEFT)
.withSize(150, 40)
.withOffset(0, -50)
.withCharacter(0)
.withOccurence(0))
.withField(FieldBuilder.signerName()
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("(hereafter referred to as")
.atPosition(TextAnchorPosition.TOPRIGHT)
.withSize(150, 20)
.withOffset(-175, -5)
.withCharacter(0)
.withOccurence(0)))
.withField(FieldBuilder.signatureDate()
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("Date")
.atPosition(TextAnchorPosition.TOPRIGHT)
.withSize(75, 40)
.withCharacter(4)
.withOffset(10, -30)
.withOccurence(0))))
.withSignature(signatureFor("[email protected]")
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("Signature of the Contractor")
.atPosition(TextAnchorPosition.TOPLEFT)
.withSize(150, 40)
.withOffset(0, -50)
.withCharacter(0)
.withOccurence(0))
.withField(FieldBuilder.signerName()
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("(hereafter referred to as")
.atPosition(TextAnchorPosition.TOPLEFT)
.withSize(150, 20)
.withOffset(-175, -5)
.withCharacter(0)
.withOccurence(1)))
.withField(FieldBuilder.signatureDate()
.withPositionAnchor(TextAnchorBuilder.newTextAnchor("Date")
.atPosition(TextAnchorPosition.TOPRIGHT)
.withSize(75, 40)
.withOffset(10, -30)
.withCharacter(4)
.withOccurence(1)))
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join Today.NET SDK
Next, I will go over the .NET SDK. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. The sample code below shows you how to edit the document block for text anchor. If you need a comparison to the basic document object creation or if this is your first time creating a package with the .NET SDK, see this blog.
.WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
.FromStream(fs, DocumentType.PDF)
.EnableExtraction()
.WithSignature(SignatureBuilder.SignatureFor("[email protected]")
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Signature of the Client")
.AtPosition(TextAnchorPosition.TOPLEFT)
.WithSize(150, 40)
.WithOffset(0, -50)
.WithCharacter(0)
.WithOccurrence(0))
.WithField(FieldBuilder.SignerName()
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("(hereafter referred to as")
.AtPosition(TextAnchorPosition.TOPRIGHT)
.WithSize(150, 20)
.WithOffset(-175, -5)
.WithCharacter(0)
.WithOccurrence(0)))
.WithField(FieldBuilder.SignatureDate()
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Date")
.AtPosition(TextAnchorPosition.TOPRIGHT)
.WithSize(75, 40)
.WithCharacter(4)
.WithOffset(10, -30)
.WithOccurrence(0))))
.WithSignature(SignatureBuilder.SignatureFor("[email protected]")
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Signature of the Contractor")
.AtPosition(TextAnchorPosition.TOPLEFT)
.WithSize(150, 40)
.WithOffset(0, -50)
.WithCharacter(0)
.WithOccurrence(0))
.WithField(FieldBuilder.SignerName()
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("(hereafter referred to as")
.AtPosition(TextAnchorPosition.TOPLEFT)
.WithSize(150, 20)
.WithOffset(-175, -5)
.WithCharacter(0)
.WithOccurrence(1)))
.WithField(FieldBuilder.SignatureDate()
.WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Date")
.AtPosition(TextAnchorPosition.TOPRIGHT)
.WithSize(75, 40)
.WithOffset(10, -30)
.WithCharacter(4)
.WithOccurrence(1)))
REST API
Finally, I will cover the REST API. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. I included the JSON that will create your document package with text anchor for convenience. Please note that OneSpan Sign’s API convention allows only one signature field (i.e. "type": "SIGNATURE") per approval in the approvals object. A second signature for a given role would need to be added as a separate approval. If you need a comparison to the basic document object creation or if this is your first time creating a package with the REST API, see this blog.
|
|
Running Your Code
Once you’ve run your code, if you log into OneSpan Sign, you should find the appropriate signatures and fields in the document in your OneSpan Sign document package, as seen below.
There you go. You have successfully created a new package with text anchors.
If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://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.
