DocuSign Element

Authentication 

The DocuSign element uses three authentication workflows - Oauth2, JWTOauth2 and Oauth2password. You can authenticate an element instance using the UI or via API calls. For detailed information on how to authenticate an instance, see our related documentation:

• Authenticate an Element Instance (UI)
• Authenticate an Element Instance (API)

All three workflows are discussed in detail further in this article. 

Oauth2

1. Sign in to https://developers.docusign.com/ to procure the API key and API secret from the administrator dashboard.
   
2. You may need to create an app to get the credentials required for authentication. While creating the app, the redirect URI should be https://auth.cloudelements.io/oauth.

You can find more details at How to get an access token - DocuSign.

Required Parameters

To authenticate an instance of the DocuSign element using Oauth2, you will need the following parameters:

Sample Configuration JSON

"configuration": {
    "docusign.environment": "demo",
    "authentication.type": "MyUsername",
    "oauth.api.key": "MyUsername",
    "oauth.api.secret": "MyUsername",
  }

JWTOauth2

To authenticate an instance of the DocuSign element using JWTOauth2, you will need to sign in to https://developers.docusign.com/ and check for details on https://developers.docusign.com/platform/auth/jwt/jwt-get-token/.

Required Parameters

Create a JWT Base64 Encoded Key

JWT Base64 Encoded Key is a Base64 encoded private key. Here is how you can get the value:

1. Create the private key.
   openssl genrsa -des3 -out private.pem 2048;
2. Create the public key.
   openssl rsa -in private.pem -outform PEM -pubout -out public.pem;
3. Convert the private key to PKCS8 and DER format (for the Java code base to read).
   openssl pkcs8 -topk8 -inform PEM -outform DER -in private.pem -out private_key_pkcs8.der -nocrypt;
4. Base64 encode the private key.
   cat private_key_pkcs8.der | base64 > base64Key.pem;
5. Create a certificate and sign it with the private key.
   openssl req -new -x509 -key private.pem -out cacert.pem -days 1095;
6. After running the steps above, you must provide an instance as public.pem and base64Key.pem
   Upload the file from the public pem of the Public key in your application as shown here and then use the file from base64Key.pem as jwtBase64EncodedKey.

Sample Configuration JSON

"configuration": {
    "docusign.environment": "demo",
    "filter.response.nulls": "true",
    "authentication.type": "jwtOauth2",
    "synchronous.bulk.notification": "true",
    "jwt.base64.encoded.key": "xxxxxxxx",
    "jwt.claim.iss": "xxxxxxxxxx",
    "oauth.api.key": "xxxxxxxx",
    "jwt.claim.sub": "xxxxxxxxx"
  }

Oauth2 Password

1. Sign in to https://developers.docusign.com/ to procure the API key from the administrator dashboard.
   
2. You may need to create an app to get the credentials required for authentication. While creating the app, the redirect URI should be https://auth.cloudelements.io/oauth.

You can find more details at Implicit Grant Authentication - DocuSign.

Required Parameters

Sample Configuration JSON

"configuration": {
    "docusign.environment": "demo",
    "filter.response.nulls": "true",
    "authentication.type": "oauth2password",
    "synchronous.bulk.notification": "true",
    "username": "xxxxxxxxxx",
    "oauth.api.key": "xxxxxxxx",
    "password": "xxxxxxxxx"
  }

Optional Authentication Parameters

These are the optional parameters you will need, to authenticate an element instance via any of the methods discussed above.

Element Fact Sheet and Reference

Authentication and Configuration Parameters

To see all authentication parameters for the DocuSign element, follow these steps:

1. Sign in to Cloud Elements and navigate to Elements.
2. Hover over the card for , and then click My Resources.
                                                                                                    
3. In the top navigation toolbar, click Setup.
4. From the Setup page, you can view a complete list of the element's authentication and configuration parameters.

Element Resources

In order to provide users with normalized APIs across Hubs, Cloud Elements resources were mapped to the following Vendor resources.

Events and Supported Resources

The DocuSign element supports events via polling and webhooks. For detailed information about our Events framework and how to configure an element instance with events, see our documentation:

• Authenticate an Element Instance with Events (UI)
• Authenticate an Element Instance with Events (API)

You can set up polling events for only the /envelopes resource of the DocuSign element:

The DocuSign element supports all other events via webhooks.

The optional configurations for events via webhooks are as shown below.

Bulk

Bulk provides an option to upload a large number of resources, such as users, to a service provider all at once. You can use bulk to download a .csv or .json file from a large number of records or upload a .csv or .json file to add multiple records. See Using Bulk for more information on managing bulk.

• To make a POST/bulk/query bulkv2 API call with a query, select * from signing-groups and check the results of a bulk job.

• 
  

• Retrieve the results of the bulk job in both .csv and  .json format. Notice that in .json the created and modified date/times do not show as expected and have an extra \\ appended for both the fields.

• This exists only in .json, as the created & modified dates/times show up as expected in csv format.

Bulk Details

Querying

The Cloud Elements Query Language ( CEQL ) provides a standard way to search across all of our elements. Rather than having users research how to query each resource at a provider, we've normalized your search experience. Cloud Elements translates your queries to the API provider's search syntax. CEQL represents the "where" portion of a typical query that can include many other components like field selection, sorting, and pagination. For more information on querying, see Querying with CEQL.

To determine whether where clause is supported for an object, you can make an API call to object/{objectName}/metadata while providing the Element version and check for "filterable"="true".

A few examples for usage of the where clause:

• /envelopes?where=from_date='2020-07-02T13:41:00Z'
• /envelopes?where=from_date='2020-12-16T19:20:30.45+01:00' and envelopeId='d3f1a749-37e6-4a09-bc1c-70802a968f81'
• /envelopes?where=from_date='2000-12-16T19:20:30.45+01:00' and status='sent'

There are several operators that are valid to be used for querying. You can find more details on them here. But each object which has "filterable"="true",  can also tell you what operators can be used for that particular filterable.

Element Extension

Element Builder gives you the integration tools to extend the current feature set of any of our elements by adding a resource or method. If your use case requires a resource our element doesn’t currently support, you can easily add it in yourself using Element Builder. DocuSign is an extendable element and therefore, you can customize it according to your needs. 

For more details, read the Extend Elements article which gives a description in detail as to how it can be done.

Discovery APIs

Discovery APIs  are usually used in conjunction with a specific authenticated element instance to:

• Identify data objects in an element
• Identify data objects and their source (the vendor, a VDR, or Cloud Elements library)
• Find metadata, including custom fields, related to an object
• Retrieve the Open API specifications (API docs) of an object

However, Discovery APIs are not supported by Cloud Elements for the DocuSign element, as there is no support by the vendor for the same. However, we do support the discovery of objects that are part of our implementation.

Element API Documentation

The base URL for all API requests is https://api.cloud-elements.com/elements/api-v2.

Provider Documentation

• DocuSign API Documentation