Pascal Pascal - 4 months ago 49
PHP Question

Submit form and prepopulate custom fields in DocuSign Envelope

For some reason I can't get my code to show the custom fields I am wanting to add in the left pane(e.g. First Name, Last Name, etc.). On submit my form should go to the envelope and prepopulate my custom fields. I've searched the DocuSign docs and also different threads on here. Any help is much appreciated. Thank you.

<?php
if(!empty($_POST)){
// Input your info:
$email = "foor@bar.com"; // your account email
$password = "password"; // your account password
$integratorKey = "wouldnt-you-like-to-know"; // your account integrator key, found on (Preferences -> API page)
$templateId = "66b7706e-936b-4438-bd5e-bd68ce47dffb"; // provide a valid templateId of a template in your account
$templateRoleName = "Test"; // use same role name that exists on the template in the console

$recipientName = 'blah bleh'; // provide a recipient (signer) name
$recipientEmail = 'yee@haw.com';
// the recipient name and email. Whatever you set the clientUserId to you must use the same
// value when requesting the signing URL
// construct the authentication header:
$color = $_POST['color'];
$number = $_POST['number'];
$animal = $_POST['animal'];

$header =
"<DocuSignCredentials>
<Username>" .
$email .
"</Username>
<Password>" .
$password .
"</Password>
<IntegratorKey>" .
$integratorKey .
"</IntegratorKey>
</DocuSignCredentials>";

// STEP 1 - Login (retrieves baseUrl and accountId)
$url = "https://demo.docusign.net/restapi/v2/login_information";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-DocuSign-Authentication: $header"));
$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 200 ) {
echo "<br>";
echo "error calling webservice, status is:" . $status;
exit(-1);
}

$response = json_decode($json_response, true);
$accountId = $response["loginAccounts"][0]["accountId"];
$baseUrl = $response["loginAccounts"][0]["baseUrl"];
curl_close($curl);

//--- display results
echo "accountId = " . $accountId . "\nbaseUrl = " . $baseUrl . "\n" . "<br>";

// STEP 2 - Create an envelope with an Embedded recipient (uses the clientUserId property)
$data = array(
"accountId" => $accountId,
"emailSubject" => "DocuSign API - Embedded Signing Example",
"emailBlurb" => "This is a test.",
"compositeTemplates" => array(
"serverTemplates" => array(
"sequence" => "1",
"templateId" => $templateId
),
"inlineTemplates" => array(
"sequence" => "2",
"recipients" => array(
"signers" => array(
"roleName" => "Signer1",
"recipientId" => "1",
"name" => "John Doe",
"email" => "johndoe@test.com",
"clientUserId" => "1234",
"tabs" => array(
"textTabs" => array(
"tabLabel" => "address",
"value" => "123 Main Street"
)
)
)
)
)
),
"status" => "sent"
);

$data_string = json_encode($data);
$curl = curl_init($baseUrl . "/envelopes" );
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string),
"X-DocuSign-Authentication: $header" )
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 201 ) {
echo "error calling webservice, status is:" . $status . "\nerror text is --> <br>";
print_r($json_response); echo "\n";
exit(-1);
}

$response = json_decode($json_response, true);
$envelopeId = $response["envelopeId"];
curl_close($curl);

//--- display results
echo "<br>Envelope created! Envelope ID: " . $envelopeId . "\n";

// STEP 3 - Get the Embedded Signing View
$data = array(
"returnUrl" => "http://www.docusign.com/devcenter",
"authenticationMethod" => "Email",
"clientUserId" => "1234",
"userName" => "John Doe",
"email" => "johnDoe@test.com"
);

$data_string = json_encode($data);
$curl = curl_init($baseUrl . "/envelopes/$envelopeId/views/recipient" );
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string),
"X-DocuSign-Authentication: $header" )
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 201 ) {
echo "error calling webservice, status is:" . $status . "\nerror text is --> ";
print_r($json_response); echo "\n";
exit(-1);
}

$response = json_decode($json_response, true);
$url = $response["url"];

//--- display results
echo "\n\nNavigate to this URL to start the embedded signing view of the envelope\n" . "<br>Embedded URL is: \n\n" . "<a href='$url'>HERE!</a>";
}
?>
<form action="" method="POST">
<label for="color">color:</label>
<input type="text" name="color">
<br>
<label for="number">number:</label>
<input type="text" name="number">
<br>
<label for="animal">animal:</label>
<input type="text" name="animal">
<br>
<button type="submit">Submit</button>
</form>

Answer

To create an Envelope using a Template and pre-populate field(s) within that Envelope's documents requires that you use the Composite Templates structure in the API request. (See the "Composite Templates" section on this page for info about Composite Templates.)

I'm not familiar with the DocuSign PHP SDK, but will explain the request syntax in JSON, and I imagine you can figure out the corresponding PHP syntax to generate the requests as shown.

The following example request (JSON) creates an Envelope that uses the specified Template with a single recipient (role name = Signer1), and pre-populates the address field with value "123 Main Street" for that recipient (embedded signer). (Although this example pre-fills just a single field for Signer1 -- you could obviously pre-fill additional fields by simply including them in the tabs object of the request along with address.)

POST https://{{env}}.docusign.net/restapi//v2/accounts/{{accountId}}/envelopes

{
    "emailSubject": "Test Pre-fill Tabs",
    "emailBlurb": "This is a test.",
    "compositeTemplates": [{
        "serverTemplates": [{
            "sequence": "1",
            "templateId": "CD0E6D53-3447-4A9E-BBAF-0EB2C78E8310"
        }],
        "inlineTemplates":[{
            "sequence": "2",
            "recipients": {
                "signers": [
                    {
                        "roleName": "Signer1",
                        "recipientId": "1",
                        "name": "John Doe",
                        "email": "johndoe@test.com",
                        "clientUserId": "1234",
                        "tabs": {
                            "textTabs": [
                                {
                                    "tabLabel": "address",
                                    "value": "123 Main Street"
                                }
                            ]
                        }
                    }
                ]
            }
        }]
    }],
    "status": "sent"
}

Once you've created the Envelope (using the above request), you'll execute a "POST Recipient View" request to get the signing URL for Signer1:

POST https://{{env}}.docusign.net/restapi//v2/accounts/{{accountId}}/envelopes/{{envelopeId/views/recipient

{
    "clientUserId": "1234",
    "userName": "John Doe",
    "email": "johndoe@test.com",
    "returnUrl": "https://www.google.com",
    "authenticationMethod": "Email"
}

(Notice that you don't specify tabs in this request.)


UPDATE #1


Starting with the code you added to your original post, I've been able to modify it such that it's now successfully creating an Envelope (using a Template), with a single embedded recipient (Signer1) and pre-populating the address text field for that signer. Here is the code -- please note that you'll need to specify values for all variables at the top of this code example.

<?php

// Set values for variables
//-----------
$email = "YOUR_DOCUSIGN_LOGIN_EMAIL";                                 // your account email
$password = "YOUR_DOCUSIGN_LOGIN_PASSWORD";                              // your account password
$integratorKey = "YOUR_DOCUSIGN_INTEGRATOR_KEY"; // your account integrator key, found on (Preferences -> API page)

$templateId = "TEMPLATE_ID";    // provide a valid templateId of a template in your account
$templateRoleName = "TEMPLATE_RECIPIENT_ROLE_NAME";                              // use same role name that exists on the template in the console

$recipientName = "SIGNER_NAME";                        // provide a recipient (signer) name
$recipientEmail = "SIGNER_EMAIL_ADDRESS";            // provide a recipient (signer) email address
$recipientId = "1";                                 // set recipient id (can be any integer value)
$clientUserId = "1234";                             // set clientUserId (can be any integer value) -- this is what makes the recipient an "embedded recipient (signer)"

$header = 
"<DocuSignCredentials>
    <Username>" . 
        $email . 
    "</Username>
    <Password>" . 
        $password . 
    "</Password>
    <IntegratorKey>" . 
        $integratorKey . 
    "</IntegratorKey></DocuSignCredentials>";



// STEP 1 - Login (retrieves baseUrl and accountId)
//-----------
$url = "https://demo.docusign.net/restapi/v2/login_information";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-DocuSign-Authentication: $header"));
$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 200 ) {
    echo "\n";
    echo "error calling webservice, status is:" . $status;
    exit(-1);
}

$response = json_decode($json_response, true);
$accountId = $response["loginAccounts"][0]["accountId"];
$baseUrl = $response["loginAccounts"][0]["baseUrl"];
curl_close($curl);

//--- display results
echo "accountId = " . $accountId . "\nbaseUrl = " . $baseUrl . "\n\n";



// STEP 2 - Create an envelope with an Embedded recipient (uses the clientUserId property)
//-----------
// tabs
$textTabs = array();
$textTabs[] = array('tabLabel' => "address", 'value' => "123 Main Street");             
$tabs = array('textTabs' => $textTabs);
#echo ("tabs:\n" . json_encode($tabs) . "\n\n");

// recipients 
$signers = array();
$signers[] = array('roleName' => $templateRoleName, 'recipientId' => $recipientId, 'name' => $recipientName, 'email' => $recipientEmail, 'clientUserId' => $clientUserId, 'tabs' => $tabs);
$recipients = array('signers' => $signers);
#echo ("recipients:\n" . json_encode($recipients) . "\n\n");

// serverTemplates
$serverTemplates = array();
$serverTemplates[] = array('sequence' => "1", 'templateId' => $templateId);
#echo ("serverTemplates:\n " . json_encode($serverTemplates) . "\n\n");

// inlineTemplates
$inlineTemplates = array();
$inlineTemplates[] = array('sequence' => "2", 'recipients' => $recipients);
#echo ("inlineTemplates:\n" . json_encode($inlineTemplates) . "\n\n");

// compositeTemplates
$compositeTemplates = array();
$compositeTemplates[] = array('serverTemplates' => $serverTemplates ,'inlineTemplates' => $inlineTemplates);
#echo ("compositeTemplates:\n" . json_encode($compositeTemplates) . "\n\n");

// request body 
$data = array('emailSubject' => "DocuSign Test - Embedded Signing", 'emailBlurb' => "Please sign. Thanks!", 'status' => 'sent', 'compositeTemplates' => $compositeTemplates);
$data_string = json_encode($data);  

$curl = curl_init($baseUrl . "/envelopes" );
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);                                                                  
curl_setopt($curl, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string),
    "X-DocuSign-Authentication: $header" )                                                                       
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 201 ) {
    echo "error calling webservice, status is:" . $status . "\nerror text is --> \n";
    print_r($json_response); echo "\n";
    exit(-1);
}

$response = json_decode($json_response, true);
$envelopeId = $response["envelopeId"];
curl_close($curl);

//--- display results   
echo "\nEnvelope created! Envelope ID: " . $envelopeId . "\n"; 



// STEP 3 - Get the Embedded Signing View 
//-----------
$data = array(
    "returnUrl" => "http://www.docusign.com/devcenter",
    "authenticationMethod" => "Email", 
    "clientUserId" => $clientUserId,
    "userName" => $recipientName,
    "email" => $recipientEmail
);   

$data_string = json_encode($data);    
$curl = curl_init($baseUrl . "/envelopes/$envelopeId/views/recipient" );
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);                                                                  
curl_setopt($curl, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string),
    "X-DocuSign-Authentication: $header" )                                                                       
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 201 ) {
    echo "error calling webservice, status is:" . $status . "\nerror text is --> ";
    print_r($json_response); echo "\n";
    exit(-1);
}

$response = json_decode($json_response, true);
$url = $response["url"];

//--- display results
echo "\n\nNavigate to this URL to start the embedded signing view of the envelope:\n\n" . $url . "\n\n"; 

?>

Disclaimer: although this code is functional and achieves the objective, this is my first foray into working with PHP, so there's likely a better (more efficient) way to write this code. I welcome feedback if any PHP experts are so inclined.