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

Deprecated observer Definition. See <ObserverUser> below.

<ObserverUser>

x

<UserName>

Contains an array of UserNames:

<ObserverUser>
  <UserName>user1@example.com</UserName>
  <UserName>user2Login</UserName>
</ObserverUser>

Sets observers for envelopes.. The observers can view the envelope, but have no signature-fields.

If email notification is active, the observers will receive an email with the envelope-link.

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

<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.See <PasswordRequired> for details

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

<PasswordRequired>

<PasswordRequired>

List of users that have to enter the document password.

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

Deprecated <Observer> definition. See <ESign><ObserverUser> instead.

<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

StringPasswords

for envelopes are not supportedDeprecated. Use <PasswordRequired> instead.

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.

<PasswordRequired>

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:

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

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.

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

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.