fmESignature Link (DocuSign Edition) Getting Started Guide

We recommend creating a free DocuSign Sandbox account to use when testing the fmESignature Link (DocuSign Edition) solution or your integration. A sandbox account is a full-featured DocuSign development environment that never expires (no credit card required either) and can be created in a few minutes:

Create Sandbox

Go to Sandbox

When you’ve completed your testing you can switch from the sandbox account to your live DocuSign production account.

If you would like to learn more about the DocuSign eSignature API please visit the DocuSign Developer Centre:

DocuSign Developer Centre

The DocuSign eSignature Glossary is also a handy reference if you’re not familiar with the common terms (envelope, tab, template etc):

DocuSign eSignature Glossary

DocuSign Sandbox Setup

N.B. the following instructions apply to fmESignature Link v1.4 or later which use the Authorization Code Grant OAuth Flow for authenticating with DocuSign. If you are using fmESignature Link v1.36 or earlier please follow the instructions in our JWT Grant OAuth Flow Setup guide.

Setting up your DocuSign Sandbox account to allow you to send test document signing requests from the fmESignature Link file only takes a few minutes – you need to complete the following steps:

1. create your DocuSign Sandbox account
2. create a new API and Integration Keys in the Sandbox
3. copy/paste the keys into the fmESignature Link (DocuSign Edition) Setup screen

We have a short video demonstrating the setup of the DocuSign Sandbox and creating a new API integration – check out the videos page to view this video (YouTube link). The DocuSign Getting Started guide also has details on creating your first API integration.

Once you’ve created your free Developer Sandbox Account you need to first create the Integration Key that you will use with the fmESignature Link file. We recommend having the fmESignature Link file open at the same time on the  Setup screen so you can copy/paste keys from your Sandbox account directly to FileMaker:

After you have logged in to your Sandbox account select  Settings from the navigation menu across the top:

On the lower left side of the Admin Console select  API and Keys to view your existing API apps and create a new set of API keys. 

Click the  ADD APP & INTEGRATION KEY button to create a new Sandbox App:

First enter an App Name to use for your integration and click the Add button to see the rest of your integration settings:

You will need to record information from this page and copy and paste it into the Setup screen in the fmESignature Link file.

Integration Key: this is generated automatically by DocuSign. Copy and paste this into the Integration Key field in the Sandbox Preferences

Secret Keys: click the Add Secret Key button to generate a new key. Copy and paste this into the Client Secret field in the Sandbox Preferences. N.B. the Client secret will only ever be displayed once and will not be visible once you click the Save button (you can always generate a new secret if necessary). 

Authentication: select Authorization Code Grant (should already be set as the default)

RSA Keypairs: you can ignore this

Additional Settings: Redirect URIs: click the ADD URI button to create a new Redirect URI. We recommend using the following URI: 

https://docusign.com

which is also the default value that we set for the Redirect URL field in the fmESignature Link file. If you have changed this (e.g. to your own website) copy and paste the URI into the Redirect URL field in the Sandbox Preferences. N.B. the value in the DocuSign App must also be exactly the same in the fmESignature Link file (you will get an error if these are not identical).

Click  Save when you have finished. The Sandbox Preferences in the fmESignature Link file should look like this:

We now need to perform a one time authorisation to grant approval to fmESignature Link to use the DocuSign App you have just created. Click the Authenticate button which will open a new Card window and take you to the DocuSign login page where you can login and grant approval to the fmESignature Link file:

Enter your DocuSign Sandbox credentials (you might be prompted to verify the device if DocuSign recognises that you are logging in from a new device or browser - you will be prompted to enter a code that is sent to your email) 

If you have entered the Client Secret or Integration Key incorrectly you will get an error like this:

Double check that you have entered the Integration Key, Client Secret and Redirect URI correctly and not made any errors when copy/pasting these across to the fmESignature Link file.

If this is the first time you have attempted to authenticate the DocuSign App you will also be prompted to provide consent:

Click Accept when prompted to provide consent for the fmESignature Link file to create and send envelopes using the DocuSign API.

Once you have successfully authenticate with DocuSign you will then be taken to the Redirect URI you entered for your DocuSign App:

To complete the Authorization Code Grant OAuth flow click the Continue button in the bottom right hand corner of the Web Viewer which will exchange the code for an Access Token and generate the following:

1. Access Token
2. Expires At (uses the FileMaker Server timestamp to handle users in multiple time zones)
3. Refresh Token
4. Base URI
5. Account ID

which are saved to their corresponding fields in the Sandbox Preferences:

These will be used to authenticate with your DocuSign app from now on – you won’t be required to login to the DocuSign website unless your Refresh Token expires or your tokens are otherwise revoked. Access Tokens expire after 8 hours (we keep track of this in the Expires At field) and can be refreshed automatically using the Refresh Token. Refresh Tokens expire after 30 days: if you don’t refresh your access token within 30 days you will need to click the Authenticate button and reauthorise the app. You can also schedule the DocuSign Authentication - OAuth 2.0 Refresh Access Token FileMaker script to be performed on a schedule (e.g. daily or weekly) to ensure the Tokens do not expire).

Once permission has been granted you are then able to use fmESignature Link to send document signing requests automatically without requiring the user to login and authorise each request.

Templates Setup

The fmESignature Link file supports a number of different types of Templates that you can send to recipients for signing.

1. you can generate a PDF from a FileMaker layout and use that as the document to send for signing. This PDF can include merged data from your FileMaker solution and is uploaded with each signing request
2. you can store a PDF file in a FileMaker container field to use as the document to send for signing. This PDF is uploaded with each signing request
3. you can create a Template within DocuSign to use as the document to send for signing (including support for multiple recipients and roles)

We have a number of short videos demonstrating how to work with the different Templates – check out the videos page to view these videos.

FileMaker Layout Templates

The fmESignature Link file includes an example Template called Customer Agreement Standard which demonstrates how to generate a PDF from a FileMaker layout dynamically and use that as the document to be sent to a recipient for signing. It uses the  Customer Agreement PDF layout which is a single page PDF which is generated by the script that runs when you send a request using this Template. It includes 4 Tabs (see below) to capture a signature, name, position and initials. A second example that uses the `Customer Agreement Auto Place PDF` layout demonstrates how to use Auto-place (anchor tagging), where DocuSign will automatically add fields near each occurrence of a given string in a template or document.

PDF from a FileMaker Container Field

The fmESignature Link file includes an example Template called FileMaker Container Field Sample which demonstrates how to store a PDF in a FileMaker container field and use that as the document to be sent to a recipient for signing. It is a single page PDF which is stored in the Template PDF field and includes 2 Tabs (see below) to capture a signature and a name.

DocuSign Template

The fmESignature Link file includes an example DocuSign Template called Sample Tenancy Agreement which demonstrates how to reference a DocuSign Template and use that as the document to be sent to a recipient for signing. It is a single page PDF with 2 Template Roles (Tenant and Landlord) and includes 3 Tabs for each Role (see below) to capture a signature, name and date.

Template Tabs

A DocuSign Tab – also called a Field or Tag – are used in several ways. First they are used to indicate to a recipient where a signature or initials are required. Second, tabs can be used to show data or information to recipients, such as dates, company names, titles, etc. Third, tabs may be used as editable information fields where signers can add data to a document.

Some Tabs are automatically populated by DocuSign (such as Full Name) from the data you send as part of the signing request. You specify the position for each tab using x/y co-ordinates or by using the Auto-place (anchor tagging) feature to have DocuSign automatically place tabs at every location where a specified text string, also known as an anchor, is found in a document.

fmESignature Link allows you to add the following Tabs to a Template:

Full Name: Displays the recipient’s full name. This value can’t be set.
Sign Here: Allows the recipient to sign a document. May be optional. This value can’t be set.
Initial Here: Allows the recipient to initial the document. May be optional. This value can’t be set.
Email: Allows the recipient to enter an email address. This is a one-line field that checks that a valid email address is entered. This value be set.
Company: Displays the recipient’s company name. This value can’t be set.
Title: Displays the recipient’s title. This value can’t be set.
Text: Allows the recipient to enter any type of text. This value can be set.
Date Signed: Displays the date that the recipient signed the document. This value can’t be set.
First Name: Displays the recipient’s first name. This value can’t be set.
Last Name: Displays the recipient’s last name. This value can’t be set.

You can also use the Auto Place (anchor tagging) feature of DocuSign to have it automatically add fields near each occurrence of a given string in a template or document. See the fmESignature Link (DocuSign Edition) AutoPlace Tabs (Anchor Tagging) page for further details.

We have a short video demonstrating how to work with Template Tabs – check out the videos page to view this video.

Template Roles
Template Roles are used with Templates that you setup in DocuSign where you can assign multiple signing roles for multiple recipients. For example you might have a document that needs to be signed by 2 parties, such as a Tenant and a Landlord. Using Template Roles allows you to create Tabs for each Recipient which they can complete when they receive the signing request. You can also specify he order for each recipient – for example you might want the Tenant to sign the document first and the Landlord last.

We have a short video demonstrating how to work with DocuSign Templates and Template Roles – check out the videos page to view this video.

Sending a Signing Request
You can generate signing requests (DocuSign refers to these as an Envelope and you will see references to the Envelope ID and Status in the fmESignature Link file) in a number of different ways:

1. Contacts: from the Contact Details screen you can click the Create New Signing Request button to generate a new Request record with the Contact added as the recipient. You then need to select the Template for this Request

2. Templates: from the Template Details screen you can click on the Template Request tab and then click the New Request button to create a new Request for the selected Template and then add your recipient

3. Requests: from the Request Details screen you can create a new blank record and select the Template and add the recipient.

If you are using a DocuSign Template for your Request which includes multiple Roles you will need to add a Recipient for each Role and assigned the Position to determine the order in which each recipient receives the request. For other Template types you will usually just be sending the Request to a single recipient.

Once you have selected the Template and added your Recipient/s you can send the Request by clicking the  Send Request button in the top toolbar. The fmESignature Link file will then perform the authentication with the DocuSign API and refresh the tokens if required. Once it has authenticated successfully it will send the request to DocuSign and they will then email the recipient with a link to sign the request.

Checking the Status of a Signing Request

• Sent: The email notification has been sent to at least one recipient. The envelope remains in this state until all recipients have viewed the documents. (Shown in Reports and History only)
• Delivered: All recipients have viewed the documents.
• Waiting for Others: The envelope has at least one recipient who has yet to complete their action.
• Completed: An envelope is completed once all of the recipients have completed their actions.
• Expired: A document that has exceeded its set expiration period without completing will expire. Recipients can no longer view or sign the expired document.

You can get the full list of possible statuses here. DocuSign limits Status requests to once every 15 minutes or less frequently: we impose a 20 minute wait in the fmESignature Link file before you can re-check the Status of a request just to be safe.

You can also have DocuSign automatically push completed documents to your FileMaker Server – see our Webhooks guide for more information.

Downloading the Completed Document
Once a request has been completed by all parties (you will typically get notified via email from DocuSign that this has happened) you can then download the completed PDF file from DocuSign by clicking the  Download Signed PDF button which downloads the PDF file into the Signed PDF field in the fmESignature Link file.

You can also have DocuSign automatically push completed documents to your FileMaker Server – see our Webhooks guide for more information.

Downloading the Completed Form Data
Once a request has been completed as well as downloading the Completed PDF file you can also download the raw form data that was entered by the recipient/s. To download the Form Data click on the Form Data tab then click the  Get Completed Form Data button to download the form data for the request. These are typically name/value pairs which we parse out, as well as storing the full Form Data response in the Completed Form Data field on the left of the Request Details screen.

Integration in your own FileMaker Solution

You should now be comfortable with sending signing requests and downloading data between FileMaker and DocuSign. You can view each of the scripts in the Script Debugger as you go to see what steps are being taken – we have commented the scripts to explain each step of the process. You are now ready to tackle the integration with your own FileMaker solution.

N.B. as we are continually updating the fmESignature Link file the screenshots below might not look exactly the same as what you see. Please refer to your fmESignature Link file for the latest version of these.

Step 1: Custom Functions – Copy and Paste or Import

This requires FileMaker Pro Advanced – you can either copy the Custom Functions from the fmEcommerce Link file or you can import them into your solution file. If you already have any of these custom functions installed you can skip those:

Step 2: Tables – Copy and Paste or Import

This requires FileMaker Pro Advanced – you can either copy the Tables from the fmEcommerce Link file or you can import them from your solution file:

Depending on your integration and your existing solution file won’t need to import all of the following tables if you already have an existing matching table:

Contacts: this stores the Contact records (recipients that you send signing requests to)

FormData: this stores the FormData records that are downloaded when you download the Form Data for a Request

Preferences: this is a single record preferences table that stores the account settings/keys. If you already have a single record Preferences table you can use that. You will need to import the record from this table into your solution.

Navigation: this is part of the fmESignature Link file to provide the top level navigation names and usually will not be required

Requests: this stores the signing request records that are sent to the recipient/s

RequestsContacts: this stores the Recipient/s that were sent for each Request

ServerSideErrors: this stores records that are generated by the server side/Webhooks scripts when they encounter an error or you use the debugging log feature

Tabs: this is the master table of Tabs that can be added to each Template. You will need to import the records from this table into your solution.

TemplateRoles: this stores the Template Roles that are added to a Template record

Templates: this stores the Template records that are associated with each Request that you send

TemplateTabs: this stores the Template Tabs that are added to a Template record

Webhooks: this stores a record for each Webhook that is received. If you’re not using Webhooks you can ignore this.

Step 3: Relationship Graph – Table Occurrences and Relationships

You will need to recreate the Table Occurrences and Relationships from the fmESignature Link file in your solution file. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of table occurrences and relationships so these will need to be recreated manually. As with importing tables if you did not import certain tables you will not need to recreate table occurrences/relationships associated with those tables you did not import:

Step 4: Create Layouts

You will need to create any necessary layouts in your solution file with the same names as the fmEcommerce Link file. If you did not import certain tables then you will not need to create layouts for those tables. At this step you are only creating the blank Layouts with the same name as in fmEcommerce Link. You will be copy/pasting the layout objects/content at a later step. As we have not imported any scripts yet copy/pasting layout content would mean any buttons that reference scripts will be broken.

As you will be recreating layouts in your existing solution file we will be assuming that you will with to recreate the layouts using the same theme/style as your existing solution and not necessarily keep the layouts the same as they are in the fmEcommerce Link file. The layouts in the fmEcommerce Link file use the Cool Gray theme.

The “DEV” layouts are layouts designed for the developer and are kept hidden from users.

We find having the Manage Layouts window open for both the fmEcommerce Link file and your solution file side by side is the quickest way to create new layouts in your solution file. You can quickly copy the Layout Name from the fmEcommerce Link file, create a new Layout in your solution file and paste in the name and then select the correct table occurrence to use in the Show Records from menu.

Step 5: Scripts – Copy and Paste or Import

You can use FileMaker Pro/Pro Advanced to either copy/paste or import the scripts from the fmEcommerce Link file. You should import all scripts in the following folders if you are intending to download/upload data from these API endpoints:

• DocuSign API
• Contacts
• Templates
• Requests
• Server Scripts/Webhooks

You can generally not import scripts in the following folders as they are used in the fmESignature Link demo file and usually not required for your solution file:

System

Databuzz

Step 7: Value Lists

You will need to recreate the Value Lists from the fmEcommerce Link file in your solution file. You can use FileMaker Pro/Advanced to copy and paste the value lists from the fmEcommerce Link file to your file:

Step 6: Layout Contents – Copy and Paste Layout Objects/Content

Now that we have the necessary value lists and scripts in your solution file you can now copy/paste the Layout objects/content from the layouts in the fmEcommerce Link file. You will first need to size the layouts and layout parts to the correct sizes, or you can customise these to suit your requirements. We are assuming that you will be changing the layouts to match your existing theme and styles, but whilst you are testing the integration you can copy/paste these “as is” and once everything is working you can then come back and restyle the layouts to suit your requirements.

Step 7: OnFirstWindowOpen Script Trigger

The fmESignature Link file has a OnFirstWindowOpen Script Trigger set via the File Menu>File Options:

The OnFirstWindowOpen Script script performs a number of functions that are specific to the fmEcommerce Link file, but you may need to replicate some of this functionality in your existing OnFirstWindowOpen Script Trigger in your solution file (or set a OnFirstWindowOpen Script Trigger if you do not currently have one set). The most likely features you will need to recreate in your OnFirstWindowOpen Script Trigger include:

Step 8: Import Records

You will need to import the records from the following tables into the corresponding table in your solution:

• Tabs
• Preferences (should only have 1 record)

Step 9: Create buttons for DocuSign API Calls

You will need to create some buttons in your existing layouts to perform the following functions (where required):

Send Request (found on the Request Details layout)

You can copy/paste these buttons from the layouts in the fmEcommerce Link file.

Once you can successfully send a signing request, download the completed PDF file and Form Data you are ready to go live.

fmurlscript Extended Privileges and fmp URLs

fmESignature Link uses a Web Viewer and fmp urls as part of the authentication process with the DocuSign API so you will need to enable the fmurlscript Extended Privilege for any required Privilege Sets in your FileMaker solution that you are integrating with:

If you have multiple versions of FileMaker Pro installed it will attempt to use the last version of FileMaker Pro/Pro Advanced that was installed when opening the fmp url. The FileMaker 18 Platform now allows version specific fmp urls (e.g. fmp18://) which you can take advantage of if all your users will be using v18.

We’ve seen issues with FileMaker Pro v17 opening fmp urls with FileMaker Pro v16, particularly on the macOS platform. We’ve had success using a free 3rd party tool called RCDefaultApp which can be downloaded here:

Switch to DocuSign Production Environment (Go Live) – once you’ve completed the setup/testing phase in the Sandbox environment and are ready to switch to the live Production environment you will need to promote your integration key from your developer (demo) account to a production DocuSign account. This involves Requesting a go-live review in eSignature Admin and updating the fmESignature Link settings with the Production Integration App details.

Further details on the go live process can be found here in our FAQ article:

DocuSign Integration Go Live Process