Moving Forward Virtually with DocuSign

DocuSign is an industry standard application platform for collecting digital signatures on important documents. If you’re using a custom Claris FileMaker solution to help run your business, and DocuSign for collecting digital signatures, you should consider integrating the two systems. By using FileMaker’s Insert from URL script step, and the very robust DocuSign REST API, you can realize some operational efficiencies that are pretty amazing.

To see an example of what we’re talking about, check out this video demo of a custom Claris FileMaker solution that is integrated with DocuSign.

DocuSign Account Configuration

To achieve this integration, we first need to configure our DocuSign account for API access. We’ll need to be a DocuSign admin for the organization, and we’ll need to upgrade our account to a developer tier to enable API access. Fortunately, there’s a free tier that allows us to experiment without limits, but note that all documents created with the free tier will be watermarked as “demonstration document only”. DocuSign Pricing

Once we have enabled our developer account (free or otherwise), navigate to the developer dashboard and locate the Apps and Keys page. On this page, select “Add App and Integration Key”, give the new app a name, select Implicit Grant in the Authentication section, and add a Redirect URI. The redirect URI can point to any valid web page (I used www.codence.com). Copy the integration key, we will need this in the next step.

The DocuSign API

The DocuSign API is very well documented. In this example, we are referring to the eSignature REST API v2.1, specifically the sections on envelopes and authenticating with an Implicit Grant.

Authenticating to DocuSign

With the Implicit Grant method, we’re going to use a web viewer to authenticate to DocuSign. The URL for the web viewer should look something like this:

The client_id in this URL is the integration key from above. When we point the web viewer at this URL we’ll get a DocuSign branded authentication page where our user enters an email and password. Once we login with our credentials, we’ll be redirected to the redirect_uri specified. Buried in the source of this page is an access token that we’ll need to capture. We’ll use the FileMaker function GetLayoutObjectAttribute ( “webViewerName”; “source” ) to capture the source of the results page and parse out the access token and its expiration time.

Web Viewer Source

We’ll use this access token in all subsequent API requests, and we’ll also want to compute an expiration timestamp based on the timestamp of the above authentication request, and the expires_in (seconds) parameter that we parsed. We’ll want to keep an eye on this timestamp and get a new token once the current one has expired.

Use text parsing functions to capture the token and expiration time from the web viewer source:

Preparing the FileMaker Layout

In this example, we are going to use a FileMaker layout to prepare our document to be signed. We will save it as a PDF and then upload it to DocuSign. We need to configure our layout so that we can instruct DocuSign where to ask for a signature. DocuSign allows us to define tags that we can embed in our PDF to indicate where we want our DocuSign user to interact with the document. These tags are just text strings, and we will use white text for these so that they’re not visible in our document.

Here is our document in layout mode. Note the white text tags indicating where we want our DocuSign user to initial, and sign the document. We have temporarily changed the background of the layout part to a darker shade so that the white tags are visible in this screenshot.

Save as PDF and Upload to DocuSign

We’ll use the Save Records as PDF script step to create a PDF from our layout and then upload this document to DocuSign via the API.
Uploading the document to DocuSign is arguably the trickiest part of this implementation. We need to do a bit of work to get this right. We’re going to need the name and email of the signer, our PDF (base64 encoded), and a JSON object that describes what DocuSign refers to as the envelope. An envelope is a collection of one or more documents for consideration by the signer. In this case, we have a single (PDF) document, and we need to define the properties of the envelope which is going to include this document.
Our envelopeJSON object includes elements describing the status of the envelope, and the name and email of the signer and the base64 encoded document itself. Note that the documents and recipients elements are actually arrays that allow multiple items. In our example, we’ve got the one document and the one recipient, but these arrays can be extended as necessary. The recipients element includes the signer name and email address, and also the tabs element where we define the anchorString and the placement of the DocuSign element relative to the anchorString when DocuSign interprets our document for display to the signer.
This envelopeJSON object gets used in the definition of our cURL options; note that we also need to include our access token.

This all gets assembled into our API request which we execute with the Insert from URL script step on line 31 in the script above. If everything goes well, we should receive a JSON object in our reply of the form:

We will need the envelopeId for any future requests for this envelope, the status indicates that the signer has been notified by email, and the timestamp indicates when the signer was notified.

What Just Happened?

If we make a successful call to the API, we’ll get a verbose response which includes all sorts of detail about our envelope. The one item that we’re interested in is the status element near the bottom. A status of completed lets us know that the signer has successfully signed our contract.

We’ll update our local FileMaker record appropriately and then retrieve the signed document from DocuSign. We’ll need to make another API request to get the documentId(s). As before, our URL endpoint includes our account id and the envelopeId for this specific set of documents, and our cURL options just includes our access token. We loop through the list of documents and place them in their respective containers.

Once we retrieve these documents, we’re done! Though it took a while to explain this all, the entire process takes just a few seconds to complete – the slow step is waiting for the signer to complete their process.

Business Agility