Quick Start: Signature Appliance Web Agent API

The DocuSign Signature Appliance Web Agent is the fastest and easiest way to add open, standard digital signatures to your application. Word, Excel, and PDF files can be signed in their native formats.

The DocuSign Signature Appliance Web Agent

The Web Agent API includes a full User Experience (UX) layer. The UX enables the user to preview and then sign the document.

Complete Signing Ceremony UI

The Web Agent provides a complete signing ceremony including choice of graphical signature appearance, signature details and more.

You can also enable the UX to provide the user with management features: update the user's graphical signatures, pre-set signing reasons and more.

Complete Signing Ceremony UI

The Web Agent provides a complete signing ceremony including choice of graphical signature appearance, signature details and more.

You can also enable the UX to provide the user with management features: update the user's graphical signatures, pre-set signing reasons and more.

Choosing a Signature Location

The Web Agent signing screen enables the signer to choose a pre-set signature location or, for PDF documents, use a drag and resize tool to set the signature location on the page.

Choosing a Signature Location

The Web Agent signing screen enables the signer to choose a pre-set signature location or, for PDF documents, use a drag and resize tool to set the signature location on the page.

Controlling the Web Agent

Your web app controls the Web Agent by sending requests and receiving responses via https. The requests and responses are sent in XML data format.

API Endpoints

The endpoint for development is https://webagentdev.arx.com/
For example, https://webagentdev.arx.com/Sign/UploadFileToSign

For production, you will host your own instance of the Web Agent.

Getting Started

Obtain a developer account

Sign up for a free DocuSign Signature Appliance Developer Sandbox account.

Check that your signing account was created by using the Developer Web App to sign a PDF.

Make a jpg scan of your signature and use the Developer Web App to upload it. Click on your name (upper right corner of the web screen) to upload your graphical signature.

Quick Start

It's easy to add the Web Agent to your web app. Use this guide, the Hello World examples, the API documentation, and our support team to quickly create a proof of concept and final product.

DocuSign hosts an instance of the Web Agent for developers. The service point url is https://webagentdev.arx.com/ You can immediately start signing by using your developer's account. Use your email as the user name.

Verifying Signatures: Trusting the signer's root certificate

The Web Agent itself supports signature verification. But it is more common for relying parties (recipients of signed documents) to use the free Adobe PDF Reader to verify signatures.

Software is not installed on client computers to enable signature verification. But the signer's root certificate does need to be trusted by the recipient computer’s local Adobe truststore. While DocuSign can use signer certificates whose root certs are already in the Adobe truststore, it is also common to use certificates that are not pre-trusted.

In a typical case, the signer's root certificate belongs to her organization and is not in the default Adobe truststore. For example, see this United States Department of Agriculture memo on adding their root certificate to the client PC's truststores.

Your developer account's signing certificate uses a root certificate issued by DocuSign. The easiest way to install the certificate in your Adobe and Microsoft truststores is to use CoSign Nation

  1. Open CoSign Nation
  2. Click "ARX CoSign Trial" to select its certificate.
  3. Click Download and fill in the form to download a small executable.
  4. The executable installs the certificate and configures Adobe to trust it.

Examples and the Web Agent Test App

Please click this page's Hello World tab (above) to see example web apps that sign PDF files using the Web Agent.

A Test App is also available. It enables you to quickly try out the effects of using different parameter values with the Web Agent.

Configuration information

The Web Agent is an ASP.net application. It requires a Windows server with IIS and HTTPS enabled. Each instance of the Web Agent can uses a DocuSign Signature Appliance to provide signing services. For developers, DocuSign hosts an instance of the Web Agent that is configured to use the DocuSign Signature Appliance used for developer accounts.

For production, customers install a DocuSign Signature Appliance and an instance of the Web Agent.

Design Patterns

This section provides additional information about integrating the Web Agent with your web app.

User Experience

The Web Agent provides a rich and smooth User Experience for your clients:

  1. Your web app prepares the PDF document to be signed.
  2. The user starts the signing process by clicking a "Sign" link or button on your web app.
  3. The user sees the authentication form and authenticates with the appliance
  4. The Web Agent displays a preview of the document. The user signs the document
  5. The user can sign the document again, or clicks the "Done" button
  6. Your web app receives the signed document from the Web Agent. Your web app processes the signed document as needed: filing it, mailing it, enabling it to be downloaded, etc.

In all cases, it is important that users should not need to press a "Continue" button or link after they have finished signing a document. Your web app should proactively present the next action screen to the user. If allowed by your web app, the Web Agent can also enable the user to manage his graphical signatures, and more.

Protocol Overview

The UX described above is implemented using the Web Agent protocol:

  1. User clicks a "Sign with DocuSign" link or button on your web app.
    • Your web app sends the Web Agent a UploadFileToSign request including the finishURL and the document to be signed. A sessionId is returned.
  2. Your web app then returns a redirect to the browser. The redirect's url is the Web Agent's url with the sessionId included as a query parameter.
    1. The user interacts with the Web Agent, previewing and signing the document
    2. The Web Agent redirects the user's browser to your web app's finishURL. The sessionId and returnCode are included in the query parameters
  3. Your web app should now do two actions: return a "Processing..." wait page to the user and retrieve the signed file from the Web Agent. There are several techniques available:
    • Recommended: Immediately return a "Processing..." page to the user. The page also includes an Ajax call back to your web app. Your web app retrieves the file from the Web Agent using the DownloadSignedFileG operation, and returns a "next_page_url" to the Ajax request. The Processing... page then loads the next_page_url page. Benefit: smoothest UI for the user.
    • Recommended: Immediately return a "Processing..." page to the user. The page also includes meta-level refresh to your web app. The server retrieves the file from the Web Agent, and returns the next page. Benefit: A good UI for the user but the issues of possibly starting the refresh before the "Processing" page's graphics have loaded need to be examined and tested.
    • Not recommended: Immediately return a web page to the user that enables him to click "Continue". The Continue page then retrieves the file from the Web Agent. Downside: Your web app will only be able to retrieve the signed file from the Web Agent if the user clicks the Continue button. This is a UI problem since it is reasonable for users to feel that they have signed the file when they pressed "Done" within the Web Agent--why do they need to press "Continue" to "complete" the signing? Note: some of the examples use this technique to simply demonstrate the Web Agent, but it is not recommended for a production system.
    • Not recommended: Immediately retrieve the file from the Web Agent, then return the next web page to the user. Downside: the user will not receive any interstitial feedback, just a wait, after clicking "Done" in the Web Agent's UI.
    • Not recommended: Fork a process to retrieve the file from the Web Agent. Simultaneously, return the next wep page to the user. Benefit: the signed file will always retrieved from the Web Agent. Downside: Need to re-synchronize the user's expectations with the background process--suppose the user wants to immediately see the signed file but it hasn't yet been fully fetched from the Web Agent?

Web Security

These days, it is always a good idea to use HTTPS/TLS. But it is not required for your web app since it does not need to handle the user's signing credentials. In all cases, your app will communicate with the Web Agent by using HTTPS and will redirect the user's browser to the Web Agent's HTTPS address for authentication. Your app does not need an HTTPS certificate for these purposes.

Maintaining State

Because your web app redirects to the Web Agent, your web app needs to maintain its state about the signer, the document being signed, etc. Several design patterns are available:

Cookie: Your web app can track its session state information by using a standard first party cookie. The Web Agent will not interfer with the cookie. Later, your app uses the cookie to retrieve the user's state.

FileID parameter: The Web Agent enables your web app to set a fileID value as part of the file upload. The fileID is later returned to your web app when the user is redirected to your app after signing. Your app can use the fileID to retrieve the user's state.

Redirect query parameter: Your web app sets the finishURL when it uploads the file to be signed. The finishURL can include your own query string values. Later, when the web app redirects the user to your app, it can use the query parameter to retrieve the user's state. Note that your app shouldn't use parameter names sessionId, docId or returnCode since the Web Agent sets those parameters.

iframe: Your web app can maintain state through use of the "containing" section of the web page while including the Web Agent within an iframe. Your app controls the containing page, so it can use your framework's usual techniques for maintaining state.

Hello World: Signing a PDF

The Hello World example enables the user to sign a PDF file. Source is available from GitHub: Node.JSASP.NET, and Ruby.

Instant demo! The Node.JS software can be deployed to Heroku using Heroku's free service tier. No credit card needed.

Introduction

Your web app will receive the end user's request to sign a document. Your app will create an XML Signing Request for the Web Agent and post it to the Web Agent. The XML request includes the file to be signed, using Base64 encoding.

Normally, the response to the signing request will include the success status code and a sessionID. The sessionID is used to re-direct the user's browser to the Web Agent server or to open an iframe to the location.

Posting the Signing Request

In file CSWADemo.aspx.cs, the CSWAConnectButton_Click method calls the PostXML method using the UploadFileToSign service point URL and the data. The data is sent in the format of key-value pair and the key must be "inputXML".

In the example, CSWAPath is the URL of the CSWA application and INPUT_XML_KEY is a constant name for "inputXML". Note that we also use UrlEncode to prevent the URL parser from misinterpreting an embedded "?, &" or other special characters.

// Sending a POST request to UploadDoc.aspx page with the XML. The parameter name is "inputXML"
string response = Helper.PostXML(Helper.CSWAPath + "Sign/UploadFileToSign", Helper.INPUT_XML_KEY + 
    "=" + Server.UrlEncode(inputXML));

// The received response is in the form of XML as well.
// If the request was handled successfully the response should include a success return code (0)
// and CSWA session ID
XmlDocument xml = new XmlDocument();
xml.LoadXml(response);
string returnCode = xml.DocumentElement.GetElementsByTagName("returnCode")[0].InnerText.Trim();
string sessionID = null;
if (xml.DocumentElement.GetElementsByTagName("sessionId").Count > 0) {
    sessionID = xml.DocumentElement.GetElementsByTagName("sessionId")[0].InnerText.Trim();
}

// If the return code is 0 and the session ID has returned in the response, we can now redirect 
// to the Signceremony service point with the sessionID parameter.
// In this example we set the "src" attribute of the IFrame to the URL.
if (returnCode == Helper.SUCCESS && !string.IsNullOrEmpty(sessionID)) {
    CSWAIFrame.Attributes["src"] = Helper.CSWAPath + "Sign/Signceremony" + "?sessionId=" + sessionID;
}

Retrieving the Signed File

After the user concludes his session with the Web Agent, it will re-direct the user's browser to your app. You set the finishURL in the XML sent with your Signing Request. The Web Agent will include get parameters for the sessionID, your docID, a return code and an optional error message. Your app uses the return code, sessionID and the DownloadSignedFileG service point to retrieve the signed file.

In this example, the web agent will redirect to retrieveSignedFile.aspx page. This page handles the "pulling" of the signed document.

First, the "Page_Load" method checks if the signing succeeded and if so, extracts the docId and sessionId parameters. Then it uses the "pullDoc" method to retrieve the signed file.

string docId = Request.QueryString["docId"];
string sessionId = Request.QueryString["sessionId"];

try
{
    // Empty Request (no docId parameter)
    if (string.IsNullOrEmpty(docId))
        throw new Exception("Missing parameters");

    // error was returned
    string retVal = Request.QueryString["returnCode"];
    if (retVal != null && retVal != "0")
    {
        // An error was received
        throw new Exception(Request.QueryString["errorMessage"]);
    }

    if (!string.IsNullOrEmpty(sessionId))
    {
        // Document was signed and needs to be retrieved.
        // Pull the signed document from the web agent
        string fileName = Helper.pullDoc(docId, sessionId);

        //update the text on the screen
        linkToDoc.InnerText = fileName;
        linkToDoc.HRef = fileName;
        LabelResultMessage.Text = "The document was successfully signed";
    }
    else
    {
        // Empty Request (no sessionId parameter)
        handleError("Missing parameters");
    }
}
catch (Exception ex)
{
    handleError(ex.Message);
}

File Helper.cs includes the pullDoc method

public static string pullDoc(string i_DocId, string i_SessionId)
{
    string docPath = null;

    string response = SendRequest(wscPath + "Sign/DownloadSignedFileG" + "?sessionId=" + i_SessionId, null, null, "GET");

    XmlDocument xml = new XmlDocument();
    xml.LoadXml(response);
    string returnCode = xml.DocumentElement.GetElementsByTagName("returnCode")[0].InnerText;

    if (returnCode != SUCCESS)
    {
        throw new Exception("Pull doc error: " + xml.DocumentElement.GetElementsByTagName("errorMessage")[0].InnerText);
    }

    if (xml.DocumentElement.GetElementsByTagName("Document").Count > 0)
    {
        string base64EncodedFile = xml.DocumentElement.GetElementsByTagName("content")[0].InnerText;
        string contentType = xml.DocumentElement.GetElementsByTagName("contentType")[0].InnerText;
        docPath = i_DocId + "." + contentType;
        File.WriteAllBytes(HttpContext.Current.Server.MapPath("~/" + docPath), Convert.FromBase64String(base64EncodedFile));
    }

    return docPath;
}