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:

Parameter	Description
-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. Note: This will be supported in future version.
/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:

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

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:

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`
Create a signature template XML according to the following example:

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

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:

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

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 pdf-page/viewer.

Limitations:

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

Limitations: 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:

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

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:

 @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

Explanation:

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

Download and install PdfCreator
Start PDFCreator
Click Application Settings, select Printers, click Add Printer. Name the new printer e.g. xyzmo Client Printer. Click Save.
Click Profile Settings, add a new profile using +. Name the new profile e.g. Open in xyzmo Client.
Go to Document (of the new profile), use <InputFileName> as Title.
Go to Auto-Save (of the new profile), check Enable automatic saving, configure Target Folder to your desired save directory.
Go to Actions (of the new profile), uncheck Open Document, check Run script, apply the settings below. Click Save.

Script File: C:\Program Files (x86)\xyzmo Client\SIGNificantOfflineClient.exe
Uncheck Wait until script execution has ended

Click Application Settings, select Printers, select xyzmo Client Printer, set Profile to Open in xyzmo Client. Click Save.
Test your Pdf Printer

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.

Download and install PdfCreator.
Start PDFCreator.
Click Printer, click Add Printer. Name the new printer e.g. xyzmo Client Printer. Click OK.
Click Profiles, add a new profile using Add. Name the new profile e.g. Open in xyzmo Client.
Select the new profile in the listbox, click on the wrench icon beside Destination Folder.
In this window, select Automatic on the top selection and use <InputFileName> for Filename,

insert your desired save directory as Target directory (must not left empty!) and
uncheck the Open file after saving option and press OK

Click on the Add Action-button (see screenshots above)
In this window, select Run Program
Now, enter C:\Program Files (x86)\xyzmo Client\SIGNificantOfflineClient.exe for the Program File and uncheck Wait Until the program has ended.
Click Printer, check the xyzmo Client printer as primary printer and select the new created profile Open in xyzmo Client for that printer.
Test your Pdf Printer.

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.