Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

The structure of the XML as svg can be found here: eso.svg

and created via .xsd:

The svg also contains XML elements which aren't relevant for TyrService upload. 

General remark:

  • If an element has the possible Integer values 0 and 1, 0 means false and 1 means true.

  • Elements which are not definable at upload time are put in brackets. (Those elements are added to the xml file when calling the Tyr-Service method "retrieveXML" and provide additional information about the processing of the envelope / document)

  • Complex types are defined in dedicated tables below and linked in the "Type" column.

<ESign> : Root-Element

ESign is the root element of the XML. (Java) classes can be created using a .xsd file. The file will be provided on request. Not all XML-elements are processed by websignatureOffice, but only by eSignatureOffice.

<ESign> contains the following children. Only children marked with "webso" are relevant for websignatureOffice.

If the xml defines an envelope, only the elements marked green are used as children of <ESign>. The other elements will be defined for each document in ESign.SignatureRequestEnvelope.Documents.Document. If the xml defines a single document, the children of <ESign> are used.

<ESign>:

XML-Element

webso

Type

description

<Window>

<Signatures>

x

<Signatures>

Contains the signature-field definitions. Possible Signature Types are

<Signature>: The field is defined with a search item (<Placeholder>) within the pdf-file

<DigSig>: The field is defined with a signature-filed within the pdf-file

<Static>: The field is defined with coordinates

<FillInfo>

x

<FillInfo>

Contains a List of Name-Value Pairs to fill formfields within the pdf-document

<GUIMode>

<SCSPath>

<ReadBeforeSign>

<DeviceKind>

<BlindPadSearch>

<PublicKey1Emulation>

<SCS>

<CorpCode>

<Overlapped>

<AfterSigning>

<AfterCancel>

<PDF>

x

base64

base64 encoded PDF-file

<PDFName>

x

String

name of the pdf shown in GUI. If no name is set, the name will be set dynamically:

upload_2022-07-21_46669.pdf

<TapToSign>

x

Integer

1/0

"true" or "false" / "1" or "0" (false by default or if tag isn't defined). If TapToSign is "true" the signature fields can be activated/signed via clicking into the individual field within the iSignatureOffice or aSignatureOffice App (instead of clicking the start-signing button).

<TapToSignOnly>

x

Integer

1/0

If "1"/ "true" the pen icon (start signing button) in the Apps will be disabled and you need to click into the signature field to sign.

<PdfNoBiodata>

x

If present, the method retrieveXml will fill the field with the base64 encoded pdf without biometric data.

The document doesn't contain the certificates but pictures of the signatures.

The <PDF> tag will still be filled with the signed document.

See Condition.DocumentNoBiodata

At upload time the field must be empty.

<DisableHelpButton>

<DisableInfoButton>

<ShowDialogPrintButton>

<ShowFormFillButton>

<HideSignControllButtons>

<HideLcdSignButton>

<DeviceKeys>

<OpenResult>

<LastMacroNumber>

<MacroButtonHistory>

<Macro1Upload>

<Zoom>

<ScrollInSignMode>

<HashDialog>

<Found>

<Signed>

<Output>

<DeviceDetails>

tbd: not applicable at upload time

<DueDate>

x

DateTime

2019-07-21

This tag defines the expiration date of the signature request / envelope.

Example: <DueDate>2019-07-21</DueDate>

If <DueDate> is defined, <DueDays> <DueWeeks> and <DueMonths> will be ignored.

If neither <DueDate> <DueDays> <DueWeeks> and <DueMonths> are defined, the expiration time is unlimited.

If <DueDate> is in the past, no due date will be set.

<DueDays>,

<DueWeeks>,

<DueMonths>

x

Integer

Tags are defining the expiration of the signature request / envelope.

With setting a value in one of the three tags, the due date will be the date x days / weeks or months after the time of upload.

The relevant value is always the next expected date. For example <DueDays> is set with the value 9 and <DueWeeks> is set with the value 1, the due date will be 7 days later (one week)

If <DueDate> is defined, <DueDays> <DueWeeks> and <DueMonths> will be ignored.

If neither <DueDate> <DueDays> <DueWeeks> and <DueMonths> are defined, the expiration time is unlimited.

<MandatorySkippable>

Integer

1/0

If set to 1 (true) mandatory fields can be skipped.

This optional tag defines, if mandatory signature fields are skippable (value 1) or not (value 0).

If no value is set or tag is not defined, mandatory signature fields are not skippable.

<Observer>

x

String

userName /

email-adress

Sets an observer for a document. The observer can view the document, but has no signature-fields.

If email notification is active, the user will receive an email with the document-link.

Possible values are a valid email adress or the userName (login) of an active user.

(If the xml defines an envelope and Document.Observer is not defined, ESign.Observer will be used)

<CallbackUrl>

x

String (URL)

www.example.com/event

Defines a callbackURL for the document. If not present, the default callbackURL (server settings) will be used. See e) Callback-API

<DocumentPassword>

x

String

Defines a document password.

If a user has to enter the password is defined in the <Signatures> Element. see <PasswordRequired>

NOTE: Document passwords are stored in plain text in visible for the document creator.

<SignatureGroups>

x

<SignatureGroups>

Contains a list of SignatureGroups. 

(If the xml is an envelope, signature groups can also be defined in ESign.SignatureRequestEnvelope.SignatureGroups.)

<ExecutionOrder>

x

Integer

deprecated ExecutionOrder – specifies field execution order. Possible values: 0 – ABC   ABC ABC, 1 – AAA BBB CCC, 2 – as sorted.

<SignatureRequestEnvelope>

x

<SignatureRequestEnvelope>

defines an Envelope which can contain several documents and download-conditions.

<AppAvailability>

x

Defines how long the signatureRequest / document is available in the app.

<ActiveFrom>: Date from which the document is visible in the app

<ActiveUntil>: Date until the document is visible in the app.

(<DeleteOnServer> : deprecated)

<AppAvailability>
  <ActiveFrom>2022-07-22</ActiveFrom>
  <ActiveUntil>2022-07-25</ActiveUntil>
</AppAvailability>

Document will be visible in app from 22/7/2022 till 25/7/2022

<CryptoIDSelection>

<SignatureOrder>

x

<SignatureOrder>

Defines in which order the users of the document/envelope have to sign.

Contains a list of <SignaturePosition>.

<SignatureOrder> : Defining an order for the signatories

Defines in which order the users of the document/envelope have to sign.

Contains a list of <SignaturePosition>.

Each <SignaturePosition> contains a list of <UserName>. <UserName> can be the login name of a registered user or an email address.

<SignatureOrder>:

XML-Element

webso

Type

description

<SignaturePosition>

x

Contains a list of <UserName> which defines the signatories on the given position.

example

explanation

    <SignatureOrder>
        <SignaturePosition>
            <UserName>signer1@example.com</UserName>
            <UserName>registeredUserLogin</UserName>
        </SignaturePosition>
        <SignaturePosition>
            <UserName>signer2@example.com</UserName>
        </SignaturePosition>
        <SignaturePosition>
            <UserName>signer3@example.com</UserName>
            <UserName>registered_user2@example.com</UserName>
        </SignaturePosition>
    </SignatureOrder>

The document contains signatures for five users.

  1. First the guest user with the email adress signer1@example.com and the registered user with the login "registeredUserLogin" have to sign.

  2. After all users from position one signed their fields, the guest user signer2@example.com can sign the document

  3. After all users from position two signed their fields, the guest user signer3@example.com and the registered user defined by the user email adress registered_user2@example.com can sign the document.

Note: Each user can only be set to one position. So "registeredUserLogin" and "registered_user2@example.com" are not the same users!

<SignatureRequestEnvelope> : Several Documents and download conditions

SignatureRequestEnvelopes group several signaturerequests. The envelopes can contain documents and download conditions. The user has to fullfill the condition before or after signing. The position of the document / condition inside the envelope is defined with the <Position> element.

If the xml contains an envelope, all <ESign> children which are not green, are defined for each document in ESign.SignatureRequestEnvelope.Documents.Document.

<SignatureRequestEnvelope>:

XML-Element

webso

Type

description

<EnvelopeName>

x

String

Defines the name of the envelope shown in the UI.

If no name is provided, it will be generated: upload_2022-07-19 11:00:02.478

<OrderMandatory>

x

Integer

1/0

If 1 (true) the download conditions must be fullfilled in the defined order in the xml. 

If 0 (false) the conditions can be fullfilled at any time.

e.g.: If the envelope contains a signature request on position one and a download condition on position two, it's not possible to fullfill the download condition before signing if <OrderMandatory> is 1. 

field is mandatory.

<SignatureGroups>

x

<SignatureGroups>

Contains a list of <SignatureGroup>s. 

If the XML is an envelope, the SignatureGroups can either be defined in ESign.SignatureGroups or ESign.SignatureRequestEnvelope.SignatureGroups.

<Documents>

x

<Documents>

Contains the documents of the envelopes.

Most children elements of ESign are defined inside the <Document> element.

<Conditions>

x

<Conditions>

Contains the download conditions of the envelope.

<Conditions> : Download Conditions for users of a document

It's posible to set download conditions in a <SignatureRequestEnvelope>. The user has to download the document before or after signing.

The element <Conditions> contains a list of one or more <Condition> elements.

<Condition>:

XML-Element

webso

Type

description

<Position>

x

Integer

The Position of the condition inside the document.

Positions are defined for each condition and document in the envelope.

<ConditionType>

x

String

only possible value is "download"

<PDF>

x

base64

A pdf file encoded in base64 to download. 

Alternativley <DocumentFromPosition> can be defined.

<PDFName>

x

String

name of the document to download.

<DocumentFromPosition>

x

Integer

Defines which document should be downloaded to fullfill the condition. Necessary if <PDF> is not defined.

<DocumentNoBiodata>

x

Integer

1/0

Defines if the document should be downloaded with or without the biodata

If 1 (true) the downloaded document just contains a pictures of the signatures with the text "copy"/"Kopie" but no certificate and no biodata (signature data).

<InfoText>

x

String

a text shown, when the download popup appears.

<ShowInViewer>

x

Integer

1/0

If true (1) the download condition with a preview image of the pdf  is shown in the viewer.

<SignatureGroupName>

x

String

Defines which signatureGroup has to fullfill the download condition.

<UserName>

x

String

Login name of a registered user or an email address. Defines which technical user has to fullfill the download condition.

<AfterSigning>

(<finished> / <FinishedXmlDateTime>)

(x)

When a condition is finished and the method retrieveXML is called, <finished> and <FinishedXmlDateTime> will be added to the returned XML.

Not applicable at upload time.

<Documents> : The documents of a <SignatureRequestEnvelope>

<Documents> contains a list of <Document> elements. The defined documents are shown in the envelope.

(If the xml doesn't contain a signatureRequestEnvelope, the document-attributes are defined as children of <ESign>.)

A document can be defined in a download condition (<DocumentFromPosition>).

<Document>:

XML-Element

webso

Type / example

description

<Position>

x

Integer

Position of the document inside the signatureRequestEnvelope

<PDF>

x

base64

base64 encoded PDF file

<Signatures>

x

<Signatures>

Contains the signature-field definitions. Possible Signature Types are

<Signature>: The field is defined with a Placeholder within the pdf-file

<DigSig>: The field is defined with a signature-filed within the pdf-file

<Static>: The field is defined with coordinates

<PDFName>

x

String

name of the pdf shown in GUI. If no name is set, the name will be set dynamically:

upload_2022-07-21_46669.pdf

<FillInfo>

x

<FillInfo>

Contains a List of Name-Value Pairs to fill formfields within the pdf-document

<TapToSign>

x

Boolean

"true" or "false" / "1" or "0" (false by default or if tag isn't defined). If TapToSign is "true" the signature fields can be activated/signed via clicking into the individual field within the iSignatureOffice or aSignatureOffice App (instead of clicking the start-signing button).

<TapToSignOnly>

x

Boolean

If "1"/ "true" the pen icon (start signing button) in the Apps will be disabled and you need to click into the signature field to sign.

(<PdfNoBiodata>)

x

If present, the method retrieveXml will fill the field with the base64 encoded pdf without biometric data.

The document doesn't contain the certificates but pictures of the signatures.

The <PDF> tag will still be filled with the signed document.

See Condition.DocumentNoBiodata

Doesn't need to be filled at upload time.

<Signed>

<OutPut>

<DueDate>

x

DateTime

2019-07-21

Deprecated: The DueDate for a signature request / envelope should be defined as a child of <ESign>!

This tag defines the expiration date of the signature request.

Example: <DueDate>2019-07-21</DueDate>

If <DueDate> is defined, <DueDays> <DueWeeks> and <DueMonths> will be ignored.

If neither <DueDate> <DueDays> <DueWeeks> and <DueMonths> are defined, the expiration time is one week.

<DueDays>,

<DueWeeks>,

<DueMonths>

x

Integer

Deprecated: The DueDate for a signature request / envelope should be defined as a child of <ESign>!

Tags are defining the expiration of the signature request.

With setting a value in one of the three tags, the due date will be the date x days / weeks or months after the time of upload.

The relevant value is always the next expected date. For example <DueDays> is set with the value 9 and <DueWeeks> is set with the value 1, the due date will be 7 days later (one week)

If <DueDate> is defined, <DueDays> <DueWeeks> and <DueMonths> will be ignored.

If neither <DueDate> <DueDays> <DueWeeks> and <DueMonths> are defined, the expiration time is one week.

<MandatorySkippable>

x

Integer

1/0

If set to 1 (true) mandatory fields can be skipped.

This optional tag defines, if mandatory signature fields are skippable (value 1) or not (value 0).

If no value is set or tag is not defined, mandatory signature fields are not skippable.

<Observer>

x

String

userName / email-adress

Sets an observer for a document. The observer can view the document, but has no signature-fields.

If email notification is active, the user will receive an email with the document-link.

Possible values are a valid email adress or the userName (login) of an active user.

(If the xml defines an envelope and Document.Observer is not defined, ESign.Observer will be used)

<CallbackUrl>

x

String (URL)

www.example.com/event

Defines a callbackURL for the document. If not present, the default callbackURL (server settings) will be used. See e) Callback-API

<DocumentPassword>

x

String

Passwords for envelopes are not supported.

Defines a document password.

If a user has to enter the password is defined in the <Signatures> Element. see <PasswordRequired>

It is possible to set different passwords for distinct documents in the envelope. When opening a document-viewer the specified password of the document must be entered. When opening the envelope-viewer the password of the first document in the envelope must be entered.

<ExecutionOrder>

x

Integer

deprecated ExecutionOrder – specifies field execution order. Possible values: 0 – ABC   ABC ABC, 1 – AAA BBB CCC, 2 – as sorted.

<Signatures> : Signature field definitions

With <Signatures> signature fields in documents are defined. All signatures are children of the <Signatures> element.

There are 3 ways to define the Signature Positions inside the document.

  • <Static> define static coordinates for the field

  • <Signature> searches the pdf for a given <PlaceHolder> and sets the field at that position

  • <DigSig> uses an empty signature field allready defined in the document.

<Static>, <Signature> and <DigSig> fields differ in their definition. Some elements can be set in all signature types:

common xml elements in <Static>, <Signature> and <DigSig>:

XML-Element

webso

Type / example

description

<PasswordRequired>

x

Integer

1/0

true or false, defines if the signer of the signature has to enter the password when opening the document.

If a password is assigned to the document by default <PasswordRequired> is set to true. It must be explicitly set to false to prohibit the password prompt.

The <DocumentPassword> is defined globally.

Note: The first appearence of <PasswordRequired> in the signature fields of a distinct user defines whether the user has to enter a password. eg:

A user has three signature fields.

  • In the first field <PasswordRequired> is not defined, in the second field it is "1", in the third field it is "0" → password is required

  • In the first field <PasswordRequired> is not defined, in the second field it is "0", in the third field it is "1" → password is NOT required

  • In the first field <PasswordRequired> is "1", in the second field it is not defined, in the third field it is "1" → password is required

  • <PasswordRequired> isn't defined in any field → password is required

(<Signed>)

When the method retrieveXML is called and the field is signed, the element is set to 1.

<Signed> can't be set at upload time.

<Mandatory>

x

Integer

1/0

Is an optional field indicating that signature field is mandatory.

 <Mandatory>1</Mandatory> means mandatory field

<Mandatory>0</Mandatory> means optional field

If no value is set, the field is optional.

<Textblock>

<Zoom>

<Stamp>

x

<Stamp>

Stamp can be:

  1. the image can be omitted, then only a text is added defined. Line breaks are defined with "\r\n".

  2. only an image can be defined

  3. if both image and text are defined, then the text is added to the stamp image and overlayed upon the signature

If <SignatureType> value of the signature element is 0, a stamp creation without signature will be set, otherwise it's a combination of stamp and signature.

A stamp can't be defined for digitalStamp (<SignatureType>1) because the stamp image including the email address or username of the signee is generated automatically.

<Signer>

<UserName>

x

String

Login name of a registered user or an email address. Defines which technical user has to sign the field.

If no <UserName> is defined, a self-sign field (for own/ xml-upload user) is set.

If the email adress doesn't belong to a registered user a guest user will be created.

<Reason>

x

String

Can be used to set the reason for the signature which will be visible in the pdf certificate.

<SignatureType>

x

Integer

0-4

The available values are:
*0 = stamp data (text/image) without signature
1 = digital stamp (signature with user certificate instead of hand-written signature)
2 = html-signer signature only
3 = pad signature only
4 = app / phone / tablet signature only (QR code, link, sms)
If no signature type is defined, a selection window appears. 

The signer can choose between following types: StepOver signature pad OR one of our apps OR HTML-signer (with a pen or your finger on your mobile device)

The behaviour of the document viewer after clicking "sign now" for the different <SignatureType>s are shown below:

please note: If a SigatureGroup is defined, the signatureType will be ignored.

<SignatureGroupName>

x

String

The name of the <SignatureGroup>

<HtmlSignerWidth>

x

Decimal

depricated

Defines the displayed / zoomed signature field width (in cm) for signatures with HTML signer (and with apps)

<SmsToken>

x

With this tag you can define if user have to enter a auto-generated SMS token before entering the document (two factor authentication).

The SmsToken element has to be part of the <Signature> / <DigSig> / <Static> element and requires following parameters:

<Number>: the mobile number excluding the phone code / country code

<PhoneCode>: the international phone code of the mobile number according to iso 3166-1 alpha 2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ).

('DE' for Germany, 'US' for United States, 'GB' for Great Britain, etc.)

You can only set one <SmsToken> element for each <Signature> / <DigSig> / <Static> element and only one <SmsToken> element for each signatory (defined via <UserName> for other user or self-sign fields).
Means if you have more than one signature elements for the same user within the XML, only the last set number and phone code will be defined for the signatory.

<Signature>
    <SignatureType>2</SignatureType>
    <Placeholder>Signature1</Placeholder>
    <Height>2</Height>
    <Width>3.5</Width>
    <SmsToken>
        <Number>173123456</Number>
        <PhoneCode>DE</PhoneCode>
    </SmsToken>
</Signature>

<SelectionPhoneTabletDetails>

x

<SelectionPhoneTabletDetails>

Defines what options are shown in the Phone/Tablet overlay:

The child elements <OptionQRCode>, <OptionLink> and <OptionSMS> have the values 0 or 1.

Note: If SignatureType is not 4 (handwritten), <SelectionPhoneTabletDetails> will be ignored.

<Signature> : Intelligent signature field definition

<Signature> fields use <PlaceHolders> to define the position of the signature fields in the pdf. A placeholder is a string/text in the pdf.

<Signature>:

XML-Element

webso

Type

description

<Placeholder>

x

String

The placeholder for the intelligent signature placement. The placeholder is a string inside the pdf document.

If several strings are found, a signature field will be placed for every occurence.

The top left corner of the placeholder is the top left corner of the signature field. The field can be displaced with Offset_X and Offset_Y.

<Width>

Decimal

Width of the field in cm.

<Height>

Decimal

Height of the field in cm.

<FilterSignature>

x

Filter the signature by the number they are found inside the document. 

Although the element is defined for all signature definitions, it's only applicable for <Signature>.

<FilterSignature>Begin:End;</FilterSignature>

<FilterSignature>Begin:End;Begin2:End2;</FilterSignature>

Note: If <FilterSignature> is defined, <FilterPage> will be ignored.

Sample:

<FilterSignature>1:1;</FilterSignature>     (only first appareance)

<FilterSignature>1:3;</FilterSignature>     (1, 2 and 3 appareance)

<FilterSignature>1:1;5:6;</FilterSignature>     (1, 5 and 6 appareance)

<FilterSignature>3:-1;</FilterSignature>     (3 until last appareance)

<FilterSignature>-2:-1;</FilterSignature>     (second to last and last appareance)

<Signature>
    <SignatureType>2</SignatureType>
    <Placeholder>Signature1</Placeholder>
    <Height>2</Height>
    <Width>3.5</Width>
    <FilterSignature>-3:-1;</FilterSignature>
</Signature>

Signature fields are only created for the last three placeholder matches.

<FilterPage>

x

String

Filter the signature by the pages, which means you can define on which pages the signature should be offered to the signer.

Although the element is defined for all signature definitions, it's only applicable for <Signature>.

Sample:

<FilterPage>1:1;</FilterPage>     (only first page appareance)

<FilterPage>1:3;</FilterPage>     (1, 2 and 3 page appareance)

<FilterPage>1:1;5:6;</FilterPage>     (1, 5 and 6 page appareance)

<FilterPage>3:-1;</FilterPage>     (3 until last page appareance)

<FilterPage>-2:-1;</FilterPage>     (second to last page and last page appareance)

Note: If <FilterSignature> is defined, <FilterPage> will be ignored.

<Signature>
    <SignatureType>2</SignatureType>
    <Placeholder>Signature1</Placeholder>
    <Height>2</Height>
    <Width>3.5</Width>
    <FilterPage>2:3;</FilterPage>
</Signature>

Signature fields are only created on page two and three.

<DisplacementTLIndex>

<FeldPositionIndex>

<Page>

<X>

<Y>

<Offset_X>

x

Decimal

Horizontal displacement of the signature field in cm.

If offset is positive, the field will be moved right.

<Offset_Y>

x

Decimal

Vertical displacement of the signature field in cm.

If offset is positive, the field will be moved down.

<RectPosX>

<RectPosY>

<BeforeSignConfirmation>

<Location>

<Background>

<FrameColor>

<FrameThickness>

<Static> : static signature field definition

Static signature fields are defined by coordinates (in cm) on the given pdf page.

<Static>:

XML-Element

webso

Type

description

<Page>

x

Integer

The page of the signature field.

<X>

x

Decimal

The horizontal coordinate of the top left corner of the signature field.

<Y>

x

Decimal

The vertical coordinate of the top left corner of the signature field.

<Height>

x

Decimal

The height of the signature field.

<Width>

x

Decimal

The width of the signature field.

<RectPosX>

<RectPosY>

<DigSig> : Using pdf signature fields

<DigSig> fields use signature fields which are allready defined in the pdf. <FieldName> corresponds to the name of the signature field of the pdf.

<DigSig>:

XML-Element

webso

Type

description

<FieldName>

x

String

The name of the digital signature in the pdf document

<Stamp> : Add an image or text to a signature

Stamp can be:

  1. the image can be omitted, then only a text is added defined. Line breaks are defined with "\r\n".

  2. only an image can be defined

  3. if both image and text are defined, then the text is added to the stamp image and overlayed upon the signature

stamp Definition (without <Image>):

<Stamp>:

XML-Element

webso

Type

description

<Text>

x

String

The stamp text. If not set, only the image will be set.

the text lines can contain the time and date of signature, the format is defined using strftime semantics http://man7.org/linux/man-pages/man3/strftime.3.html (Because of time conversion it is not possible to use "%" as a single  character in the stamp text; e.g. "%h %% %F" won't be processed correctly).

New line can be entered with \r\n symbols.

<Color>

HEX

Color of the text.

The default color is "000000" (black). The value is a string containing rgb values in hex (two bytes per value, 0-255), i.e. red would be ff0000, green 00ff00, blue 0000ff

<Font>

<Size>

<TextWidth>

x

Integer

Text rectangle width in cm.

<TextHeight>

x

Integer

Text rectangle height in cm.

<Text_X>

x

Integer

Horizontal position of the upper left corner of the text rectangle in cm.

<Text_Y>

x

Integer

Vertical position of the upper left corner of the text rectangle in cm.

<Image>

x

base64

The base64 stamp image. If not present only the text will be set.

<Position>

x

Integer

position defines the position of the stamp in the signature:

1 | 2 | 3
4 | 5 | 6
7 | 8 | 9

center would be 5, 4 left, 9 lower right corner etc.

<Offset_X>

Integer

Horizontal offset of the image / text rectangle from the defined <Position> in cm.

The stamp should never be cut off, the image should be scaled if necessary to prevent this (keeping ratio).

The offset can be negative.

<Offset_Y>

Integer

Vertical offset of the image / text rectangle from the defined <Position> in cm.

The stamp should never be cut off, the image should be scaled if necessary to prevent this (keeping ratio).

The offset can be negative.

<SelectionPhoneTabletDetails> : Define which options are shown to share a link when signing with smartphone/tablet.

<SelectionPhoneTabletDetails> can either be defined for a single Signature or for SignatureGroups.

Defining in Signatures

  • The SignatureType must be 4

Defining in SignatureGroup

  • SignatureGroup.ShowSignatureTypePopUp must be 1

  • SignatureGroup.ShowSignatureTypePopUpDetails.SelectionPhoneTablet must be 1

If OptionSMS is true, a phone number can be defined. A SMS will be send with a link to the document.

<SelectionPhoneTabletDetails>:

XML-Element

webso

Type

description

<OptionQRCode>

x

Integer

1/0

If 1 QRCode option is shown

<OptionLink>

x

Integer

1/0

If 1 link option is shown

<OptionSMS>

x

Integer

1/0

If 1 sms option is shown.

<Number>

x

Integer

Can be set if <OptionSMS> is 1.

If <OptionSMS> is 0, it will be ignored.

Defines the phone number for the sms link without the country code.

<PhoneCode>

x

String

Can be set if <OptionSMS> is 1.

If <OptionSMS> is 0, it will be ignored.

Defines the country code according to ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 )

example

explanation

<Signature>
    <Placeholder>Unterschrift 123</Placeholder>
    <Height>2.0</Height>
    <Width>4.0</Width>
    <SignatureType>4</SignatureType>
    <SelectionPhoneTabletDetails>
        <OptionQRCode>1</OptionQRCode>
        <OptionSMS>1</OptionSMS>
        <OptionLink>0</OptionLink>
        <Number>173123456</Number>
        <PhoneCode>DE</PhoneCode>
    </SelectionPhoneTabletDetails>
</Signature>

A <Signature> is defined with the width 4cm and height 2cm without <SignatureGroup>.

The SignatureType is 4 = Phone/Tablet.

When clicking on "sign now" the Popup appears with the QR-code to scan and the tab to send a SMS containing a link to the document to the given number.

<FillInfo> : Filling PDF-formfields

<FillInfo> contains a List of <FillEntry>. 

If the xml defines a single document, <FillInfo> is defined at ESign.FillInfo.

If the xml defines a <SignatureRequestEnvelope> <FillInfo> is defined for each document of the envelope at ESign.SignatureRequestEnvelope.Documents.Document.FillInfo

<FillEntry>:

XML-Element

webso

Type

description

<Name>

x

String

The name (identifier in the pdf) of the pdf formfield.

<Value>

x

String

The value to be set for the formfield.

example

explanation

  <FillInfo>
    <FillEntry>
      <Name>Text1</Name>
      <Value>foo</Value>
    </FillEntry>
    <FillEntry>
      <Name>Text2</Name>
      <Value></Value>
    </FillEntry>
    <FillEntry>
      <Name>RadioButton5</Name>
      <Value>Yes</Value>
    </FillEntry>
    <FillEntry>
      <Name>CheckBox4</Name>
      <Value>Yes</Value>
    </FillEntry>
    <FillEntry>
      <Name>CheckBox3</Name>
      <Value>No</Value>
    </FillEntry>
    <FillEntry>
      <Name>Optionsfeld1</Name>
      <Value>Ja</Value>
    </FillEntry>
    <FillEntry>
      <Name>Kombinationsfeld3</Name>
      <Value>Option3</Value>
    </FillEntry>
  </FillInfo>

  1. sets the value of text field with identifier "Text1" to "foo"

  2. clears the value of text field with identifier "Text2"

  3.  sets the value of the radiobutton-group with identifier "RadioButton5" to "Yes"

  4. checks the checkbox with the identifier "Checkbox4"

  5. unchecks the checkbox with the identifier "Checkbox3"

  6. sets the value of radiobutton-group with identifier "Optionsfeld1" to "Ja"

  7. sets the value of dropdown list with identifier "Kombinationsfeld3" to "Option3".

The identifiers and values can be defined in Adobe Acrobate or other PDF creation software.

The values can be changed in the viewer.

Note:

  • Observers can't change formfield values.

  • With the server setting formfields_writable_for_others=false you can prohibit editing formfields in the viewer by other users.

<SignatureGroups> : Grouping signature fields

<SignatureGroups> contains a list of <SignatureGroup>

It can either be defined under ESign.SignatureGroups or ESign.SignatureRequestEnvelope.SignatureGroups.

All fields of a SignatureGroup belong to the same user.

<SignatureGroups> overwrite the order of the signatures: All fields in the first groups are signed first, then the fields of the second group etc.

Note: If SignatureGroups are used, the document must contain only one technical user!

<SignatureGroup>:

XML-Element

webso

Type

description

<SignatureGroupName>

x

String

Defines the name of the signatureGroup. (mandatory)

<ShowSignatureTypePopUp>

x

Integer

1/0

defines if the signatureTypePopup is shown.

If 1 (true), the signatureTypePopup will be shown.

Note: If <ShowSignatureTypePopUp> is true, <ShowSignatureTypePopUpDetails> must be defined! (see below)

<ShowSignatureTypePopUpDetails>

x

<ShowSignatureTypePopUpDetails>

With the tag <ShowSignatureTypePopUpDetails> and it's child tags

<SelectionPad>, <SelectionPhoneTablet>, <SelectionDisplay> (all int's with 1 or 0 values) 

the SignatureTypePopUp can be defined showing all or just some of the signature type selections.

Note:

  • If <ShowSignatureTypePopUpDetails> is not set, no SignatureTypePopUp will be shown.

  • If <ShowSignatureTypePopUp> is not set or 0, <ShowSignatureTypePopUp> will be ignored.

  • tbd: If <SignatureGroup> with <ShowSignatureTypePopUpDetails> is defined, the <SignatureType> in <Signatures> value will be ignored!

<SignatureFieldColor>

<ShowSignatureTypePopUpDetails> : Define which signing options are presented in SignatureGroups

The Element <ShowSignatureTypePopUpDetails> defines which signing options are presented for each individual <SignatureGroup> when clicking on "sign now".

It is mandatory, if SignatureGroup.ShowSignatureTypePopUp is 1 (true).

SignatureTypePopUp:

<ShowSignatureTypePopUpDetails>:

XML-Element

webso

Type

description

<SelectionPad>

x

Integer

 1/0

If 1 the option "SIGNATURE PAD" is shown

<SelectionDisplay>

x

Integer

 1/0

If 1 the option "ON THIS DISPLAY" is shown.

<SelectionPhoneTablet>

x

Integer

 1/0

If 1 the option "SMARTPHONE/TABLET" is shown.

If <SelectionPhoneTablet> is 1, it is possible to further define which methods are shown to share the link after clicking "Smartphone/Tablet" with <SelectionPhoneTabletDetails> (see below)

<SelectionPhoneTabletDetails>

x

<SelectionPhoneTabletDetails>

If <SelectionPhoneTablet> is 1, you can further define the methods to send the viewer link with <SelectionPhoneTabletDetails>.

Possible options are Link, QR-Code and SMS (with phone number definition).

<SelectionPhoneTabletDetails> is described in Section Signatures.

  • No labels