Using EchoSign API with Codenvy

Below are various different projects talking to EchoSign API that you can create with Codenvy Factories:


This document will explain the details of integrating the EchoSign API into Codenvy. EchoSign API is a set of powerful APIs that allow users to send documents for electronic signature from their applications. The explanation has been done with 2 very basic Java servlet projects that makes use of the EchoSign API to explain some basic features provided by the API.

Before proceeding to the creation of the Java projects, please register at https://secure.echosign.com/public/upgrade?type=developer&rf=https%3A%2F%2Fsecure.echosign.com%2Fpublic%2Fhome%3Flocale%3Den_US with your email id and this will create a developer account for you. You can also register at https://www.echosign.adobe.com/en/free-account.html?leadSource=Website and then contact the customer support to convert your account to a developer account. After the developer account is created, the API key will be available at https://secure.echosign.com/account/echosignApi :

echosign-apikeys

You will then need to contact the EchoSign support to get an Application Id(which is a secure Id) and Application secret key for usage in your application and if you have paid EchoSign accounts, then you can create your own applications.

The EchoSign API has various methods to integrate with your application for various functionalities such as retrieving tokens to perform the other operations and sending documents for e-signature.

You can get more information about the API methods at https://secure.echosign.com/public/docs/restapi/v1. This section allows you to try out the methods using the input parameters and returns back the HTTP Request URL that will be required to invoke the relevant method from your Codenvy application and the response that you would get out of it. For example, if you want to invoke the Access Tokens method, you would do the following steps –
a) Select the ‘tokens’ operation from the list and expand it and enter the input parameters in the JSON format(please use your application and API keys) –

echosign-iosection

b) On hitting ‘Try Out’ button, you will get back the HTTP request URL and the response –

echosign-iosectionoutput

The first factory workspace source code is to explain the process of retrieving the access token using the EchoSign API.

Create the first Project

Login to your Codenvy workspace and create a WAR project named as ‘EchoSignSample’. This will have the following structure:

echosign-structure

Create pom.xml File

To make use of the Echosign API through HttpClient as a servlet, please update the pom.xml to include the HttpClient and Java EE Web API jars and the servletapi jar and the json jar into your project as Maven dependencies:

<dependencies>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>servlet-api</artifactId>
      <version>2.5</version>
    </dependency>
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.2.5</version>
    </dependency>    
    <dependency>
      <groupId>javax</groupId>
      <artifactId>javaee-web-api</artifactId>
      <version>6.0</version>
    </dependency>
    <dependency>
      <groupId>com.googlecode.json-simple</groupId>
      <artifactId>json-simple</artifactId>
      <version>1.1.1</version>
    </dependency>
  </dependencies>
  

This will include these jars in your project as follows:

echosign-dependencies

Create Java class

Now, create a Java class named ‘EchoSignServlet.java’ that will send a HTTP POST url with the JSON arguments to request an access token from the EchoSign API. The Application keys and API keys are passed as JSON objects. All this is done inside the doPost() method which is invoked by the doGet() method:

 protected void doPost(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException {
        
        StringBuffer sb = null;
        try {
            String postURL = "https://secure.echosign.com:443/api/rest/v1/auth/tokens";
            
            HttpPost req = new HttpPost(postURL);
            req.setHeader("Content-Type", "application/json");
            
            JSONObject applicationCredentials = new JSONObject();
            applicationCredentials.put("applicationId",  "absjdldjdkdfjk");
            applicationCredentials.put("applicationSecret",  "253738383hdjdkdfkdfjdjd");
            
            JSONObject userCredentials = new JSONObject();
            userCredentials.put("apiKey",  "hdjdjshsjws738");
            userCredentials.put("email",  "abc@pqr.com");
            userCredentials.put("password",  "djdjdjdk");
            
            JSONObject tokenCredentials = new JSONObject();
            tokenCredentials.put("applicationCredentials",  applicationCredentials);
            tokenCredentials.put("userCredentials",  userCredentials);
            
            StringEntity reqEntity = new StringEntity(tokenCredentials.toJSONString());

            req.setEntity(reqEntity);
      
            HttpResponse res = client.execute(req);
            HttpEntity entity = res.getEntity();
            String responseString = new BasicResponseHandler().handleResponse(res);
            if (entity != null) {
                EntityUtils.consume(entity);
            }
 
            sb = new StringBuffer("<br/>Simple POST request to url : "+ postURL +"<br/><br/>");
            sb.append("*** Request headers ***").append("<br/>");
            Header[] requestHeaders = req.getAllHeaders();
            for (Header header : requestHeaders) {
                sb.append(header.toString()).append("<br/>");
            }
            sb.append("***********************").append("<br/><br/>");
 
            sb.append("*** Response headers ***").append("<br/>");
            sb.append(res.getStatusLine()).append("<br/>");
            Header[] headers = res.getAllHeaders();
            for (Header header : headers) {
                sb.append(header.toString()).append("<br/>");
            }
            sb.append("***********************").append("<br/><br/>");
           
            sb.append("*** Response Body ***").append("<br/>");
            sb.append(responseString).append("<br/>");
            
        } catch (Exception ex) {
            ex.printStackTrace();
            sb = new StringBuffer(ex.toString());
        }
       
        request.setAttribute("data", sb.toString());
        RequestDispatcher rd = request.getRequestDispatcher("/success.jsp");
        rd.forward(request, response);
   }

Create index.jsp File

Your Codenvy project will have an index.jsp which will invoke the Servlet class:

<%
    response.sendRedirect("/hello");
%>

Create success.jsp File

Your Codenvy project will have a success.jsp which will be invoked from the EchoSignServlet class to display the response on the browser.

<html>
  <body>
    <div>
      <p>Data : <br/><%=request.getAttribute("data") %></p>
      <br/>
    </div>
 </body>
</html>

Create web.xml

The servlet mapping ‘/hello’ is defined in the web.xml as follows:

<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
  <display-name>EchoSign Servlet App</display-name>
  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>com.codenvy.EchoSignServlet</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>hello</servlet-name>
    <url-pattern>/hello</url-pattern>
  </servlet-mapping>
</web-app>

Build and Run Your first Project

Now you build and run your Codenvy project and the access token will be displayed in the browser:

echosign-tokenoutput

This token can then be used in the second project.

The second factory workspace source code is to explain the process of sending a library document(pre-defined template document) to other users for electronic signature. Before creating the project, you can create the Library document at https://secure.echosign.com/account/addDocumentToLibrary using a template document that you would send to other users for an e-signature :

Create the second Project

Login to your Codenvy workspace and create a WAR project named as ‘EchoSignSample1’. This will have the same structure as the first project and the pom.xml will define the same dependencies as the first project.

Create Java class

Now, create a Java class named ‘EchoSignServlet.java’ that will send a HTTP POST url with the JSON arguments to send the library document to other recipients using the EchoSign API. The required arguments are passed as JSON objects. More information on the arguments will be available in the API documentation. All this is done inside the doPost() method which is invoked by the doGet() method:

 protected void doPost(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException {
        
        StringBuffer sb = null;
        try {
            String postURL = "https://secure.echosign.com:443/api/rest/v1/agreements";
            
            HttpPost req = new HttpPost(postURL);
            req.setHeader("Content-Type", "application/json");
            req.setHeader("Access-Token", "2AAABLblqZhBwpwDN5Ju5CNka7NVo-U5WDkWq-e2fQWjArvlq8U5o92ejWD6D28hUNilkPrYJ7XU*");
            
            JSONObject documentCreationInfo = new JSONObject();
            documentCreationInfo.put("name",  "Echosign Document");
            documentCreationInfo.put("message",  "Sample Signature Document");
            
                       
            ArrayList<String> documentIdList = new ArrayList<String>();
            documentIdList.add("Echosign Document");
            documentCreationInfo.put("libraryDocumentNames", documentIdList);
            
            JSONObject recipients = new JSONObject();
            recipients.put("email",  "abc@pqr.com");
            recipients.put("role",  "SIGNER");
            JSONArray recipientsArr = new JSONArray();
            recipientsArr.add(recipients);
            documentCreationInfo.put("recipients", recipientsArr);
            
            documentCreationInfo.put("signatureType",  "ESIGN");
            documentCreationInfo.put("signatureFlow",  "SENDER_SIGNATURE_NOT_REQUIRED");
            
            JSONObject securityOptions = new JSONObject();
            securityOptions.put("password",  null);
            securityOptions.put("protectOpen",  false);
            securityOptions.put("webIdentityProtection",  null);
            securityOptions.put("kbaProtection",  null);
            documentCreationInfo.put("securityOptions",  securityOptions);
            
            JSONObject agreementInfo = new JSONObject();
            agreementInfo.put("documentCreationInfo",  documentCreationInfo);
            
            StringEntity reqEntity = new StringEntity(agreementInfo.toJSONString());

            req.setEntity(reqEntity);
      
            HttpResponse res = client.execute(req);
            HttpEntity entity = res.getEntity();
            String responseString = new BasicResponseHandler().handleResponse(res);
            if (entity != null) {
                EntityUtils.consume(entity);
            }
 
            sb = new StringBuffer("<br/>Simple POST request to url : "+ postURL +"<br/><br/>");
            sb.append("*** Request headers ***").append("<br/>");
            Header[] requestHeaders = req.getAllHeaders();
            for (Header header : requestHeaders) {
                sb.append(header.toString()).append("<br/>");
            }
            sb.append("***********************").append("<br/><br/>");
 
            sb.append("*** Response headers ***").append("<br/>");
            sb.append(res.getStatusLine()).append("<br/>");
            Header[] headers = res.getAllHeaders();
            for (Header header : headers) {
                sb.append(header.toString()).append("<br/>");
            }
            sb.append("***********************").append("<br/><br/>");
           
            sb.append("*** Response Body ***").append("<br/>");
            sb.append(responseString).append("<br/>");
            
        } catch (Exception ex) {
            ex.printStackTrace();
            sb = new StringBuffer(ex.toString());
        }
       
        request.setAttribute("data", sb.toString());
        RequestDispatcher rd = request.getRequestDispatcher("/success.jsp");
        rd.forward(request, response);
   }

Create index.jsp File

Your Codenvy project will have an index.jsp which will invoke the Servlet class:

<%
    response.sendRedirect("/hello");
%>

Create success.jsp File

Your Codenvy project will have a success.jsp which will be invoked from the EchoSignServlet class to display the response on the browser. The response would have the agreement Id.

<html>
  <body>
    <div>
      <p>Data : <br/><%=request.getAttribute("data") %></p>
      <br/>
    </div>
 </body>
</html>

The web.xml will be same as the first project.

Build and Run Your second Project

Now you build and run your Codenvy project and the response will be displayed in the browser similar to the first project. At the same time, the template library document will be sent to the recipients.

echosign-sendagreementoutput

In a similar way, you can use various API methods of EchoSign to perform various operations that may be required within your application.