Skip to content

Commit 62094a1

Browse files
author
Majid Mallis
committed
Updated the documentation to use the new getUserInfo method
1 parent 3a58234 commit 62094a1

File tree

1 file changed

+105
-111
lines changed

1 file changed

+105
-111
lines changed

‎README.md‎

Lines changed: 105 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -80,108 +80,102 @@ This client is available through the following Java package managers:
8080
Usage
8181
=====
8282

83-
To send a signature request from a Template using 3-legged OAuth:
83+
To send a signature request from a Template using OAuth Authorization Code Grant:
8484

8585
```java
8686
import com.docusign.esign.api.*;
8787
import com.docusign.esign.client.*;
8888
import com.docusign.esign.model.*;
89-
import com.docusign.esign.client.auth.AccessTokenListener;
90-
91-
import org.apache.oltu.oauth2.common.token.BasicOAuthToken;
89+
import com.docusign.esign.client.auth.OAuth;
90+
import com.docusign.esign.client.auth.OAuth.UserInfo;
9291
import java.awt.Desktop;
9392

93+
import java.io.IOException;
94+
9495
public class DocuSignExample {
9596
public static void main(String[] args) {
9697
String RedirectURI = "[REDIRECT_URI]";
9798
String ClientSecret = "[CLIENT_SECRET]";
9899
String IntegratorKey = "[INTEGRATOR_KEY]";
99100
String BaseUrl = "https://demo.docusign.net/restapi";
100-
String OAuthBaseUrl = "https://account-d.docusign.com";
101101

102-
ApiClient apiClient = new ApiClient(OAuthBaseUrl, "docusignAccessCode", IntegratorKey, ClientSecret);
103-
apiClient.setBasePath(BaseUrl);
104-
// make sure to pass the redirect uri
105-
apiClient.configureAuthorizationFlow(IntegratorKey, ClientSecret, RedirectURI);
106-
Configuration.setDefaultApiClient(apiClient);
102+
ApiClient apiClient = new ApiClient(BaseUrl);
107103
try
108104
{
109-
// get DocuSign OAuth authorization url
110-
String oauthLoginUrl = apiClient.getAuthorizationUri();
111-
// open DocuSign OAuth login in the browser
112-
System.out.println(oauthLoginUrl);
113-
Desktop.getDesktop().browse(URI.create(oauthLoginUrl));
114-
// IMPORTANT: after the login, DocuSign will send back a fresh
115-
// authorization code as a query param of the redirect URI.
116-
// You should set up a route that handles the redirect call to get
117-
// that code and pass it to token endpoint as shown in the next
118-
// lines:
119-
String code = "<once_you_get_the_oauth_code_put_it_here>";
120-
// assign it to the token endpoint
121-
apiClient.getTokenEndPoint().setCode(code);
122-
// optionally register to get notified when a new token arrives
123-
apiClient.registerAccessTokenListener(new AccessTokenListener() {
124-
@Override
125-
public void notify(BasicOAuthToken token) {
126-
System.out.println("Got a fresh token: " + token.getAccessToken());
105+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
106+
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
107+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
108+
109+
String randomState = "[random_string]";
110+
java.util.List<String> scopes = new java.util.ArrayList<String>();
111+
scopes.add(OAuth.Scope_SIGNATURE);
112+
// get DocuSign OAuth authorization url
113+
URI oauthLoginUrl = apiClient.getAuthorizationUri(IntegratorKey, scopes, RedirectURI, OAuth.CODE, randomState);
114+
// open DocuSign OAuth login in the browser
115+
Desktop.getDesktop().browse(oauthLoginUrl);
116+
// IMPORTANT: after the login, DocuSign will send back a fresh
117+
// authorization code as a query param of the redirect URI.
118+
// You should set up a route that handles the redirect call to get
119+
// that code and pass it to token endpoint as shown in the next
120+
// lines:
121+
/*String code = "[once_you_get_the_oauth_code_put_it_here]";
122+
OAuth.OAuthToken oAuthToken = apiClient.generateAccessToken(IntegratorKey, ClientSecret, code);
123+
124+
System.out.println("OAuthToken: " + oAuthToken);
125+
126+
// now that the API client has an OAuth token, let's use it in all
127+
// DocuSign APIs
128+
UserInfo userInfo = apiClient.getUserInfo(oAuthToken.getAccessToken());
129+
130+
System.out.println("UserInfo: " + userInfo);
131+
// parse first account's baseUrl
132+
// below code required for production, no effect in demo (same
133+
// domain)
134+
apiClient.setBasePath(userInfo.getAccounts().get(0).getBaseUri() + "/restapi");
135+
Configuration.setDefaultApiClient(apiClient);
136+
String accountId = userInfo.getAccounts().get(0).getAccountId();*/
137+
138+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
139+
// *** STEP 2: CREATE ENVELOPE FROM TEMPLATE
140+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
141+
142+
// create a new envelope to manage the signature request
143+
EnvelopeDefinition envDef = new EnvelopeDefinition();
144+
envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
145+
146+
// assign template information including ID and role(s)
147+
envDef.setTemplateId("[TEMPLATE_ID]");
148+
149+
// create a template role with a valid templateId and roleName and assign signer info
150+
TemplateRole tRole = new TemplateRole();
151+
tRole.setRoleName("[ROLE_NAME]");
152+
tRole.setName("[SIGNER_NAME]");
153+
tRole.setEmail("[SIGNER_EMAIL]");
154+
155+
// create a list of template roles and add our newly created role
156+
java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
157+
templateRolesList.add(tRole);
158+
159+
// assign template role(s) to the envelope
160+
envDef.setTemplateRoles(templateRolesList);
161+
162+
// send the envelope by setting |status| to "sent". To save as a draft set to "created"
163+
envDef.setStatus("sent");
164+
165+
// instantiate a new EnvelopesApi object
166+
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
167+
168+
// call the createEnvelope() API
169+
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
170+
}
171+
catch (ApiException ex)
172+
{
173+
System.out.println("Exception: " + ex);
174+
}
175+
catch (Exception e)
176+
{
177+
System.out.println("Exception: " + e.getLocalizedMessage());
127178
}
128-
});
129-
// ask to exchange the auth code with an access code
130-
apiClient.updateAccessToken();
131-
132-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
133-
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
134-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
135-
136-
AuthenticationApi authApi = new AuthenticationApi(apiClient);
137-
LoginInformation loginInfo = authApi.login();
138-
139-
// parse first account ID (user might belong to multiple accounts) and baseUrl
140-
String accountId = loginInfo.getLoginAccounts().get(0).getAccountId();
141-
String baseUrl = loginInfo.getLoginAccounts().get(0).getBaseUrl();
142-
String[] accountDomain = baseUrl.split("/v2");
143-
144-
// below code required for production, no effect in demo (same domain)
145-
apiClient.setBasePath(accountDomain[0]);
146-
Configuration.setDefaultApiClient(apiClient);
147-
148-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
149-
// *** STEP 2: CREATE ENVELOPE FROM TEMPLATE
150-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
151-
152-
// create a new envelope to manage the signature request
153-
EnvelopeDefinition envDef = new EnvelopeDefinition();
154-
envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
155-
156-
// assign template information including ID and role(s)
157-
envDef.setTemplateId("[TEMPLATE_ID]");
158-
159-
// create a template role with a valid templateId and roleName and assign signer info
160-
TemplateRole tRole = new TemplateRole();
161-
tRole.setRoleName("[ROLE_NAME]");
162-
tRole.setName("[SIGNER_NAME]");
163-
tRole.setEmail("[SIGNER_EMAIL]");
164-
165-
// create a list of template roles and add our newly created role
166-
java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
167-
templateRolesList.add(tRole);
168-
169-
// assign template role(s) to the envelope
170-
envDef.setTemplateRoles(templateRolesList);
171-
172-
// send the envelope by setting |status| to "sent". To save as a draft set to "created"
173-
envDef.setStatus("sent");
174-
175-
// instantiate a new EnvelopesApi object
176-
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
177-
178-
// call the createEnvelope() API
179-
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
180-
}
181-
catch (com.docusign.esign.client.ApiException ex)
182-
{
183-
System.out.println("Exception: " + ex);
184-
}
185179
}
186180
}
187181
```
@@ -192,8 +186,9 @@ To send a signature request from a Template using JWT Auth (for service integrat
192186
import com.docusign.esign.api.*;
193187
import com.docusign.esign.client.*;
194188
import com.docusign.esign.model.*;
189+
import com.docusign.esign.client.auth.OAuth;
190+
import com.docusign.esign.client.auth.OAuth.UserInfo;
195191

196-
import java.util.List;
197192
import java.io.IOException;
198193

199194
public class DocuSignExample {
@@ -209,6 +204,10 @@ public class DocuSignExample {
209204
ApiClient apiClient = new ApiClient(BaseUrl);
210205

211206
try {
207+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
208+
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
209+
/////////////////////////////////////////////////////////////////////////////////////////////////////////
210+
212211
// IMPORTANT NOTE:
213212
// the first time you ask for a JWT access token, you should grant access by making the following call
214213
// get DocuSign OAuth authorization url:
@@ -218,23 +217,18 @@ public class DocuSignExample {
218217
// END OF NOTE
219218

220219
apiClient.configureJWTAuthorizationFlow(publicKeyFilename, privateKeyFilename, OAuthBaseUrl, IntegratorKey, UserId, 3600); // request for a fresh JWT token valid for 1 hour
221-
Configuration.setDefaultApiClient(apiClient);
222-
223-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
224-
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
225-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
226-
227-
AuthenticationApi authApi = new AuthenticationApi();
228-
LoginInformation loginInfo = authApi.login();
229-
230-
// parse first account ID (user might belong to multiple accounts) and baseUrl
231-
String accountId = loginInfo.getLoginAccounts().get(0).getAccountId();
232-
String baseUrl = loginInfo.getLoginAccounts().get(0).getBaseUrl();
233-
String[] accountDomain = baseUrl.split("/v2");
234220

235-
// below code required for production, no effect in demo (same domain)
236-
apiClient.setBasePath(accountDomain[0]);
221+
// now that the API client has an OAuth token, let's use it in all
222+
// DocuSign APIs
223+
UserInfo userInfo = apiClient.getUserInfo(apiClient.getAccessToken());
224+
225+
System.out.println("UserInfo: " + userInfo);
226+
// parse first account's baseUrl
227+
// below code required for production, no effect in demo (same
228+
// domain)
229+
apiClient.setBasePath(userInfo.getAccounts().get(0).getBaseUri() + "/restapi");
237230
Configuration.setDefaultApiClient(apiClient);
231+
String accountId = userInfo.getAccounts().get(0).getAccountId();
238232

239233
/////////////////////////////////////////////////////////////////////////////////////////////////////////
240234
// *** STEP 2: CREATE ENVELOPE FROM TEMPLATE
@@ -281,9 +275,17 @@ See [SdkUnitTests.java](https://github.com/docusign/docusign-java-client/blob/ma
281275

282276
# Authentication
283277

284-
## Service Integrations that use Legacy Header Authentication
278+
## User Applications that use OAuth Authentication
279+
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.
280+
The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
281+
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.
282+
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
283+
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.
284+
5. Set the authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`
285285

286-
([Legacy Header Authentication](https://docs.docusign.com/esign/guide/authentication/legacy_auth.html) uses the X-DocuSign-Authentication header.)
286+
## Service Integrations that use the Deprecated Header Authentication
287+
288+
([Deprecated Header Authentication](https://docs.docusign.com/esign/guide/authentication/legacy_auth.html) uses the X-DocuSign-Authentication header. Please switch to OAuth ASAP.)
287289

288290
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.
289291
The url for the login method is www.docusign.net for production and demo.docusign.net for the developer sandbox.
@@ -293,14 +295,6 @@ The `baseUrl` field is part of the `loginAccount` object. See the [docs and the
293295
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
294296
5. Set the authentication header as shown in the examples by using `Configuration.Default.AddDefaultHeader`
295297

296-
## User Applications that use OAuth Authentication
297-
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.
298-
The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
299-
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.
300-
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
301-
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.
302-
5. Set the authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`
303-
304298

305299
Testing
306300
=======

0 commit comments

Comments
 (0)