▲ Top

Extraction

When you upload a document to OneSpan Sign, you can leverage the following time-saving features:

Text Anchor Extraction

Text Anchor Extraction enables a package sender to position a field or signature, based on text in the uploaded document.

Text Anchor Extraction is available only in the API call that uploads the document. It is not available in subsequent calls.

To enable Text Anchor Extraction on a field, ensure that:

  1. The uploaded document that contains the Text Anchor has extraction enabled.
  2. The field and signature that will be positioned according to the Text Anchor have their Text Anchor objects set.

Anatomy of a Text Anchor

When you build a Text Anchor, you must configure the parameters in the following table.

Parameter Purpose
Anchor Text

The exact string that will be searched for in the uploaded document

Index The "occurrence" of the string. For example, if index = 2, the software will skip the first two occurrences of Anchor Text, and use the third occurrence to calculate position.
Character Index The index of the character within the Anchor Text that will be used to calculate the position
Anchor Point Which corner of the specified character to use as the base for calculating position
Left Offset An absolute offset applied to the final x value
Top Offset

An absolute offset applied to the final y value

Height

The height of the field position to be calculated

Width

The width of the field position to be calculated

The following code sample illustrates how to create a field whose position is specified by a Text Anchor.

Position Extraction

Position Extraction ensures that the exact position and size of a field or signature in an uploaded PDF file are automatically retained in the OneSpan Sign system.

Position Extraction is available only in the API call that uploads the document. It is not available in subsequent calls.

To enable Position Extraction on a field or signature, ensure that:

  • The name of the field or signature in the SDK model is exactly the same as its name in the uploaded PDF file.
  • Both the document and the field or signature are set to "extract". To set a field or signature to "extract", you must invoke the withPositionExtracted() method on the builder.

The following code samples extract the position of a signature from an uploaded PDF document.

Document Extraction

Document Extraction looks for appropriately named signatures and fields in an uploaded PDF document, and for each one, it creates a OneSpan Sign signature or field. The positions and sizes of the signatures and fields from the PDF are automatically retained in OneSpan Sign.

Document Extraction is available only in the API call that uploads the document. It is not available in subsequent calls.

To enable Document Extraction on a particular PDF document, you must enable extraction on the document in the SDK model before you create the relevant document package.

The information needed to create each OneSpan Sign signature or field is taken from the name of the PDF signature or field.

To create a OneSpan Sign signature field, the PDF field must have a name of the form [Signer.SigStyle#], where:

  • Signer is the custom ID of the signer.
  • SigStyle# is a signature style (Capture, Initials, or Fullname) combined with an integer for uniqueness. For example: Capture1 or Fullname09.

If you want the signature field to be optional, simply use the following format: [Signer.SigStyle#.Optional].

To create an unbound OneSpan Sign field, the PDF field must have a name of the form [Signer.SigStyle#.FieldStyle#], where:

  • Signer.SigStyle# identifies the signature associated with this field.
  • FieldStyle# is a field style (Textfield or Checkbox) combined with an integer for uniqueness. For example: Textfield2 or Checkbox6.

To create a bound OneSpan Sign field, the PDF field must have a name of the form [Signer.SigStyle#.label#.Binding], where:

  • Signer.SigStyle# identifies the signature associated with this field.
  • label# is an identifier of the field, consisting of the word label combined with an integer for uniqueness.
  • Binding is a field style. The possible values are Date or {approval.signed}, Name or {signer.name}, Title or {signer.title}, and Company or {signer.company}. Both members of each pair signify the same field style.

All parts of a PDF field name are matched using case-insensitive matches. For example, a field named [Agent1.Fullname1.label1.Date] is treated the same as a field named [AGENT1.FULLNAME1.LABEL1.DATE].

Example

Here is an example. Suppose a package has two signers whose custom IDs are Agent1 and Client1. Further suppose that extraction is enabled, and that a PDF is uploaded which has fields with the following names:

[Agent1.Fullname1]
[Agent1.Fullname1.label1.Date]
[Agent1.Fullname1.Textfield1]
[Agent1.Fullname1.Checkbox1]
[Agent1.Fullname2.Optional]
[Client1.Capture1]
[Client1.Capture1.label1.Name]
[Client1.Capture1.label2.Date]
[Client1.Capture1.label3.Title]
[Client1.Initials1]
[Client1.Initials2]

Before signing, Agent1 must complete two fields:

[Agent1.Fullname1.Textfield1]
[Agent1.Fullname1.Checkbox1]

Once those fields are complete, Agent1 can sign [Agent1.Fullname1], and [Agent1.Fullname1.label1.Date] will automatically be filled with the date of signing.

Client1 needs to sign in three places:

[Client1.Initials1]
[Client1.Initials2]
[Client1.Capture1]

Once these are all signed, the remaining fields will be filled:

[Client1.Capture1.label1.Name]
[Client1.Capture1.label2.Date]
[Client1.Capture1.label3.Title]

Text Tag Extraction

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.

When a Text Tag inserts an object in a document, that object overwrites and thus obscures any preexisting content in that place.

To use this feature, you must understand the following:

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,...]}}

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.
  • 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("Option")}}
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.

Using the Feature

The following code samples illustrate how to use Text Tag Extraction.

Video Tutorial

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