DocuSign Integration

Why DocuSign integration with Checkbox?

DocuSign integration allows e-signatures to be collected digitally through DocuSign and saved on the Checkbox platform.


Who can integrate DocuSign to Checkbox?

Enabling DocuSign requires action from a DocuSign Developer account holder and Checkbox Account Administrator. This enables DocuSign integration for all Reports the Checkbox Account Administrator has access to.

The following guide will assist you in setting up your DocuSign account to integrate with Checkbox platform.

Note: if you do not have a DocuSign Developer account, you can sign up for one here


DocuSign integration best practices

When connecting your Docusign account with Checkbox, it is best practice to connect both a Docusign Demo Integration Key and a Docusign Production Integration Key. Docusign Demo is used for testing purposes while Docusign Production is used for sending out live envelopes. 

 

How to enable the DocuSign Integration

Important Note: Checkbox and DocuSign must be open in the same browser in the following process.

 

Creating a Docusign Demo Key

In this initial step we will set up a demo docusign key. This key will later be promoted into the production key. As a final step, we will need to create a separate demo key.

  1. Login into your Docusign Demo Account via https://appdemo.docusign.com/
  2. Go to "Settings" at the top, followed by "My Apps & Keys" on the left
  3. Add App & Integration Key - Name it "Checkbox Primary Key"
  4. Open Checkbox DocuSign Demo Integration settings on another tab. This can be found in the admin panel (via your name in the top right hand corner) -> Integrations -> E-signature -> Docusign Demo
  5. Copy URL that the Checkbox platform provides for the DocuSign Demo Key
  6. Go back to DocuSign Platform - In the Demo integration settings, add the URL link from Checkbox into the URI section of the App key.
  7. Ensure that "Authorisation" is set to "Authorisation Code Grant" (It should be this way be default).
  8. Generate RSA and store it in a safe place (preferably a password saver). Save both the public and private keys - though you will only need the private key.
  9. Once you've (1) set the URI, (2) created a private key and saved it safely - click Save in DocuSign.
  10. Copy of the Integration key of the Docusign Demo Key. Store this safely you will need it for when you set this up in Checkbox.
  11. Capture DocuSign Demo User Account GUID - this is the user that will be sending out the e-signature envelopes. To find the User GUID - go to "Users" on the left hand side, click on the user, and there will be a unique GUID per user.
  12. Go back to Checkbox DocuSign Demo Integration settings
  13. Paste the User Account GUID, Integration Key and Private RSA Key. Make sure to include the lines "-----BEGIN RSA PRIVATE KEY-----", and "-----END RSA PRIVATE KEY-----" , and remove extra space/line that might be copied across from RSA Key.
  14. Click Save and then click Obtain Consent - make sure you are logged in to DocuSign Developer Account on the same browser
  15. If all goes well, it will bring you back to the Checkbox > Account Settings > Integration page with no other notification

 

Test Demo Configuration

  1. Configure ESIGN in a test app - Create a simple app with a FORM capturing email address, a DOCGEN, then ESIGN block. Having an Email Field on a FORM will allow you to Bulk Import in preparation for promotion to production.
  2. Promote your App to Test Version then initiate an Assessment from the Project Team. Note, DocuSign will not work in preview.
  3. Check Receipt of Envelopes. Sign and Complete Review. There should be a red watermark in the test documents.

 

Promoting Demo Key to Production

Docusign Production keys are Demo keys that have been promoted. For Checkbox, this means anytime we promote a Demo key to Production - we need to replace the old Demo key with a new Demo key.

  1. In preparation of promoting your Demo Docusign Key to Production, you need to initiate 20 successful API Calls. This must be consecutive, so the recommendation is to do this via Bulk Import for your test app - or by manually running 20 assessments.
  2. After you have run at least 20 assessments, log into your Docusign Sandbox account https://appdemo.docusign.com/
  3. Go to "Settings" at the top, followed by "My Apps & Keys" on the left
  4. Locate your Demo Key and click Actions > Start - Go-Live Review. The review may take 5-20 minutes to complete.
  5. Once the Review shows “Review Passed”, select Actions > Go-Live Account
  6. Select Production Account and click Next.
  7. It will ask you to login into your Production DocuSign Account (not Developer Account) and to accept Terms and Conditions
  8. Once Live, open a new tab and navigate to your Production DocuSign account (via https://app.docusign.com). Here we will need to re-connect the Production Details between DocuSign and Checkbox.
  9. Open Checkbox DocuSign Production Integration settings on another tab
  10. Copy URL from Checkbox
  11. Go back to DocuSign Production integration settings, add URL link shown in Checkbox into the URI section of the Docusign Production Key.
  12. Generate RSA and store it in a safe place (preferably a password saver). Save both the public and private keys - though you will only need the private key.
  13. Once you've (1) set the URI, (2) created a private key and saved it safely - click Save in DocuSign.
  14. Copy of the Integration key of the Docusign Production Key. Store this safely you will need it for when you set this up in Checkbox.
  15. Capture DocuSign Production User Account GUID - this is the user that will be sending out the e-signature envelopes. To find the User GUID - go to "Users" on the left hand side, click on the user, and there will be a unique GUID per user.
  16. Go back to Checkbox DocuSign Production Integration settings
  17. Paste the User Account GUID, Integration Key and Private RSA Key. Make sure to include the lines "-----BEGIN RSA PRIVATE KEY-----", and "-----END RSA PRIVATE KEY-----" , and remove extra space/line that might be copied across from RSA Key.
  18. Click Save and then click Obtain Consent - make sure you are logged in to DocuSign Production Admin environment on the same browser.
  19. If all goes well, it will bring you back to the Checkbox > Account Settings > Integration page with no other notification
  20. (This is a must) After you have set up the production key, you MUST create another demo key to overwrite the old Demo key settings. Follow Creating a Docusign Demo Key to create a new docusign demo key and overwrite the old Demo keys. You must obtain consent for the new demo key. If you do not overwrite the old demo key details with a new demo key - the production key will not work.

Test Production Configuration

⚠️ Warning! Generation of envelopes using the Docusign Production will entail a cost/usage to your envelope allowance. Having said that, to confirm that the Docusign Production settings are working, you may want to run 1~2 envelopes. Proceed with caution.

  1. Go back to your ESIGN test app and “Publish” the App
  2. Within the Project Team, click "Details" and make sure the production setting is set to "Docusign Production"
  3. Initiate an Assessment
  4. Check Receipt of Envelopes. Check that the document doesn’t have Demo Watermark. Sign and Complete Review.
  5. Go back to the Test Version of the ESIGN test app
  6. Check App Details and make sure it’s pointing to DocuSign Demo
  7. Initiate an Assessment.
  8. Check Receipt of Envelopes. Check that the Demo Watermark is back. Sign and Complete Review.

Other Notes:

  • DocuSign Account must have Admin permission during configuration
  • DocuSign User Account GUID configured in Checkbox must be logged in to DocuSign Admin console as well when obtaining consent. This has to be the same DocuSign Account in order for Obtain Consent to work.
  • DocuSign User Account GUID must be unique within DocuSign environment - the user account that will be used in Integration must only exist once within the DocuSign account (e.g. if you have setup DEV, SIT, and UAT environments, the GUID must only exist in one of the environments.)
  • The DocuSign user’s details will be reflected as sender details when an envelope is sent out. That is, the Name and Email of the GUID will be attached to all envelopes that go out.
  • The same DocuSign Demo Account must exist in DocuSign PROD with the same permission. It can be downgraded once the configuration is complete and tested working.