10.2 Signing location with id reference
When a document is added, the eSignatures API will search for signing fields or text markers in the document. The visual location of these fields or markers will then decide the location of the signature in the PDF. The MarkerOrFieldId parameter is used to reference such a field or marker. By doing so, the coordinate parameters of the Add Document To Package call will become forbidden. The eSignatures configuration has options to restrict which text fields or text strings are matched.
Note: identifiers need to be unique! A single document should not contain signing fields, text fields or text markers with the same identifier.
Attention: The Document Portal and eSignatures API use the same detection logic. This means that the Text Marker Format and Text Field Format settings in the External API must match the ones used in the Configuration Index, and vice versa.
10.2.1 PDF signature fields
If the PDF contains dedicated (empty) signature fields, then the id of such a field will be matched against the value given in the parameter MarkerOrFieldId to see if the id of the field is equal.
10.2.1.1 Detection of PDF signature fields
PDF signature fields are detected using the PDF Signature Field Name.
10.2.1.2 Example
To specify which MarkerOrFieldId an Actor should use, see the Actor parameters below. The examples hereunder only include all the required parameters and use the PDF Signature Field Name example from section 10.2.1.1 above.
For all Actor parameters, see sections 5.4.5.1, 5.5.5.1 and 5.7.6.2.
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"SigningFields": [
{
"MarkerOrFieldId": "PDF Signature Field Name"
}
],
"SigningTypes": [
{
"SigningType":"Digital"
}
],
}
]
10.2.2 PDF text fields
A PDF can contain text input fields (form-field). The name property of the input field should equal the id given in the parameter MarkerOrFieldId.
Note: text fields are only used when the document has not been signed yet, and their names must correspond to the format defined in the Configuration Index.
Important: this name is not necessarily the one displayed when you hover over the field. The name can only be reliably verified when opening the PDF in Acrobat Professional’s “Form Edit” mode.
10.2.2.1 Detection of PDF Text fields
Pay attention if your PDF documents contain editable text fields. If the name of a such a text field corresponds to the Text Field Format (regex) you or your administrator configured in the Configuration Index, the text field will be converted to a signature field in eSignatures, and the original text field will not be displayed. This is intended behavior.
If you want to upload PDF documents with editable text fields, and prevent eSignatures from converting them into signature fields, make sure the name of the text field you create in your PDF Solution does not correspond to the Text Field Format that has been defined in the Configuration Index of eSignatures. Using the default regex, this means your Text Field Name should not start with a # if you do not want them converted.
#[a-zA-Z]+(?:\d*.)?\d+.
Regex explanation
- The leading # means the Text Field must start with a hashtag
- [a-zA-Z] matches any character from a to z, in small or capital letters
- The + indicates 1 or more occurrences of the previous sub-expression
- ?: means the preceding item is optional and matches at most once
- \d is a metacharacter that matches any digit, which is identical to [0-9]
- '*' means 0 or more instances of the preceding token
- . matches the . character
- ? is an occurrence indicator denoting 0 or 1 occurrence (i.e. optional)
- The + indicates 1 or more occurrences of the previous sub-expression
Note: Text Fields can't be added in eSignatures itself but must be added to the pdf before upload.
10.2.2.2 Example
To specify which MarkerOrFieldId an Actor should use, see the Actor parameters below.
The examples hereunder only include all the required parameters and use the PDF Signature Field Name example from 10.2.2.1.
For all Actor parameters, see sections 5.4.5.1, 5.5.5.1 and 5.7.6.2.
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"SigningFields": [
{
"MarkerOrFieldId": "SIG01",
}
],
"SigningTypes": [
{
"SigningType":"Digital",
}
],
}
]
10.2.3 Text markers
In addition, the document will be scanned for special markers in the text.
The format of such markers can be finetuned in the Configuration Index but it will always be of a form like #XXX000_H_W# (see below for what all parts mean). The MarkerOrFieldId parameter will then be matched against the XXX000 part of the text marker to see if they are equal, the “#” should not be passed.
Instead of adding signature fields one by one in eSignatures, you can choose to add Text Markers to the documents you upload. Text Markers are pieces of text that indicate where the signature fields must be placed, and which dimensions they must have. This can be useful if all your signature fields must be placed at the same location and require a specific size.
Tip: the location in the document where you put the Text Marker is where the signature field will be placed.
Note: signing fields placed over the marker are transparent, it’s required to change the font color of text markers to the background color. This restriction needs to be handled for all text markers. Calculation for dimensions and location is based on (PDF point units = (mm * 72dpi) / 25.4).
BEWARE! You must type the markers in one fluent go. Otherwise the solution will recognize each stop and delete as a specific character, thus failing the equality check.
Markers should have the format #XXX000_H_W#:
- X: to indicate that it is a signature field location
- 0: numerical identification of the signature field (by default ‘01’, ‘02’, ‘03’ …)
- H: height of the signature field.
- W: width of the signature field. Example: #SIG01_100_200#
10.2.3.1 Detection of Text Markers
Text Markers must correspond to the Text Marker Format (regex) defined in the Configuration Index. Otherwise the signature field won't be placed correctly, or not placed at all. The default format for searching Text Markers in a document (regex) is as follows:
#[a-zA-Z]+(?:\d*.)?\d+(?:\d*.)?\d+(?:\d*.)?\d+#
Regex explanation
- The leading # means the Text Field must start with a hashtag
- [a-zA-Z] matches any character from a to z, in small or capital letters
- The + indicates 1 or more occurrences of the previous sub-expression
- ?: means the preceding item is optional and matches at most once
- \d is a metacharacter that matches any digit, which is identical to [0-9]
- ’** means 0 or more instances of the preceding token
- matches the character
- ? is an occurrence indicator denoting 0 or 1 occurrence (i.e. optional)
- The + indicates 1 or more occurrences of the previous sub-expression
In practice this means a Text Marker should always be in the following format #SIGidentifier_Height_Width#.
E.g. #SIG01_100_200#.
In this example a signature field of 100 points high and 200 points wide will be placed. When adding a Text Marker, always put the Height value (minimum 70 points) in front of the Width value (minimum 112 points).
- Text Markers should not be combined with rotated PDFs because detected signature fields won't be rotated automatically to match the PDF text direction. They'll be placed near the text marker on a best-effort approach.
- Text Markers cannot be added in eSignatures itself but must be added to the document/PDF before you upload it.
10.2.3.2 Example
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"SigningFields": [
{
"MarkerOrFieldId": "SIG01",
}
],
"SigningTypes": [
{
"SigningType":"Digital",
}
],
}
]