Skip to content

Commit 1a68df5

Browse files
LarryKlugerDSLarryKlugerDS
authored
Merge pull request #99 from docusign/DEVDOCS-335_LarryK_Readme
Update Readme
2 parents 32fee64 + 62d4182 commit 1a68df5

File tree

1 file changed

+87
-200
lines changed

1 file changed

+87
-200
lines changed

‎README.md‎

Lines changed: 87 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -17,34 +17,30 @@ commented out
1717

1818
You can sign up for a free [developer sandbox](https://developers.docusign.com/).
1919

20-
Requirements
21-
============
20+
## Requirements
2221

2322
Node 4 or later.
2423

25-
Installation
26-
============
27-
28-
### NPM Package Manager
24+
## Installation via the NPM Package Manager
2925

30-
Install the client locally: `npm install docusign-esign --save --save-exact` (note you may have to use `sudo` based on your permissions)
26+
`npm install docusign-esign --save`
3127

32-
Alternatively you can just copy the source code directly into your project.
33-
34-
#### Dependencies
28+
## Dependencies
3529

3630
This client has the following external dependencies:
3731
* [email protected]
3832
* [email protected]
3933
* [email protected]
4034

41-
Usage
42-
=====
35+
# Usage
36+
37+
## OAuth Authorization Code Grant
38+
39+
See the [Node.JS OAuth Authorization Code Grant flow](https://github.com/docusign/docusign-code-examples/tree/master/node)
40+
example for Node.JS 8.10 or later. It also shows how to use the SDK with promises instead of callback functions.
4341

44-
To initialize the client, make the Login API Call and send a template for signature:
45-
### SDK version 3.x.x
42+
The following example uses callback functions.
4643

47-
#### OAuth Authorization Code Grant
4844
uncomment auth code grant section in test/OAuthClientTests.js, run it and then open http://localhost:3000.
4945
```javascript
5046
const express = require('express');
@@ -99,74 +95,15 @@ app.listen(port, host, function (err) {
9995

10096
console.log('Your server is running on http://' + host + ':' + port + '.');
10197
});
102-
10398
```
104-
#### OAuth Implicit Grant
105-
uncomment implicit grant section in test/OAuthClientTests.js, run it and then open http://localhost:3000.
106-
```javascript
107-
108-
const express = require('express');
109-
const docusign = require('docusign-esign');
110-
const apiClient = new docusign.ApiClient();
111-
112-
const app = express();
113-
const port = process.env.PORT || 3000;
114-
const host = process.env.HOST || 'localhost';
115-
116-
const integratorKey = '68c1711f-xxxx-xxxx-xxxx-b49b4211d831'; // An IK for a mobile docusign account
117-
const redirectUri = 'http://localhost:3000/auth';
118-
const basePath = 'https://demo.docusign.net/restapi';
119-
120-
const responseType = apiClient.OAuth.ResponseType.TOKEN; // Response type of token, to be used for implicit grant
121-
const scopes = [apiClient.OAuth.Scope.EXTENDED];
122-
const randomState = "*^.$DGj*)+}Jk"; // after successful login you should compare the value of URI decoded "state" query param with the one created here. They should match
123-
124-
apiClient.setBasePath(basePath);
125-
126-
app.get('/', function (req, res) {
127-
const authUri = apiClient.getAuthorizationUri(integratorKey, scopes, redirectUri, responseType, randomState);//get DocuSign OAuth authorization url
128-
//Open DocuSign OAuth login in a browser, res being your node.js response object.
129-
res.redirect(authUri);
130-
});
131-
132-
app.get('/auth', function (req,res) {
133-
// IMPORTANT: after the login, DocuSign will send back a new
134-
// access token in the hash fragment of the redirect URI.
135-
// You should set up a client-side handler that handles window.location change to get
136-
// that token and pass it to the ApiClient object as shown in the next
137-
// lines:
138-
res.send();
139-
});
140-
141-
app.get('/auth/:accessToken', function (req, res) {
142-
// This a sample endpoint to allow you to pass in the previously recEIved accesstoken to log in via getUserInfo
143-
// ex: http://localhost:3000/auth#access_token=<token>&expires_in=<expiresIn>&token_type=<tokenType>&state=<randomState>
144-
// ex: http://localhost:3000/auth/<token>
14599

146-
const accessToken = req.params.accessToken;
100+
## OAuth JSON Web Token (JWT) Grant
147101

148-
apiClient.getUserInfo(accessToken, function (err, userInfo) {
149-
if (err)
150-
console.log(err)
151-
152-
console.log("UserInfo: " + userInfo);
153-
// parse first account's baseUrl
154-
// below code required for production, no effect in demo (same
155-
// domain)
156-
apiClient.setBasePath(userInfo.accounts[0].baseUri + "/restapi");
157-
res.send(userInfo);
158-
});
159-
});
102+
See the [Node.JS Service Integration](https://github.com/docusign/eg-01-node-jwt) example for Node 8.10 or later.
103+
It uses the OAuth JWT Grant flow. It also demonstrates how to use the SDK with promises.
160104

161-
app.listen(port, host, function(err) {
162-
if (err)
163-
throw err;
105+
The following example can be used with an older version of Node.JS.
164106

165-
console.log('Your server is running on http://' + host + ':' + port + '.');
166-
});
167-
168-
```
169-
#### Using JSON Web Token Bearer Grant
170107
```javascript
171108
var docusign = require('docusign-esign');
172109
var async = require('async');
@@ -268,151 +205,102 @@ async.waterfall([
268205
});
269206
```
270207

271-
### SDK version 2.x.x using 2-legged authentication only
272-
```javascript
273-
var docusign = require('docusign-esign');
274-
var async = require('async');
275-
276-
var integratorKey = '***'; // Integrator Key associated with your DocuSign Integration
277-
var email = 'YOUR_EMAIL'; // Email for your DocuSign Account
278-
var password = 'YOUR_PASSWORD'; // Password for your DocuSign Account
279-
var docusignEnv = 'demo'; // DocuSign Environment generally demo for testing purposes
280-
var fullName = 'Joan Jett'; // Recipient's Full Name
281-
var recipientEmail = '[email protected]'; // Recipient's Email
282-
var templateId = '***'; // ID of the Template you want to create the Envelope with
283-
var templateRoleName = '***'; // Role Name of the Template
284208

285-
var baseUrl = 'https://' + docusignEnv + '.docusign.net/restapi';
209+
```
210+
#### OAuth Implicit Grant
211+
uncomment implicit grant section in test/OAuthClientTests.js, run it and then open http://localhost:3000.
212+
```javascript
286213
287-
// initialize the api client
288-
var apiClient = new docusign.ApiClient();
289-
apiClient.setBasePath(baseUrl);
214+
const express = require('express');
215+
const docusign = require('docusign-esign');
216+
const apiClient = new docusign.ApiClient();
290217
291-
// create JSON formatted auth header
292-
var creds = JSON.stringify({
293-
Username: email,
294-
Password: password,
295-
IntegratorKey: integratorKey
296-
});
297-
apiClient.addDefaultHeader('X-DocuSign-Authentication', creds);
218+
const app = express();
219+
const port = process.env.PORT || 3000;
220+
const host = process.env.HOST || 'localhost';
298221
299-
// assign api client to the Configuration object
300-
docusign.Configuration.default.setDefaultApiClient(apiClient);
222+
const integratorKey = '68c1711f-xxxx-xxxx-xxxx-b49b4211d831'; // An IK for a mobile docusign account
223+
const redirectUri = 'http://localhost:3000/auth';
224+
const basePath = 'https://demo.docusign.net/restapi';
301225
302-
async.waterfall([
303-
function login (next) {
304-
// login call available off the AuthenticationApi
305-
var authApi = new docusign.AuthenticationApi();
306-
307-
// login has some optional parameters we can set
308-
var loginOps = new authApi.LoginOptions();
309-
loginOps.setApiPassword('true');
310-
loginOps.setIncludeAccountIdGuid('true');
311-
authApi.login(loginOps, function (err, loginInfo, response) {
312-
if (err) {
313-
return next(err);
314-
}
315-
if (loginInfo) {
316-
// list of user account(s)
317-
// note that a given user may be a member of multiple accounts
318-
var loginAccounts = loginInfo.getLoginAccounts();
319-
console.log('LoginInformation: ' + JSON.stringify(loginAccounts));
320-
var loginAccount = loginAccounts[0];
321-
var accountId = loginAccount.accountId;
322-
var baseUrl = loginAccount.baseUrl;
323-
var accountDomain = baseUrl.split("/v2");
324-
325-
// below code required for production, no effect in demo (same domain)
326-
apiClient.setBasePath(accountDomain[0]);
327-
docusign.Configuration.default.setDefaultApiClient(apiClient);
328-
next(null, loginAccount);
329-
}
330-
});
331-
},
226+
const responseType = apiClient.OAuth.ResponseType.TOKEN; // Response type of token, to be used for implicit grant
227+
const scopes = [apiClient.OAuth.Scope.EXTENDED];
228+
const randomState = "*^.$DGj*)+}Jk"; // after successful login you should compare the value of URI decoded "state" query param with the one created here. They should match
332229
333-
function sendTemplate (loginAccount, next) {
334-
// create a new envelope object that we will manage the signature request through
335-
var envDef = new docusign.EnvelopeDefinition();
336-
envDef.setEmailSubject('Please sign this document sent from Node SDK');
337-
envDef.setTemplateId(templateId);
230+
apiClient.setBasePath(basePath);
338231
339-
// create a template role with a valid templateId and roleName and assign signer info
340-
var tRole = new docusign.TemplateRole();
341-
tRole.setRoleName(templateRoleName);
342-
tRole.setName(fullName);
343-
tRole.setEmail(recipientEmail);
232+
app.get('/', function (req, res) {
233+
const authUri = apiClient.getAuthorizationUri(integratorKey, scopes, redirectUri, responseType, randomState);//get DocuSign OAuth authorization url
234+
//Open DocuSign OAuth login in a browser, res being your node.js response object.
235+
res.redirect(authUri);
236+
});
344237
345-
// create a list of template roles and add our newly created role
346-
var templateRolesList = [];
347-
templateRolesList.push(tRole);
238+
app.get('/auth', function (req,res) {
239+
// IMPORTANT: after the login, DocuSign will send back a new
240+
// access token in the hash fragment of the redirect URI.
241+
// You should set up a client-side handler that handles window.location change to get
242+
// that token and pass it to the ApiClient object as shown in the next
243+
// lines:
244+
res.send();
245+
});
348246
349-
// assign template role(s) to the envelope
350-
envDef.setTemplateRoles(templateRolesList);
247+
app.get('/auth/:accessToken', function (req, res) {
248+
// This a sample endpoint to allow you to pass in the previously recEIved accesstoken to log in via getUserInfo
249+
// ex: http://localhost:3000/auth#access_token=<token>&expires_in=<expiresIn>&token_type=<tokenType>&state=<randomState>
250+
// ex: http://localhost:3000/auth/<token>
351251
352-
// send the envelope by setting |status| to 'sent'. To save as a draft set to 'created'
353-
envDef.setStatus('sent');
252+
const accessToken = req.params.accessToken;
354253
355-
// use the |accountId| we retrieved through the Login API to create the Envelope
356-
var accountId = loginAccount.accountId;
254+
apiClient.getUserInfo(accessToken, function (err, userInfo) {
255+
if (err)
256+
console.log(err)
357257
358-
// instantiate a new EnvelopesApi object
359-
var envelopesApi = new docusign.EnvelopesApi();
258+
console.log("UserInfo: " + userInfo);
259+
// parse first account's baseUrl
260+
// below code required for production, no effect in demo (same
261+
// domain)
262+
apiClient.setBasePath(userInfo.accounts[0].baseUri + "/restapi");
263+
res.send(userInfo);
264+
});
265+
});
360266
361-
// call the createEnvelope() API
362-
envelopesApi.createEnvelope(accountId, envDef, null, function (err, envelopeSummary, response) {
363-
if (err) {
364-
return next(err);
365-
}
366-
console.log('EnvelopeSummary: ' + JSON.stringify(envelopeSummary));
367-
next(null);
368-
});
369-
}
267+
app.listen(port, host, function(err) {
268+
if (err)
269+
throw err;
370270
371-
], function end (error) {
372-
if (error) {
373-
console.log('Error: ', error);
374-
process.exit(1);
375-
}
376-
process.exit();
271+
console.log('Your server is running on http://' + host + ':' + port + '.');
377272
});
378-
273+
379274
```
380275

381-
See [CoreRecipes.js](./test/Recipes/CoreRecipes.js) for more examples.
276+
# The basePath
382277

383-
Sample App
384-
=======
385-
386-
Check out the LoanCo sample app - an open source app that showcases the Node.js SDK and demonstrates several common DocuSign workflows and features:
387-
388-
Run the app: https://loancosample.docusign.com/
278+
This section applies to applications which use OAuth for authentication with DocuSign.
389279

390-
Get the code: https://github.com/docusign/sample-app-loanco-nodejs
280+
The SDK must be configured to use the correct `basePath` for the accredited user's DocuSign account.
391281

392-
![LoanCo Sample Application](loanco.png)
282+
To determine the user's basePath:
393283

284+
1. After obtaining a Bearer token, call the
285+
[OAuth::userInfo endpoint](https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints).
394286

395-
# Authentication
287+
The `getUserInfo` method can be used to call the OAuth::userInfo endpoint. See the file
288+
[ApiClient.js](https://github.com/docusign/docusign-node-client/blob/master/src/ApiClient.js), line 713.
396289

397-
## Service Integrations that use Legacy Header Authentication
290+
Use the results to choose the account. One of the user's accounts is their default account.
291+
The method's results include the selected account's `base_uri` field.
398292

399-
([Legacy Header Authentication](https://docs.docusign.com/esign/guide/authentication/legacy_auth.html) uses the X-DocuSign-Authentication header.)
293+
Note: The host for the OAuth::userInfo method is `account-d.docusign.com` for the demo/developer environment,
294+
and `account.docusign.com` for the production environments.
295+
1. Combine the base_uri with "/restapi" to create the basePath.
296+
Use the basePath for your subsequent API calls for the account id.
400297

401-
1. Use the [Authentication: login method](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/) to retrieve the account number **and the baseUrl** for the account.
402-
The url for the login method is www.docusign.net for production and demo.docusign.net for the developer sandbox.
403-
The `baseUrl` field is part of the `loginAccount` object. See the [docs and the loginAccount object](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/#/definitions/loginAccount)
404-
2. The baseUrl for the selected account, in production, will start with na1, na2, na3, eu1, or something else. Use the baseUrl that is returned to create the *basePath* (see the next step.) Use the basePath for all of your subsequent API calls.
405-
3. As returned by login method, the baseUrl includes the API version and account id. Split the string to obtain the *basePath*, just the server name and api name. Eg, you will receive `https://na1.docusign.net/restapi/v2/accounts/123123123`. You want just `https://na1.docusign.net/restapi`
406-
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
407-
5. Set the authentication header as shown in the examples by using `Configuration.Default.AddDefaultHeader`
408-
409-
## User Applications that use OAuth Authentication
410-
1. After obtaining a Bearer token, call the [OAuth: Userinfo method](https://docs.docusign.com/esign/guide/authentication/userinfo.html). Obtain the selected account's `base_uri` (server name) field.
411-
The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
412-
1. Combine the base_uri with "/restapi" to create the basePath. The base_uri will start with na1, na2, na3, eu1, or something else. Use the basePath for your subsequent API calls.
413-
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
414-
5. Create the `authentication_value` by combining the `token_type` and `access_token` fields you receive from either an [Authorization Code Grant](https://docs.docusign.com/esign/guide/authentication/oa2_auth_code.html) or [Implicit Grant](https://docs.docusign.com/esign/guide/authentication/oa2_implicit.html) OAuth flow.
415-
5. Set the authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`
298+
You can and should cache the basePath for at least the user's session with your application. It changes very infrequently.
299+
1. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
300+
1. Create the `authentication_value` by combining the `token_type` and `access_token` fields you
301+
receive from a DocuSign OAuth flow.
302+
See the [authentication guide.](https://developers.docusign.com/esign-rest-api/guides/authentication)
303+
1. Set the SDK's authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`
416304

417305
Testing
418306
=======
@@ -432,8 +320,7 @@ Feel free to log issues against this client through GitHub. We also have an act
432320
License
433321
=======
434322

435-
The DocuSign Node Client is licensed under the following [License](LICENSE).
436-
323+
The DocuSign Node Client is licensed under the MIT [License](LICENSE).
437324

438325
[npm-image]: https://img.shields.io/npm/v/docusign-esign.svg?style=flat
439326
[npm-url]: https://npmjs.org/package/docusign-esign

0 commit comments

Comments
 (0)