Enabling signers to update their data

Your application is integrated with DocuSign! You’re sending out documents to be signed, either via email or you’re using embedded signing. Life’s good.

Then your LOB (Line of Business) internal client attended a Momentum conference and now realizes that signers should be able to update their name and address during the signing ceremony. She wants to give the signers those options and have the new data stored in your company’s CRM (Customer Relationship Management) system. The rest of this blog shows how to accomplish this. All files referenced in this blog can be downloaded and extracted from this zip file hosted on Box (Blog_SignerNameChange.zip).

The signer’s user experience (UX)

During the “Signing Ceremony” on a web browser, the signer can change their name and initials when they complete the “Adopt Your Signature” process.

On a mobile device or tablet, signers directly draw their signatures on the device, so there is no opportunity for them to update their name at that time. But you can give them the ability to update their name by adding an additional text field (tab) to the document.

We’ll show the signer their name and address (as recorded in our CRM database) and enable them to update it during the signing ceremony.

Creating the envelope

To handle the case of updating the signer’s name during a mobile signing ceremony, we’ll add a “signer1name” text field when creating the envelope. We’ll also add the address text fields and set their initial values from our company database. We’re using autoplace (anchor text) to locate the fields on the page. To keep the example short, I’m only using a city field rather than a complete set of address fields.

I’m using an HTML document (see the simple_agreement.html file) for this example so you can easily see the anchor strings. The HTML source is quite short.

The JSON request body for the Envelopes: create method (see the envelope_create.json file) includes some specific features:

• The eventNotification object enables the DocuSign Connect (webhook) system to send us an XML notification after the envelope is completed (signed). For this example, the notification will be sent to the requestbin.com service. It enables us to see the incoming notification from DocuSign. For production, you’d use your own listener software.
• We’re setting the values of the text tabs by using the value field. Since we’re setting the tabs’ values, we also set the locked field to false. This enables the tabs to be edited by the signer.
• We’re using the anchorYOffset field to line up the tabs with document’s text.

Making the request

You can try out the Envelope create call by using Postman, curl, or your own app. Remember that the HTML document needs to be base64 encoded and inserted into the JSON request.

Signing the envelope

For this example, our signer, “Jackie Williams,” made several changes when she signed the envelope:

1. She changed her name in the “Adopt Your Signature” modal window to “Jackie Williams II.” She made the same change in the body of the document, in the “Full Name” field.
2. She also changed her city in the body of the document from “London” to “Wembley.”

Results via the Connect webhook

There are two ways for your application to learn about and process the signed envelope and the updated name and address information.

The first, and best technique, is to simply wait for the incoming message from the DocuSign Connect system. You can view the complete XML notification message (see the notification_message.xml file).

The notification message includes information on the updated Full Name text tab:

<TabStatus>
    <TabLabel>Full Name</TabLabel>
    <TabValue>Jackie Williams II</TabValue>
    <OriginalValue>Jackie Williams</OriginalValue>
    …
</TabStatus>

I’ve omitted some unimportant fields. Note the TabValue field, showing the updated value and the helpful OriginalValue field. Your app can use this information to enable either an automatic or semi-automatic update to your company’s data for Jackie.

The notification message includes similar information for the City field.

Jackie also updated her name when she completed the Signature Adoption process. The name she entered is sent as the UserName in the RecipientStatus section of the notification message:

<EnvelopeStatus>
    <RecipientStatuses>
        <RecipientStatus>
            <Type>Signer</Type>
            <Email>jackie@example.com</Email>
            <UserName>Jackie Williams II</UserName>

The original UserName (Jackie Williams) is not included in the notification message. You can retrieve it from your database, use a text tab as shown in this example, or include it as a recipient custom field.

Results via EnvelopesRecipients: List

The EnvelopesRecipients: List method can also be used to retrieve the envelope’s information. Use the “include_tabs” query parameter to see the tabs’ new values. The method’s response (see the list_recipients_result.json file) only shows the final values. The initial values can be retrieved from your database or stored as custom fields when the envelope is created.

The updated signer name set in the Adopt Your Signature modal window is returned as the “name” field in the results.

A “corner case”

In this example, note that it is possible for a signer who uses the web browser to update her name using only the Adopt Your Signature screen or the “Full Name” text field. You’ll need to handle this case too. And remember that mobile/tablet signers don’t have the opportunity to enter an updated name when they sign—that’s why we’re including the Full Name text field.

Summary

With DocuSign, it’s easy to enable your signers to verify and correct key data during the signing ceremony. You can either update your company database automatically with the new information, or use a person to review each update from signers.

Please let us know if this technique is useful! Contact us via developers@docusign.com.