Input-XML - 4.Additional Tags

Owned by Andy Erd
Last updated: Mar 30, 2022
8 min read

Additional tags

NameDescription

<CorpCode>

Allows to pass license code inside XML file.

The code must be either a Base64-encoded content of corpcode.lic file or a path to such a file.

<GUIMode> 

Switches between different UI modes.

Currently there are modes 0, 1, 2 and 3 available. This tag may be omitted, then eSignatureOffice will work in old ‘traditional’ UI mode.

<DeviceKind> or <PADART>

Restricts valid signature devices to naturaSignPad-Series only.

<AutoStartSig>

If this tag is included, eSignatureOffice starts signing automatically after document is opened.

AutoStartSig can be combined with the signature Groups

<AutoStartSig> GroupName </AutoStartSig> to start a specific Group of signatures.

<AutoStartPDF>

eSignatureOffice enters PDF Form Fill mode automatically after document is opened.

Some Buttons like Viewmode and Administration will be disabled.

<AutoStartFormFill>

eSignatureOffice enters PDF Form Fill mode automatically after document is opened, without disabling functionallity like <AutoStartPDF>.

<AllowSkipAndAbortLastSig>

Allows at the last Signature skipping and aborting the signature process.

<AfterSigning>

<AfterSigning DisableManualSign="true">

<AfterSigning DisableManualSign="false">

Allows you to define a macro action which should be triggered when signing was successful.

Values: MacroX or Nothing

DisableManualSign, is optional an allows to start a manual signature after all defined signatures are completed

Samples: <AfterSigning>Macro4</AfterSigning>

<AfterSigning DisableManualSign="true">Macro1</AfterSigning>

<AfterCancel>

<AfterCancel DisableManualSign="true">

<AfterCancel DisableManualSign="false">

Allows you to define a macro action which should be triggered when signing was cancel by the user.

Values: MacroX or Nothing

DisableManualSign, is optional an allows to start a manual signature after all defined signatures are completed

Samples: <AfterCancel>Nothing</AfterCancel>

<AfterCancel DisableManualSign="true">Macro1</AfterCancel>

*<DueDays> , <DueWeeks> , <DueMonths>

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)

*<DueDate>

This tag defines the expiration date of the signature request.

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

<SCSPath> or <SCS> 

Gives possibility to update eSignatureOffice settings using SCS path or Base64-encoded file.

If this tag is included, settings from the file are applied before opening the PDF document.


It´s possible to provide a multiple SCS Version inside the XML, in that case the Versionnumber needs to be added to the tag like <SCS Version="122">.

  • In case the Version number is higher than the actual installation the SCS will be ignored

  • If they more than 1 possible SCS inside the XML, the highest Version will be used

  • In case the eSignatureOffice Version is older than August 2017 (eSignatureOffice 5.4), the Version specific SCS Version will be ignored (no support of Version specific SCS handover inside XML).

Sample:

<SCSPath>....</SCSPath>
<SCSPath Version="139">....</SCSPath>
<SCSPath Version="118">....</SCSPath>

In case eSignatureOffice supports Versions >= 139 is would take the 139 SCS Version, in case its supports Versions <139 and >= 118 the Version 118 would be used. Otherwise the eSignatureOffice would use the SCS without Version in that Sample.


*<SmsToken>

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 (ISO2 code: '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.

Example:

<Signature>
	<SignatureType>2</SignatureType>
	<Placeholder>signature</Placeholder>
	<Height>1.5</Height>
	<Width>5</Width>
	<UserName>Testuser</UserName>
	<SmsToken>
		<Number>15122334455</Number>
		<PhoneCode>DE</PhoneCode>
	</SmsToken>
</Signature>
*<Stamp>

The stamp element has to be part of the <Signature> / <DigSig> / <Static> element.
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.

Stamp can be:
1. the image can be omitted, then only a text is added defined by line1, line2, ... linex
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

a. 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
b. the coordinates x,y,width and height define a rectangle containing the text. The text should be scaled to fill the rectangle (width). x,y represent the upper left coordinates of the text in the stamp image if one is supplied.
c. 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

d. an offset can be defined by offset-x and offset-y that is added to the stamp position (can be negative). The stamp should never be cut off, the image should be scaled if necessary to prevent this (keeping ratio).
e. a color needs to be defined for the text. 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
f. the font used should be a non serif font similar to Windows Arial.

Sample:

<Signature>
	<SignatureType>0</SignatureType> <!-- stamp only, no signature --> 
	<Placeholder>Test</Placeholder>
	<Width>6</Width>
	<Height>2</Height>
	<Stamp>
   		<Text>%d.%m.%Y %H:%M:%S</Text>
		<Color>000cff</Color>
	   	<Image></Image>
	   	<TextWidth>3</TextWidth>
	   	<TextHeight>1</TextHeight>
   		<Text_X>0</Text_X>
	   	<Text_Y>0</Text_Y>
   		<Position>7</Position>
	   	<Offset_X>0</Offset_X>
   		<Offset_Y>0</Offset_Y>
	</Stamp>
</Signature>
*<TapToSign>"true" or "false" (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).
<NoSealedMessage> 

Normally a message box with text "document sealed" appears after eSignatureOffice digitally seals the document.

If this tag is included, the message will not be shown.

  
<ReadBeforeSign> If this tag is included, signing mode is disabled after start.

User has to scroll to the bottom of the document, before signing mode becomes available.

There are 3 ways of specifying "ReadBeforeSign" option:


First way:

<ReadBeforeSign/> - If single empty tag is provided, sign button is disabled (grayed out) until the document is completely read.

Second way:

<ReadBeforeSign> 
   <Message/> 
</ReadBeforeSign>

when the empty <Message/> tag is included, default message ("please read the document completely before it can be signed") is displayed after Sign button is clicked.

Third way:

<ReadBeforeSign> 
   <Message>Please read the document.</Message> 
</ReadBeforeSign>

 with this configuration a custom message is displayed.

<Overlapped/> 

Is an optional tag, that turns on overlapped mode of operation.

In this mode function sigFileXml is terminated immediately after call, while eSignatureOffice keeps running in background. Calling application must meet special requirements, please refer to SecureSign documentation.

<PDF>Contains either Base64-encoded PDF file content or path to document file. The tag is necessary.
  

<PDF-Merge> Tag contains a set of <PDF> tags, each starting with "PDF", which will be merged together, either Base64-encoded PDF file content or path to document file.

The tag is deleted on file-save time, the new merged PDF is either inserted at a existing <PDF> tag outside of the <PDF-Merge> tag or a new <PDF> tag is inserted.

Example
<PDF-Merge>
  <PDF-1>...</PDF-1>
  .....
  <PDF-n>...</PDF-n>
</PDF-Merge>
<DisableHelpButton/>, <DisableInfoButton/>Each tag disables and removes the appropriate button from the top panel.
<BlindPadSearch/>

Suppresses device configuration Dialog, if pad was changed.

Normally when signature is started, eSignatureOffice checks, if previously configured device is still connected and if not - device configuration dialog is shown.

When <BlindPadSearch/> is included in XML, eSignatureOffice tries to find signature devices without showing configuration dialog.

<ShowDialogPrintButton/>Adds "print with dialog" button to the toolbar, even if minimal control set is configured using <GUIMode>1</GUIMode>.
<ShowFormFillButton>Adds "form fill mode" button to the toolbar, even if minimal control set is configured using <GUIMode>1</GUIMode>.
<HideSignControlButtons/>Hides control panel with 'OK', 'Repeat', 'Skip' and 'Back' buttons in signing mode. This tag has no effect in 'traditional' UI mode.
<HideLcdSignButton/>Hides green 'sign now' button in the bottom of LCD. By default 'sign now' is shown, when signature set is provided.
<HideSupportButton/>When signature set file is passed as command-line parameter the "Support" - Button in the Dialog-Form is not displayed, if this parameter is set to 1. Overwrites registry and start Parameter.
<DisableXinFormMode/>Disables the usage of the X for closing eSignatureOffice in form mode.
<DisableBackButton/>

Disables the usage of the Back Button when in sign mode.

<DisableHashAbort/>Disables the Abort Button while displaying the Hash.
<DisableAutoJumpToPrevField/>Disables Automatic jump.
<EnableLastFieldSkipping/>Enables the skipping of the last field.
<AddSearchHistory>1</AddSearchHistor>

Additional search history is written to Output XML and/or RET file. Default is off.

Possible Values: 0=no search history, 1=write search history,

if omitted then no search history,

<AddSearchHistory/> is the same as omitting or value 0.

<ShowCancelOptionalSignature>1

</ShowCancelOptionalSignature> 

When an optional field is used, an additional "Cancel" Button is switchable. Default is off.

Possible Values: 0=no cancel button, 1=cancel button,

if omitted then cancel button off, <ShowCancelOptionalSignature/> is the same as omitting or value 0.

The <ShowCancelOptionalSignature> needs to be placed in the level where <signatures> are used

 

<Signatures>
   <ShowCancelOptionalSignature>1</ShowCancelOptionalSignature>
   <Signature>
    <Placeholder>Unterschrift Depotinhaber 1</Placeholder>
    ...
   </Signature>
   <Signature>
    ...
   </Signature>
   ...
</Signatures>
<DocumentLabelInToolBar/> Enables the document Label in Toolbar.
<Macro1Upload>...</Macro1Upload>

Overrides upload location for macro button 1.

Similar tags can be included for macro buttons 2..10 (<Macro2Upload>..<Macro10Upload>).

<Zoom>

Is an optional tag, that defines the default zoom value after a document is opened.

Text inside the tag can be either an integer value in range 10..300 (denotes percent),

or Fit, that means fit to screen

or Width, that means fit to page width.

<ZoomAfterSign>

Is an optional tag, that defines zoom value after signing (even when canceling) the document in eSignatureOffice/webSign/secureSign.

Text inside the tag can be either an integer value in range 10..300 (denotes percent),

or Fit, that means fit to Screen

or Width, that means fit to page width

or Keep when not to change.

Default zoom value is Fit.

<ZoomLCD> 

Is an optional tag, that defines zoom value on the colour Device, when document view is enabled at startup.

The text inside the tag is an integer value in range 0..2,

0 = Fit to Width

1 = Fit to LCD (complete Page)

2 = maximal possible Zoom on Device


The Short form of the tag <ZoomLCD/> defaults to the value 0 = Fit to Width.

<ScrollInSignMode> This tag allows scrolling of a document in sign mode. By default scrolling is disabled.

There are several ways of usage:


<ScrollInSignMode/> - Allows scrolling and disables auto-return.

<ScrollInSignMode>
 <Autoreturn/>
</ScrollInSignMode>


Empty <Autoreturn/> Tag turns on auto-return feature. When document has been scrolled and then left untouched, after a short delay, it's being scrolled back to the signature field automatically.

<ScrollInSignMode>
 <Autoreturn>
 <Delay>2000</Delay>
 <Speed>Instant</Speed>
 </Autoreturn>
</ScrollInSignMode>

Optional tag <Delay> Defines idle time in milliseconds, after which the document is being scrolled back. The default value is 5000, i.e. 5 seconds.

Optional <Speed>Instant</Speed> Tag disables animation, when auto-scrolling back to signature field. Instead of Scrolling, document jumps back instantly.

<DeviceKeys>

Disables all signature devices, except devices with encryption key hash equal to one of the values listed inside this tag.

There may be one or more <Hash>...</Hash> tags inside <DeviceKeys>.

Each <Hash> must contain a hash value of device encryption key.

<ErrorMessage> Text is shown to the user, when he tries to use a device with a different encryption key.

<HashDialog> 

Overrides default text in signed hash confirmation dialog.

<Width> and <Height> specifies the size of the dialog window,

<Message> is the text shown to user. There must be %s placeholder for the real hash value in the message text.

<PdfNoBiodata> 

When included in input XML, turns on creation of additional document with the same set of signatures, but without real biometrical data.

It's possible to specify either a path to the document,

like <PdfNoBiodata>C:\TEMP\no-bd.pdf</PdfNoBiodata>

or provide empty <PdfNoBiodata/> tag.

If empty tag is provided, document without biometrical data will be stored directly inside XML in base-64 encoded way.

<FrameColor>

Overrides default signature frame color. The value of the tag must have numerical (decimal or hexadecimal) format.

<FrameThickness>

Overrides default signature frame thickness.

<DocumentPassword>Sets the documentpassword. If a has to enter the password is specified in the <Signature>-tag. See Input-XML - 2.Signature fields Definition and Text on LCD <PasswordRequired>
  

<DeviceDetails/> Tag passed as input tag, is filled with device model name, serial number and firmware version on output.

Parameters of device used for last signature are stored.

See filling sample below.

<DeviceDetails>
  <Model>StepOver naturaSign Pad Mobile</Model>
  <FirmwareVersion>4.3 E.1.1293</FirmwareVersion>
  <SerialNumber>123457001</SerialNumber>
</DeviceDetails>

<var> Allows you to define a variable, which you can use for Macro functionality. You need to place each variable into a child tag <varN>.

<var>
    <var1>Max</var1>
    <var2>Mustermann</var2>
    <var3>Max@Mustermann.de</var3>
</var>

*) These features are only implemented in webSignatureOffice so far.