Using variables
- Andy Erd
Description
You can use 3 different kinds of variables in eSignatureOffice:
- External variables, which must be set as startparameter or in the Input-XML
- Document variables are values which will be read from the current PDF document
- Stamp variables, which are predefined values
These variables allow you to create a more flexible workflow. It's possible, for example, to decide if your text in the optional signature stamp or on the signature pad display should contain data from the document itself or not.
1. External-Variables
Input
The External variables can be set as startparameters by using -varN=<Value> The N stands for a number, so you can use more than only 1 variable.
Parameter-Sample:
C:\Program Files (x86)\StepOver\...\SOSigOffice.exe "C:\Test\Mustermann.pdf" -VAR1=Max -VAR2=Mustermann -VAR3=Max@Mustermann.de
In case you are using the a XML file as input, you can define the variables in it by using the <varN> tag. The N stands for a number, so you can use more than only 1 variable
XML-Sample:
<var>
<var1>Max</var1>
<var2>Mustermann</var2>
<var3>Max@Mustermann.de</var3>
</var>
Usage
To use a given variable in eSignatureOffice, you have to surround the VARN with squared brackets [ ]. The N is the number of the variable.
For example:
C:\Temp\[VAR1]\Files\[VAR2].pdf
When using the variables defined as start parameter or xml-tag like in the samples above, the filename is changed to:
C:\Temp\Max\Files\Mustermann.pdf
because VAR1 was defined as "Max" and VAR2 was defined as "Mustermann".
2. Document-Variables
The document variables can be set by clicking on the magnifying glass next to some text fields. Like the external variables, the document variables are surrounded by squared brackets [ ].
Short Type (used until eSignatureOffice 4.10)
example: [F:"<search text>":<number of characters>:W]
| F: | Command to search for a PDF form field. If this part is not included, then a normal text search will be done. |
| :W | If this is included at the end of a variable call, then empty spaces at the beginning and the end of the search result will be removed and only the first word found will be returned as search result. |
| "<search text>" | Text to be searched. Always has to be specified. |
| :<number of characters> | Maximum number of characters, which are supposed to be part of the search result written behind the search text. Always has to be specified. Reduce this number to return only a smaller part of the search result. |
Extended Type
[F:"<search text>":<after>:"<stoptext>":<before>:"<default>":E"<exchange>":W:D:T:N]
| F: | Command to search for a PDF form field. If this part is not included, then a normal text search will be done. |
| :W | If this is included at the end of a variable call, then empty spaces at the beginning and the end of the search result will be removed and only the first word found will be returned as search result. |
| :D | If this is included at the end, an empty default string will be used. |
| :T | If this is included at the end, the given exchange text will be used, if the search text has been found. |
| :N | If this is included at the end, this search will not be done when the document is loaded, but only as soon as the search result is needed (e.g. when filling a text form field and then later using its content for renaming when saving the file) (introduced in eSO 4.12) |
| "<Search text>" | Text to be searched. Always has to be specified. |
| :<After> | Maximum number of characters, which are supposed to be part of the search result written after the search text. Always has to be specified. Reduce this number to return only a smaller part of the search result. At least one of <before> or <after> has to be larger than 1. |
| :"<Stop text>" | Text boundary from which or up to which the search result will restricted to. Optional parameter. Also allowed to be "" (empty) |
| :<Before> | Maximum number of characters, which are supposed to be part of the search result written before the search text. Optional parameter. Reduce this number to return only a smaller part of the search result. At least one of <before> or <after> has to be larger than 1. |
| :"<Default>" | If this is included and the search text is not found, the value given here will be used as default search result. Optional parameter. |
| :E"<Exchange>" | If this is included and the search text is found, the value given here will be used as exchange search result. Optional parameter. |
| :U"<Charlist>" | Only the defined Chars are used from the search result Charlist = <Start>,<End>[;<Another Start>,<Another End>]; Start and End are always present. if Start/End is negative the positon is calculated from the end of the search result Sample :U"40,42;45,50;-10,-1;" |
| :X"<Regex>" | use a regular expression to get the final result from the search result. <RegEx> is Base64 Encoded (there are spezial chars used which are also used in the definition here (colon, square brackets etc) |
Example:
The text "This is an example for the text search" will be searched with the following definition:
["example":13:"text":4:W]
The text search for "example", 6 characters before and 13 characters after that, returns "is an for the text" as search result.
The given stoptext "text" is found after the search text and so the search result is cut off to "is an for the"
However, as the next word after the search text is "for" and the ":W" parameter was used, only this one word is used as final search result.
ZUGFeRD Type
ZUGFeRD is a standardized form of digital invoicing practice https://de.wikipedia.org/wiki/ZUGFeRD (German).
For this a XML file is embedded in a PDF/A3 document. The content of this XML file can be used in eSignatureOffice.
CID = CrossIndustryDocument (root object in XML).
[CID:"<Search text>":"<Default>":E"<Exchange>"].
| "<Search text>" | Text to be searched. Always has to be specified. |
| :"<Default>" | If this is included and the search text is not found, the value given here will be used as default search result. Optional parameter. (Introduced in eSO V5.6) |
| :E"<Exchange>" | If this is included and the search text is found, the value given here will be used as exchange search result. Optional parameter. (Introduced in eSO V5.6) |
| :U"<Charlist>" | Only the defined Chars are used from the search result Charlist = <Start>,<End>[;<Another Start>,<Another End>]; Start and End are always present. if Start/End is negative the positon is calculated from the end of the search result Sample :U"40,42;45,50;-10,-1;" |
| :X"<Regex>" | use a regular expression to get the final result from the search result. <RegEx> is Base64 Encoded (there are spezial chars used which are also used in the definition here (colon, square brackets etc) |
The following search texts are only supposed to be reference points. The different branches and leaves of the tree structure are separated by slashes "/".
Either the complete path can be used or only a part of the path. This is shown with the GrandTotalAmount example following. The text parts "ram:","rsm:","udt:" written before the actual informations do not have to be provided.
| Search text | Description |
|---|---|
| /SpecifiedSupplyChainTradeTransaction/ApplicableSupplyChainTradeSettlement/SpecifiedTradeSettlementMonetarySummation/GrandTotalAmount | Complete path for the total amount. The associated attribute "CurrencyID" is added, so a complete total amount is shown, e.g. "64.33 EUR" |
| GrandTotalAmount | Grand total amount. |
| HeaderExchangedDocument/ID | Invoice number |
| BuyerTradeParty/ID | Customer number |
PostalTradeAddress | Customer address, everything below that structure point is used: (PostCode, LineOne, CityName) |
PostalTradeAddress/LineOne PostalTradeAddress/PostcodeCode PostalTradeAddress/CityName | Separate parts of the customer's postal address. |
| BuyerReference | Order number |
| SpecifiedTradePaymentTerms/Description | Payment terms |
There can be much more information embedded in the XML file. Here an example:
Progress indicator
This menu has 3 columns: the search text, the search result and its current status. Only when all search texts have a result, the confirmation button will be usable.
| Status | Beschreibung |
|---|---|
 | The search text was not found in the document and no default text was specified, so the user has to define the search result himself. |
 | The search text was not found in the document or the result is empty, so the default text has been used. |
 | The search text has been found in the document, the result is shown. |
 | Search in progress, nothing found, yet. |
 | The search text has been found in the document, however the search result is empty and no default text was specified, so the user has to define the search result himself. |
 | A fatal error occured during the text search, so the user has to define the search result himself. |
3. Variables for Stamp and File handling
The following variables can be used in the stamp settings, either globally or in a signature set.
| Text | Description |
|---|---|
| [Signer] | The signer of the current signature, either entered in the optional dialog after the signature or specified beforehand (e.g. in the signature set). At this position the text is inserted. |
| [-Signer] | The input field in the dialog is not shown, altough the Signer is shown in stamp. |
| [!Signer] | The static Label before the Signer is ommited |
| [Reason] | The signer's reason for signing the document, either entered in the optional dialog after the signature or specified beforehand (e.g. in the signature set). At this position the text is inserted. |
| [-Reason] | The input field in the dialog is not shown. altough the Reason is shown in stamp. |
| [!Reason] | The static Label before the Reason is ommited |
| [Location] | The current location when signing, either entered in the optional dialog after the signature or specified beforehand (e.g. in the signature set). At this position the text is inserted. |
| [-Location] | The input field in the dialog is not shown. altough the Location is shown in stamp. |
| [!Location] | The static Label before the Location is ommited |
| [Time] | The current date and time in the format 'c' : <Day>.<Month>.<Year> <Hour>:<Minute> |
| [Copyright] | The StepOver copyright text. |
| [Date:<Format>] | The current date and/or time, following the double-point is the date/time format string, editable as described below. |
[User] | The current Windows login username. |
[SignCount] | Total number of signatures in this document. |
| [SignValid] | Number of valid signatures done in this document. |
| [SignNotValid | Number of invalid/erroneous signatures in this document. |
| [FilePath] | Filename and path of the source document (e.g. "C:\Documents\invoice.pdf" ) |
| [FileExt] | Only the filename of the source document (e.g. "invoice.pdf" ) without its path, but with file extension. |
| [File] | Only the filename without path and file extention (e.g. "invoice" ) |
| [FileDir] | Path without filename, including trailing backslash "\" |
| [FileDrive] | Drivename including trailing backslash "\" |
| [FileExtention] | Only the extension of the filename (do not mix up with [FileExt] = filename with extention) |
Sample for the File variables:
Date/Time Format String
Please be aware, that all texts like the names of weekdays or months are depending on the operating system settings. So, if your OS is running in English, you will get English names. eSignatureOffice cannot influence this.
| Text (not case sensitive) | Description |
|---|---|
| '' (empty string) | Displays like 'c' |
| c | Date using the format given by DD.MM.YY (Standard in Germany), followed by the time using the format HH:MM. The time is not displayed, if the date-time value indicates midnight precisely. |
| d | Day as number without leading zero (1.-31.) |
| dd | Day as number with a leading zero (01.-31.) |
| ddd | Weekday abbreviated (Sun, Mon ... Sat) |
| dddd | Weekday as a full name (Sunday, Monday ... Saturday) |
| ddddd | Date in DD.MM.YY |
| dddddd | Date in lonic format |
| e | Displays the year in the current period/era as a number without a leading zero (Japanese, Korean and Taiwanese locales only). |
| ee | Displays the year in the current period/era as a number with a leading zero (Japanese, Korean and Taiwanese locales only). |
| g | Displays the period/era as an abbreviation (Japanese and Taiwanese locales only) |
| gg | Displays the period/era as a full name. (Japanese and Taiwanese locales only). |
| m | Month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed. |
| mm | Month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed. |
| mmm | Displays the month as an abbreviation (Jan - Dec) |
| mmmm | Month as full name (January - Decembre) |
| yy | Year as a two-digit number (00-99). |
| yyyy | Year as a four-digit number (0000-9999). |
| h | Hour without a leading zero (0-23). |
| hh | Hour with a leading zero (00-23). |
| n | Minute without a leading zero (0-59). |
| nn | Minute with a leading zero (00-59). |
| s | Second without a leading zero (0-59). |
| ss | Second with a leading zero (00-59) |
| z | Millisecond without a leading zero (0-999). |
| zzz | Millisecond with a leading zero (000-999). |
| t | Time using the format hh:mm |
| tt | Time using the long format |
am/pm Am/Pm AM/PM | Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case and the result is displayed accordingly. |
| a/p | Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly. |
| ampm | Uses the 12-hour clock for the preceding h or hh specifier, and displays the contents of the TimeAMString global variable for any hour before noon, and the contents of the TimePMString global variable for any hour after noon. |
| / | Date separator character |
| : | Time separator character |
'hh:mm' "dd.mm.yyy" | Characters enclosed in single or double quotes are displayed as-is, and do not affect formatting. |
Example:
[Date:hh:nn:ss] --> 08:58:50 [Date:dd/mm/yyyy] --> 16.11.2015 [Date:dd.mm.yy hh:mm:ss] --> 16.11.15 08:58:50 [Date:dddd dd of mmmm yyyy] --> Monday 16 of November 2015
PLEASE NOTE that Windows is not allowing specific characters like : or / for a filename, you have to replace them with a different character.