View source for ViewSign Standard Integration Guide

=Client Integration Guide=
This guide describes integration scenarios for the Client. It is intended for the integrator (software developer/customizer) at your organization.

==Command Line==
You can start xyzmo Client via the command line.

'''To start xyzmo Client'''
* Run the following command:  
 '''SIGNificantOfflineClient.exe''' filename

The following parameters are supported:
{| class="wikitable" width=auto
!style="background-color:#c41230; color:#ffffff;"|Parameter 
!style="background-color:#c41230; color:#ffffff;"| Description
|-
| style="width: 15%"| '''-b64''' || Mark filename as base64 encoded. Must be before the filename. This is useful for filenames containing special characters.
Example: SignificantOfflineClient.exe -b64 "ASDLFKJASLDFKJ ALSK=="
|-
|'''filename''' || The full path and filename of the file that xyzmo Client should open.
Example: c:\Temp\document.pdf
|- 
|'''/DisableStringRemoving''' || Disables the removing of Sig-/Ord-/Attachment-/… Strings from the document when it’s loaded.
|-
|'''/disablesigstringparsing''' || Disables Sig String parsing.
|-
|'''/disableordstringparsing''' || Disables Ord String parsing.
|-
|'''/signatureTemplate''' || This parameter tells the client to take the Signature Template XML given with its full path to create and position signature fields. Refer to the appropriate chapter for more details.
|-
|'''/config''' || This parameter takes an alternative _global.xml from a given path.
:<small>'''Note:''' This will be supported in future version.</small>
|-
|'''/attachAsFile''' || This parameter takes a file and attaches it as file attachment. A full qualified path name is required.
Example: /attachAsFile c:\testfiles\test.pdf /attachAsFile "\\testres.trosoft.local\testfiles\test.xml"
=> this would attach the file c:\testfiles\test.pdf and c:\test2\test.doc
|-
|'''/attachAsPage''' || This parameter takes a file and attaches it as additional page. A full qualified path name is required.
Example: /attachAsPage "\\testres.trosoft.local\testfiles\test.pdf" /attachAsPage c:\test2\test.jpg
=> This would attach the file c:\testfiles\test.pdf and c:\test2\test.jpg as additional pages.
|-
|'''/sq''' || This parameter limits signing to a certain signature field given by the given sequence number (only for stepping and autostep)
Example (doc. contains fields with sq=1 to sq=10): /sq 1 /sq 2 /sq 5 => this limits signing to the signature fields with sq=1, 2 and 5.
Example (doc. contains fields with no sq numbers): /sq 1 /sq 2 /sq 5 => this effectively disables signing of existing signature fields.
Example (doc. contains fields with sq=1 to sq=10): /sq 1 /sq 2 /sq 15 => this limits signing to the signature fields with sq=1, 2; 15 is ignored
|-
|'''/username''' || This parameter limits signing to the signature fields of a specific user
Example: /username userA
/username LoggedOnUser - the logged on user; which is "userA" for example.
=> If a username is given, the user is only allowed to sign the signature fields for the given username.
|-
|'''/cbv1; /cbv2; /cbv3''' ||  Additional cmd parameters, will be passed to a custom action.
|}

==Signature Strings==
Signature Strings (short: “sig-strings”) are markers you can place in your document to position a signature field. Example: `sig` - this will place a signature field at exactly that position.

Available options for the sig-strings:

'''sig''': creates a signature field in the PDF. This field is mandatory. Example:
 `sig`

'''fd''': text description of the signature (= field description). The description cannot contains commas. This field is optional. If no field description is given, a default text will be used. Example:
 `sig, fd=Please sign this document immediately`

'''uid''': the signer's user ID. Example:
 `sig, uid=JohnS`

'''sq''': the signature's sequence number within the document.  Example:
 `sig, sq=1`

'''bio''': indicates whether biometric authentication is required for this signature. When using biometric authentication, a user id is required. The following values are accepted:
* 0 (default): no biometric authentication required
* 1: biometric authentication requiredExample:
 `sig, uid=JohnS, bio=1`

'''req''': indicates whether a signature field is mandatory. The following values are accepted:
* 0 (default): the signature field is not required
* 1: the signature field is required
'''ck1''', '''ck2''', '''ck3''': the label of the custom key field 1, 2, and 3
'''ckv1''', '''ckv2''', '''ckv3''': the value of the custom key field 1, 2, and 3.
Example:
 `sig, ck1=customID, ckv1= 123456`

'''sm''': sign method
* Tablet: sign and use the default signing certificate
* Tablet_AND_Certificate: sign on the signature tablet and let the user choose which signing certificate to use
* Stamp: seal and use the default signing certificate
* Stamp_AND_Certificate: seal and let the user choose which signing certificate to use
* Stamp_AND_Tablet: sign on the signature tablet, seal and use the default signing certificate
* Stamp_AND_Tablet_AND_Certificate: sign on the signature tablet, seal and let the user choose which signing certificate to use
* TabletPOSinline
Example:
 `sig,uid=JohnS, sm=Tablet_AND_Certificate`

'''signImg''': name of the signing background image which is displayed on the signature tablet (provided the tablet supports this functionality). Note that the image has to present separately for every tablet in the dedicated directory (i.e. in DeviceImages/Wacom_STU500, DeviceImages\Wacom_STU520, ...) 
Example:
 `sig,uid=JohnSm,signImg=signform1.bmp

'''ord''': use this parameter to let the application rename the openend Pdf file. Example:
 `ord, fn=contract.pdf`

'''att''': the attachment strings allow the customer to define the files which are added as attachment, either as a file or as an additional page.
* `att, fn=test.xml,type=asFile` => this attaches the file called test.xml as file attachment.
* `att, fn=test.pdf,type=asPage` => this attaches the file as additional page(s).
* `att, fn=c:\testfiles\test.jpg, type = asFile` => this takes the file from the given path; attention the file path and file name must not contain commas!

'''ly''': the name of the signature layout (defined in <install-dir>\config\SignatureLayouts.xml) which is used for signing. Example:
 `sig, ly=myLayout`

'''fna''': the name of the signature field. Example:
 `sig, fna=SignField123`

'''sfw''': the width of the signature field. Example:
 `sig, sfw=100`

'''sfh''': the height of the signature field. Example:
 `sig, sfh=100`

==Signature Templates==
Signature templates are XML files which can be used to predefine signature fields (or signature field properties) for a document. This is helpful if you encounter scenarios where you cannot add sig-strings to your original documents (e.g. because your customer does not allow it).

To use this functionality, follow the following steps:
# Create a signature template
# Call the xyzmo Client from the command line by providing the path to the document and the signature template

Create a signature template

Create an XML file according to the following example:
<syntaxhighlight lang="XML">
<signatureTemplate>
 <version>1.2.0.0</version> 
 <positionUnits>pdfUnits</positionUnits> 
 <positionReferenceCorner>Lower_Left</positionReferenceCorner>
 <!-- If you need to convert values using a different reference corner, follow these steps:
 * Find out the physical size of the page of your document. If you are using i.e. A4 paper size, the physical size of the paper is 297 x 210 mm (see  http://www.papersizes.org/a-paper-sizes.htm)
 * Convert the physical size to postscript points (for the A4 paper size, just google: "297 mm to postscript points" and "210 mm to postscript points")
 * The converted values without the decimal values (841 postscript points / 595 postscript points) is the value of the Upper Right position corner. Use these values to convert your coordinates according to the reference corner they are using. 
 -->
 <sig> 
  <param name="uid"></param>
  <param name="fd">Plase sign here to confirm to the Terms and Conditions:</param>
  <height>50</height>
  <width>40</width>
  <positionX>30</positionX>
  <positionY>150</positionY>
  <positionPage>1</positionPage>
 </sig>
 <sig> 
  <param name="uid">backoffice</param>
  <param name="fd">Please sign to confirm the customers insurance policy</param>
  <height>20</height> <width>40</width> 
  <positionX>30</positionX>
  <positionY>50</positionY>
  <positionPage>1</positionPage> 
 </sig> 
</signatureTemplate>
</syntaxhighlight>

Explanation:
* '''positionUnits''': The units in which the height, width and positions are provides.
:Possible values: “pdfUnits”.
* '''positionReferenceCorner''': the corner of the document from which the positionX and positionY values are calculated.
:Possible values: "Lower_Left"
* '''sig''': 1-n signature fields.
* '''param name=xxx''': defines a parameter/property of the signature field. Example: <param name=uid>backoffice</param> This will cause the client to use "backoffice" as the signatory’s UID/name. Any of the parameters used in sig-strings can be added to the signature layout using this syntax.
* '''width/height''': the width and height of the signature field. If ommited the default value will be used.
* '''positionX/positionY''': the x-y coordinate of the lower left corner of the signature field on the page.
* '''positionPage''': the page where the signature field is positioned.

Call the xyzmo Client from the command line by providing the path to the document and the signature template

Example:

 SIGNificantOfflineClient.exe c:\temp\document.pdf /signatureTemplate c:\temp\sigTemp.xml

The result in the client will look like the following:

===Signature Template with References===
The capability to use and modify a signature template was alredy described in the previous chapter. In addition to that you can combine the means of sig-strings and signature template XML in one step.

The idea is to use the sig-strings in the document just for positioning the signature fields and have everything else (size, field description etc.) in the signature template. This enables you to use special characters and large text elements in the field which might be troublesome when used directly in the sig-strings in the document.

'''To make use of this feature follow these steps:'''
<ol><li> position the signature fields in your document with sig-string which contain references to the signature template; Examples: 
'''`sig,ref=customer`''' '''`sig,ref=type_10`'''</li>
<li>Create a signature template XML according to the following example:</li></ol>
<syntaxhighlight lang="XML">
<signatureTemplate>
  <version>1.2.0.0</version>
  <positionUnits>pdfUnits</positionUnits>
  <positionReferenceCorner>Lower_Left</positionReferenceCorner>

  <sig ref="customer">
      <param name="uid"> </param>
      <param name="fd">Plase sign here to confirm to the Terms and Conditions:</param>
      <height>50</height>
      <width>40</width>
  </sig>
  <sig ref="type_10">
      <param name="uid">backoffice</param>
      <param name="fd">Please sign to confirm the customers insurance poolicy</param>
      <height>20</height>
      <width>40</width>
  </sig>
</signatureTemplate>
</syntaxhighlight>

'''Explanation:'''

o <sig '''ref="customer"'''>: This attribute is matched with the “ref” option in the sig-string.

o Call the client from the command line by providing the path to the document and the signature template. Example:

SIGNificantOfflineClient.exe c:\temp\document.pdf /signatureTemplate c:\temp\sigTemp_ref.xml

The result in the client looks like the screen below:

===Signature Template for field modification===
A Signature Template can also be used for altering an alredy existing field in a PDF. The idea is to use any PDF form designer for just for positioning the signature fields and have everything else (field description etc.) in the signature template.

'''To make use of this feature follow these steps:'''
# Position the signature fields in your document with a PDF form designer and remember the field names
# Create a signature template XML according to the following example:
<syntaxhighlight lang="XML">
<signatureTemplate>
  <version>1.2.0.0</version>
  <positionUnits>pdfUnits</positionUnits>
  <positionReferenceCorner>Lower_Left</positionReferenceCorner>

  <sig existingfield="field1"> <!-- this is an existing field extension entry, it will extend parameters for an existing signature field "field1" -->
    <param name="uid">Test</param>
  </sig>
</signatureTemplate>
</syntaxhighlight>

'''Explanation:'''

o <sig '''existingfield="field1"'''>: This attribute is matched with a field with name “existingfield”.

o Call the client from the command line by providing the path to the document and the signature template. Example:

SIGNificantOfflineClient.exe c:\temp\document.pdf /signatureTemplate c:\temp\sigTemp_existingFields.xml

:'''Hint:''' create one large signature template XML for all your document types and reference it from your documents.

==Customization==
===Configure Size of Signing-Dialogue===
'''Available since version 20.14'''

In the global.xml file in the section "signatureScreen" the size of the signature screen can be specified in percent.

In detail, the size for "Sign (POS inline)" and all other signing methods can be configured separately. The reason is that the Sign (POS inline) gets signed on the pdf and all other signing method in a separate window.

'''Sign (POS inline)'''

Here the attributes posWidth and posHeight are used, whereby width and height can be configured individually, both or nothing(default size).

Only whole numbers between 10 and 100 can be set, whereby the values indicate the percentage on the <u>pdf-page/viewer</u>.

<u>Limitations</u>:
* max zoom level is 9
* min width/height is 400pt/300pt
* when both are placed width overrules the height attribute

'''All others'''

Here the attributes signWidth and signHeight are used, whereby width and height can be configured individually, both or nothing(default size).

Here also only whole numbers between 10 and 100 set, whereby the values indicate the percentage on the <u>program window</u>.

<u>Limitations</u>:
Here only the window gets enlarged.

==FAQ==
This chapter lists some common integration questions.

 '''How can I define a signature field and have the user enter his name later?'''
:Use a sig-string without “uid”, e.g. ‘sig,fd=Please enter your name and sign’ . The system will create a signature field but the signer’s name is changeable.

 '''How can I check if the Offline Client is still running?'''
:Check if the process “SIGNificantOfflineClient” with different command line arguments than "/runservice" is running. A "SIGNificantOfflineClient" process with command line arguments "/runservice" is the xyzmo Client background service.

 '''How can I check which of the signature fields where signed?'''
:Analyze the Document Status Report XML. This report is written when you click a custom button or can be written every time the document is opened or changed. Refer to the Admin Guide for Details.

 '''How can I return to the Offline Client in case the user did not sign the required signature fields?'''
:Just open the PDF directly with the Offline Client.

 '''How can I change the text elements in the Offline Client?'''
:Change the text in the language XML (ProgramFiles\xyzmo Client\LanguageFiles\<language>.xml. Attention: These files are overwritten during update – therefore you have to restore and update them again manually.

==Appendix: Custom Button Example==
This is a very simple example for a custom button command line but it shows what it is all about. The xyzmo client currently supports two custom buttons. The customButton1 is shown in the top toolbar, where customButton2 is located near the bottom right corner of the application window. At the moment, only customButton1 supports displaying a button text and overlay text (i.e. tooltip).
More samples can be found in the xyzmo Client installation directory in the file Samples\CustomActions.txt

'''_global.xml configuration section:'''
<syntaxhighlight lang="XML">
<customButton1>
    <enableIf values="pdfOpened;requiredFieldsSigned">pdfOpened</enableIf>
    <buttonText>Button Tester</buttonText>
    <overlayText>Button Tester</overlayText>
    <saveSignatureFieldsBeforeAction values="0;1">0</saveSignatureFieldsBeforeAction>
    <command>C:\Program Files\xyzmo Client\button_tester.cmd</command>
    <arguments>%FILENAME% %DocStatusReport%</arguments>
    <postCommandAction values="none;reloadPdf;closeClient">closeClient</postCommandAction>
</customButton1>
</syntaxhighlight>

The command is called with the arguments FILENAME and DocStatusReport. You can also use those variables also as part of another argument. e.g. /f:%filename% /ds:%DocStatusReport% . For details refer to the Admin Guide.

'''button_tester.cmd:'''
<syntaxhighlight>
 @echo off
 echo CUSTOM BUTTON TESTER
 echo ---------------------
 echo - FILENAME %1
 echo - DocStatusReport %2
 echo .
 echo press any key to open these files
 pause

 echo analyze the Document Status XML Report:
 notepad %2

 echo send the signed file back to the customer app
 %1
</syntaxhighlight>
'''Explanation''':
{| class="wikitable" width=auto
!style="background-color:#c41230; color:#ffffff;"| Item 
!style="background-color:#c41230; color:#ffffff;"| Explanation
|-
| style="width: 15%"| '''echo – FILENAME 1''' || The batch files takes the received arguments (%1, %2) - %FILENAME and $DocStatusReport% and print it to the console.
|-
|'''pause''' || It waits for a key press.
|- 
|'''notepad 2''' || The %DocStatusReport XML is opened in the notepad for viewing. In reality you analyze the XML here.
|-
|'''%1''' || The document itself is opened by the registered default application (typical Acrobat Reader). In reality you transfer the signed file back to you Customer App. After this step is complete, the script exits and closes the Offline Client.
|}

==Appendix: Create a PDF Printer with pdfCreator 2.X==
This chapter will show you how to create a Pdf Printer using PdfCreator, which will print PDFs directly to the xyzmo Client. Of course you can use other Pdf Printers too.

<ol><li>Download and install PdfCreator</li>
<li>Start PDFCreator</li>
<li>Click '''Application Settings''', select '''Printers''', click '''Add Printer'''. Name the new printer e.g. '''xyzmo Client Printer'''. Click '''Save'''.</li>
<li>Click '''Profile Settings''', add a new profile using +. Name the new profile e.g. '''Open in xyzmo Client'''.</li>
<li>Go to '''Document''' (of the new profile), use <InputFileName> as '''Title'''.</li>
<li>Go to '''Auto-Save''' (of the new profile), check '''Enable automatic saving''', configure '''Target Folder''' to your desired save directory.</li>
<li>Go to '''Actions''' (of the new profile), uncheck '''Open Document''', check '''Run script''', apply the settings below. Click '''Save'''.</li>
* Script File: '''C:\Program Files (x86)\xyzmo Client\SIGNificantOfflineClient.exe'''
* Uncheck '''Wait until script execution has ended'''
<li>Click '''Application Settings''', select '''Printers''', select '''xyzmo Client Printer''', set '''Profile''' to '''Open in xyzmo Client'''. Click '''Save'''.</li>
<li>Test your Pdf Printer</li></ol>

==Appendix: Create a PDF Printer with pdfCreator 4.X==
This chapter will show you how to create a Pdf Printer using PdfCreator, which will print PDFs directly to the xyzmo Client. Of course you can use other Pdf Printers too.
<ol><li>Download and install PdfCreator.</li>
<li>Start PDFCreator.</li>
<li>Click '''Printer''', click '''Add Printer'''. Name the new printer e.g. '''xyzmo Client Printer'''. Click '''OK'''.</li>

<li>Click '''Profiles''', add a new profile using '''Add'''. Name the new profile e.g. '''Open in xyzmo Client'''.</li>

<li>Select the new profile in the listbox, click on the wrench icon beside '''Destination Folder'''.</li>

<li>In this window, select '''Automatic''' on the top selection and use <InputFileName> for '''Filename''',</li>
* insert your desired save directory as '''Target directory''' (must not left empty!) and
* uncheck the '''Open file after saving''' option and press '''OK'''

<li>Click on the '''Add Action'''-button (see screenshots above)</li>
<li>In this window, select '''Run Program'''</li>

<li>Now, enter '''C:\Program Files (x86)\xyzmo Client\SIGNificantOfflineClient.exe''' for the '''Program File''' and uncheck '''Wait Until the program has ended'''.</li>

<li>Click '''Printer''', check the '''xyzmo Client printer''' as primary printer and select the new created profile '''Open in xyzmo Client''' for that printer.</li>

<li>Test your Pdf Printer.</li></ol>

==Appendix: Integrate in Explorer context menu of PDF files==
If you want to open PDF files directly with xyzmo client for cases where you want to sign them, but you probably don't want to change the default program used to open PDF files, you can add an "Open with xyzmo client" entry in the context menu of your PDF files.

Following menu entry can be added to the context menu, shown when clicking a PDF file with the ''right'' mouse button:



===Manual installation in Registry Editor===
'''You should do this only if you are aware of the risks of manually editing the Windows Registry!'''
* Manually search in Windows Registry Editor for the reference key used to manage .pdf files (HKEY_CLASSES_ROOT\.pdf - if Adobe Acrobat Reader DC is your standard application for PDF, it will refer to AcroExch.Document.DC
* In _HKEY_CLASSES_ROOT\AcroExch.Document.DC create the folder "shell", and subfolder "xyzmo"
* In the folder "xyzmo", set Default value to "Open with xyzmo client"
* create a sub folder "command"
* In the folder "command", set Default value to
 "C:\Program Files (x86)\xyzmo Client\SIGNificantOfflineClient.exe" "%1"

===Install via prepared .reg file===
* Download the file from AddXyzmoClientToContextMenu.reg
* Double-click the .reg file and confirm dialogs from Registry Editor

==Appendix: DMS Integration via DMS-Printer==
When your archive / document management system (DMS) provides a "Print to DMS" printer driver, where the printer driver "uploads" the document to the DMS and perhaps lets you fill meta data for the archive document, you can integrate a "send to DMS" functionality as custom button (e.g. CustomButton2) and with printing features of Adobe Acrobat Reader. The CustomButton2 will then be displayed in the bottom right corner of the xyzmo Client's application window.

First of all, check the printer name. Acrobat Reader DC may have some limitations regarding printer driver name. It seems the printer driver name must have a name not longer than 10 characters and without spaces. Therefore, the printer name can easily be renamed in Windows' "Devices and Printers" view, in printer preferences (you probably have to enable the "edit preferences" button first).

Then, configure the CustomButton2 (See Appendix for details).
Suggested configuration:

   <customButton2>
            <enableIf values="pdfOpened;requiredFieldsSigned">requiredFieldsSigned</enableIf>
            <overlayText>
            </overlayText>
            <saveSignatureFieldsBeforeAction values="0;1">1</saveSignatureFieldsBeforeAction>
            <command>C:\Program Files (x86)\Adobe\Acrobat Reader DC\Reader\AcroRd32.exe</command>
            <arguments>/t %FILENAME% ##DMS-PRINTER##</arguments>
            <postCommandAction values="none;reloadPdf;closeClient">reloadPdf</postCommandAction>
          </customButton2>

You have to replace ##DMS-PRINTER## with your printer name, e.g. PrintToDMS

You can also replace the bu_custom2.png and bu_custom2_over.png (in xyzmo Client's \config\skin folder) by an "to DMS" icon, or any other icon of your choice.

{{#seo:
|title=ViewSign
|title_mode=append
|keywords=ViewSign, Standard, Integration
|description=ViewSign integration guide.
}}

[[Category:ViewSign Standard]]