Explore our blog

Expanded Launcher Example: Retrieve Envelope Tab Data

We’re thrilled to announce new code examples for our eg03 launchers. Today we’re going to discuss one of the examples to retrieve envelope tab data information. While already available in the NodeJS and PHP launchers, this addition to the launcher lineup will help you better understand and visualize some aspects of the Build-it path. Today we’re providing snippets in C# and PowerShell for ease of implementation; look for these additions to be added to the Curl (Bash) eg03 launcher.

Background

Let’s consider a scenario on how you would better facilitate automation. Pretend that you are a property management company where your mainline business activity involves processing and collecting paperwork. Your company is already harnessing the power of the DocuSign eSignature platform. Furthermore, part of this approval process employs a third-party credit history lookup service with API-enabled products. In other words, your staff currently sends and reviews completed envelopes as part of the application process; then, through data entry, manually initiates a credit history lookup action. From there they again need to set up a fresh envelope manually with either an approval offer or a rejection letter. The process outlined may take a minimum of 20 minutes to complete and requires manual intervention by at least one (though more than likely two to five) employees of the property management company. The process shown here is an ideal candidate for automation via Tabs, through the DocuSign eSignature Rest API.

Send an Envelope

Set up your application form document. A variety of formats are acceptable. but DOCX or PDF will work just fine. On this application be sure to have numeric and data collection forms for such items as income, current/former addresses, or other data that can be passed on to the credit history lookup service. When setting up an envelope definition, set the tab identifiers using DocumentIds, TabLabels, and RecipientIds; these tab identifiers can be used together to provide a greater level of flexibility. As a best practice, try to mask form values containing sensitive information with asterisks. To do this in the API, simply include the "concealValueOnDocument":true," attribute in your Tab object. With your document(s) ready, go through the steps of preparing an envelope through either an API call or through your developer sandbox (or production account) dashboard. Explaining the mechanism behind creating and sending an envelope is beyond the scope of this post, but is available through the Requesting a Signature Via Email Quickstart Guide and through our various aforementioned code launchers above. What is essential is that, once an envelope has been sent and completed, you retain the generated envelope ID so you can look up the tab attributes.

Collect Envelope Tabs Data

With the envelope completed, use its EnvelopeId along with your DocuSign AccountId to look up the data that was saved on those tabs for the envelope. The JSON result will contain your tabs data and can be parsed however you choose so that the next step in automation occurs. Following along the scenario regarding our property management enterprise: We've collected a name, one or more addresses, a gross income, and their masked social security number. Send this data in a POST request to your third-party processing provider via their API endpoint. From there, your application's logic can take the response data and automatically append an auto-generated document with the credit history response and attach it to that existing envelope along with another custom Tab declaring that the request was approved or declined.

C#

var basePath = "https://demo.docusign.net/restapi";
// Step 1: Obtain your OAuth token
var accessToken = "eyJ0eXAiOiJ.....NVCV6DoAv0w"; //represents your {ACCESS_TOKEN}
var accountId = "0000000"; //represents your {ACCOUNT_ID}
var envelopeId = "22055432-xxxx-xxxx-xxxx-a203dbedee77";
// Step 2: Construct your API headers
var config = new Configuration(new ApiClient(basePath));
config.AddDefaultHeader("Authorization", "Bearer " + accessToken);
// Step 3: Call the eSignature REST API
EnvelopesApi envelopesApi = new EnvelopesApi(config);
EnvelopeFormData results = envelopesApi.GetFormData(accountId, envelopeId);
string userName = null;
string userSSN = null;
string userIncome = null;
IDictionary<string, string> otherFields = new Dictionary<string, string>();
for (int i = 0; i < results.FormData.Count; i++)
{
    string checkCondition = results.FormData[i].Name;
    string tabValue = results.FormData[i].Value;
    switch (checkCondition)
    {
        case "Full Name":
            userName = tabValue;
            break;
        case "Social":
            userSSN = tabValue;
            break;
        case "Gross Income":
            userIncome = tabValue;
            break;
        default:
            Console.WriteLine("Unexpected input: {0} : {1}", checkCondition, tabValue);
            otherFields[checkCondition] = tabValue;
            break;
    }
}
Console.WriteLine("Response: ");
Console.WriteLine("Name: {0}", userName);
Console.WriteLine("Social Security Number: {0}", userSSN);
Console.WriteLine("Gross Income: {0}", userIncome);
foreach (KeyValuePair<string, string> attrib in otherFields)
{
    Console.WriteLine("OtherFields Key: {0}, Value: {1}",
    attrib.Key, attrib.Value);
}
//TODO: Send these values to the Credit Reporting API Service

NodeJS

const docusign = require('docusign-esign');
// Step 1: Obtain your OAuth token
let accessToken = "eyJ0eXAiOiJ.....sCteGwBrjkuD_byJxuEpg"; //represents your {ACCESS_TOKEN}
let accountId = "0000000"; //represents your {ACCOUNT_ID}
let envelopeId = "22055432-xxxx-xxxx-xxxx-a203dbedee77";
 
// Step 2: Construct your API headers
let dsApiClient = new docusign.ApiClient();
   dsApiClient.setBasePath("https://demo.docusign.net/restapi");
   dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
   let envelopesApi = new docusign.EnvelopesApi(dsApiClient)
     , results = null, userName = null, userSSN = null, userIncome = null;
 
   // Step 3. Call EnvelopeFormData::get
   // Exceptions will be caught by the calling function
 
   try {
      
   results = envelopesApi.getFormData(accountId, envelopeId);
   results.then(res => {
       // console.log(res.formData);
  
  
otherFields = [];
 
for (var i = 0; i  {
   console.log(`OtherFields Key: ${element.Key}, Value: ${element.Value}`);
});
 
})
.catch(e => console.error(`Inner Error: ${e}`));
 
   } catch(e) {
       console.log(`Outer Error: ${e}`)
   }
//TODO: Send these values to the Credit Reporting API Service

PHP

// Step 1: Obtain your OAuth token
$args = array('base_path' => "https://demo.docusign.net/restapi",
             'ds_access_token' => "eyJ0eXAiOiJNVCIsI.....GwBrjkuD_byJxuEpg",
             'account_id' => "0000000",
             'envelope_id' => "22055432-xxxx-xxxx-xxxx-a203dbedee77");
 
$userName = null; $userSSN = null; $userIncome = null; $otherFields = [];
 
try{
$config = new \DocuSign\eSign\Configuration();
 
// Step 2: Construct your API headers
$config->setHost($args['base_path']);
$config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']);
$api_client = new \DocuSign\eSign\Client\ApiClient($config);
 
// Step 3. Call EnvelopeFormData::get
// Exceptions will be caught by the calling function
$envelope_api = new \DocuSign\eSign\Api\EnvelopesApi($api_client);
$results = $envelope_api->getFormData($args['account_id'], $args['envelope_id']);
# results is an object that implements ArrayAccess. Convert to a regular array:
$convertedJson = json_decode((string)$results, true);
// var_dump($convertedJson['formData']);
 
foreach ($convertedJson['formData'] as $seq => $parent) {
       switch ($parent['name']) {
           case 'Full Name':
               $userName = $parent['value'];
               break;
          
           case 'Social':
               $userSSN = $parent['value'];
               break;
          
           case 'Gross Income':
               $userIncome = $parent['value'];
               break;
          
           default:
               $otherFields[$parent['name']] = $parent['value'];
               break;
   }
}
 
echo "\n\n"."Response:";
echo "\n"."Name: " . $userName;
echo "\n"."Social Security Number: " . $userSSN;
echo "\n"."gross Income: " . $userIncome;
echo "\n";
foreach ($otherFields as $key => $value) {
   echo "\n"."Unexpected Form Data: ".$key." : ".$value;
}
echo "\n\n";
 
}
catch (\DocuSign\eSign\ApiException $e) {
$error_code = $e->getResponseBody()->errorCode;
$error_message = $e->getResponseBody()->message;
echo $error_code ." : ".$error_message;
exit();
}
 
// //TODO: Send these values to the Credit Reporting API Service

PowerShell

# Step 1: Obtain your OAuth token
# Note: These values are not valid, but are shown for example purposes only!
$oAuthAccessToken="eyJ0eXAiOiJNVCI.....wtyrfUVu7VgHxR4l_tFA"
#Setup variables for full code example
# Note: These values are not valid, but are shown for example purposes only!
$APIAccountId="0000000"
$envelopeId="22055432-xxxx-xxxx-xxxx-a203dbedee77"
 
#Step 2: Construct your API headers
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.add("Authorization","Bearer $oAuthAccessToken")
$headers.add("Accept","application/json")
$headers.add("Content-Type","application/json")
# Step 3: a) Make a GET call to the form_data endpoint to retrieve your envelope tab values
#         b) Display the JSON response
$uri = "https://demo.docusign.net/restapi/v2.1/accounts/$APIAccountId/envelopes/$envelopeId/form_data"
$otherData = @{}
try{
write-host `r`n"Response:"
$response = Invoke-RestMethod -Uri $uri -headers $headers -method GET | foreach { $_.formData } 
foreach ($data in $response)
{
 
switch($data.name){
    "Full Name" { $userName=$data.value; Break };
    "Social" { $userSSN=$data.value;  Break };
    "Gross Income" { $userIncome=$data.value; Break }; 
    Default { 
        write-host "Unknown Key: " $data.name ", Value:" $data.value; 
        $otherData[$data.name] = $data.value;
        Break 
        }  
    }
 
 
}
 
write-host  `r`n"Full Name: " $userName
write-host  "Social Security Number: " $userSSN
write-host  "Gross Income: " $userIncome `r`n
 
foreach($key in $otherData.Keys){
 
 write-host "OtherFields Key: " $key ", Value:" $otherData[$key]; 
}
 
}
catch{
write-host "Something Went Wrong, Please check your configuration"
       #On failure, display a notification, X-DocuSign-TraceToken, error message, and the command that triggered the error
       $continue = $false
       
       foreach($header in $_.Exception.Response.Headers){
           if($header -eq "X-DocuSign-TraceToken"){ write-host "TraceToken : " $_.Exception.Response.Headers[$int]}
               $int++
           }
   write-host "Error : "$_.ErrorDetails.Message
   write-host "Command : "$_.InvocationInfo.Line
}

Use this feature in tandem with our upcoming conditional recipients feature to further automate the approval pipeline by requiring secondary and tertiary reviews or approvals up the ladder. To do this, attach an old envelope's document into a new envelope, include some custom tabs for decision block text fields, and set up the recipient flow for your approval process. Feel free to begin this activity right away by setting up a developer account through the DocuSign Developer Center. If you’re just learning of DocuSign and would like to give it a test-drive firsthand, check out our interactive LoanCo sample application.

Additional resources

Author

Aaron Jackson-Wilde

Programmer Writer

Published

August 28, 2019