<PasswordRequired>

x

Integer

1/0

Deprecated password definition. See <PasswordRequired> below

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 for a biometric signature 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)

Detailed Description: https://stepoverinfo.atlassian.net/wiki/spaces/WEBSO/pages/181960712/j+ESign+Input+XML#4.-Defining-the-%E2%80%9Csignature-type%E2%80%9D-%3CSignatureType%3E

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

<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.

(<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 for a biometric signature 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)

Detailed Description: https://stepoverinfo.atlassian.net/wiki/spaces/WEBSO/pages/181960712/j+ESign+Input+XML#4.-Defining-the-%E2%80%9Csignature-type%E2%80%9D-%3CSignatureType%3E

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

<SignatureGroupName>

x

String

The name of the <SignatureGroup>

<HtmlSignerWidth>

x

Decimal

Deprecated!

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

<SmsToken>

x

Deprecated: SmsTokens are defined in the <ESign>.<SmsTokens> element. See https://stepoverinfo.atlassian.net/wiki/spaces/PAF/pages/edit-v2/126484481#%3CSmsTokens%3E%3A-MFA-sms-envelope-protection

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.

<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>

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.

<QesUser>

x

List of <QesUser>

QES definition of a signer:

<ESign>
	...
	<Qes>
		<QesUser>
			<!-- QesUser see below > -->
			...
		</QesUser>
		<QesUser>
			<!-- QesUser see below > -->
			...
		</QesUser>
	</Qes>
	...
</ESign>

<QesProviderId>

x

Integer

The id of the qes service provider. Either <QesProviderId> or <QesProvider> must be provided.

<QesProvider>

x

String

The name of the qes service. Either <QesProviderId> or <QesProvider> must be provided.

example:

<QesProvider>signius</QesProvider>

<UserName>

x

String

The UserName. It is used to map the Qes data of the user to the signature fields.

<SmsTokens>

x

List of <SmsToken>

SmsToken definition of a signer:

<ESign>
    ...
	<SmsTokens>
		<SmsToken>
            <!-- SmsToken see below-->
             ...
		</SmsToken>
		<SmsToken>
            <!-- SmsToken see below-->
            ...
		</SmsToken>
	</SmsTokens>
    ...
</ESign>

<UserName>

x

String

The UserName. It is used to map the sms protection data of the user to the signature fields.

<Number>

x

Number

The phone number without country code.

e.g.: 173 123 123

<PhoneCode>

x

String

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 ).

e.g. “de” for Germany

<Name>

x

String

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

<Value>

x

String

The value to be set for the formfield.

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".

Image Added

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.

<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.

Image Added

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>

<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.

<PasswordRequired>

x

List of <UserName>

The <PasswordRequired> element contains a list of <UserName>. Every user in

<UserName>

x

string

Defines which users have to enter the password.

<DocumentPassword>

x

string

The password of the document or envelope.