Web Services Example Part 5 – DocuSign Integration

It is about time to continue the web services series. This time I want to focus at integrating with DocuSign, a service to send and sign documents electronically. Documents are stored in the cloud and can easily be managed with the DocuSign portal.

First of all one might ask why DocuSign is a useful web service for Dynamics NAV. The answer is simple, it’s useful if signed documents is part of the process in your solution. Possible scenario’s are: sign sales quotes or order confirmations, shipping documents, timesheets, used materials sheets, etc. I’m pretty sure that you can add more scenario’s.

DocuSign intro

There is a lot of information available on the DocuSign website about plans and pricing. However, these plans do not allow you to use the web service API. Documents need to be sent manually through the DocuSign website. To get access to the DocuSign API you need to buy an API Plan. This is different from what I knew at the time of NAV Techdays 2015 when I demonstrated this integration. It appears that the pricing plan was changed just one day before NAV Techdays 2015 started!

The demo code that I share with you is a basic integration for sending out a sales order confirmation for digitally signing by the customer. That should fit in the Start-Up API. You should also be aware of the fact the your integration needs to go through a certification process before it can use the production API. That looks somewhat bureaucratic, but it proves that DocuSign take security seriously.

To first test and explore the DocuSign integration, you can signup for a free developer sandbox. This is an account that uses the DocuSign demo environment and has access to all features, up to Enterprise level and it does not expire. Also, this account cannot be used for any legal binding purposes. Last, but not least, there is a complete developer center where you can access all resources that you might need when you create an integration.

The process

The basic process for DocuSign is to send a document for signature. The flow of this basic process is explained on this page. From here you can see that there are a number of terms that play a role in the process:

• Envelope
• Document
• Tab
• Recipient

You can read more about these terms on this page.

And of course the DocuSign web service API plays a central role in this process. So let’s look at the web service itself.

The web service API

The DocuSign web service is available with both SOAP and REST API. If you want to stay completely independent of any external component, except the .Net Framework, you could try to learn the REST API. However, I recommend to make use of the C# SDK that can be downloaded from this project at GitHub: https://github.com/docusign/docuSign-csharp-client

The example code below makes use of the dll’s from this GitHub project. You could either follow the normal GitHub process to pull the package by using the NuGet Package Manager in Visual Studio. The NuGet package site can be found here: https://www.nuget.org/packages/DocuSign.eSign.dll/. After installing the package in your Visual Studio project, you can copy the dll’s to the NAV Add-ins folder.

Alternatively, if you want to download the dll’s directly, use the Download link on the NuGet site. This will download a .nupkg file to your local computer. Unblock the file (right click –> properties –> check Unblock –> Ok) and then simply unzip the file. E.g. use 7-Zip for this purpose. After unzipping, go to \bin\Debug folder and copy all .dll files to the NAV Add-ins folder. You will end up with three dll files:

• DocuSign.eSign.dll
• Newtonsoft.Json.dll
• RestSharp.dll

Now with these files you can call the DocuSign web service API without the hassle of juggling around with all individual REST web services calls and converting the JSON results to strong typed objects.

The code

The first time I published this web service example, the code was different. The reason is that the used SDK has been updated to a new version. So I decided to rewrite, and also restructure, the code example. And this time I had a good C# example that I could translate into C/AL code. The C# example code can be found here: https://www.docusign.com/developer-center/recipes/request-a-signature-via-email.

The complete code can be downloaded here: https://github.com/ajkauffmann/DynamicsNAV (Yes, I did join GitHub, let’s see where this ends…)

After downloading the objects (and probably renumbering them, if needed) you can open the DocuSign setup page via the Service Connections page. No Menusuite needed. To enable this, I used the Discovery Event pattern as explained on Waldo’s blog: http://www.waldo.be/2016/03/02/discovery-event-pattern/. And again (like the SMS web service example), the setup table uses this pattern for secure storing passwords.

The example code uses an event subscription on the action ‘Email Confirmation’ on the Sales Order page (Page 42) and Sales Order List (Page 9305). To bypass the normal behavior of this action, the code uses the OnBeforeActionEvent and runs its own code. Then, before returning to the action code, an ERROR(‘’) is used, so the execution stops. If anything was modified in the database, a COMMIT must also be used.

I do not consider this as a best practice, it is only used to create an example that does not modify any object. Yes, I could deliver the example code as an Extension, but hey, it’s just an example…

Function RequestSign in Codeunit 60010 DocuSign Management controls the process. The first step

First, the code tries to log in at the web service. Notice that TryFunction is used for the LoginApi function. This allows to catch a .Net error and handle it.

The Configuration object that is passed to the LoginApi function is important. It will be used in the final call to the web service when sending the envelope.

After logging in, the next steps are performed:

• Create envelope
• Add the PDF document to the envelope
• Add a recipient to sign the document
• Create a tab on the document
• Add the signer to the envelope

Now the envelope is ready to be sent to the recipient. Setting the status to ‘sent’ results in immediately sending the document after creating it with the web service API.

The result

After clicking on the Email Confirmation the document is sent to the recipient. The web service API returns an envelope id. This id can be used for subsequent web service calls to retrieve the status of the document and eventually to download the signed document. The example code only displays the envelope id. No code was created to manage to complete process up to the download of the signed document.

The recipient receives an email that asks him to review the document.

And here is the signed document:

Well, that’s it. I hope it can help somebody to get up and running with a DocuSign integration.