I’ve been using SharePoint 2013 to digitally sign documents with DocuSign. In this article I’m describing how DocuSign works and how to implement a Nintex workflow in SharePoint to get your documents digitally signed.
DocuSign Introduction
Table of Contents
The important terms to get familiar with first:
Envelope – This represents a package used to mail documents to recipients. The envelope carries information about the sender and timestamps to indicate the progress of the delivery procedure. It contains collections of Documents, Tabs and Recipients.
Document – A document that is to be delivered, representing the content to be reviewed and/or signed. Documents have names and are always base64 encoded while in the system.
Tab – This represents a DocuSign Tag (also known as a Stick-eTab®) on a document. It is used in several ways. First, it is used to indicate to a recipient where a signature or initials are required. Second, it is used to include various bits of information in a document in a manner similar to Form Fields or Macros. For example, a tab may automatically fill in the Company Name of a recipient when the document is signed. Third, it is used as editable information fields where signers can add data to a document.
Recipient – Someone who receives the envelope and, optionally signs and initials the documents where indicated by tabs.
Approaches
Implementing Digital Signatures in SharePoint I’ve looked at the following options:
- Using the DocuSign options, however this doesn’t give me the control over the workflow that I want.
- Using the out of the box Nintex actions that are available within Nintex Workflow.
- Using the DocuSign API
Nintex Actions
For simplicity reasons I’m keeping the workflow to the minimum here. My actual workflow has a lot of back and forth approval steps.
To make the DocuSign integration work I first include a send document action in my workflow.
Once the document is sent I’m checking for the current status of the envelop
Once the signing of the document is complete I download the signed PDF
The major floors that I found with this approach is that the envelops in Nintex are limited to one recipient.
Looking at the above Envelope definition that I found on the DocuSign website:
This represents a package used to mail documents to recipients.
As you can see in the Send documents settings Recipient email and Recipient name only expect one email address and name.
Luckily Nintex listens to their user base and has implemented their uservoice site. The item on this list for the issue can be found here: Nintex Uservoice
DocuSign API
The next appraoch is to call the DocuSign API directly from Nintex. DocuSign has a very advanced API.
There is a REST API and a SOAP API available.
In my example I’m using the SOAP API.
Within the Soap API there is a Web method available called CreateAndSendEnvelope. It is possible to split this up into two separate calls if that is preferred. In case it needs to be split up then use CreateEnvelop and SendEnvelop.
So In Nintex I’m creating a Web request action. (Not “Call a web service” action) and I’m connecting to /api/3.0/dsapi.asmx. Using a Call a web service action I’m collecting the right name of the method and the base Xml as the Web request action doesn’t give this to me.
To keep the Xml a bit simpler I’m actually deciding to split up the Create and Send of the Envelop.
The in my Web request action I’m completing the Soap action and setting it to CreateEnvelope
Ok, that is a big Xml to complete.
So first I simplified the Xml by taking all the options things out.
<?xml version=”1.0″ encoding=”utf-8″?>
<soap:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m=”http://www.docusign.net/API/3.0″>
<soap:Header>
</soap:Header>
<soap:Body>
<m:CreateEnvelope>
<m:Envelope>
<m:Asynchronous>true</m:Asynchronous>
<m:AccountId>d88698c8-7b58-4323-bfe6-d5dc970665f2</m:AccountId>
<m:Documents>
<m:Document>
<m:ID>{ItemProperty:ID}</m:ID>
<m:Name>{ItemProperty:Title}</m:Name>
<m:PDFBytes>{WorkflowVariable:base64Binary}</m:PDFBytes>
</m:Document>
</m:Documents>
<m:Recipients>
<m:Recipient>
<m:ID>1</m:ID>
<m:UserName>Pieter Veenstra</m:UserName>
<m:SignerName>Pieter Veenstra</m:SignerName>
<m:Email>pieter.veenstra@mycomp.co.uk</m:Email>
<m:Type>Signer</m:Type>
<m:RequireIDLookup>false</m:RequireIDLookup>
<m:DeliveryMethod>Email</m:DeliveryMethod>
</m:Recipient>
</m:Recipients>
<m:Tabs>
<m:Tab>
<m:DocumentID>{ItemProperty:ID}</m:DocumentID>
<m:RecipientID>1</m:RecipientID>
<m:PageNumber>1</m:PageNumber>
<m:XPosition>100</m:XPosition>
<m:YPosition>100</m:YPosition>
<m:Type>SignHere</m:Type>
</m:Tab>
</m:Tabs>
<m:Subject>This is the subject</m:Subject>
<m:EmailBlurb>This is the blurb</m:EmailBlurb>
</m:Envelope>
</m:CreateEnvelope>
</soap:Body>
</soap:Envelope>
Then within the Add Header action I’m adding a X-DocuSign-Authentication Header.
Leaving this header out would result in the following error:
User_Authentication_Failed – Missing authentication header
So What does this header look like? The header is some Xml which contains a username, a password and an integrator key. After you have setup a developer tenant for DocuSign you can generate the Integrator key. This is described in a DocuSign article
<DocuSignCredentials>
<Username>4b045690-bcef-4424-8d26-e0d23aa1130b</Username>
<Password>MySecretPassword</Password>
<IntegratorKey>92f767de-54d2-4dee-9566-5cbbafa2d385</IntegratorKey>
</DocuSignCredentials>
Well that is the first bit done. The envelope is created now we need to send this envelop to the recipients specified in the envelop xml.
No I need to get my EnvelopID, so that I can tell DocuSign which envelop to send. In the web request I can collect the result of the web call. I’m storing this in a variable called varResult.
The varResult now contains an Xml with the EnvelopeID hidden in it. The EnvelopeID can be found with the XPath (/soap:Envelope/soap:Body/defaultNS:CreateEnvelopeResponse/defaultNS:CreateEnvelopeResult/defaultNS:EnvelopeID)
Potential Issues
While I experimented with the above I found that I was able to send pdf files but word documents would fail with the following error message:
Error: the document is corrupt
To resolve this I had to add some more Xml:
<m:Document>
<m:ID>{ItemProperty:ID}</m:ID>
<m:Name>{ItemProperty:Title}</m:Name>
<m:PDFBytes>{WorkflowVariable:base64Binary}</m:PDFBytes>
<m:FileExtension>docx</m:FileExtension>
</m:Document>
Sending the envelop
To send the envelop I’m creating another Web request. I’m using the same authentication header again.
The Method to be used this time is SendEnvelope.
I’m also including the following Xml.
<?xml version=”1.0″ encoding=”utf-8″?>
<soap:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m=”http://www.docusign.net/API/3.0″>
<soap:Header>
</soap:Header>
<soap:Body>
<m:SendEnvelope>
<m:EnvelopeId>{WorkflowVariable:varEnvelopID}</m:EnvelopeId>
<m:AccountId>d88698c8-7b58-4323-bfe6-d5dc970665f2</m:AccountId>
</m:SendEnvelope>
</soap:Body>
</soap:Envelope>
And then the document is sent to my recipients. Then as a test I aded some more recipients and my problem has been resolved:
Hybrid Approach
As I’m only having a problem with the creation of the envelop it might be possible In the previous section to use the Send Envelop action that Nintex Workflow offers, however I have not tried that.