fmESignature Link (DocuSign Edition) Updated to Use Authorization Code Grant OAuth Flow

When we were originally developing v1.0 of fmESignature Link back in 2018/2019 one of the first decisions we had to make was which of the three OAuth Types we should choose for handling the authentication with the DocuSign API: JWT Grant, Authorization Code Grant or Implicit Grant. Each flow has its pros and cons and we eventually settled on using the JWT Grant OAuth Flow. The main advantage of using the JWT Grant is that it doesn’t require a user to be present after initially gaining consent. The downside to using the JWT Grant is that FileMaker Pro cannot natively generate the JWT (JSON Web Token) required as part of the flow in requesting the access token that you ultimately need.

We found a workaround using a FileMaker Web Viewer and a JavaScript function that we could pass parameters to which would generate the JWT and return that as a parameter to a FileMaker script called via the FMP URL protocol. The downside to using a FileMaker Web Viewer is that this cannot be performed as a FileMaker Server script (either via Perform Script on Server or as part of a script scheduled using the Admin Console). We created some PHP files that used either the Data API or the older PHP API to handle scripts that needed to run under FileMaker Server.

We were never 100% comfortable with using the Web Viewer and as more customers have deployed and integrated fmESignature Link over the past few years we have become aware of some further limitations with using this approach. We’ve had reports that the FMP URL script wasn’t firing all the time, particularly on Windows and iOS. Troubleshooting these is particularly challenging and we often struggled to reproduce them in our own testing. Another downside to the Web Viewer approach concerned when the FMP URL script would run if you had a long running FileMaker script that you wished to incorporate the sending of a request to DocuSign. You couldn’t always control when the FMP URL script would run – at least until FileMaker Pro 19.1.3 was released. As we support all versions of FileMaker Pro from v16 onwards we couldn’t rely on this either. On Windows the script we wanted to run immediately after the Web Viewer loaded was added to the end of the FileMaker script stack and would run when the currently running FileMaker script finished, by which time the context had changed and it was too late for our script!

After implementing a similar version of the Authorization Code Grant OAuth Flow for our fmAccounting Link (Xero Edition) solution in 2019 we became convinced that this would ultimately be a much better experience for our fmESignature Link (DocuSign Edition) solution as well. It would require the user to perform an initial approval inside of the fmESignature Link file but after that we can programatically refresh the tokens without user intervention. This can also be setup a server schedule so that the token is refresh daily/weekly etc so that it will never expire.

We’ve just released v1.4 of fmESignature Link which now uses the Authorization Code Grant OAuth Flow instead of the JWT Grant OAuth Flow. If you’re currently using fmESignature Link v1.36 or earlier and everything is working well for you there’s no need to rush out and change anything here. You can continue to use the JWT Grant OAuth Flow if it’s working well for you.

If you have encountered some of the issues described above and would like to simplify the authentication and remove the dependency on the Web Viewer then you can update your existing integration using the latest version of the fmESignature Link file. We’ve put together a number of new and updated support articles to assist you with this process:

fmESignature Link (DocuSign Edition) Getting Started Guide

Authorization Code Grant OAuth Flow Setup Video

Authorization Code Grant OAuth Flow Details

Converting from the JWT Grant to the Authorization Code Grant OAuth Flow

All of the changes can be copied across from the v1.4 file into integrations using earlier versions of fmESignature Link and the process should generally take around 30 minutes to complete. In addition to the new fields, scripts and layout that you can copy across you only need to update two existing FileMaker scripts and one existing FileMaker layout. We’ve tried to keep these changes to a minimum and none of the scripts that send requests to the DocuSign API will need to be updated.

Other Changes in v1.4

In addition to the Authorization Code Grant OAuth Flow changes outlined above we’ve also include some new features in this release, including:

• added support for PDF Form Fields transformation and a new Template Example for this
• added support for Radio Group Tabs
• updated Webhooks to use JSON notifications for the the eventNotification webhook (change from XML)

The full list of changes are listed in the version history notes here. Existing customers can download this version from the link on your original order email (contact us if you need the link to be reset etc).

Now that we have the Authorization Code Grant OAuth Flow changes out of the way we are working on adding support for SMS Notifications to fmESignature Link and hope to have this released shortly.