b) ESign Input XML: Creating signature requests
- Leonard Schubert
- Dennis Machowetz
- Andy Erd
The Tyrservice method processXML is used to upload an XML which contains one or more PDF as a base64 string and the signature field definitions.
Example: Uploading a single document with signature fields.
ESign ist the root element of the XMLs.
<?xml version="1.0" ?>
<ESign>
...
</ESign>1. Defining the document
The PDF/A document must first be converted to a base64 string. For writing an XML by hand, online tools can be used to encode the file. (https://base64.guru/converter/encode/pdf )
The base 64 string must be inserted in a <PDF> tag.
Optionally you can define a <PDFName> which will be shown in websignatureOffice. If no name is provided, a name is generated containing the date and document_id: e.g. “upload_2023-01-16_51327.pdf”.
<?xml version="1.0"?>
<ESign>
<PDFName>example document</PDFName>
<PDF>JVBERi0xLjcNCi...</PDF>
</ESignThis XML will upload a document with the name “example document” without any signature fields. The document would be shown as “new” in websignatureOffice and it is possible to add signature fields in the UI to create a signature request.
2. Adding signature fields.
Signature fields are listed in the tag <Signatures>.
There are currently three ways to define the position of the field in the document.
XML element |
|
|
|---|---|---|
<Static> | With a <Static> signature field, the position is defined with absolute coordinates in the document. All Units are in centimeter. The X and Y coordinates are measured from the top left corner. The field in the example is positioned 5 cm from the left, 10 cm from the top and has a height of 2 cmand width of 4 cm. | <Signatures>
<Static>
<Page>1</Page>
<X>5</X>
<Y>10</Y>
<Height>2</Height>
<Width>4</Width>
</Static>
...
</Signatures> |
<DigSig> | With <DigSig> the position and size of the signature field is derived from an allready existing signature field in the PDF. For that it is necessary to define the field in an PDF editor (e.g. Adobe). In the XML the field is referenced by the form field name in the PDF with the tag <FieldName>. It is not necessary to define the size and position because this is derived from the PDF. | |
<Signature> | The position of a <Signature> is derived from a string in the document. The string is defined with the tag <Placeholder>. The tyrservice will search the document for the provided string and place the signature field at the strings coordinates. Additionally it is necessary to define the size (width and height). |
The complete XML for a document named “example document”containing one signature field definition using <Signature>:
The document must contain the string “Signature1”. The signature field is set at every position where the string occurs.
Example documents
The XML contains one signature of each type described above.
original document:
The document contains the XML definition of the three signatures. The signature fields will be placed under the description.
The document contains one digital signature field with the name “DigSig1”. The field can be shown in a pdf reader. The document also contains the string “Signature1” which is used for the <Signature> definition.
XML:
The allready existing digital signature field in the document is referenced with the tag <FieldName> in the <DigSig> section with “DigSig1”. The signature will be placed in the defined field.
The signature field of the <Signature> block will be placed at the position of the text “Signature1” in the document. The text is referenced by <Placeholder> in the <Signature> block.
Viewer
The three signature definitions are interpreted by the tyrservice and shown in the websignatureoffice viewer:
signed document
When signing with websignature office the digital signatures with certificates are added to the document:
3. Defining signatories.
A signature field can be assigned to a user with the tag <UserName>. If no <UserName> is provided, the signatory of the field is the uploading user like in the example above.
The <UserName> must either contain the login name of a registered websignature office user or a valid email address. A notification email informing the signer of the signature request will be send to the email address of the registered user or the email address provided. (In the example below to “someperson@example.com”):
4. Defining the “signature type”
WebsignatureOffice supports different signature types to sign a document. The signature type is set with the tag <SignatureType> which contains an Integer (0-4).
xml | description | example |
|---|---|---|
<SignatureType>0</SignatureType> | stamp data (text/image) without a signature: The xml tag <Stamp> within the signature definition is mandatory. It may contain an image (in base64), a text or both. When clicking “sign now” in the document viewer, all signatures with type 0 will be added to the document without further interaction. For more details of the stamp definition see XML Elements overview
Behaviour after start signing: 
| |
<SignatureType>1</SignatureType> | digital stamp (signature with user certificate instead of hand-written signature): When using a digital stamp, the user may add a comment and the date to the signature. If the user is a registered websignatureOffice user, he has to enter his password.
Behaviour after start signing:
|
|
<SignatureType>2</SignatureType> | html-signer signature only: The document is signed with the mouse cursor in a browser.
Behaviour after start signing:
|
|
<SignatureType>3</SignatureType> | pad signature only
Behaviour after start signing: webso connects to the signature pad and the signature field will be shown on the pad If no pad connector is installed, a link to a download site is shown. If the pad connector is installed, but no pad connectet: Notification is shown. The pad doesn’t have a suitable key: Signing is not possible, notification is shown.
| |
<SignatureType>4</SignatureType> | remote signature only
Behaviour after start signing: remote signature type popup is shown. Possible options:
The shown options can be defined in <SelectionPhoneTabletDetails>.
|
With <SelectionPhoneTabletDetails> : customize the remote signature popup |
<SignatureType> not defined | If no <SignatureType> is provided, the user can choose between
Behaviour after start signing: The signature type popup is shown. For <SignatureGroup>s the popup can be customized in <ShowSignatureTypePopUpDetails>.
|
With <SignatureGroup> Definition and <SelectionPhoneTablet> definition: Remote signature (SignatureType 4) selection definition. |
All signature types can contain a <Stamp> image and text.
If no <SignatureType> is provided, the signatory can choose between html-signer (2), pad signature (3) and remote signature (4).