This repo is a Ruby on Rails application that demonstrates:
This launcher includes code examples for the following workflows:
-
Embedded Signing Ceremony. Source. This example sends an envelope, and then uses an embedded signing ceremony for the first signer. With embedded signing, the DocuSign signing ceremony is initiated from your website.
-
Send an envelope with a remote (email) signer and cc recipient. Source. The envelope includes a pdf, Word, and HTML document. Anchor text (AutoPlace) is used to position the signing fields in the documents.
-
List envelopes in the user's account. Source. The envelopes' current status is included.
-
Get an envelope's basic information. Source. The example lists the basic information about an envelope, including its overall status.
-
List an envelope's recipients Source. Includes current recipient status.
-
List an envelope's documents. Source.
-
Download an envelope's documents. Source. The example can download individual documents, the documents concatenated together, or a zip file of the documents.
-
Programmatically create a template. Source.
-
Send an envelope using a template. The example creates an envelope using a template and sets the initial values for some of its tabs (fields). Source.
-
Send an envelope and upload its documents with multpart binary transfer. Source. Binary transfer is 33% more efficient than using Base64 encoding.
-
Embedded sending. Source. Embeds the DocuSign web tool (NDSE) in your web app to finalize or update the envelope and documents before they are sent.
-
Embedded DocuSign web tool (NDSE). Source.
-
Embedded Signing Ceremony 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.
-
Payments example: an order form, with online payment by credit card. Source.
-
Get the envelope tab data. Retrieve the tab (field) values for all of the envelope's recipients. Source.
-
Set envelope tab values. 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. Source.
-
Set template tab values. The example creates an envelope using a template and sets the initial values for its tabs (fields). The example also stores metadata with the envelope. Source.
-
Get the envelope custom field data (metadata). The example retrieves the custom metadata (custom data fields) stored with the envelope. Source.
-
Requiring an Access Code for a Recipient Source. This example sends an envelope that requires an access-code for the purpose of multi-factor authentication.
-
Requiring SMS authentication for a recipient Source. This example sends an envelope that requires entering in a six digit code from an text message for the purpose of multi-factor authentication.
-
Requiring Phone authentication for a recipient Source. This example sends an envelope that requires entering in a voice-based response code for the purpose of multi-factor authentication.
-
Requiring Knowledge-Based Authentication (KBA) for a Recipient Source. This example sends an envelope that requires passing a Public records check to validate identity for the purpose of multi-factor authentication.
-
Requiring ID Verification (IDV) for a recipient Source. This example sends an envelope that requires the recipient to upload a government issued id.
-
Creating a permission profile Source. This code example demonstrates how to create a user group's permission profile using the Create Profile method.
-
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.
-
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.
-
Deleting a permission profile Source. This code example demonstrates how to an account's permission profile using the Delete AccountPermissionProfiles method. You cannot delete the Everyone nor the Administrator profile types as those are defaults.
-
Creating a brand Source. This example creates brand profile for an account using the Create Brand method.
-
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.
-
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.
-
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.
-
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: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip steps 1 and 2 below as they're automatically performed for you.
-
A DocuSign Developer Sandbox account (email and password) on demo.docusign.net. Create a free account.
-
A DocuSign Integration Key and secret key (a client ID). 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.
You will need the Integration Key itself, and its secret.
The Integration key must include a Redirect URI of
{base_url}/auth/docusign/callbackWhere
{base_url}is the url for the web app.By default, the rails app starts on url
http://localhost:3000So the default Redirect URI for your Integration Key is
http://localhost:3000/auth/docusign/callback -
Ruby version 2.7.1 or later. Or you can update the Gemfile to use other versions of Ruby.
-
A name and email for a signer, and a name and email for a cc recipient.
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip steps 4, 5, and 6 below as they're automatically performed for you.
-
Download or clone this repository to your workstation to directory code-examples-ruby
-
cd code-examples-ruby
-
Install the needed gems listed in the Gemfile:
Run bundler install
-
Copy the file config/appsettings.example.yml into a new file named config/appsettings.yml
-
Update the file config/appsettings.yml with the Integration Key and other settings. Note: The terms "client_id" and "Integration key" are synonyms. They refer to the same thing.
-
Update your Integration Key's settings to include a Redirect URI for your installation of the example. See Prerequisites item #2, above for more information.
-
To start the development web server and application:
Run rails s Note that on Windows additional actions might be necessary:
- Install sqlite3: gem install sqlite3 --platform=ruby
- Download curllib.dll (https://curl.haxx.se/windows/)
- libcurl-x64.dll should be copied as libcurl.dll
- Place curllib.dll into Ruby
C:\\<Ruby installation>\bin
-
Open a browser to the example's base url to view the index page.
- Create a developer sandbox account on developers.docusign.com if you don't already have one.
- Create a new API key in the Admin panel: https://admindemo.docusign.com/api-integrator-key
- Take note of the Integration Key.
- Generate a RSA Keypair and copy the private key to a secure location.
- Set a Redirect URI of
http://localhost:3000/auth/docusign/callbackas mentioned in the installation steps above.
- Create a new file in the config folder named docusign_private_key.txt, and paste in that copied RSA private key, then save it.
- Update the file config/appsettings.yml and include the settings from step 2.
Obtaining consent does not need to be configured, as it is already being done in the code at JwtAuth::JwtCreator#update_token
From there you should be able to run the launcher using bundle exec rails server then selecting JSON Web Token when authenticaing your account.
To use the payments example, create a test payments gateway for your developer sandbox account.
See the PAYMENTS_INSTALLATION.md file for instructions.
Then add the payment gateway account id to the config/application.rb file.
The examples in this repository can also be used with the Implicit grant OAuth flow. See the Authentication guide for information on choosing the right authentication flow for your application.
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.