This case leads you through the process of the API call to prepare an envelope. Generally this call helps you to prepare all steps and the whole configuration for an envelope you want to send later.
The Story
A car seller is in the final step of selling the car to a customer. He/She creates the contract and adds all the features, that the car will later include, in the document. In order not to overwrite the signature field with text, the seller has created a dynamic field so that the signature field is dynamically placed on the page.
Use Case Description
In a car sales, it is likely that with additional features, which should be installed in the new car, the signature field in the contract is not always on the same position (page 1) but on the second or third. Therefore, it makes sense to place dynamic placeholders. Exactly this case will be described here.
Integration
Advanced Document Tags
Advanced document tags are a solution to define interactive form elements in a PDF document by inserting text placeholders. Such advanced document tags are considered in following use cases:
- Creating a draft or template from eSignAnyWhere WebUI
- Creating a draft or sending an envelope via eSignAnyWhere API by using the prepare-method for document parsing.
Alternatives
eSignAnyWhere is offering following alternatives to insert interactive elements:
- Prepare a PDF document with Acrobat Form Fields (simple field types such as text input can be defined e.g. with OpenOffice; signature fields can be inserted with Adobe Acrobat Pro.
Form Fields can't be assigned automatically to the proper signer. Less options for configuration. - Use the simpler sig-string notation as plain-text within the PDF document
Sig strings are supported also by other products of Namirial (xyzmo Client, etc). Fields created via sig strings can't be assigned automatically to the proper signer. Less options for configuration. Benefit is the freely definable start (and optional end) marker string. - Define the fields entirely in the envelope JSON structures when creating a draft or sending an envelope via API
Dimension limitation
Please note that if the height or width of the advanced document tag exceeds the size (width and height) of the document following notification will be displayed:
General Syntax
Recommendations for correct parsing
Note that the Advanced Document Tag must be placed in a single-line within your document. No word wrap (also no automatic word wrap) must happen within your document tag. To ensure that parsing the document tag works fine, use a small, but not too small, font. We recommend to use a sans-serif font (e.g. Arial) in the advanced document tag and use a font size of 4pt to avoid issues with unexpected spaces being inserted between characters during parsing.
The advanced document tag starts with two opening square brackets ("[["), followed by the field definition parameters which are separated by the colon (":"). The advanced document tag ends with two closing square brackets ("]]").
The first field definition parameter is the field name (optionally prefixed by a quantifier ("!" or "*").
The 2nd field definition parameter is the assignment.
Then, attributed element definitions follow.
The first element definition is the field type, attributed in brackets ("(" and ")") with parameters of the field.
Additional element definitions such as labels, default text, font setting, sizing or offset may follow.
Parameters
! | required (optional) |
* | read only (optional) |
fieldname | String (required) |
:signer1 | Assigned to signer; “signer” or “signer1”, “signer2”, … (required) |
:objecttype | Type, e.g. signature, combobox, … (mandatory) |
:property | additional parameters (allow using of some short notation (e.g. l,r,c instead left, right, center, …)) |
Signature Fields
Note: The following signature types are supported: Click2Sign, Draw2Sign, Type2Sign, RemoteSignature, BiometricSignature, LocalCertificateSignature, DisposableCertificate, OtpSignature (as of October 2019, eSAW 3.6) and additionally SwissComOnDemandCertificate since eSAW 21.27.
Sample for Click2Sign and Draw2Sign
[[!sigField1:signer1:signature(sigType="Click2Sign,Draw2Sign",batch=1):label("some label"):size(width=150,height=60)]]
sigType, batch, label, size are optional.
Sample for Automatic Remote Signature
Note: To use an automatic remote signature you must have the role “Automatic Sealing Sender” enabled, otherwise you are not able to proceed.
[[!sig1:signer1:signature(sigType="AutomaticRemoteSignature"):size(height=50):label("some label")]]
Attachments
[[myAttachment:signer:attachment:label("some label"):size(width=10,height=10)]]
label, size are optional.
Textfield
Please note: If a textfield has a default text configured and is set "required" the textfield will be considered as "already filled". This means that it is possible to finish the envelope without explicitely typing data into the textfield.
[[*myText:signer2:text(maxLength=100,password=1,multiline=true):default("default text"):font(name=Arial, color=#FF0000, size=12):alignment(left):size(width=10,height=10)]]
maxLength, password, default, font, alignment (left|right|center), size, multi-line are optional.
Input Validation 
The (optional) input validation definition might be helpful to limit the user input to the expected values. Also check the workstep configuration documentation for accepted formats.
- Date
- Requires a date field for signer1
[[!someDate:signer1:date(format="dd. MMMM yyyy"):range(from="13. März 2018",to="18. December 2019")]]
- range is optional and must match with defined format
- Email
- optional for email field
[[someMail:signer:email()]]
- Number
[[someNumber:signer:number(decimalPlaces=2,decimalSeparator=comma,thousandsSeparator=point,symbol="€",symbolLocation=endWithBlank):range(from="-300,00 €",to="5.000,00 €")]]
- range, decimalSeparator, thousandsSeparator, symbol, symbolLocation, are optional
- decimalSeparator: comma, point, apostrophe, none
- thousandsSeparator: comma, point, apostrophe, blank, none
- symbolLocation: start, startWithBlank, end, endWithBlank
- range must match with defined format
- phone
[[somePhone:signer:phone(type=international)]]
- type: international, internationalLeadingZero, internationalLeadingPlus
- time
[[someTime:signer:time(format="HH:mm"):range(from="12:00",to="18:00")]]
- range is optional
- range must match the defined format
Checkbox
A required checked checkbox is for only one signer.
[[!chk1:signer:checkbox:size(width=10,height=10):checked]]
checked, size is optional.
RadioButton
All items of a group have to have the same name. Group of three RadioButtons for one recipient:
[[testRbnGroup:signer:radio(Red):size(width=10,height=10):checked]] [[testRbnGroup:signer:radio(Green):size(width=10,height=10)]] [[testRbnGroup:signer:radio(Blue):size(width=10,height=10)]]
checked, size is optional.
DropDown
[[myDrop:signer:dropdown(options="Red,Green,Blue",values="R,G,B",editable=1):default("R"):font(name=Arial, color=#FF0000, size=12):alignment(left):size(width=10,height=10)]]
values, editable, default, size, font, alignment (left|right|center) are optional.
List
[[myList:signer:list(options="Red,Green,Blue",values="R,G,B",multiSelect=1):default("R"):font(name=Arial, color=#FF0000, size=12):alignment(left):size(width=10,height=10)]]
values, multiSelect, default, size, font, alignment (left|right|center) are optional.
Offset
You can define a offset by using
:offset(x=-10.5,y=-50.6)
The offset starts at the lower left position, is using points as units and numbers (double) as input. A positive x value moves to right and a positive y value moves up. Note: this is support eSAW version 3.0+.
Variables
Use to reuse some fragments and allow an easier placement of the text markup into floating text.
Definition:
[[#myFontSettings=:font(name=Arial, color=#FF0000, size=12):alignment(left)]]
Usage:
[[myList:signer:list(options="Red,Green,Blue",values="R,G,B",multiSelect=1):default("R")$myFontSettings:size(width=10,height=10)]]
In the next section you can find a input validation example for REST. With this configuration only numbers from -300,00 to 5.000,00 are allowed in the Textfield.
"Range": {
"From": "-300,00 €",
"To": "5.000,00 €"
},
you can type in any numbers. If you define the same number for “FROM” and “TO” you can only type in the given number. For example if you define 400,00 for “FROM” and “TO” the recipient can only type in this number into the Text Field.
The following steps (including the optional use of the advanced document tag) are necessary for the API call:
- prepare a document with advanced document tags
- upload the document
- prepare the envelope
- send the envelope
Please also see the developer mode for this tutorial here: Visit the developer mode.
Prepare a document with advanced document tags
For this case you can use the following document which includes one text field and one checkbox:
Download the document advanced_document.pdf.
Upload the document
Make sure you upload a document which contains advanced document tags to see the differences in preparing the envelope.
Preparing the envelope
If you are using the Advanced Tags via API you have to call file/prepare to use them.
| Method | REST endpoint |
|---|---|
| POST | https://demo.esignanywhere.net/api/v6/file/prepare |
For this call you need the File Id which you got from the upload file call and the following sample configuration:
{
"FileIds": [
"6a1eef93-1234-1234-9526-bceda76addba"
],
"ClearFieldMarkupString": true,
"SigStringConfigurations": [
{
"StartPattern": "string",
"EndPattern": "string",
"ClearSigString": true,
"SearchEntireWordOnly": true
}
]
}
Please note the following: If you define “false” for the "ClearFieldMarkupString" the field markup string will not be cleared. If you choose “true” the field markup string will be cleared.
"ClearFieldMarkupString": true,
After successful configuration you get as response the configuration for the fields you added with the field markups.
{
"UnassignedElements": {
"TextBoxes": [],
"CheckBoxes": [],
"ComboBoxes": [],
"RadioButtons": [],
"ListBoxes": [],
"Signatures": [],
"Attachments": [],
"LinkConfiguration": {
"HyperLinks": [],
"DocumentLinks": []
}
},
"Activities": [
{
"Action": {
"Sign": {
"Elements": {
"TextBoxes": [
{
"ElementId": "myText1",
"Required": true,
"Value": "Place for signer1",
"DocumentNumber": 1,
"Validation": {
"Type": "None"
},
"FieldDefinition": {
"ReadOnly": false,
"MaxLength": 100,
"IsMultiline": false,
"IsPassword": false,
"TextFormat": {
"TextColor": "255, 0, 0",
"FontSizeInPt": 12.0,
"FontName": "Arial",
"Bold": false,
"Italic": false,
"TextAlign": "Center"
},
"Position": {
"PageNumber": 1,
"X": 72.0,
"Y": 563.4767578125
},
"Size": {
"Width": 200.0,
"Height": 65.149999999999991
}
}
}
],
"CheckBoxes": [
{
"ElementId": "chk1",
"DocumentNumber": 1,
"Required": true,
"IsChecked": true,
"FieldDefinition": {
"Position": {
"PageNumber": 1,
"X": 72.0,
"Y": 439.8017578125
},
"Size": {
"Width": 25.0,
"Height": 25.0
},
"ReadOnly": false
}
}
],
"ComboBoxes": [],
"RadioButtons": [],
"ListBoxes": [],
"Signatures": [],
"Attachments": [],
"LinkConfiguration": {
"HyperLinks": [],
"DocumentLinks": []
}
}
}
}
}
]
}
Sending the envelope
You can now add the configuration you get as response from the prepare call to your send envelope call and send the document to recipients.
FAQ
The Advanced Document Tag does not fit into a table cell. How can I solve that?
We recommend to use a variable that holds the entire Advanced Document Tag. Variables are not restricted to be just a parameter part of the advanced document tag; they can even store the entire notation.
The variable can be defined outside the table structure. Then, inside the table, just use the variable reference.
I am using Advanced Document Tags for Dropdown Configuration. But my list of allowed values is quite long. Even with small font size, I cannot make it fitting into a single line. How to proceed?
It's allowed to use variables to define a subset of the value list, and then either define another variable that merges the different subsets, or use the list of subsets directly in the Advanced Document Tag.
Example:
[[#ListItems01=A,B,C]] [[#ListValues01=v1,v2,v3]] [[#ListItems02=D,E,F]] [[#ListValues02=v4,v5,v6]] [[myDropDown:signer1:dropdown(options="$ListItems01,$ListItems02",values="$ListValues01,$ListValues02",editable=1):font(name=Arial, color=#FF0000, size=12):alignment(left):size(width=10,height=10)]]