Java Launcher Code Examples

Github repo: https://github.com/docusign/code-examples-java

This GitHub repo includes code example for the DocuSign eSignature REST API, for the DocuSign Rooms API and for the Click API.

To use the Rooms API code examples, modify the DS_API_NAME setting at the end of the application.json file. Set the value to ROOMS. To use the Click API code examples, modify the DS_API_NAME setting at the end of the application.json file. Set the value to CLICK.

Note: to use the Rooms API you must also create your DocuSign Developer Account for Rooms.

This repo is a Java Spring Boot application that demonstrates how to authenticate with DocuSign via the Authorization Code Grant flow. When the token expires, the user is asked to reauthenticate. The refresh token is not used.

The Spring Boot security Oauth2 boot autoconfigure package is used for authentication.

The OAuth library is used in the file WebSecurityConfig.java.

For more information about the scopes used for obtaining authorization to use the eSignature API, see the Required Scopes section.

1. Use embedded signing.
   Source This example sends an envelope, and then uses embedded signing for the first signer. With embedded signing, DocuSign signing is initiated from your website.
2. Request a signature by email (Remote Signing).
   Source The envelope includes a pdf, Word, and HTML document. Anchor text (AutoPlace) is used to position the signing fields in the documents.
3. List envelopes in the user's account.
   Source
4. Get an envelope's basic information.
   Source The example lists the basic information about an envelope, including its overall status.
5. List an envelope's recipients and their current status.
   Source
6. List an envelope's documents.
   Source
7. Download an envelope's documents.
   Source This example can download individual documents, the documents concatenated together, or a zip file of the documents.
8. Programmatically create a template.
   Source
9. Request a signature by email using a template.
   Source
10. Send an envelope and upload its documents with multipart binary transfer.
    Source Binary transfer is 33% more efficient than using Base64 encoding.
11. Use embedded sending.
    Source
12. Embedded DocuSign web tool (NDSE).
    Source
13. Use embedded signing from a template with an added document.
    Source This example sends an envelope based on a template. In addition to the template's document(s), the example adds an additional document to the envelope by using the Composite Templates feature.
14. Payments example: an order form, with online payment by credit card.
    Source
15. Get the envelope tab data.
    Source Retrieve the tab (field) values for all of the envelope's recipients.
16. Set envelope tab values.
    Source The example creates an envelope and sets the initial values for its tabs (fields). Some of the tabs are set to be read-only, others can be updated by the recipient. The example also stores metadata with the envelope.
17. Set template tab values.
    Source The example creates an envelope using a template and sets the initial values or its tabs (fields). The example also stores metadata with the envelope.
18. Get the envelope custom field data (metadata).
    Source The example retrieves the custom metadata (custom data fields) stored with the envelope.
19. Requiring an Access Code for a Recipient
    Source This example sends and envelope that requires an access-code for the purpose of multi-factor authentication.
20. Requiring SMS authentication for a recipient
    Source This example sends and envelope that requires entering in a six digit code from an text message for the purpose of multi-factor authentication.
21. Requiring Phone authentication for a recipient
    Source This example sends and envelope that requires entering in a voice-based response code for the purpose of multi-factor authentication.
22. Requiring Knowledge-Based Authentication (KBA) for a Recipient
    Source This example sends and envelope that requires passing a Public records check to validate identity for the purpose of multi-factor authentication.
23. Requiring ID Verification (IDV) for a recipient
    Source This example sends and envelope that requires the recipient to upload a government issued id.
24. Creating a permission profile
    Source This code example demonstrates how to create a user group's permission profile using the Create Profile method.
25. Setting a permission profile
    Source This code example demonstrates how to set a user group's permission profile using the Update Group method. You must have already created permissions profile and group of users.
26. Updating individual permission settings
    Source This code example demonstrates how to update individual settings for a specific permission profile using the Update Permission Profile method. You must have already created permissions profile and group of users.
27. Deleting a permission profile
    Source This code example demonstrates how to an account's permission profile using the Delete AccountPermissionProfiles method.
28. Creating a brand
    Source This example creates brand profile for an account using the Create Brand method.
29. Applying a brand to an envelope
    Source This code example demonstrates how to apply a brand you've created to an envelope using the Create Envelope method. First, creates the envelope and then applies brand to it. Anchor text (AutoPlace) is used to position the signing fields in the documents.
30. Applying a brand to a template Source This code example demonstrates how to apply a brand you've created to a template using using the Create Envelope method. You must have at least one created template and brand.
31. Bulk sending envelopes to multiple recipients
    Source This example creates and sends a bulk envelope by generating a bulk recipient list and initiating a bulk send.
32. Pausing a signature workflow Source
    Source This code example demonstrates how to create an envelope where the workflow is paused before the envelope is sent to a second recipient.
33. Unpausing a signature workflow
    Source This code example demonstrates how to resume an envelope workflow that has been paused
34. Use conditional recipients
    Source This code example demonstrates how to create an envelope where the workflow is paused before the envelope is sent to a second recipient.
35. Request a signature by SMS delivery
    Source This code example demonstrates how to send a signature request via an SMS message using the Envelopes: create method.

For more information about the scopes used for obtaining authorization to use the Rooms API, see the Required Scopes section.

Note: To use the Rooms API you must also create your DocuSign Developer Account for Rooms. Examples 4 and 6 require that you have the DocuSign Forms feature enabled in your Rooms for Real Estate account.

1. Create room with Data.
   Source This code example creates a new room in your DocuSign Rooms account to be used for a transaction.
2. Create a room from a template.
   Source This code example creates a new room using a template.
3. Create room with Data.
   Source This code example exports all the avialalble data from a specific room in your DocuSign Rooms account.
4. Add forms to a room.
   Source This code example adds a standard real estate related form to a specific room in your DocuSign Rooms account.
5. How to search for rooms with filters.
   Source This code example searches for rooms in your DocuSign Rooms account using a specific filter.
6. Create an external form fillable session.
   Source This code example create an external form that can be filled using DocuSign for a specific room in your DocuSign Rooms account. This example create an external form that can be filled using DocuSign for a specific room in your DocuSign Rooms account.
7. Create a form group. Source. This code example create a form group for your DocuSign Rooms for Real Estate account.
8. Grant office access to a form group. Source. This code example assign an office to a form group for your DocuSign Rooms for Real Estate account. Granting office access to a form group will enable you to filter which form groups are available based on that office.
9. Assign a form to a form group. Source. This example demonstrates how to assign a form to a form group for your DocuSign Rooms for Real Estate account. As a prerequisite, ensure that you have created a form group and set the office ID on this form group before proceeding.

For more information about the scopes used for obtaining authorization to use the Click API, see the Required Scopes section

1. Create Clickwraps.
   Source This code example shows how to create a clickwrap.
2. Activate Clickwrap.
   Source This code example shows how to activate a new clickwrap that you have already created.
3. Clickwrap Versioning.
   Source This code example shows how to create a new clickwrap version.
4. Get a list of Clickwraps.
   Source This code example shows how to get a list of clickwraps.
5. Get Clickwrap Responses.
   Source This code example shows how to get clickwrap responses.

• Authentication with Docusign via Authorization Code Grant flow . When the token expires, the user is asked to re-authenticate. The refresh token is not used in this example.

• Authentication with DocuSign via the JSON Web Token (JWT) Grant. When the token expires, it updates automatically.

  Note: Before you can make any API calls using JWT Grant, you must get your user’s consent for your app to impersonate them. To do this, the impersonation scope is added when requesting a JSON Web Token.

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 2 below as it is automatically performed for you.

1. A DocuSign developer account (email and password) on demo.docusign.net. Create a free account.

2. A DocuSign Integration Key (a client ID) that is configured to use the OAuth Authorization Code flow. You will need the Integration Key itself, and its secret. To use JSON Web token, you will need the Integration Key itself, the RSA Secret Key and an API user ID for the user you are impersonating.

   If you use this launcher on your own workstation, the Integration key must include following Redirect URIs:

   • http://localhost:8080/login&type=acg
   • http://localhost:8080/login&type=jwt

   If you will not be running the launcher on your own workstation, use the appropriate DNS name and port instead of localhost:8080. A sample Redirect URI: http://myserver.it.mycompany.com/login

3. JDK 11 or later

4. Maven

5. A name and email for a signer, and a name and email for a cc recipient. The signer and the cc email cannot be the same.

6. Optional Lombok Annotations Processing configured for your IDE.

You will need the integration key and its secret. The integration key must include a redirect URI of

{app_url}/login&type=acg where {app_url} is the URL you have associated with the folder where the source files are located. For example, if you have created a web server that enables the URL

http://localhost:8080/

to execute files on the /public folder of this example, then you must add a redirect URI to your integration key with the value http://localhost:8080/login&type=acg

You will need the integration key, an RSA private key, and the user ID (GUID) of the impersonated user. The private part of the RSA key pair must be copied over and stored in a private.key file located in src\main\resources\private.key.

Note: Before you can make any API calls using JWT Grant, you must get your user’s consent for your app to impersonate them. To do this, the impersonation scope is added when requesting a JSON Web Token.

1. Download or clone this repository.
2. The project includes a Maven pom file.

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip the next step as it was automatically performed for you.

1. Configure the project by overriding necessary properties from the src\main\resources\application.example.json and saving this file as application.json file. Don't add this file into the Git index.
2. Add VM argument -Dspring.profiles.active=dev to your IDE
3. Note that IntelliJ IDEA Community Edition does not directly support Spring Boot applications.
4. [Optional] Install Lombok for your IDE (See the IntelliJ or Eclipse instructions below for specific details).

NOTE: If Lombok Annotations Processing is not installed in your IDE, you will see several errors regarding undefined methods. These methods are generated at compile time and do not otherwise impact the functionality of the launcher.

Launchers are built as a dedicated application with embedded TomCat server. Build:

$ cd code-examples-java
$ mvn package

Run:

$ java -Dspring.profiles.active=dev -jar target/code-examples-java-1.0-SNAPSHOT.war

The IntelliJ IDE Ultimate edition can be used with the launcher. The IntelliJ Ultimate edition is required due to its support for Spring Boot and JSP view pages.

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip Steps 1 and 2 as they were automatically performed for you.

1. Download or clone the code-examples-java repository.
2. Open the src\main\resources\application.example.json file.
   Configure the launcher by pasting the following data from your DocuSign developer account Apps and Keys page:
   DS_SIGNER_NAME (a string value for the Signer's name)
   DS_SIGNER_EMAIL (a string value for the Signer's email address)
   DS_TARGET_ACCOUNT_ID (the API Username in the Apps and Keys page)
   authorization.code.grant.client.client-id (Integration Key)
   authorization.code.grant.client.client-secret (Select the Actions button to the right of your Integration Key > Edit > Authentication > + ADD SECRET KEY > Secret Key)
   jwt.grant.client.client-id (Integration Key)
   wt.grant.client.impersonated-user-guid (API Username)
   Save this file as application.json
   Don't add this application.json file to your GitHub repo since it contains personal information.
3. Start IntelliJ Ultimate and choose the Open or Import option.
   
4. Use the popup file chooser to select code-examples-java or your unzipped Quickstart directory.
5. The Import Project wizard will open. It's a series of screens. On the first screen, select Import project from external model and Maven.
6. Click Finish and the project will be displayed in the IDE.

IntelliJ uses Run/Debug Configuration to manage settings for running the launcher.

Set up a Run/Debug Configuration for the launcher:

1. Use the menu command Run > Edit configurations...
   to open the configuration manager.

2. Click the + (plus) sign to add a new configuration. The configuration type is Spring Boot. You may need to open the additional templates section of the template chooser.

3. Update the form with the Name of the configuration to code-examples-java and the Main class for the configuration, com.docusign.App Tip: use the ... (ellipses) button next to the field to choose the Main class.

Under Spring Boot select the Enable debug output checkbox.

Select the OK button.

Use a Run menu option to run or debug the launcher.

After the application finishes building, open your browser to http://localhost:8080

Click File, then Settings. From there select Plugins. Open the Marketplace tab and type Lombok. It should have an author named Michail Plushnikov. Click install then restart IntelliJ.

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip Steps 1, 2, and 4.

1. Download or clone the code-examples-java repository.

2. Open the src\main\resources\application.example.json file.
   Configure the launcher by pasting the following data from your DocuSign developer account Apps and Keys page:
   DS_SIGNER_NAME (a string value for the Signer's name)
   DS_SIGNER_EMAIL (a string value for the Signer's email address)
   DS_TARGET_ACCOUNT_ID (the API Username in the Apps and Keys page)
   authorization.code.grant.client.client-id (Integration Key)
   authorization.code.grant.client.client-secret (Select the Actions button to the right of your Integration Key > Edit > Authentication > + ADD SECRET KEY > Secret Key)
   jwt.grant.client.client-id (Integration Key)
   wt.grant.client.impersonated-user-guid (API Username)
   Save this file as application.json
   Don't add this application.json file to your GitHub repo since it contains personal information.

3. Open Eclipse and select import. When the window appears, select the Maven folder, then select Existing Maven Project, and Browse for your Quickstart folder name or code-examples-java.

   1. Under Projects, the pom.xml file should be selected.
   2. Select the Add project(s) to working set checkbox to save the project link to your Eclipse workspace. Select Finish.

4. Next, select Run, then Run Configurations, and right-click Maven Build, then New Configuration to clean and compile:

   1. In the Name field, input: build
   2. In Base Directory, input: ${workspace_loc:/code-examples-java}
   3. In Goals, input: clean package
   4. Select the JRE tab. Under Runtime JRE, ensure it lists jdk-11 or higher. Select Apply to save.

5. In the Run Configurations dialog box, in the left sidebar, right-click Java Application, then New Configuration:

   1. In the Name field, input: App
   2. In the Project field, input: code-examples-java
   3. In the Main class field, input: com.docusign.App
   4. Select the JRE tab. Under Runtime JRE, ensure it lists jdk-11 or higher. Select Apply to save.
   5. Select Run to run the launcher. A browser window should automatically open to the consent page.

6. [Optional] Download the lombok.jar to your local machine. To install Lombok, open a terminal or command line. Run java -jar lombok.jar

To use the payments example, create a test payments gateway for your developer account. See the PAYMENTS_INSTALLATION.md file for instructions.

Then add the payment gateway account id to the application.json file.

This repository uses the MIT License. See the LICENSE file for more information.

Pull requests are welcomed. Pull requests will only be considered if their content uses the MIT License.