API Demo & Guide

Downloads

The API demo for sign pro PDF can be downloaded here:

Download	Description
API-Demo-V4.zip	Zip file containing sign pro PDF's API sample

The zip contains the following files:

Directory	Description
`bin\`	Contains test app
`scripts\API Command Demo`	Contains API command tests in `.txt` files with supporting PDF files
`scripts\Text Tag Demo`	Contains text tag command tests in `.txt` files with supporting PDF files

API Modes

There are two modes of API operation:

Text Tag Mode: In this mode, sign pro PDF instructions are inserted in text tags within the PDF.
API Mode: In this mode, all of the sign pro PDF instructions are included in the command line.

Starting sign pro PDF API

To simplify testing, the demo application TestSignProAPI.exe is included.

API Demo

Read File

This will read a JSON script file into a text box. The JSON script can be edited before starting the sign pro app. The read operation replaces the original text as follows:

($currentdir) is converted to the path of the loaded file
Escape code backslash \ is converted to \\

Browse to the scripts folder and select one of the JSON script .txt files provided in either:

scripts\API Command Demo
scripts\Text Tag Demo

The script files are configured to demonstrate the API with the included PDF files. Once the file has been read into the edit window, the contents can be modified to trial alternative API functions.

Preprocessor: Note that the original file contents' text string ($currentdir) is converted to the current folder name to simplify script file management. This means that the script folders can be relocated and continue to function correctly.

Submit

Select Submit to validate and encode the JSON structure entered in the edit window. There is an option to submit as x86 or x64. If successful, the sign pro PDF application is started with the command-line parameters:

C:\Program Files\Wacom sign pro PDF\Sign Pro PDF.exe -api signpro:<base64-json>

To support sign pro v3, Ctrl-Submit starts the sign pro application as:

C:\Program Files\Wacom sign pro PDF\WacomGSS.signpro.exe -api signpro:<base64-json>

The operation can also be started manually by entering the command in a DOS command prompt. Either copy the encoded string from the status window or encode the JSON structure using an online utility such as base64encode.org.

Browse

Users have the option to select the EXE manually if it is not installed in the standard location under Program Files by using "Browse".

Web Browser

Sign pro can also be called via the web. The operation can alternatively be started manually by entering the URL in a browser: signpro:<base-64-json>

How to Integrate

For users wishing to integrate sign pro into a web browser:

Insert a button, anchor tag, redirect, etc., that references sign pro with signpro:<base-64-json>.
Alternatively, call the URL with signpro:<base-64-json>.

An example of the pre-base 64 JSON can be viewed below:

{
  "file": {
    "input": {
      "filesystem": null,
      "http_get": "http://fileserver.com/document.pdf"
    },
    "output": {
      "filesystem": null,
      "http_post": "http://<your-web-service>",
      /* the web service can be organised as per the developer’s wishes, in regard to the doc(s) that the integrator is receiving */
    },
    "authentication": { ... }
  },
  "configuration": {
    "process_text_tags": true
  }
}

An example of this can be seen below: after entering the example URL into the browser, the "API Demo.pdf" document will be opened:

API Integration

The user will then be presented with the following view.

API Integration

For more information on how to organize this, please view the input and output tables within API Specification.

It is recommended that the browser is accessed via a button or text tag, as the URL method can have limitations. Additional information about limitations per browser can be viewed below.

Browser Limitations

Please be aware that the length of the URL command is limited. Refer to your browser of choice’s character limitations for more information.

Command Line

Once the JSON structure has been saved, it can be passed in the command line for direct processing, e.g.:

C:\Program Files (x86)\Wacom sign pro PDF\Sign Pro PDF.exe -apiFile C:\dev\json-file.txt

For successful operation, file parameters will be saved with the full pathname:

"input": {
  "filesystem": "C:\\docs\\mydoc.pdf",
  "http_get": null
}

Additionally, the sign pro PDF installer creates the file association for the extension .signpro. A JSON file saved with the .signpro extension can be double-clicked to launch the application with direct processing.

Demonstration

Text Tag Mode

The file "API Demo Text Tags.pdf" demonstrates the use of text tags. The Tags in the file are as follows:

Create signature area on Page 1 & 3:

{{[[Type=Signature,Page=1:3,Height=44,Width=150,X=200,Y=600,Name=TestSignature,Signer=John Smith,Reason=Testing]]}}

Create Initials area on Page 2:

{{[[Type=Initial,Page=2,Name=InitialsTest,Signer=John Smith,Reason=Test initials,X=72,Y=72]]}}

To start the demonstration, select the 'demo text tags.txt' script, then press Submit:

{
  "file": {
    "input": {
      "filesystem": "C:\\API-Demo\\scripts\\TextTag Demo\\API Demo - Text Tags.pdf",
      "http_get": null
    },
    "output": {
      "filesystem": "C:\\API-Demo\\scripts\\TextTag Demo\\API-Demo - Text Tags.out.pdf",
      "http_post": null
    },
    "authentication": {
      "pdf_user_password": null,
      "http_user": null,
      "http_password": null
    }
  },
  "configuration": {
    "show_annotate": false,
    "show_manual_signature": false,
    "error_handler_url": null,
    "process_text_tags": true
  },
  "initials": null
}

The command starts sign pro PDF and creates the signing areas defined.

Text Tag Mode

In this demo sign pro PDF has been started without manual signature placement or annotations enabled. By modifying the JSON structure these can be enabled in subsequent tests, e.g.:

 "configuration": {   
    "show_annotate": true,   
    "show_manual_signature": true,   
    "error_handler_url": null,   
    "process_text_tags": true    },   

Similarly the JSON structure can be modified to test other functions, such as document password protection.

API Mode

The file "API Demo.pdf" can be used to demonstrate API mode, where all commands are passed in the JSON structure. Select the script file 'demo api.txt':

{
  "file": {
    "input": {
      "filesystem": "C:\\API-Demo\\scripts\\API Command Demo\\API Demo.pdf",
      "http_get": null
    },
    "output": {
      "filesystem": "C:\\API-Demo\\scripts\\API Command Demo\\API Demo.out.pdf",
      "http_post": null
    },
    "authentication": {
      "pdf_user_password": "pass",
      "http_user": null,
      "http_password": null
    }
  },
  "configuration": {
    "show_annotate": false,
    "show_manual_signature": false,
    "error_handler_url": null,
    "process_text_tags": false
  },
  "signatures": [
    {
      "name": "signature_1",
      "signer": "John Smith",
      "reason": "Testing",
      "type": "FSS",
      "biometric": true,
      "required": true,
      "location": {
        "Page": "1",
        "X": 200,
        "Y": 600,
        "W": 150,
        "H": 44
      }
    },
    {
      "name": "signature_2",
      "signer": "Jane Smith",
      "reason": "Testing",
      "type": "FSS",
      "biometric": true,
      "required": true,
      "location": {
        "Page": "3",
        "X": 200,
        "Y": 600,
        "W": 150,
        "H": 44
      },
      "device": {
        "selection_mode" : "DefaultDevice",
        "default_device" : "DTH-1152;123"
      }
    }
  ],
  "initials": [
    {
      "name": "initials_1",
      "signer": "John Smith",
      "reason": "Test initials",
      "type": "FSS",
      "biometric": true,
      "required": true,
      "location": {
        "Page": "2",
        "X": 77,
        "Y": 77
      }
    }
  ]
}

The command starts sign pro PDF and creates the signing areas similar to the Text Tags demo. In this case, signatures are marked as 'Required' and must be completed before the document can be saved.

API Mode

SharePoint

When using SharePoint, functions such as registering an application or getting an access token need to be done via API calls.

For SharePoint, input parameters look something like:

"file": {
  "input": {
    "ms_graph": {
      "document_id": "012...",
      "user_email": "abc..."
    }
  },
  "output": {
    "ms_graph": {
      "document_id": "012...",
      "user_email": "abc..."
    }
  },
  "authentication": {
    "ms_graph_access_token": "xyz..."
  }
}

OneDrive

Like SharePoint, OneDrive’s functions must be accessed by calling the app. Unlike SharePoint, a drive_id is used instead of a user’s email.

"file": {
  "input": {
    "ms_graph": {
      "document_id": "012...",
      "drive_id": "abc..."
    }
  },
  "output": {
    "ms_graph": {
      "document_id": "012...",
      "drive_id": "abc..."
    }
  },
  "authentication": {
    "ms_graph_access_token": "xyz..."
  }
}

In both cases, the app must be properly programmed to know or obtain the document_id, ms_graph_access_token, and either drive_id or user_email.

Tablet Display Mode

To set sign pro PDF to open on a display tablet, the following setting in user.config must be edited manually:

<setting name="TabletScreenSelection" serializeAs="String">
    <value></value>
</setting>

Note: There is no UI for changing this.

For use in the API, the setting is tablet_selection in the configuration section, e.g.:

"configuration": {
  "tablet_display": true,
  "tablet_selection": "bottom"
}

Supported values are "left", "right", "top", "bottom", "first", and "last". The API value overrides (but does not overwrite) the config setting.

Note: These settings should only be used for Citrix or RDP.

Troubleshooting

Error Starting API

To use the API functionality, the sign pro PDF license must be set to Evaluation or Enterprise, including SIGNPRO_API_ACCESS. If this is not enabled, an error message will be displayed:

API access prohibited

Invalid JSON

Before attempting to start sign pro PDF, the test validates the JSON structure. An error message will be displayed in the Status window, for example, if there is a missing comma:

Validating JSON...
After parsing a value, an unexpected character was encountered: ". Path 'file', line 17, position 2. Invalid Json

The structure must be corrected before attempting to submit.

Error Message Displayed by Sign pro PDF

If the API commands cannot be processed, an error message will be displayed. Check the content of the JSON structure and/or the text tags, particularly file paths. The JSON structure can be validated online, for example, at jsonformatter.curiousconcept.com.

Downloads​

API Modes​

Starting sign pro PDF API​

Read File​

Submit​

Browse​

Web Browser​

How to Integrate​

Browser Limitations​

Command Line​

Demonstration​

Text Tag Mode​

API Mode​

SharePoint​

OneDrive​

Tablet Display Mode​

Troubleshooting​

Error Starting API​

Invalid JSON​

Error Message Displayed by Sign pro PDF​

Downloads

API Modes

Starting sign pro PDF API

Read File

Submit

Browse

Web Browser

How to Integrate

Browser Limitations

Command Line

Demonstration

Text Tag Mode

API Mode

SharePoint

OneDrive

Tablet Display Mode

Troubleshooting

Error Starting API

Invalid JSON

Error Message Displayed by Sign pro PDF