DocuSign - How to automatically import completed envelopes into ImageNow/Perceptive Content

DocuSign eSignature, ImageNow/Perceptive Content

There are two methods of automatically importing completed DocuSign envelopes into ImageNow/Perceptive Content, and both of these methods are dependent upon very specific conditions. There is no departmental cost associated with either of the methods. Option 2, in particular, will likely depend upon a new template for a new DocuSign process: it is exceedingly unlikely that Option 2 will be able to identify, retrieve, and properly import any existing/historical envelopes from DocuSign.

Please thoroughly review the information presented here so that you may examine your DocuSign process and determine which of the two methods is best suited to your use case. The following overview expects that you already have an ImageNow solution in place. If you wish to pull completed envelopes into ImageNow but do not currently have an ImageNow solution, you must contact imagenow@vcu.edu to plan and develop the ImageNow solution first.

Additionally, please note that, when requesting either of the import solutions, please provide us with the template name or direct link to the template, not the PowerForm URL.

Documenting Your Procedures and Processes

All departments are responsible for documenting ImageNow and DocuSign business processes/procedures for business continuity and staff training on your specific processes, whether for an integration or not. Please use the following ImageNow departmental procedures and training template to document your processes and procedures:

Template for ImageNow/Perceptive Content Departmental Procedures and Training

It is expected that your DocuSign template creator has completed all of the training courses in the VCU DocuSign Training Roadmap, and that your template creator regularly reviews the Roadmap for updates and best practices:

VCU DocuSign Training Roadmap

Option 1: Dedicated Generic/Departmental Email Account for an ImageNow Email Integration

By far the simplest and fastest method is to have all completed DocuSign email notifications copied or forwarded to a generic email account dedicated to your DocuSign processes. The ImageNow email agent will pull all email messages from a specific VCU GMail account and import them into one ImageNow queue. VCU DocuSign administration (docusign@vcu.edu) is not involved in the email integration. All aspects of the email integration are managed by ImageNow administration personnel (imagenow@vcu.edu).

Importing the documents into ImageNow from a GMail account is essentially an all-or-nothing proposition: we have no method of being able to differentiate envelopes as belonging to this import process versus personal information from HR, Payroll, etc., and so an individual’s @vcu.edu email account is by no means suitable. You must have a generic/departmental account that is solely used as the destination for Completed departmental DocuSign email notifications that you wish imported into ImageNow as part of this process. All email messages and their attachments are pulled from the generic email account into a single ImageNow workflow queue so that you may perform all additional indexing and routing of the document. Please note that this means the completed PDF attachment is pulled from the generic email account (i.e., from GMail): it is not pulled directly from the DocuSign account. Again, this method pulls all email from the GMail account, so if you were using this particular email account for general Q&A, those emails would also be pulled into ImageNow. You must have a generic email account that is used solely as the landing account for all completed DocuSign email messages for this process. Remember that all messages from a single email account will be pulled into one ImageNow queue. If you have two different DocuSign forms that you wish to pull into two different ImageNow queues, you would have to have two different generic email accounts.

If all of the completed email notifications and their attachments are already only in your personal @vcu.edu email account, you will have to manually identify those, manually download them, and manually import them into ImageNow. You may also be able to forward each one to the generic email account in question, allow the ImageNow email agent to retrieve them, and then perform any indexing in ImageNow. Completed envelopes that reside in the generic account going forward will automatically be pulled into ImageNow via the ImageNow email agent (depending on the size. Please see the Limitations below).

Benefits

• Your department may use the same generic DocuSign account for all departmental envelopes that you will be manually indexing in ImageNow.
  
  
• Setup for this process is managed entirely by imagenow@vcu.edu

Limitations

• +5MB attachments - DocuSign omits attachments if the file size exceeds 5MB, and there is a maximum limit of 15 documents that can be attached to the completed email. This solution depends upon being able to pull the attachments from the generic email account, not from the DocuSign account. Envelopes whose attachments exceeded 5MB will not be in the email account: those envelopes must be manually identified in the Inbox or workflow queue then transferred from the generic account’s DocuSign account using the ImageNow Printer, import, or drag-n-drop features. Additional details: https://docs.google.com/document/d/1NqhhSr2vhfmMAdoX7BmRTKZGrdxpgKW7ZOL444kdOb0/edit#heading=h.6s72boponfbu
  
  
• Indexing - ImageNow email capture will receive Sender and Email Subject Line information, but DocuSign field data cannot be used for automated indexing when added to workflow. Your department will manually index all documents imported by this process. Please note that exceedingly long email subject lines will be truncated, so it may be best to avoid including “Please DocuSign:” at the beginning of your email subject lines. You could include it at the end of the email subject line, however.

Special Note for Consideration

While this method does not perform any type of automated indexing of DocuSign envelopes/documents in ImageNow, it is strongly recommended that you get into the habit of customizing all of your DocuSign form’s data labels: https://docs.google.com/document/d/1BwE3x0Tju5tqfpv6KHK_-fwcNwVTKzbrGs0kCiovTYc/edit#bookmark=id.6m60f8y0o7y8

Requirements

• IT service desk request https://go.vcu.edu/ramscentral to Collaboration Services for a new generic email account https://collaborate.vcu.edu/generic-accounts/
  
  
• An existing or new ImageNow implementation for this specific use-case. To request a new ImageNow solution, please submit an IT service desk https://go.vcu.edu/ramscentral request to ImageNow detailing the purpose of the solution.
  
  
• IT service desk request https://go.vcu.edu/ramscentral to connect new email account to ImageNow
  
  
• DocuSign template/envelope must either include the generic account as a Carbon Copy at the end of the signature process, or–in the case of a PowerForm–the generic account should be the PowerForm sender so that completed envelopes are returned to the generic account for business continuity.
  
  
• Requesting department will update their procedures for business continuity https://collaborate.vcu.edu/apps/imagenow/end-user-procedures/

Option 2. ImageNow iScript/DocuSign eSignature REST API hybrid: Automatic Import of Completed Envelopes into ImageNow and Automatic Indexing of Key Fields in ImageNow

Note that this is not a traditional API solution, as it involves a hybrid of ImageNow iScript and REST API.

It is assumed that your DocuSign template creator has completed all of the training courses in the VCU DocuSign Training Roadmap, and that your template creator regularly reviews the Roadmap for updates and best practices:

VCU DocuSign Training Roadmap

This option would ordinarily expect a high volume of Completed envelopes per year for the specific type of records being imported into ImageNow. Given how the API identifies Completed envelopes, it is very likely that this would only work for a brand new DocuSign solution so that we can arrive at a unique code to include in the Completed email subject line of the envelopes to be retrieved. If you are attempting to import existing/historical envelopes, this type of integration will probably not be feasible. Any historical envelopes would have to be manually imported into ImageNow by your department's personnel.

Considerations:

• It is expected that any DocuSign-ImageNow integration is for a brand new DocuSign template and its forthcoming envelopes, not for historical envelopes in the DocuSign system. There are a variety of things worked out during the design/development process, particularly the crucial piece: the Completed email subject line. Data labels could also be a consideration.
• The API script (i.e., the ImageNow iScript responsible for executing API calls to DocuSign, identifying Completed envelopes, retrieving them, and importing them into ImageNow) relies exclusively on a unique, contiguous sequence of up to 48 characters in the email subject line of the Completed envelopes. It does not search a specific end-user account in DocuSign or a specific template or PowerForm: it is concerned solely with Completed envelopes in account ID #11599208, meaning that it retrieves all envelopes in the standard VCU enterprise DocuSign account (regardless as to the actual end-user sending account, and regardless as to what template or standalone envelope was used) with that sequence of characters in the email subject line. The contiguous sequence of characters in the Completed email subject line cannot contain certain characters such as:  \, /, (, ) There may be others that we haven’t yet identified. 
• Because the email subject line is the unique key to identifying envelopes, it is required that a unique code be included in the email subject line (all of this would be worked out during the initial design/testing on DocuSign Demo). The code could be something such as an abbreviation of the school/department/process and a numerical value/form number, e.g.: SOFSDR001. Historical envelopes may have Completed email subject lines so generic that there is simply no method of separating them from the masses (for example, there are over 30 templates across multiple departments/schools that contain the words “new hire” in the email subject line and little else to help separate them, so every envelope across the entire university with “new hire” in the subject line would be pulled into ImageNow). DocuSign is a solution for electronic signatures on legally-immutable agreements or contracts, so there is, naturally, no method of changing anything about Completed legal documents after all signatories have signed. No code/string of text could be added to a Completed envelope in DocuSign to help identify/separate it from the masses: the contract has been etched in stone.

The API is by far the most complex and time consuming process for creating, testing, and moving into production a method of automatically importing completed envelopes and their attachments https://developers.docusign.com/docs/esign-rest-api/. DocuSign has strict requirements for creation of an integration key, testing the integration, and promoting the integration to the production DocuSign environment. There is NO method of bypassing either DocuSign’s testing requirements or the amount of time it may take for both the development and testing of the integration, and the promotion of the integration key and its scripts to production. This option also requires you to have a dedicated generic account for this process. This option pulls all completed envelopes and their attachments directly from DocuSign, so there is no 5MB limit involved in this process.

Please note that Document Management (i.e., DocuSign and ImageNow) staff do not have extensive experience with the REST API. Additionally, as this is an integration with ImageNow, the API has certain limitations due to the use of ImageNow iScripts for the process. All testing and development must be performed on the DocuSign Demo system (https://account-d.docusign.com). Requesting departments must create their DocuSign template(s)/workflow, test the template(s), and submit test envelopes on the DocuSign Demo system.

Document Management will write and test code to pull envelopes from the Demo system, and the integration must then meet all of DocuSign’s testing requirements for the integration. For integrations on VCU DocuSign domain account ID #11599208, we should not have to go through the process of creating an integration key and promoting it, so this will save some time for integrations on 11599208. For any integration in a standalone/segmented DocuSign domain, the integration key must go through DocuSign’s Go-Live process involving the promotion of the integration key to the production environment. DocuSign has stated that, once the promotion request has been submitted, it can take 3 business days for the key to be promoted to the DocuSign production environment. Once the key has been promoted, the REST API code will have to be modified/recreated on the production environment. The eSignature REST API solution is a far more complex and time consuming process than the simple email import.

For the REST API solution to be feasible, one important step that you/your department must perform is full customization of data labels in your DocuSign forms. We stress the importance of this in our Training Roadmap for DocuSign https://docs.google.com/document/d/1BwE3x0Tju5tqfpv6KHK_-fwcNwVTKzbrGs0kCiovTYc/edit#bookmark=id.6m60f8y0o7y8; however, we repeatedly see cases where no customization of data labels has been performed by the template creator.

While the eSignature REST API option avoids the need to be concerned about the 5MB limit, it does require substantial more development time. Again, both solutions require a dedicated generic/departmental account. The API script method, however, only requires one generic account, no matter how many different forms you may intend to import into ImageNow. If you have multiple forms that you intend to import into ImageNow and they use different application plans and keying structures, each form using a different plan would have to have its own API/iScript. Therefore, if you have 10 different DocuSign forms that you wish imported into 10 different ImageNow queues, you only need one generic account, but Document Management staff will create 10 different API scripts to manage the envelope retrieval from DocuSign, based on each specific combination of email subject line + ImageNow queue + data values to be indexed in ImageNow.

Benefits

• Not restricted to the 5MB limit
  
  
• Indexing - relevant DocuSign fields–based on data labels that you customized in the DocuSign template–will be used for automatic indexing of key values in ImageNow

Limitations

• It is assumed that this integration is for a brand new DocuSign-ImageNow solution, not for historical envelopes.
  
  
• It is typically assumed that you expect to have a relatively high volume of completed envelopes yearly associated with this process. 
  
  
• You must have an ImageNow solution in place for this integration, and you must have a completed template for this integration with test envelopes on the VCU DocuSign Demo system (https://account-d.docusign.com), before VCU DocuSign support can begin testing.
  
  
• Initial setup and implementation are time consuming processes. Apart from the base coding of the API/ImageNow integration, the testing process for a new integration key (if required) also requires at least 20 successful calls over a 24-hour period, and once that passes DocuSign’s requirement, the eventual promotion of the integration key from the developer’s sandbox to the VCU DocuSign production domain can take 3 business days. Departments should expect to allow for 30 days of testing and implementation of a new integration.
  
  
• If you later intend to modify the DocuSign template used for these envelopes, do not modify data labels of those specific fields used in the indexing process. If you are merely adding forms/fields to the specific template, but are otherwise not modifying the data labels of the key fields used in indexing, there is no need to advise us of the changes.
  
  
• Because indexing is hardcoded in the implementation, an entirely separate integration–new ImageNow application plan, new integration key testing/promotion, new API/iScript–would be required for each form requiring a different ImageNow application plan/keying values: this entire process begins anew.
  
  
• Collaboration Services for DocuSign and ImageNow is a small unit managing multiple university-wide applications, and there are no staff dedicated solely to the process of DocuSign-ImageNow integration. Additionally, DocuSign itself has specific time requirements and limitations that will impact the amount of time it takes to create an integration on the demo environment, successfully pass all of DocuSign’s testing requirements, and then begin the key promotion and movement of the API integration to production. There is NO method of bypassing DocuSign’s testing requirements or the amount of time it may take for the key to be promoted to production.

Requirements/Process

Generic Email and ImageNow

• If no existing generic email account is suitable for your DocuSign envelopes, submit an IT service desk request https://go.vcu.edu/ramscentral to Collaboration Services for a new generic email account https://collaborate.vcu.edu/generic-accounts/. This is to aid in centralizing your DocuSign business processes.
  
  
• An existing or new ImageNow implementation. If you need to request a new ImageNow solution, please submit an IT service desk request https://go.vcu.edu/ramscentral to Document Management, ImageNow.

Requesting Department Creates DocuSign Template and Completes Test Envelopes on the VCU DocuSign DEMO System

• Requesting department’s DocuSign template creator must have a completed template with all data labels customized on the VCU Demo system (https://account-d.docusign.com). Please note: if you intend to have similar integrations in the future, it is strongly recommended that you keep your data labels consistent across templates. For example, a data label such as “V Number” should remain “V Number” in future templates, not “V No.” in some templates and “V_num” in others. This will aid in preventing backend coding issues for future integrations. You do not need to create a PowerForm for the template on Demo merely to test envelope submission (if you do, bear in mind that the PowerForm URL is domain-dependent https://docs.google.com/document/d/1BwE3x0Tju5tqfpv6KHK_-fwcNwVTKzbrGs0kCiovTYc/edit#bookmark=id.g70zpk39xcga, so you would need to recreate the PowerForm when you upload the template to production). If you are intending the production version of the PowerForm to use a CAS Passthrough URL https://docs.google.com/document/d/1BwE3x0Tju5tqfpv6KHK_-fwcNwVTKzbrGs0kCiovTYc/edit#heading=h.619ygfcuoa71, please do not request a CAS Passthrough URL for the Demo domain: there is no need to test CAS Passthrough on Demo. Additionally, please thoroughly review all of the information in the VCU DocuSign Demos and Training Roadmap regarding PowerForms, including all of the caveats regarding CAS Passthroughs and the ability to delete a PowerForm.
  
  
• The subject line of the email message in your DocuSign template must be unique enough that the API can locate only those envelopes relevant to your process, and flexible enough that minor changes to the email subject line will not break your integration. You must assign a unique code to be included in the email subject line so that any other changes to year or semester or other wording changes do not break the integration. For example, an email subject line that only consists of something such as “2022 Award” could not only result in the inadvertent inclusion of envelopes that are not part of your process, but it will also break when you change the email subject line to “2023 Award” next year.
   
  For your planning purposes, we do wish to point out that the DocuSign email subject line is limited to 100 characters (including spaces), and that the API does rely solely on the email subject line in the Completed envelopes for identification. Additionally, the API will only search for 48 contiguous characters of your email subject line (your email subject line can be the full 100 allowed by DocuSign, but the portion used for the search will only be 48 contiguous characters). The unique code is vital to ensure that only your specific documents are retrieved.
  
  Departments must devise a unique code to include in any email subject lines you intend to use for your integrations. The code could be something such as an abbreviation of the school/department/process and a numerical value, e.g.: SOFSDR001
  
  Thus, a subject line of:
  
  SOFSDR001 School of Farming Supplemental Data Request for Spring 2025
  or
  School of Farming Supplemental Data Request for Spring 2025 SOFSDR001
  
  would give us a single, unique value of SOFSDR001 to use for identification. That code is also well under the 48-character limit.
  
  Finally, bear in mind that changes to a template are not inherited by any envelopes already in process.
• Requesting department’s template/PowerForm must either include the generic account as a Carbon Copy at the end of the signature process, or–in the case of a PowerForm–the generic account should be the PowerForm sender so that completed envelopes are returned to the generic account.
  
  
• Requesting department will generate test envelopes using their template/PowerForm and fully Complete the test envelopes on the VCU DocuSign Demo system (https://account-d.docusign.com).

Document Management (DocuSign and ImageNow support staff) Script Development and Testing

• Document Management staff will write/modify API/ImageNow iScript(s) to pull completed test envelopes/documents from the DocuSign Demo system into the ImageNow TEST system. Depending upon the integration requirements, this may also entail additional modifications or new additions to a department’s workflow queues–to include the possibility of creation of ImageNow iScripts–in ImageNow to account for routing. Any issues with the content of the department’s template (e.g., email subject lines and field data labels) will be addressed at this time, and recommendations will be made to the requesting department of any changes required for successful execution of the script.
  
  
• If attempts at running the integration are unsuccessful or otherwise generate errors or incomplete downloads, it is likely that Document Management staff will have to generate another batch of envelopes and manually sign them. DocuSign requires 20 successful, consecutive calls over a 24-hour period in order to begin the promotion of the key from the demo environment to the production environment.
  
  
• Once the integration successfully completes all of DocuSign’s testing requirements, Document Management staff can begin the Go-Live process https://developers.docusign.com/platform/go-live/ and the promotion of the key to the VCU DocuSign production system. Once the promotion request has been submitted, promotion of the key to the VCU DocuSign production system can take 3 business days. (NOTE: if you have an existing integration key that has already been promoted to the production system, we may be able to reuse that key for the new integration, thus bypassing this Go-Live step.)

Requesting Department Moves Demo Template to VCU DocuSign Production System and (if applicable) Creates any PowerForms and/or Submits CAS Passthrough URL Request to Web Services

• Once testing is successful, the requesting department may upload a copy of the completed/modified template to production (https://account.docusign.com), create the PowerForm, and–if the requesting department is expecting to populate CAS data into the form–submit a ticket to Web Services for a CAS Passthrough URL. Please thoroughly review the information in the CAS Passthrough overview here: https://docs.google.com/document/d/1BwE3x0Tju5tqfpv6KHK_-fwcNwVTKzbrGs0kCiovTYc/edit#heading=h.619ygfcuoa71 Please note that you do not need to advise docusign@vcu.edu or imagenow@vcu.edu of the creation of a CAS Passthrough URL, as that URL has no impact on DocuSign, ImageNow, or the integration: it merely populates some CAS data into your form prior to submission. The integration is concerned solely with completed envelopes and their fields/data labels.
  
  
• Requesting department will update their procedures for business continuity https://collaborate.vcu.edu/apps/imagenow/end-user-procedures/.

Document Management Staff Move/Duplicate ImageNow and DocuSign Modifications/Scripts to the Production Systems

• Document Management staff will move a copy of the API/ImageNow iScript to the ImageNow production server and modify the code to reference production systems. Any modifications or additions to the department’s ImageNow workflow queues and/or queue iScripts will also have to be manually duplicated.
  
  
• Document Management staff will create a batch (.bat) file so that the ImageNow INTOOL can call and execute the API/iScript.
  
  
• Document Management staff will create a task in the Windows Task Scheduler of the ImageNow production server to execute the batch file. All DocuSign APIs limit each account (not end-user account or specific integration key, but rather, the entire VCU DocuSign domain account) to a certain number of requests per hour. https://developers.docusign.com/platform/resource-limits/. As a general rule, the Windows Task for any given integration script will execute the API calls only once every hour or every 30 minutes on the production systems. 

Please note that if you require solutions that involve both option 1 (a dedicated email account from which you perform indexing) and option 2 (eSignature REST API), you will require two separate generic email accounts, because option 1 automatically pulls everything received in the generic email account into your designated ImageNow workflow queue.