XML Elements overview
- 1 <ESign> : Root-Element
- 2 <SignatureOrder> : Defining an order for the signatories
- 3 <SignatureRequestEnvelope> : Several Documents and download conditions
- 4 <Signatures> : Signature field definitions
- 4.1 <Signature> : Intelligent signature field definition
- 4.2 <Static> : static signature field definition
- 4.3 <DigSig> : Using pdf signature fields
- 4.4 <Stamp> : Add an image or text to a signature
- 4.5 <SelectionPhoneTabletDetails> : Define which options are shown to share a link when signing with smartphone/tablet.
- 5 <Qes>: Qualified electronic signatures
- 6 <SmsTokens>: MFA sms envelope protection
- 7 <FillInfo> : Filling PDF-formfields
- 8 <SignatureGroups> : Grouping signature fields
- 9 <PasswordRequired>: Define password protection
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 | 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 | 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:
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) | 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. See <PasswordRequired> for details |
<SignatureGroups> | x | 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 | 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> Document will be visible in app from 22/7/2022 till 25/7/2022 |
<CryptoIDSelection> |
|
|
|
<SignatureOrder> | x | Defines in which order the users of the document/envelope have to sign. Contains a list of <SignaturePosition>. | |
<PasswordRequired> |
| List of users that have to enter the document password. |
<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.
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. The <Position> element begin with position 1 (and 2, 3…).
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 | 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 | Contains the documents of the envelopes. Most children elements of ESign are defined inside the <Document> element. | |
<Conditions> | x | 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 | 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 | 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 |
<CallbackUrl> | x | String (URL) | Defines a callbackURL for the document. If not present, the default callbackURL (server settings) will be used. See e) Callback-API |
<DocumentPassword> | x | String | Deprecated. 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> |