Integration Codes

Before you start

Make sure you have the Penneo Desktop application installed
Open the Penneo Desktop application

Why do integration codes exist

Penneo integration codes offer a simple way to integrate a website or a third party service to the Penneo Desktop application, which is used to send [Case files].

The alternative is to write a full-blown integration using Penneo's REST API. However, this is usually a more involved and lengthy process, but allows a tighter integration.

Also, you don't necessarily need to have a deep knowledge about programming to implement a working solution.

URI Schema

The integration codes are written in a JSON format and uses a "URI" penneo:// to trigger the Penneo Desktop application to load and send data through other systems.

i.e. Penneo Desktop becomes the default handler of links that start with penneo://, just like your web browser handles all http:// or https:// links.

Use case

The most common use case for integration codes is sending information from your application to Penneo, to automate manual input and avoid repetitive tasks.

Esentially, from your application, you can create a "Send to Penneo" button that will carry on information to Penneo Desktop in a ready-to-send format.

With integration codes you can automate:

Creating case files with data transferred from your product or service (title, signers, documents, copy recipients, etc.)
Automatically load PDF files from your file system or a web server to Penneo Desktop.

Examples

The following is a sample of an integration code that will create a case file of type "Employment Contract", will create one signer, and will upload a PDF document from the filesystem.

{
    "name": "Hello World",
    "caseFileTypeId": "Employment contract",
    "signers": [
        {
            "name": "Someone",
            "role": "Employee",
            "email": "[email protected]"
        }
    ],
    "documents": [
        {
            "title": "test",
            "type": "Contract",
            "localPath": "C:/path/to/file.pdf"
        }
    ],
    "schemaVersion": "2.0.0"
}

Usage instructions

To demonstrate the usage, for the rest of the guide, we will make reference to this minimal integration code, which is enough to trigger Penneo Desktop to load the case file title

Basic example:

{
    "name": "Hello World",
    "schemaVersion": "2.0.0"
}

To use integration codes, it's needed to convert the JSON into a URI, and trigger that URI in your application (programatically or via a click in a web browser, for example).

The URI schema associated with Penneo Desktop is penneo://, and URIs cannot contain newlines. so the example above would become the following:

penneo://{"name": "Hello World", "schemaVersion": "2.0.0"}

If you paste this command into a browser's address bar, it will open Penneo Desktop and load the data. However, it's important to know that support for decoding characters like curly brackets differs by OS and browser, so the method of conversion will be slightly different depending on your use case. Read below for more information:

Windows (.NET)

[Instructions Pending]

Web Browsers (Javascript)

This section explains the internals of how URIs work in the browser, but we have createed a browser-uri-utils package to aid with implementations in web applications. (Read the next section)

Some customers choose to put links to open Penneo in their web applications, by adding the URI to an <a> tag or redirecting to the URI.

For compatibility purposes, we have to make the URI safe to use in all browsers, to do so, we must URL encode the content of the integration code.

We also have to tell the Penneo Desktop application that this is a URL encoded, by changing the URI schema to

penneo://browser,{url-encoded-content}

If we URL encode the sample integration code, and prefix it with penneo://browser,. We come up with the following:

penneo://browser,%7B%22name%22:%22Hello%20World%22,%22schemaVersion%22:%222.0.0%22%7D

If we make this the href attribute of a link <a> tag, like:

<a href="penneo://browser,%7B%22name%22:%22Hello%20World%22,%22schemaVersion%22:%222.0.0%22%7D">
    Open Penneo
</a>

It will trigger the Desktop Application to load the data when clicked, and it will also be compatible with older browsers such as Internet Explorer.

Please note that there is a limit of 2048 characters for the href attribute in Internet Explorer up to 11. So for really long integration codes, we recommend to use the fileReference property. [Read more]

URI Utility for web browsers `browser-uri-utils`

To use integration codes with javascript, we have created a utility that simplifies the amount of work that you have to do to implement a solution.

Click here to learn how to install and use the browser-uri-utils javascript helper

Create an integration code

You can create an integration code in two ways.

Use the JSON Schema references and build it manually
Use the built-in Integration Code utility in the Desktop Application.

Settings > Developer > Create Integration Code

Which will give you the integration code for the current configuration in the application.

i.e. It's a good starting point to fill the desktop application with the information you will need from your integration, and then go to the Create Integration Code menu item, and extract the code, and use it as a template for your implementation.

Reference PDF files in integration codes

Send local files to Penneo Desktop

{
    "documents": [{
        ...
        "localPath": "C:/path/to/local/file.pdf"
    }]
}

Especial consideration for Windows

Windows filesystems use back slashes \ for file paths, which are not part of valid JSON.

You can choose between two solutions:

Convert these backslashes to forward slashes (files will still be referenced properly)
Escape the backslashes in your integration code, as such:

{
    "documents": [{
        ...
        "localPath": "C:\\path\\to\\local\\file.pdf"
    }]
}

Send remote files to Penneo Desktop

If you reference a web URL that points to a PDF file, the Desktop application will download that PDF and convert it to a Penneo document

{
    "documents": [{
        ...
        "localPath": "https://website.com/files/sample.pdf"
    }]
}

Technical notes

The URL to the PDF file can only be of http or https protocol.
The URL has to be a link to a publicly accessible file
The Desktop Application can follow up to 5 redirects for download links. (This is useful for files hosted in Google Cloud, for example)