Table of contents
- Adobe Sign API JS SDK
- Overview
- Table of contents
- Prerequisites
- Third party dependencies
- Getting Started
- Downloading and Installing the SDK
- APIs
- Samples
- Running the Samples
- Tests
- Executing the tests
- 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:
-
In order to use the SDK, you need to have an account with Adobe Sign. Please register for a developer account here.
-
Sign in to create an application on the Adobe Sign web portal and obtain it's application/client id and client secret.
-
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.
-
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 :
AdobeSignNodeJsSdkwill 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.jsaccordingly 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.jsonto configure:
- serverPort
- keyStoreFile
- certificateFile
Steps to start the HTTPS server :
-
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.pemNote: Following parameters are used/generated in the above command
Algorithm used to generate the key pair :
RSAKeystore filename :
key.pemCertificate filename :
cert.pemKeysize :
2048 -
Provide the serverPort, location of httpServer node module, keystore file and certificate file in
AdobeSignNodeJsSdk/browser/server/serverConfig.json. -
Install the dependencies for running the server using npm :-
cd AdobeSignNodeJsSdk/browser/server
npm install
-
Run the Server
From the IDE
Right click on the file
AdobeSignNodeJsSdk/browser/server/NodeJSHTTPSServer.jsand selectRunthe 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.jsonaccordingly 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
- Click File -> New -> Project from Existing Sources.
- In the dialog that opens, select the directory which contains the collection of sources you want to import. Click OK.
- 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.jsaccordingly 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.jsonaccordingly 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)
});
})();