Integration of a DocuSign service in Scala

Table of contents

Reading Time: 2 minutes

DocuSign is the leading eSignature solution firm. Its cloud-based platform for automating the agreement process enables more than 370,000 companies and hundreds of millions of users in over 180 countries to accelerates business and simplify life.

DocuSign have a rich rest API interface and also have a SDK supports for many different languages like Java, C# , PHP etc. We can use these APIs to create and upload document, envelop and Templates on DocuSign server. Before going to do this, we need to setup a sandbox environment on DocuSign server. Basically, DocuSign provides a sandbox dev environment where you can test your application thoroughly. It is free of cost, so I would recommend to test your application in sandbox environment prior to the prod deployment.

Please go through this link to create a sandbox dev account in DocuSign server. After creation of an account, you would required to setup an authentication & authorization process with the DocuSign server for integration of your service with it. In DocuSign, it supports three type of authentications mechanism:

Authorization Code Grant: The Authorization Code Grant is an OAuth 2.0 flow that is used to grant an access token to server-hosted applications.
Implicit Grant: The Implicit Grant is an OAuth 2.0 flow that is used to grant an access token to user applications that are native to mobile devices.
JWT Grant: The JSON Web Token (JWT) grant is an OAuth 2.0 flow that is used to grant an access token to service integrations.

For more info on DocuSign authentication process. Please follow this link. To integrate the DocuSign service to our application. I have created a sample project in Scala. So once the setup and authentication process complete, we would require to put all essential credentials in application.conf file. It looks like this.

"knoldus": {
"ds_client_id" : "",
"ds_impersonated_id": "",
"ds_auth_server": "account-d.docusign.com",
"account_id": "",
"token_expiration_in_seconds": 3600,
"ds_private_key":"",
"base_path": "https://demo.docusign.net/restapi"
}

The following keys, we would required to put in application.conf:

ds_client_id: It is an integration key of your registered app on DocuSign server.
ds_impersonated_id: It is a user id for the DocuSign APIs.
account_id: This is an id of your sandbox dev account.
ds_private_key: This is a RSA private key of your DocuSign application.

Now, we have to create a JWT token with help of the above credentials prior to upload any document or template on server. For that, we have created a Scala method.

def createAndSetJWTAcessToken(clientCredentials: DocuSignCredentials): Try[OAuth.OAuthToken] = {
    Try {
      apiClient.setOAuthBasePath(clientCredentials.dsAuthServer)
      val oAuthToken = apiClient.requestJWTUserToken(
        clientCredentials.dsClientId,
        clientCredentials.dsImpersonatedId,
        List(OAuth.Scope_SIGNATURE).asJava,
        clientCredentials.dsPrivateKey.getBytes,
        clientCredentials.tokenExpirationInSeconds)
      apiClient.setAccessToken(oAuthToken.getAccessToken,
      oAuthToken.getExpiresIn)
      apiClient.setBasePath(clientCredentials.basePath)
      oAuthToken
    }
  }

Once we got a valid JWT token then we can upload any document and DocuSign will automatically put the user or organization eSignature on uploaded document.

You can also see the uploaded and signed documents on DocuSign server. For this you have to log in to account and go to template section to see the list of uploaded document.

The full DocuSign integration source code is available here.

Stay Tunes, happy learning !!!

References: