Table of contents

• Adobe Sign API JS SDK
• Overview
• Table of contents
• Prerequisites
  • For Browser
  • NodeJS
• Third party dependencies
• Getting Started
• Downloading and Installing the SDK
  • Download the SDK from Github
    • For Browser
    • NodeJS
  • Using NPM
  • Using Bower
• APIs
• Samples
  • For Browser
  • NodeJS
• Running the Samples
  • For Browser
  • NodeJS
• Tests
  • For Browser
  • NodeJS
• Executing the tests
  • For Browser
  • NodeJS
• Documentation
• Report Issues/Bugs

Adobe Sign API JS SDK

Overview

Adobe Sign SDK aims at providing an easy way to integrate the Adobe Sign RESTful web service into client applications through easy to consume client side objects wrapping the REST API functionality. This repository contains Adobe Sign’s SDK (NodeJS and browser) and samples for these APIs.

Prerequisites

For Browser

For the Browser-based SDK, the client machine should have the following software installed:

• OS: Windows/Mac/Linux
• Browser(Chrome/Firefox/Safari/Internet Explorer/Edge)
• Bower: 1.8.0

NodeJS

For the NodeJs-based SDK, the client machine should have the following software installed:

• OS: Windows/Mac/Linux
• NodeJs: 6.2.0
• NPM: 3.8.9

Third Party Dependencies

The SDK both for NodeJS & browser has hard dependency on the following third party libraries:

• superagent: 3.0.0
• validator: 6.0.0

For running the SDK on Internet Explorer, add following dependency as well:

• babel-polyfill: 6.16.0

Getting Started

The Adobe Sign clients need to follow the below steps in order to get started with it:

1. In order to use the SDK, you need to have an account with Adobe Sign. Please register for a developer account here.

2. Sign in to create an application on the Adobe Sign web portal and obtain it's application/client id and client secret.

3. Generate the OAuth access token by using the above application id and the application secret. The access token will need to be generated by using the OAuth APIs.

4. Use the generated OAuth access token for trying out the sample API code (or directly in the client application code) provided in the SDK.

Downloading and Installing the SDK

Note: The SDK can be downloaded from github, npm or bower. Also, samples & tests are only available on git repo.

Download the SDK from Github

Download the SDK source code zip from the GitHub and unzip the archive to a folder of your choice. You can also sync the git repo on your local machine. You can find the SDK here.

git clone https://github.com/adobe-sign/AdobeSignNodeJsSdk.git
    

For Browser

To use the SDK for JavaScript on your web page, copy the AdobeSignNodeJsSdk/dist directory to your web server.

Then, include the adobe-sign-sdk.js or adobe-sign-sdk.min.js file from this directory in your code.

As the SDK has hard dependency on superagent & validator, remember to include them before the SDK. For running the SDK on IE add babel-polyfill as the dependency. You can either copy these dependencies from AdobeSignNodeJsSdk/browser/vendor folder or include their CDN.

For example, include one of the following tags in your code:

    <script type="text/javascript" src="/yourpath/superagent.min.js"></script>
    <script type="text/javascript" src="/yourpath/validator.min.js"></script>
    
    <script type="text/javascript" src="/yourpath/adobe-sign-sdk.min.js"></script>

NodeJS

Note : AdobeSignNodeJsSdk will be referred to as the root directory for the SDK.

In case downloaded from git, run npm install at the root directory to resolve dependencies as follows:

    npm install    

Using NPM

Install the SDK directly from npm:

    npm install adobe-sign-sdk --save

Using Bower

Install the SDK directly from bower:

    bower install adobe-sign-sdk

APIs

The AdobeSignNodeJsSdk/rest-api-sdk/src folder contains all the Adobe Sign APIs.

Folders containing APIs are laid out as follows:

api
Each class represents a resource and the class methods refers to the operations that can be performed on that resource. Each such operation is called API.
e.g. AgreementsApi.js contains getAgreements method which retrieves all the agreements for the user.

model
Each class represents request or response class required in the API calls.
The classes are resource specific and can be found under the folders for the corresponding resources.

utils
This folder contains the helper utilities required for the execution of APIs.

Note : For the SDK for browser all the API's are bundled in AdobeSignNodeJsSdk/dist/adobe-sign-sdk.js.

Samples

For Browser

Note : If you have installed the client from bower, please find the samples here.

The samples are located at : AdobeSignNodeJsSdk/browser/rest-api-sample.
These contain html files that demonstrate how to use the API as well as some of its capabilities in browser.

NodeJS

Note : If you have installed the client from npm, please find the samples here.

The samples are located at : AdobeSignNodeJsSdk/rest-api-sample.
These contain clients of Adobe Sign's APIs that demonstrate how to use the API as well as some of its capabilities.

Folders under samples are laid out as follows:
api
Contains individual sample clients each demonstrating a specific capability. Each client is named according to the capability it demonstrates. For example, the client GetUsersInAccount.js shows how to retrieve a list of users from the account of the user on whose behalf the API call is made.

api/oAuth/server
Contains sample client demonstrating how to create a new group in an account by using the OAuth workflow. Note : It also contains a OAuthReadMe file which describes how the user can use this sample.

utils
Contains helper classes that encapsulate the API calls required by the sample clients.

resources
Contains input files used by the sample clients. These include a config.json file and pdf files required by some of the APIs.

Running the Samples

For Browser

Note : Before executing the samples edit AdobeSignNodeJsSdk/browser/rest-api-sample/resources/Config.js accordingly with your information.

Each sample client contains comments that explains briefly about the action being performed.
You should edit the Config.js configuration file to configure:

• Credentials (access token with the required scope)
• Parameters used by the samples

There are 2 ways to run the samples :

1) Using HTTPS server provided with SDK

Note : Before starting the server, update AdobeSignNodeJsSdk/browser/server/serverConfig.json to configure:

• serverPort
• keyStoreFile
• certificateFile

Steps to start the HTTPS server :

1. Please generate a keystore and certificate files and store it at the location. AdobeSignNodeJsSdk/browser/server/{keystore-file}

   Following commands can be used to generate the keystore and certificate files in the working directory.

    openssl req -newkey rsa:2048 -new -nodes -keyout key.pem -out cert.pem
    openssl x509 -req -days 365 -in cert.pem -signkey key.pem -out cert.pem
        

   Note: Following parameters are used/generated in the above command

   Algorithm used to generate the key pair : RSA

   Keystore filename : key.pem

   Certificate filename : cert.pem

   Keysize : 2048

2. Provide the serverPort, location of httpServer node module, keystore file and certificate file in AdobeSignNodeJsSdk/browser/server/serverConfig.json.

3. Install the dependencies for running the server using npm :-

    cd AdobeSignNodeJsSdk/browser/server 
    npm install 

4. Run the Server

   From the IDE

   Right click on the file AdobeSignNodeJsSdk/browser/server/NodeJSHTTPSServer.js and select Run the server.

   From the commandline

   Run the command from commandline to run the server.

   node NodeJSHTTPSServer.js
       

To run a sample in a browser of your choice, open

        https://localhost:<portNumber>/browser/rest-api-sample/api/<SampleName>.html

For example, to run the sample GetSigningUrl with server at port 9000

        https://localhost:9000/browser/rest-api-sample/api/GetSigningUrl.html

Click on the Run the Sample button.

Note Some Samples would require a document to be uploaded for the sample to run.

2) Using any HTTP Server

Note OAuth sample can only be run on a HTTPS Server.

Go to SDK root directory & start a HTTP server of your choice.

• For Python Server

        python -m SimpleHTTPServer <portNumber>

• For node http-server

		npm install http-server
		http-server -p <portNumber> .

To run a sample in a browser of your choice, open

        http://localhost:<portNumber>/browser/rest-api-sample/api/<SampleName>.html

Note : To run the sample using OAuth workflow, please go through OAuthReadMe.

NodeJS

Note : Before executing the samples edit AdobeSignNodeJsSdk/rest-api-sample/resources/config.json accordingly with your information.

Each sample client contains class comments that explains briefly about the action being performed. You should edit the config.json configuration file to configure:

• Credentials (access token with the required scope)
• Parameters used by the samples
• Output path of downloaded files

There are 2 ways to run the samples :

1) Through command line

To run all samples, use the following command :

        node_modules/grunt/bin/grunt allSamples

To run a specific sample, use the following command :

        node_modules/grunt/bin/grunt Sample:<SampleFileName>

For example, to run the sample GetSigningUrl.js, use

        node_modules/grunt/bin/grunt Sample:GetSigningUrl

2) From the IDE

Using IntellijIdea

Import the project

1. Click File -> New -> Project from Existing Sources.
2. In the dialog that opens, select the directory which contains the collection of sources you want to import. Click OK.
3. As a result, AdobeSignNodeJsSdk is imported.

To run the sample, Right click on the sample, and select Run to run it.

Note : To run the sample using OAuth workflow, please go through OAuthReadMe.

Tests

For Browser

In the SDK downloaded from git, dist folder located at AdobeSignNodeJsSdk/dist/ contains the test bundles adobe-sign-sdk-tests.js or adobe-sign-sdk-tests.min.js which have all the test cases.

NodeJS

Note : If you have installed the client from npm, please find the tests here.

The test folder contains the test cases and is located at AdobeSignNodeJsSdk/rest-api-sdk/test.

All sources under the test folder are laid out as follows:

api
Contains individual test cases for each API under the corresponding resource folder name.

resources
Contains input files used in the tests. These include a config.json file and pdf files required by some of the APIs.

utils
Contains helper classes that encapsulate the functionality required by the test classes.

Executing the tests

For Browser

Note : Before executing the tests edit AdobeSignNodeJsSdk/browser/rest-api-sdk/test/Config.js accordingly with your information.

You should edit the Config.js configuration file to configure:

• Credentials (access token with the required scope)
• Parameters used by the tests

Start a server of your choice in the root directory of the SDK or use the HTTPS Server provided at AdobeSignNodeJsSdk/browser/server/NodeJsHTTPSServer.js.

To run a specific test file

	https://<serverAddress>:<portNumber>/browser/rest-api-sdk/test/testRunner.html?grep=<TestFileName>

For example, to run the test for CreateAgreementsApiTest.js

	https://localhost:9000/browser/rest-api-sdk/test/testRunner.html?grep=CreateAgreementsApiTest

To run all the tests in a browser of your choice, open

	https://localhost:<portNumber>/browser/rest-api-sdk/test/testRunner.html

Click on Choose File to upload a document which will be used to create transient document for the tests. To run the tests, click on the Run tests button.

NodeJS

Note : Before executing the tests, edit AdobeSignNodeJsSdk/rest-api-sdk/test/resources/config.json accordingly with your information.

You should edit the config.json configuration file to configure:

• Credentials (access token with the required scope)
• Parameters used by the tests

The tests can be executed by using this command from the base directory:

    node_modules/grunt/bin/grunt test

To run a specific test file

    node_modules/mocha/bin/mocha <TestFilePath>

For example, to run the test for CreateAgreementsApiTest.js

    node_modules/mocha/bin/mocha rest-api-sdk/test/api/Agreements/CreateAgreementsApiTest.js

The tests can also be executed by using mocha from the base directory:

    node_modules/mocha/bin/mocha --recursive rest-api-sdk/test/api

Documentation

A comprehensive documentation for the APIs and the classes used can be found at AdobeSignNodeJsSdk/docs/html/index.html & AdobeSignNodeJsSdk/browser/docs/html/index.html for Node & browser SDK respectively.

License

Code released under the license which can be found here.

Report Issues/Bugs

You can report the issues in the issues section of the github repo.

Usage

Browser Sample to send an agreement using transient document

    <script src="/yourPath/AdobeSignNodeJsSdk/browser/vendor/superagent.min.js"></script>
    <script src="/yourPath/AdobeSignNodeJsSdk/browser/vendor/validator.min.js"></script>
    <script src="/yourPath/AdobeSignNodeJsSdk/dist/adobe-sign-sdk.js"></script>

    <script type="text/javascript">
    
    function SendAgreementUsingTransientDocument() {
    
       /**
        * Entry point for this sample client program.
        */

        var ACCESS_TOKEN = "YOUR_ACCESS_TOKEN";               //Access token to allow  the user to authorize API access  
  		var DIR_NAME = "SAMPLE_DIRECTORY";                    //Path structure of directory containing the file Sample.pdf
  		var FILE_NAME = "SAMPLE_PDF_FILE";                    //Name of the sample document to be used in creating a transient document.
  		var RECIPIENT_EMAIL = "RECIPIENT_EMAIL";              //Email id of recipient.
  		var RECIPIENT_SET_NAME = "SampleRecipientSetName";    //Name of recipient set  
 	    var AGREEMENT_NAME = "SampleAgreementName";           //Name of agreement
  		var MIME_TYPE = "application/pdf";                    //Mime type for pdf files.

  		var accessTokenKey = "accessToken";
 	    var mimeTypeKey = "mimeType";

 	   //Create a new context.
       var context = new AdobeSignSdk.Context();
       var transientDocumentsApi = new AdobeSignSdk.TransientDocumentsApi(context);
       var agreementsApi = new AdobeSignSdk.AgreementsApi(context);
  	   var agreementsModel = AdobeSignSdk.AgreementsModel;

	   //Set header parameters
  	   var headerParams = {};
       headerParams[accessTokenKey] = ACCESS_TOKEN;

       var file = document.getElementById('transientdocument').files[0];

       //Make API call to create transient document.
       transientDocumentsApi.createTransientDocument(headerParams,
                                                   FILE_NAME,
                                                buffer,
                                                opts)
                            .then(function(transientDocumentResponse) {
                                //Get the id of the transient document.
                                var transientDocumentId = transientDocumentResponse.getTransientDocumentId();
               
                                //Create file info object using transient document id
                                var fileInfo = new agreementsModel.FileInfo();
                                fileInfo.setTransientDocumentId(transientDocumentId);
                                var fileInfos = [];
                                fileInfos.push(fileInfo);
               
                                //Set email id of recipient.`
                                var recipientEmail = RECIPIENT_EMAIL;
                                var recipientInfo = new agreementsModel.RecipientInfo();
                                recipientInfo.setEmail(recipientEmail);
               
                                //Create an array of recipients from list of email ids.
                                var recipientSetMemberInfos = [];
                                recipientSetMemberInfos.push(recipientInfo);
               
                                //Create recipient set which will receive the agreement.
                                var recipientSetInfo = new agreementsModel.RecipientSetInfo();
                                recipientSetInfo.setRecipientSetMemberInfos(recipientSetMemberInfos);
                                recipientSetInfo.setRecipientSetRole(agreementsModel.RecipientSetInfo.RecipientSetRoleEnum.SIGNER);
                                recipientSetInfo.setRecipientSetName(RECIPIENT_SET_NAME);
               
                                //Set recipient set infos
                                var recipientSetInfos = [];
                                recipientSetInfos.push(recipientSetInfo);
               
                                //Create document creation info.
                                var documentCreationInfo = new agreementsModel.DocumentCreationInfo();
                                documentCreationInfo.setName(AGREEMENT_NAME);
                                documentCreationInfo.setFileInfos(fileInfos);
                                documentCreationInfo.setRecipientSetInfos(recipientSetInfos);
                                documentCreationInfo.setSignatureType(agreementsModel.DocumentCreationInfo.SignatureTypeEnum.ESIGN);
                                documentCreationInfo.setSignatureFlow(agreementsModel.DocumentCreationInfo.SignatureFlowEnum.SENDER_SIGNATURE_NOT_REQUIRED);
               
                                //Create agreement creation info.
                                var agreementCreationInfo = new agreementsModel.AgreementCreationInfo();
                                agreementCreationInfo.setDocumentCreationInfo(documentCreationInfo);
               
                                 //Create agreement using the transient document.
                                return agreementsApi.createAgreement(headerParams,
                                                              agreementCreationInfo);
                            })
                           .then(function(agreementCreationResponse) {
                            //Get agreement info using the agreement id.
                            return agreementsApi.getAgreementInfo(headerParams,
                                                               agreementCreationResponse.getAgreementId());
                            })
                           .then(function(agreementInfo) {
                            //Display agreement details
                            console.log("Agreement ID = " + agreementInfo.getAgreementId());
                            console.log("Agreement Name = " + agreementInfo.getName());
                            console.log("Agreement Status = " + agreementInfo.getStatus());
                            })
                            .catch(function(apiError) {
                                console.log(apiError)
                            });

    </script>
    
</head>

<body>
    Upload file to create Transient Document : <input type=file id="transientdocument"/>
    <br/><br/>
    <button onclick="SendAgreementUsingTransientDocument()">Run the Sample</button>
    <br/><br/>
</div>
</body>

NodeJS Sample to send an agreement using transient document

(function SendAgreementUsingTransientDocument() {

  /**
   * This sample client demonstrates how to send an agreement using npm module 'adobe-sign-sdk'
   */

  var AdobeSignSdk = require('adobe-sign-sdk');
  var path = require('path');
  var fs = require('fs');
  
  var ACCESS_TOKEN = "YOUR_ACCESS_TOKEN";               //Access token to allow  the user to authorize API access  
  var DIR_NAME = "SAMPLE_DIRECTORY";                    //Path structure of directory containing the file Sample.pdf
  var FILE_NAME = "SAMPLE_PDF_FILE";                    //Name of the sample document to be used in creating a transient document.
  var RECIPIENT_EMAIL = "RECIPIENT_EMAIL";              //Email id of recipient.
  var RECIPIENT_SET_NAME = "SampleRecipientSetName";    //Name of recipient set  
  var AGREEMENT_NAME = "SampleAgreementName";           //Name of agreement
  var MIME_TYPE = "application/pdf";                    //Mime type for pdf files.

  var accessTokenKey = "accessToken";
  var mimeTypeKey = "mimeType";

  //Create a new context.
  var context = new AdobeSignSdk.Context();
  var transientDocumentsApi = new AdobeSignSdk.TransientDocumentsApi(context);
  var agreementsApi = new AdobeSignSdk.AgreementsApi(context);
  var agreementsModel = AdobeSignSdk.AgreementsModel;

  //Set header parameters
  var headerParams = {};
  headerParams[accessTokenKey] = ACCESS_TOKEN;

  //Find absolute path of the file
  var absoluteFilePath = path.join(DIR_NAME,
                                   FILE_NAME);
  var fileBytes = fs.readFileSync(absoluteFilePath);
  var buffer = new Buffer(fileBytes);

  var opts = {};
  //Set mime type of the file
  opts[mimeTypeKey] = MIME_TYPE;

  //Create trasient document
  transientDocumentsApi.createTransientDocument(headerParams,
                                                FILE_NAME,
                                                buffer,
                                                opts)
                       .then(function(transientDocumentResponse) {
                         //Get the id of the transient document.
                         var transientDocumentId = transientDocumentResponse.getTransientDocumentId();
               
                         //Create file info object using transient document id
                         var fileInfo = new agreementsModel.FileInfo();
                         fileInfo.setTransientDocumentId(transientDocumentId);
                         var fileInfos = [];
                         fileInfos.push(fileInfo);
               
                         //Set email id of recipient.`
                         var recipientEmail = RECIPIENT_EMAIL;
                         var recipientInfo = new agreementsModel.RecipientInfo();
                         recipientInfo.setEmail(recipientEmail);
               
                         //Create an array of recipients from list of email ids.
                         var recipientSetMemberInfos = [];
                         recipientSetMemberInfos.push(recipientInfo);
               
                         //Create recipient set which will receive the agreement.
                         var recipientSetInfo = new agreementsModel.RecipientSetInfo();
                         recipientSetInfo.setRecipientSetMemberInfos(recipientSetMemberInfos);
                         recipientSetInfo.setRecipientSetRole(agreementsModel.RecipientSetInfo.RecipientSetRoleEnum.SIGNER);
                         recipientSetInfo.setRecipientSetName(RECIPIENT_SET_NAME);
               
                         //Set recipient set infos
                         var recipientSetInfos = [];
                         recipientSetInfos.push(recipientSetInfo);
               
                         //Create document creation info.
                         var documentCreationInfo = new agreementsModel.DocumentCreationInfo();
                         documentCreationInfo.setName(AGREEMENT_NAME);
                         documentCreationInfo.setFileInfos(fileInfos);
                         documentCreationInfo.setRecipientSetInfos(recipientSetInfos);
                         documentCreationInfo.setSignatureType(agreementsModel.DocumentCreationInfo.SignatureTypeEnum.ESIGN);
                         documentCreationInfo.setSignatureFlow(agreementsModel.DocumentCreationInfo.SignatureFlowEnum.SENDER_SIGNATURE_NOT_REQUIRED);
               
                         //Create agreement creation info.
                         var agreementCreationInfo = new agreementsModel.AgreementCreationInfo();
                         agreementCreationInfo.setDocumentCreationInfo(documentCreationInfo);
               
                         //Create agreement using the transient document.
                         return agreementsApi.createAgreement(headerParams,
                                                              agreementCreationInfo);
                       })
                       .then(function(agreementCreationResponse) {
                         //Get agreement info using the agreement id.
                         return agreementsApi.getAgreementInfo(headerParams,
                                                               agreementCreationResponse.getAgreementId());
                       })
                       .then(function(agreementInfo) {
                         //Display agreement details
                         console.log("Agreement ID = " + agreementInfo.getAgreementId());
                         console.log("Agreement Name = " + agreementInfo.getName());
                         console.log("Agreement Status = " + agreementInfo.getStatus());
                       })
                       .catch(function(apiError) {
                         console.log(apiError)
                       });
               
})();