This Getting Started Guide demonstrates how to use the fmESignature Link (DocuSign Edition) file and connect it to your DocuSign account (sandbox or production). The fmESignature Link (DocuSign Edition) file currently includes the following examples:
- Send Document Signing Requests: you can use fmESignature Link to send documents that are generated dynamically from a FileMaker layout, from a PDF file stored in a FileMaker container field, or using a DocuSign Template (including support for multiple recipients and roles)
- Pre-populate custom fields: you can pre-populate custom fields with data from your FileMaker solution or use a hardcoded value for all recipients
- Download Completed Documents: download the completed document once all parties have signed
- Document Templates: store document templates and attached tabs to capture signatures, initials, dates and text from recipients (these can be generated dynamically from a FileMaker layout, from a PDF file stored in a FileMaker container field, or using a DocuSign Template).
- Auto Place (anchor tagging): use the Auto Place feature which automatically adds fields near each occurrence of a given string in a template or document
- Download DocuSign Template Tabs and Roles: you can download Tabs and Roles for DocuSign Templates at the click of a button
- Envelope Status: check the current Status of a sent signing request
- Download Form Data: download the completed form data for each recipient
- FileMaker Server Schedules: setup FileMaker Server Schedules to poll DocuSign every 20 minutes for any new completed agreements (requires FileMaker Server and PHP Custom Web Publishing)
- Webhooks: have completed PDFs pushed automatically to FileMaker within seconds of being completed (requires FileMaker Server and either the FileMaker Data API or PHP Custom Web Publishing). See the fmESignature Link (DocuSign Edition) Webhooks page for further details.
We are continually updating the fmESignature Link (DocuSign Edition) file to include additional examples. If you would like to see an example for other features supported by the DocuSign API please let us know.
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:
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:
The DocuSign eSignature Glossary is also a handy reference if you’re not familiar with the common terms (envelope, tab, template etc):
DocuSign Sandbox Setup
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:
- create your DocuSign Sandbox account
- create a new API and Integration Keys in the Sandbox
- 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. 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 Go To Admin from the profile menu in the top right hand corner:
Your API Username can be found by selecting Users from the left hand menu then click on your username in the list and your API Username should appear in the top right corner. Copy and paste this into the API Username field in the Sandbox Preferences.
On the lower left side of the Admin Console select API and Keys to create a new set of API keys. The API Account ID will be generated automatically by DocuSign. Copy and paste this into the API Account ID field in the Sandbox Preferences
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 – for some of the information you will only get one chance to record this (you can always delete the integration and create a new one if this happens) so be careful as you record the information.
Integration Key: this is generated automatically by DocuSign. Copy and paste this into the Integrator Key field in the Sandbox Preferences
Authentication: select Authorization Code Grant (should already be set as the default)
RSA Keypairs: click the Add RSA Keypair button to generate a Public and Private Key. Record these somewhere safe as they are only visible once upon creation. Copy and paste the Private Key into the Private Key field in the Sandbox Preferences
Additional Settings: Redirect URIs: add the following URI: https://docusign.com
Click Save when you have finished. We now need to perform a one time
Once you’ve created your API keys and entered these into the Setup screen in the fmESignature Link file you need to then get consent to allow the fmESignature Link file to make API calls on behalf of a user. To allow fmESignature Link to impersonate a user via API calls click the Request Application Consent button – it will open your web browser and redirect you to a page like this where you can grant consent:
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.
- 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
- 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
- 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 you will see the following screen appear:
fmESignature Link uses the JSON Web Token (JWT) Grant authentication method – 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
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
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. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of Value Lists so these will need to be recreated manually:
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: 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 you need to first send 20 successful contracts from the Sandbox environment.
Once these have been successfully sent and completed you can then apply for a review and move your API from the sandbox to a production account. Further details on the go live process can be found here:
DocuSign API – Go Live Process FAQ
There is also a helpful video series covering the Go Live Process on YouTube
Version History – to see what’s new with each update check out the version history log
