adobe-sign-sdk

    1.1.0 • Public • Published

    Table of contents

    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 
    
    1. 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)
                           });
                   
    })();
    
    

    Install

    npm i adobe-sign-sdk

    DownloadsWeekly Downloads

    181

    Version

    1.1.0

    License

    Apache-2.0

    Last publish

    Collaborators

    • adobe-admin