Using DocuSign with Codenvy


Use Codenvy Factory to instantly start working with a sample DocuSign API project:


This tutorial will explain the details of integrating the DocuSign API into Codenvy. DocuSign API provides various functions to obtain e-signature on your documents. The explanation has been done with a very basic Java project that makes use of the DocuSign API and XML APIs to explain the basic features provided by the API.

Register With DocuSign

Before proceeding to the creation of the Java project, please register at http://www.docusign.com/developer-center with your email id and this will generate keys which will be used for the integration(please click on the ‘Get a Free Dev Account’ button:
docusign-signup

On registering the application, you can generate and see your keys by logging into https://demo.docusign.net/MEMBER/MemberLogin.aspx and then going to the ‘Preferences/API’ section:
docusign-keys

To assist the integration with the different methods of DocuSign API, the DocuSign API has a Quick Start section at http://www.docusign.com/developer-center/quick-start/overview and API Tools section at http://www.docusign.com/developer-center/quick-start/api-explorer which will give you information of the methods and their input parameters that are needed to get the desired output out of them and the return values. The API Tools section is divided into 2 sub-sections -
a) API Explorer at http://iodocs.docusign.com/ which provides an interactive method of providing inputs and getting the desired output thereby getting the request and response calls
b) API Walkthroughs at http://iodocs.docusign.com/apiwalkthroughs which will give code snippets to perform various API functions such as Requesting Signature from Pre Defined Templates and from a normal document:

docusign-apiwalkthrough1

docusign-apiwalkthrough2

We will use the example to request a signature from a pre-defined template created within your DocuSign account. The template can be created at the ‘Manage’ section of your account:

docusign-createtemplate

You will get a template id which will be used in the code and within the template you can upload your document that needs to be signed and the recipient email ids who need to sign that document.

Create a Project

Now, login to your Codenvy workspace and create a WAR project named as ‘DocusignSample’. This will have the following structure:
docusign-structure

Create pom.xml File

To make use of the DocuSign API as a Java project through XML APIs, please update the pom.xml to include the jaxp-api jar into your project as Maven dependencies:

  <dependencies>
    <dependency>
      <groupId>javax.xml</groupId>
      <artifactId>jaxp-api</artifactId>
      <version>1.4.2</version>
    </dependency>
  </dependencies>

  <repositories>
     <repository>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <id>central</id>
      <name>Maven Repository Switchboard</name>
      <url>http://repo1.maven.org/maven2</url>
     </repository>
  </repositories>

Create Java Class

Now create a Java class named DocusignSample.java that will talk to the DocuSign website with the Http request URL to first get a login information(containing the account id and base url to make the signature request) using the account user id, password and api key and then will talk to the Docusign website again with the template id to send the document for eSignature to the recipients defined in the template. All this is done inside the method process() in the sample source Java class. The parsing of the XML request and response from each API call is done using the XML Java APIs.

	public static void process() throws Exception
	{

		HttpURLConnection conn = null;		// connection object used for each request
		String url = "";			// end-point for each api call
		String body = "";			// request body
		String response = "";			// response body
		int status;				// response status

		//============================================================================
		// STEP 1 - Login API Call
		//============================================================================

		url = "https://demo.docusign.net/restapi/v2/login_information";
		body = "";	// no request body for the login call

		// create connection object, set request method, add request headers
		conn = InitializeRequest(url, "GET", body);

		// send the request
		System.out.println("Sending Login request...\n");
		status = conn.getResponseCode();
		if( status != 200 )	// 200 = OK
		{
			errorParse(conn, status);
			return;
		}

		// obtain baseUrl and accountId values from response body
		response = getResponseBody(conn);
		baseURL = parseXMLBody(response, "baseUrl");
		accountId = parseXMLBody(response, "accountId");
		System.out.println("-- Login response --\n\n" + prettyFormat(response, 2) + "\n");

		//============================================================================
		// STEP 2 - Signature Request from Template API Call
		//============================================================================

		url = baseURL + "/envelopes";	// append "/envelopes" to baseUrl for signature request call

		// this example uses XML formatted requests, JSON format is also accepted
		body = "<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">" +
				"<accountId>" + accountId + "</accountId>" +
				"<status>sent</status>" + 	// "sent" to send envelope, "created" to save as draft envelope
				"<emailSubject>DocuSign API Call - Signature request from template</emailSubject>" +
				"<templateId>" + templateId + "</templateId>" +
				"<templateRoles>" +
				"<templateRole>" +
				"<email>" + email + "</email>" +
				"<name>" + recipientName + "</name>" +
				"<roleName>" + roleName + "</roleName>" +
				"</templateRole>" +
				"</templateRoles>" +
				"</envelopeDefinition>";

		// re-use connection object for second request...
		conn = InitializeRequest(url, "POST", body);

		System.out.println("Sending signature request from template...\n");
		status = conn.getResponseCode(); // triggers the request
		if( status != 201 )	// 201 = Created
		{
			errorParse(conn, status);
			return;
		}

		// obtain envelopeId value from response body
		response = getResponseBody(conn);
		envelopeId = parseXMLBody(response, "envelopeId");
		System.out.println("-- Signature Request response --\n\n" + prettyFormat(response, 2));
		System.out.println("Signature request has been sent to " + email  + "!\n");
	}

There are other private methods in the Java class that support the process() method.

Create index.jsp File

Your Codenvy project will have an index.jsp which will invoke the Java class -

<%
    com.codenvy.DocusignSample docusignSample = new com.codenvy.DocusignSample();
    docusignSample.process();
%>

Now you build and run your Codenvy project and then the recipient of the template Ids will receive an email from Docusign containing the document for eSignature.

You can see the request being sent in your account dashboard:

docusign-output

You can also see the current status of the requests within your dashboard and you can also check the logs to see the output from the Java class that we have used above. You can use other DocuSign methods from the API Walkthrough section in a similar way to meet the custom needs of your application.