During the Microsoft Build 2018 conference, I presented to an audience of 70+ developers, along with my colleague Mihaela Cristina Cris, on how to integrate the DocuSign eSignature API into the Microsoft technology stack. We showed how to create a .NET console app to send a DocuSign envelope using our C# SDK. We also showed how to create a simple webhook listener with an Azure function to send DocuSign Connect messages when the envelope status changed. Finally, we showed how to download completed (signed) documents, again using the DocuSign C# SDK, and optionally uploading them into a SharePoint document library.
Ready: Preparing for the demo
In this blog post, we document what we showed at Microsoft Build 2018 so you can follow the steps from A-Z to setup and run the code yourself. We also made the code available in a GitHub repo here. If you have any questions about this demo or if you have any suggestions about other content you’d like to see, please email me at tony dot mann at docusign dot com (trying to avoid SPAM bots ?) or create a comment at the bottom of this post. Note that we don’t show you how to create a SharePoint document library. Uploading completed envelopes into a SharePoint document library is optional.
Set: Setting up the demo
In this section, we show you how to setup your environment. There are three different pieces to setup, each of which we cover in this blog:
- Microsoft Azure
- Microsoft Visual Studio
Within your DocuSign account, there are three tasks you’ll perform. First you’ll create a sandbox account and configure your app with an integrator key and other authorization parameters. Then you’ll authorize your account to use the integrator key as a service integration with a one-time approval. You’ll upload a document as a reusable template, then finally configure DocuSign Connect with webhook parameters so you can monitor envelope status.
Creating and configuring a sandbox account
To begin, you create and setup your DocuSign account, as outlined in the following steps:
- Create a DocuSign sandbox account.
The first thing you’ll need is a DocuSign sandbox account. If you already have one, you can skip this step. In a sandbox account (also called a demo account), you can tryout all DocuSign features, including our eSignature API. We don’t ask for a credit card number and your account never expires. The only caveat is that you can’t use a sandbox account for legally-binding documents. In fact all documents sent from a sandbox account have a watermark indicating as such. To create a sandbox account, click here and simply follow the instructions – It’s very straightforward.
- Create and configure an integrator key.
An integrator key is needed for developing with any of our APIs. When you configure an integrator key, you also specify the security keys and passwords that your app will use during the OAuth2 authentication flow process. Here are the steps to create an integrator key:
- Login to your sandbox account that you created in step #1.
- Click your picture icon on the top-right, then click Go to Admin. The Admin dashboard appears.
- Scroll down to INTEGRATIONS section and click API and Keys.
- In the My Integrator Keys section, click the ADD INTEGRATOR KEY button.
- Enter the name of your app in the App Description field. For this example, we entered MSBuild2018Demo, like this:
- Click the ADD button, which creates a unique integrator key (32-byte GUID) value, assigns it to your App Description in your account, and also expands the screen to prompt for additional configuration information, like this:
- For this post, we show you how to use JWT authentication, which is typically used for service integrations, but there are other types of authentication you can use, based on your scenario and use-cases. You can review those scenarios in our Developer Center in the REST API Authentication Overview topic. For JWT authentication, you won’t need a secret key, but you will need a redirect URI and an RSA keypair.Note: This example assumes you will grant individual user consent to use an account, but if your account administrator grants consent for your app at the organization level (known as Org Admin), you won’t need a redirect URI.
- Click the ADD URI button and enter the redirect URI for your application. In an OAuth Authorization Code or Implicit Grant flow, the redirect URI is used on the initial request to the DocuSign authentication server to verify the URI is authorized. For this example, we simply entered https://www.docusign.com.
- Click the ADD RSA KEYPAIR button. This automatically generates a private and public key pair. Copy both of these keys to a file because, for security reasons, you won’t be able to view these again. For this example, you’ll only need the private key though. You’ll store the private key a file named PrivateKey.txt file that will be referenced in your Visual Studio C# code. Click OK to return to the Edit API Integrator screen. Here’s what it looks like after you configure your app:
- Click the SAVE button and your app/integrator key will be updated and placed onto your dashboard, like this:
Your app and integrator key is now configured in your DocuSign account.
Granting user consent: authorizing your app to use your account
After creating the required parameters for your app, including integrator key, redirect URI, and an RSA key pair, you need to perform a one-time authorization for your app to use your login credentials as a service integration, known as granting user consent. This is a very simple operation whereby you enter a specific URL into your browser and you’ll be prompted to login to authorize the app by following these steps:
- Open a web browser and paste this URL into the address bar:
where you substitute these values:
- <ik> is the integrator key you created earlier in this blog post.
- <uri> is the redirect URI you created earlier in this blog post.
- If your integrator key and redirect URI values are correct, you’ll be prompted to authorize consent, like this:
- Click the ACCEPT button and if you are not already logged into the account requesting permission, you’ll be prompted to do so.
Creating a DocuSign template
DocuSign templates are used when you are going to send the same set documents (with different field values) many times. A template can start with virtually any type of content – a Word document, image file, PDF, or virtually anything else. For this example, you’ll upload a Word document and store it as a template. It takes only a few minutes, by following these steps:
- Login to your sandbox account.
- On the top menu, click TEMPLATES.
- Click the yellow New button, then Create Template.
- Give your template a name. For this example, we used MSBuild2018 Template.
- In the Add Documents to the Envelope section, click the Upload button.
- Navigate to a file you want to upload as a template. If you want to follow this example, we’ve included a file named AgreementSample.docx in the GitHub repo code.
- In the Add Recipients to the Envelope section, you must enter at least one recipient. Since the template will be reused and the email address will be different each time, simply enter a generic role name that you will refer to in your code. For this example, simply enter Signer in the Role field and leave Name and Email blank.
- Click the yellow Next button at the top of the screen. This brings up what we call the tagger. This screen is where you tag your document/template with the locations on the document that will contain DocuSign fields.
- Drag a Date Signed, Name, and Signature field onto the document so it looks like this:
- Click the yellow SAVE AND CLOSE button. Your template is saved to the list of templates on your My Templates screen.
- Open your template again by clicking the name.
- Next to the name of your template, click the small (i) link. This brings up the Template ID, which you will need in your code. Here’s what it looks like:
- Click the Copy link and save your Template ID. This doesn’t need to be in a file like the private key did, but you will need it in your C# code.
Configuring DocuSign Connect
DocuSign Connect is the name of our webhook product that sends notifications upon change in envelope status. You configure the URL listener address where DocuSign sends messages, as well as which specific messages to send. You’re going to be amazed how simple that is by following these steps:
- Log into your sandbox account.
- Click your picture icon on the top-right, then click Go to Admin. The Admin dashboard appears.
- Scroll down to INTEGRATIONS section and click Connect. You’ll see a list of DocuSign Connect configurations.
- If your account shows the Connect Not Enabled message, click the ENABLE CONNECT button.
- Click the ADD CONFIGURATION button, then Custom.
- In the Name field, give your Connect configuration a name that indicates what this configuration is for. In this example, we use the name MSBuild2018 Azure Webhook.
- In the URL to Publish field, enter the full web address of your webhook listener. If you are following this example, this address will be the URL of your Azure function webhook listener, which we show you later in this blog. Note that this must be an SSL (HTTPS) connection. If you don’t know the address of your webhook listener yet, can just save your configuration with a placeholder address, such as https://TODO-Later, but you’ll have to edit this Connect configuration when you know the URL after you create your Azure function later in this blog post.
- Scroll down to the bottom of the screen and select which events will trigger the webhook notification. For this example, we selected Envelope Sent (which sends a notification when your C# code sends an envelope using the CreateEnvelope SDK method) and Envelope Signed/Completed (which sends a notification when the user signs the document in the envelope you send). You can also configure DocuSign Connect to send Document PDF (the completed documents) and the Certificate of Completion (the audit trail) in the payload schema, but that’s not included in this demo.
- Click the ADD button and your custom Connect configuration will be saved and your dashboard will be updated, like this:
In the demo, we used an Azure function to show how easy it is to create a webhook listener. If you don’t have an Azure account, you can create a free Azure account. Here’s how simple it is to create an Azure function webhook listener:
- Login to your Azure account at https://portal.azure.com.
- Click the + (Create a resource) sign and select Serverless Function App, as shown here:
- When creating an Azure resource for the first time, it can be a little daunting. There are many options, including specifying your app name, subscription, resource group, hosting plan, location, storage, and application insights location. The good news is that for a demo, the only thing you really need to think about is the name of your app. The rest of the information can simply use the default values presented by the Azure wizard. However, there are a couple of things to note:
- If you are going to use the Azure function for anything other than a test or demonstration, you’ll need to think about resource groups, storage locations, etc. because this can affect your usage charges. New free Azure accounts are given a $200 credit (in the US anyway) at the time of this writing, which is more than enough credit to do demos and testing.
- The name of the app winds up being the base URL your function’s public address will use, so it has to be unique, meaning that no other Azure users have selected it. The URL will be in the format of https://<uniqueapp>.azurewebsites.net. The Azure wizard will let you know if your selected name is not unique. Here’s what that looks like:
- After you select a unique app name, click the Create button. This creates a function app that serves as a container for an Azure function, but didn’t actually create the function itself. I’ll show you how to do that shortly.For our example, surprisingly, MSBuild2018Demo was available for our app name, so we grabbed it, which makes our base URL https://msbuild2018demo.azurewebsites.net. It will take a few minutes for your function app to be created and deployed to your Azure account. Note that Azure automatically converts all public URLs to lower case.
Important Note: You won’t be able to test your Connect configuration with our function app above. You’ll have to create your own.
- Refresh your Azure dashboard and look for your new function (which is listed as an App Service) with the lightning bolt icon, like this:
- Click your app service name to show a screen that looks like this:
- Move your mouse over the Functions menu. You’ll see a + icon to create a new function. Click the + icon to bring up a wizard to help you create your function. Click Custom function, as shown here:
- A list of function templates appears. Scroll down to locate Generic webhook and click the C# link, like this:
- In the Name field, enter the name of your function. Since this function will be created within the previously created function app, it should have a specific purpose and be named accordingly. For example, we named our function DocuSignConnectWebhook, as shown here:
- Click the Create button. Your function is created with default code. This is how your function should look in the Azure portal at this point:
- At the top of the function screen, click the </> Get function URL link, which presents a small dialog box that gives you the web address of your Azure function within the function app.
- In the Key dropdown, select default (Host key) and click Copy, like this:
- Navigate back to your DocuSign Connect configuration and paste the function URL into the URL to Publish field to replace the previous placeholder value of https://TODO-Later.
- Replace the default Azure function code with the code from the AzureFunctionCode.txt file in the GitHub repo source code for this example.
- Your Azure function should now look like this:
- Click the Save button to save your Azure function code.
- Click the Integrate menu under your Azure function name.
- In the HTTP trigger section, select Standard from the Mode dropdown list. If you don’t do this, the webhook listener will expect the input format to be JSON, but DocuSign Connect sends messages in XML format, which is allowed in Standard mode. Here’s what your screen should look like:
- Click the Save button to save your changes.
- Click the name of your Azure function again.
- On the right-hand part of the screen, click the Test tab. By default, when you create an Azure function, a default JSON structure with sample data is placed in the Request body field that you can use to test your Azure function code. This default JSON structure is not valid as a DocuSign Connect payload. In the GitHub repo source code for this blog post example, copy the contents of the AzureFunctionTest.txt file paste it into the Request body field (making sure that you completely overwrite the prior value in all lines), like this:
- Click the Run button and verify in the log section at the bottom of the screen that you have no errors and you see an EnvelopeID value of all zeros and a Status of Sent. This means that the test XML (which contains these values) was successfully sent through Azure function, but remember this was just a test within the function. The message did not come from DocuSign Connect yet – you’ll do that later in the section Go: Running the Example later in this blog post. Your screen should look like this if you successfully ran the test:
Microsoft Visual Studio
For the Visual Studio code in C#, you don’t need to do very much to run this example. The solution, named MSBuild2018.sln which includes a single project named MSBuild2018.csproj, contains all references and code you’ll need to run the project (assuming you setup everything according to this blog post). Here are a few things you need to do:
- If you don’t already have it, install Visual Studio 2017. For the demo we showed at Microsoft Build, we used Visual Studio 2017 Community Edition, which is free. You can download it here.
- Download the sample code for this blog post in the GitHub repo here.
- Open the PrivateKey.txt file and replace the contents with the private key info when you created your integrator key in the Creating and Configuring a Sandbox Account section earlier in this blog post. Make sure you include the BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY lines in the file.
- Open the App.config file and replace the following values (noted with the ReplaceMe placeholder) with those from your account:
DocuSign developer account configuration
- UserID – The API Username value from your DocuSign sandbox/developer account in the API and Keys section. Note that this value also shows the email address you used when you created your account, but the value you need is the 32-byte GUID.
- IntegratorKey – Integrator key value generated when you configured your DocuSign app in the Creating and Configuring a Sandbox Account section of this blog post.
DocuSign envelope configuration
- TemplateID – Template ID value that you created in the Creating a DocuSign Template section of this blog post.
- RecipientEmail – Enter an email address of the recipient who should receive the document to sign.
SharePoint configuration (optional)
- ShowSharePointDemo – If this value is false (default), running the C# code will not upload completed documents to SharePoint, but it will if the value is true.
- SiteUrl – URL of your SharePoint site.
- TargetLibrary – Target document library in your SharePoint site that will receive download DocuSign envelopes.
- UserName – User name that has permission to write to the target document library.
- Password – Password for the account that has permission to write to the target document library.
- After supplying the configuration values above, you are ready to run the example in the next section.
Go: Running the example
After you setup your DocuSign account, configure your app (integrator key), create a template, download the code for this example, and configure it, you’re ready to run it. To run the example, here’s what you do:
- Within Visual Studio, click the Start button or press F5 to run the app. Assuming you didn’t omit any steps earlier in this blog, you should see a console app that lets you know each step along the way.
- If you have enabled the SharePoint demo (by setting the ShowSharePointDemo flag to true), the first thing that happens when you run the code is that a DocuSign envelope is created and sends a document based on the stored template for signature to the email address indicated in the SenderEmail configuration parameter. The console app pauses while you wait for the recipient to sign the document. It looks like this:
- Sign the email.
- Press any key on the console app to continue with uploading the completed document to the SharePoint document library specified in your SharePoint configuration earlier. If there are no errors, your console app will look like this:
- Login to your SharePoint site and navigate to your document library to see that the C# code created a new folder with the same name as the Envelope ID. Inside that folder are two documents – the completed (signed) document and a certificate of completion, which is an audit trail of the entire transaction. The SharePoint document library looks like this:
- If you don’t have the SharePoint demo enabled (by setting the ShowSharePointDemo flag to false), the console app ends at step #2 above.
Extending the example
This example is only the beginning. It was intended to get you started with a bunch of technologies in the Microsoft stack, but it was primarily geared towards showing you how to use our eSignature API with our C# SDK.
You could also extend this example, by configuring DocuSign Connect to send the completed PDFs and Certificate of Completion in the webhook payload. You could parse the stream and store the documents wherever you’d like. Note that if your documents are large, this may not always be best way to download documents.
The code can certainly be made more robust with exception handling, etc. You can also extend this by instead of pausing the console app and you indicating when a document is signed, you could move the code into the Azure function to automatically continue with the workflow when the envelope is completed. This is a little more involved because you’d have to sideload the DocuSign DLL into Microsoft Azure. We showed the pausing because it’s more controllable in a demo situation ?.
Come see us and learn more at our upcoming annual customer conference, called Momentum, in San Francisco from June 20-21, 2018 or extend the example from this blog post and enter our Momentum Hackathon from June 9-10, 2018.